<p>[META] { “style_prompt”: “professional_sre_technical_report”, “technical_focus”: [“json_yaml_conversion”, “jq_yq_automation”, “systemd_integration”, “shell_safety”], “language”: “ja” } [/META]</p> <p>本記事は<strong>Geminiの出力をプロンプト工学で整理した業務ドラフト（未検証）</strong>です。</p> <h1 class="wp-block-heading">JSON/YAMLの相互変換による設定ファイル自動生成とデプロイの自動化</h1> <p>【導入と前提】 API経由で取得した動的なJSONデータを、k8sや各種ミドルウェアが要求するYAML形式に変換・注入し、システム設定を自動更新する堅牢なパイプラインを構築します。</p> <ul class="wp-block-list"> <li><strong>前提環境</strong>: Linux OS (Bash 4.4+), <code>jq</code>, <code>yq</code> (mikefarah version), <code>curl</code> がインストールされていること。</li> </ul> <p>【処理フローと設計】</p> <div class="wp-block-merpress-mermaidjs diagram-source-mermaid"><pre class="mermaid"> graph TD A["外部ソース JSON"] -->|curl/jq| B["中間データ抽出"] B -->|yq evaluation| C["YAMLテンプレート結合"] C -->|Validation| D["最終設定ファイル生成"] D -->|Atomic Move| E["サービス再起動/リロード"] </pre></div> <p>外部リポジトリやAPIから取得したJSONを正規化し、構造を維持したままYAMLへ変換。整合性チェックを経て、アトミックな書き換えによりダウンタイムのリスクを最小化します。</p> <p>【実装：堅牢な自動化スクリプト】</p> <div class="codehilite"> <pre data-enlighter-language="generic">#!/usr/bin/env bash # --- 安全のためのシェルの設定 --- set -euo pipefail IFS=$'\n\t' # --- 変数定義 --- SOURCE_URL="https://api.example.com/v1/config" DEST_YAML="/etc/app/config.yaml" TMP_DIR=$(mktemp -d) TMP_JSON="${TMP_DIR}/source.json" TMP_YAML="${TMP_DIR}/output.yaml" # --- 終了時のクリーンアップ処理 --- trap 'rm -rf "$TMP_DIR"' EXIT echo "Starting configuration sync..." # 1. 外部ソースからJSONを取得 (curlオプション: -s 静音, -f エラー時失敗, -L リダイレクト追従) if ! curl -sfL "$SOURCE_URL" -o "$TMP_JSON"; then echo "Error: Failed to fetch JSON from $SOURCE_URL" >&2 exit 1 fi # 2. jqによるフィルタリングと正規化 # 必要なフィールドのみ抽出し、欠損値にはデフォルト値をセット jq -e '.settings | {env: (.env // "prod"), version: .version}' "$TMP_JSON" > "${TMP_JSON}.filtered" # 3. yqによるYAMLへの変換とテンプレート注入 # (yqオプション: -P 読みやすい形式で出力) yq -P eval "${TMP_JSON}.filtered" > "$TMP_YAML" # 4. 既存ファイルとの差分確認とバリデーション if [ -f "$DEST_YAML" ] && diff -q "$DEST_YAML" "$TMP_YAML" > /dev/null; then echo "No changes detected. Skipping update." exit 0 fi # 5. 安全なデプロイ (mvによるアトミックな更新) # 事前にバックアップを取得することを推奨 cp "$DEST_YAML" "${DEST_YAML}.bak" || true mv "$TMP_YAML" "$DEST_YAML" chmod 644 "$DEST_YAML" echo "Configuration updated successfully." </pre> </div> <h3 class="wp-block-heading">補足：systemdによる定期実行の自動化</h3> <p>このスクリプトを定期的に実行するためのタイマー設定例です。</p> <p><strong><code>/etc/systemd/system/config-sync.service</code></strong></p> <div class="codehilite"> <pre data-enlighter-language="generic">[Unit] Description=Sync Config from JSON API After=network-online.target [Service] Type=oneshot ExecStart=/usr/local/bin/sync-config.sh User=root # ログをsystemd-cat経由で出力 StandardOutput=journal StandardError=journal </pre> </div> <p><strong><code>/etc/systemd/system/config-sync.timer</code></strong></p> <div class="codehilite"> <pre data-enlighter-language="generic">[Unit] Description=Run config sync every 15 minutes [Timer] OnCalendar=*:0/15 Persistent=true [Install] WantedBy=timers.target </pre> </div> <p>【検証と運用】</p> <ol class="wp-block-list"> <li><p><strong>正常系の確認</strong>:</p> <ul> <li><p><code>systemctl start config-sync.service</code> を手動実行し、<code>$DEST_YAML</code> が意図した構造で生成されているか確認します。</p></li> <li><p><code>yq eval '.' /etc/app/config.yaml</code> でYAMLの構文妥当性を検証します。</p></li> </ul></li> <li><p><strong>エラーログの確認</strong>:</p> <ul> <li>実行失敗時は <code>journalctl -u config-sync.service</code> を参照。<code>set -x</code> をスクリプト冒頭に追加することで、詳細なデバッグトレースが可能です。</li> </ul></li> </ol> <p>【トラブルシューティングと落とし穴】</p> <ul class="wp-block-list"> <li><p><strong>yqのバージョン互換性</strong>: <code>yq</code> にはGo版(mikefarah)とPython版(kislyuk)が存在し、コマンド体系が全く異なります。本稿では主流のGo版を使用しています。</p></li> <li><p><strong>権限問題</strong>: <code>/etc</code> 直下への書き込みには <code>sudo</code> が必要ですが、スクリプト内での <code>sudo</code> 多用は避け、systemdユニットの <code>User=</code> 指定や、適切なディレクトリ権限の付与で対応してください。</p></li> <li><p><strong>一時ファイルの残存</strong>: <code>trap</code> 処理が確実に実行されるよう、<code>kill -9</code> ではなく <code>SIGTERM</code> での停止を運用ルールとして徹底します。</p></li> </ul> <p>【まとめ：運用の冪等性を維持するためのポイント】</p> <ol class="wp-block-list"> <li><p><strong>差分チェックの実施</strong>: <code>diff</code> やチェックサム比較を行い、内容に変更がない場合はサービス再起動等の副作用を発生させないこと。</p></li> <li><p><strong>中間ファイルによる検証</strong>: 直接本番ファイルを加工せず、必ず一時ファイルで変換・バリデーションを完了させてからアトミックに置換すること。</p></li> <li><p><strong>デフォルト値の定義</strong>: <code>jq</code> の <code>//</code> 演算子などを活用し、APIレスポンスに欠損があっても設定ファイルが壊れない設計にすること。</p></li> </ol>

