CLI環境におけるJSON/YAML相互変換と設定ファイル自動生成の堅牢化

Tech

{ “role”: “SRE / DevOps Engineer”, “style”: “Technical, Robust, Practical”, “formatting”: “Markdown with Mermaid and Bash snippets”, “language”: “Japanese” }

本記事はGeminiの出力をプロンプト工学で整理した業務ドラフト（未検証）です。

CLI環境におけるJSON/YAML相互変換と設定ファイル自動生成の堅牢化

【導入と前提】

外部APIから取得したJSONデータをYAML形式の設定ファイルへ変換し、Systemdユニット等の環境定義を自動生成するワークフローを堅牢化します。

  • OS: GNU/Linux (Ubuntu/RHEL)

  • 必須ツール:

    • jq: JSONプロセッサ (v1.6以上)

    • yq: YAMLプロセッサ (mikefarah/yq v4以上)

    • curl: データ取得用

【処理フローと設計】

graph TD
A["外部JSONデータ取得"] -->|curl| B{"バリデーション"}
B -->|jq| C["JSON加工・フィルタリング"]
C -->|yq| D["YAML変換・テンプレート埋込"]
D --> E["設定ファイル出力"]
E --> F["Systemdユニット更新/再起動"]

入力データの整合性をjqで担保した後、yqを用いて構造を保持したままYAMLへ変換します。最終的にenvsubstやヒアドキュメントを組み合わせて、実環境で使用可能な設定ファイルを生成します。

【実装：堅牢な自動化スクリプト】

#!/usr/bin/env bash

# --- 堅牢化設定 ---

set -euo pipefail

# -e: エラー発生時に即座に終了


# -u: 未定義変数の参照時にエラー


# -o pipefail: パイプ途中のエラーを無視せず戻り値に反映

# --- 変数定義 ---

readonly API_ENDPOINT="https://api.example.com/v1/config"
readonly OUTPUT_DIR="/etc/myapp"
readonly WORK_DIR=$(mktemp -d)
readonly CONFIG_FILE="${OUTPUT_DIR}/config.yaml"

# 一時ファイルのクリーンアップ処理

trap 'rm -rf "$WORK_DIR"' EXIT

echo "Starting configuration update: $(date)"

# 1. データ取得（リトライ処理込み）

echo "Fetching remote JSON data..."
curl -sSL --retry 3 --retry-delay 5 \
     -H "Accept: application/json" \
     "${API_ENDPOINT}" -o "${WORK_DIR}/data.json"

# -s: 進捗非表示, -S: エラー表示, -L: リダイレクト追従


# --retry: 通信失敗時の再試行回数

# 2. JSONの妥当性確認とフィルタリング

if ! jq empty "${WORK_DIR}/data.json" > /dev/null 2>&1; then
    echo "Error: Invalid JSON received." >&2
    exit 1
fi

# 3. JSONからYAMLへの変換と特定フィールドの抽出


# jqで必要なデータのみに絞り、yqでYAML化

jq -c '.settings | .env="production"' "${WORK_DIR}/data.json" | \
    yq -P -o=yaml > "${WORK_DIR}/converted.yaml"

# -P: Pretty print, -o=yaml: 出力フォーマット指定

# 4. 設定ファイルのデプロイ（原子性の確保）

sudo mkdir -p "${OUTPUT_DIR}"
sudo cp "${WORK_DIR}/converted.yaml" "${CONFIG_FILE}.tmp"
sudo mv "${CONFIG_FILE}.tmp" "${CONFIG_FILE}"

# 5. Systemdユニットファイルの生成例

cat <<EOF | sudo tee /etc/systemd/system/myapp.service > /dev/null
[Unit]
Description=My Application Service
After=network.target

[Service]
ExecStart=/usr/bin/myapp --config ${CONFIG_FILE}
Restart=always
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target
EOF

# 6. 設定反映

sudo systemctl daemon-reload

# sudo systemctl restart myapp.service

echo "Configuration update completed successfully."

【検証と運用】

正常系の確認

生成されたYAMLの構造が正しいか、再度yqで検証します。

# YAMLのパース確認

yq eval '.' /etc/myapp/config.yaml

# Systemdユニットの構文チェック

systemd-analyze verify /etc/systemd/system/myapp.service

ログの確認

スクリプトをCronやSystemd Timerで実行している場合、標準出力・標準エラーをjournalctlで追跡可能です。

# 実行ログの確認

journalctl -t myapp-config-update

【トラブルシューティングと落とし穴】

  1. yqのバージョン互換性: Python版（yq）とGo版（mikefarah/yq）ではコマンド体系が全く異なります。本稿は広く使われているGo版に基づいています。

  2. 一時ファイルのパーミッション: mktempで作成したファイルはデフォルトで作成ユーザーのみが読み書き可能です。sudo cpなどでシステムディレクトリに配置する際、オーナー権限の修正（chown）が必要になる場合があります。

  3. 環境変数の露出: APIトークンなどをスクリプトに含める場合は、環境変数経由で渡し、set -x（デバッグ実行）を避けるか、シークレット部分をマスクする処理を追加してください。

【まとめ】

運用の冪等性を維持するための3つのポイント：

  1. 検証の分離: 変換後のデータを反映する前に、必ずjqやyqで構文チェックを行うこと。

  2. アトミックな書き換え: cpではなくmv（移動）を用いることで、中途半端な状態の設定ファイルが参照されるリスクを回避すること。

  3. リソースのクリーンアップ: trapを使用して、エラー終了時でも一時ファイルがストレージを圧迫しないようにすること。

ライセンス：本記事のテキスト/コードは特記なき限り CC BY 4.0 です。引用の際は出典URL（本ページ）を明記してください。
利用ポリシー もご参照ください。

コメント

タイトルとURLをコピーしました