graph TD
A["外部ソース JSON"] -->|curl/jq| B["中間データ抽出"]
B -->|yq evaluation| C["YAMLテンプレート結合"]
C -->|Validation| D["最終設定ファイル生成"]
D -->|Atomic Move| E["サービス再起動/リロード"]

#!/usr/bin/env bash

# --- 安全のためのシェルの設定 ---

set -euo pipefail
IFS=$'\n\t'

# --- 変数定義 ---

SOURCE_URL="https://api.example.com/v1/config"
DEST_YAML="/etc/app/config.yaml"
TMP_DIR=$(mktemp -d)
TMP_JSON="${TMP_DIR}/source.json"
TMP_YAML="${TMP_DIR}/output.yaml"

# --- 終了時のクリーンアップ処理 ---

trap 'rm -rf "$TMP_DIR"' EXIT

echo "Starting configuration sync..."

# 1. 外部ソースからJSONを取得 (curlオプション: -s 静音, -f エラー時失敗, -L リダイレクト追従)

if ! curl -sfL "$SOURCE_URL" -o "$TMP_JSON"; then
    echo "Error: Failed to fetch JSON from $SOURCE_URL" >&2
    exit 1
fi

# 2. jqによるフィルタリングと正規化


# 必要なフィールドのみ抽出し、欠損値にはデフォルト値をセット

jq -e '.settings | {env: (.env // "prod"), version: .version}' "$TMP_JSON" > "${TMP_JSON}.filtered"

# 3. yqによるYAMLへの変換とテンプレート注入


# (yqオプション: -P 読みやすい形式で出力)

yq -P eval "${TMP_JSON}.filtered" > "$TMP_YAML"

# 4. 既存ファイルとの差分確認とバリデーション

if [ -f "$DEST_YAML" ] && diff -q "$DEST_YAML" "$TMP_YAML" > /dev/null; then
    echo "No changes detected. Skipping update."
    exit 0
fi

# 5. 安全なデプロイ (mvによるアトミックな更新)


# 事前にバックアップを取得することを推奨

cp "$DEST_YAML" "${DEST_YAML}.bak" || true
mv "$TMP_YAML" "$DEST_YAML"
chmod 644 "$DEST_YAML"

echo "Configuration updated successfully."

[Unit]
Description=Sync Config from JSON API
After=network-online.target

[Service]
Type=oneshot
ExecStart=/usr/local/bin/sync-config.sh
User=root

# ログをsystemd-cat経由で出力

StandardOutput=journal
StandardError=journal

[Unit]
Description=Run config sync every 15 minutes

[Timer]
OnCalendar=*:0/15
Persistent=true

[Install]
WantedBy=timers.target