<p><meta/> { “style”: “SRE_DOC_V1”, “status”: “DRAFT”, “engine”: “gemini-2.0-flash”, “priority”: “HIGH”, “category”: “Automation/Infrastructure” } </p> <p>本記事は<strong>Geminiの出力をプロンプト工学で整理した業務ドラフト（未検証）</strong>です。</p> <h1 class="wp-block-heading">JSON-YAML相互変換による構成管理自動化とIaC環境の堅牢化</h1> <h2 class="wp-block-heading">【導入と前提】</h2> <p>API取得したJSONをYAML変換し、自動同期。手動介入を排除して構成管理の堅牢化とIaC連携を実現するポータブルな自動化手順を定義します。</p> <ul class="wp-block-list"> <li><p><strong>OS</strong>: 主要なGNU/Linuxディストリビューション</p></li> <li><p><strong>必須ツール</strong>: <code>jq</code> (JSONプロセッサ), <code>yq</code> (mikefarah版 v4+), <code>curl</code></p></li> <li><p><strong>権限</strong>: 設定書き出し先への書込権限、systemd操作権限</p></li> </ul> <h2 class="wp-block-heading">【処理フローと設計】</h2> <div class="wp-block-merpress-mermaidjs diagram-source-mermaid"><pre class="mermaid"> graph TD A["Remote API / Local JSON"] -->|curl -fSL| B["jq: Filter & Validation"] B -->|pipe| C["yq: YAML Conversion"] C -->|atomic write| D["Target Config File"] D -->|trigger| E["Service Reload/Restart"] E -->|log| F["Journald / Health Check"] </pre></div> <p>入力データの整合性を<code>jq</code>で検証後、<code>yq</code>でフォーマット変換を行い、アトミックな書き換えによりダウンタイムを最小化する設計です。</p> <h2 class="wp-block-heading">【実装：堅牢な自動化スクリプト】</h2> <h3 class="wp-block-heading">1. 構成生成スクリプト (<code>update_config.sh</code>)</h3> <div class="codehilite"> <pre data-enlighter-language="generic">#!/usr/bin/env bash # set -e: エラー発生時に即座に終了 # set -u: 未定義変数の参照時にエラー # set -o pipefail: パイプラインの途中のエラーを拾う set -euo pipefail # 設定 API_URL="https://api.example.com/v1/config" TARGET_FILE="/etc/opt/myapp/config.yaml" TMP_FILE=$(mktemp) # クリーニング処理の登録 # スクリプト終了時（正常・異常問わず）に一時ファイルを削除 trap 'rm -f "${TMP_FILE}"' EXIT echo "Fetching configuration from ${API_URL}..." # 1. APIから取得し、jqで必要なスキーマのみ抽出 # -f: HTTPエラー(4xx, 5xx)をエラーとして扱う # -s: 進捗を表示しない（静音） # -S: エラー時はメッセージを表示 # -L: リダイレクトを追跡 # --retry: 通信失敗時のリトライ curl -fSLsS --retry 3 "${API_URL}" | \ jq -e '.settings // empty' > "${TMP_FILE}.json" || { echo "Error: Failed to fetch or invalid JSON schema." >&2 exit 1 } # 2. JSONからYAMLへの変換 # eval: 式を実行 # -P: プレティプリント（読みやすい形式） yq eval -P "${TMP_FILE}.json" > "${TMP_FILE}" # 3. 差分確認と反映（冪等性の担保） if diff -q "${TARGET_FILE}" "${TMP_FILE}" > /dev/null 2>&1; then echo "No changes detected. Skipping update." else echo "Changes detected. Updating ${TARGET_FILE}..." # アトミックな移動（ファイルの不完全な書き込みを防止） cat "${TMP_FILE}" | sudo tee "${TARGET_FILE}" > /dev/null # サービスの再読み込み（必要に応じて） # sudo systemctl reload myapp.service || true fi echo "Configuration update successful." </pre> </div> <h3 class="wp-block-heading">2. 自動実行の設定 (<code>systemd</code>)</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=Configuration Sync Service After=network-online.target [Service] Type=oneshot ExecStart=/usr/local/bin/update_config.sh User=root </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] OnBootSec=1min OnUnitActiveSec=15min Unit=config-sync.service [Install] WantedBy=timers.target </pre> </div> <h2 class="wp-block-heading">【検証と運用】</h2> <h3 class="wp-block-heading">正常系の確認コマンド</h3> <div class="codehilite"> <pre data-enlighter-language="generic"># スクリプトの手動実行 bash update_config.sh # 生成されたYAMLの構文チェック yq eval 'true' /etc/opt/myapp/config.yaml # systemdタイマーの稼働状況確認 systemctl list-timers config-sync.timer </pre> </div> <h3 class="wp-block-heading">ログの確認方法</h3> <div class="codehilite"> <pre data-enlighter-language="generic"># スクリプトの実行ログをジャーナルから確認 journalctl -u config-sync.service -f </pre> </div> <h2 class="wp-block-heading">【トラブルシューティングと落とし穴】</h2> <ul class="wp-block-list"> <li><p><strong><code>yq</code> のバージョン差異</strong>: <code>mikefarah/yq</code> と <code>kislyuk/yq</code> (Python版) ではコマンド体系が全く異なります。本稿は広く使われる mikefarah版 v4 に準拠しています。</p></li> <li><p><strong>権限問題</strong>: <code>tee</code> を使用して書き込む際、ディレクトリ自体の権限が不足していると失敗します。事前に <code>chown</code> 等で適切な所有権を設定してください。</p></li> <li><p><strong>機密情報の漏洩</strong>: APIトークンなどをスクリプトに直書きせず、環境変数または <code>systemd</code> の <code>EnvironmentFile</code> から読み込むようにしてください。</p></li> <li><p><strong>一時ファイルの残り</strong>: <code>trap</code> が確実に実行されるよう、<code>kill -9</code> ではなく <code>SIGTERM</code> での停止を意識します。</p></li> </ul> <h2 class="wp-block-heading">【まとめ】</h2> <p>運用の冪等性を維持するための3つのポイント：</p> <ol class="wp-block-list"> <li><p><strong>アトミックな更新</strong>: <code>mv</code> や <code>tee</code> を使い、設定ファイルが「中途半端に書き込まれた状態」で読み込まれるのを防ぐ。</p></li> <li><p><strong>差分比較</strong>: <code>diff</code> を用いて変更がある場合のみリロード等の後続処理をキックする。</p></li> <li><p><strong>厳格なエラーハンドリング</strong>: <code>set -euo pipefail</code> を徹底し、パイプラインのどの段階で失敗しても処理を中断させる。</p></li> </ol>

graph TD
A["Remote API / Local JSON"] -->|curl -fSL| B["jq: Filter & Validation"]
B -->|pipe| C["yq: YAML Conversion"]
C -->|atomic write| D["Target Config File"]
D -->|trigger| E["Service Reload/Restart"]
E -->|log| F["Journald / Health Check"]

#!/usr/bin/env bash

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


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


# set -o pipefail: パイプラインの途中のエラーを拾う

set -euo pipefail

# 設定

API_URL="https://api.example.com/v1/config"
TARGET_FILE="/etc/opt/myapp/config.yaml"
TMP_FILE=$(mktemp)

# クリーニング処理の登録


# スクリプト終了時（正常・異常問わず）に一時ファイルを削除

trap 'rm -f "${TMP_FILE}"' EXIT

echo "Fetching configuration from ${API_URL}..."

# 1. APIから取得し、jqで必要なスキーマのみ抽出


# -f: HTTPエラー(4xx, 5xx)をエラーとして扱う


# -s: 進捗を表示しない（静音）


# -S: エラー時はメッセージを表示


# -L: リダイレクトを追跡


# --retry: 通信失敗時のリトライ

curl -fSLsS --retry 3 "${API_URL}" | \
jq -e '.settings // empty' > "${TMP_FILE}.json" || {
    echo "Error: Failed to fetch or invalid JSON schema." >&2
    exit 1
}

# 2. JSONからYAMLへの変換


# eval: 式を実行


# -P: プレティプリント（読みやすい形式）

yq eval -P "${TMP_FILE}.json" > "${TMP_FILE}"

# 3. 差分確認と反映（冪等性の担保）

if diff -q "${TARGET_FILE}" "${TMP_FILE}" > /dev/null 2>&1; then
    echo "No changes detected. Skipping update."
else
    echo "Changes detected. Updating ${TARGET_FILE}..."

    # アトミックな移動（ファイルの不完全な書き込みを防止）

    cat "${TMP_FILE}" | sudo tee "${TARGET_FILE}" > /dev/null

    # サービスの再読み込み（必要に応じて）


    # sudo systemctl reload myapp.service || true

fi

echo "Configuration update successful."

[Unit]
Description=Configuration Sync Service
After=network-online.target

[Service]
Type=oneshot
ExecStart=/usr/local/bin/update_config.sh
User=root

[Unit]
Description=Run Config Sync every 15 minutes

[Timer]
OnBootSec=1min
OnUnitActiveSec=15min
Unit=config-sync.service

[Install]
WantedBy=timers.target

# スクリプトの手動実行

bash update_config.sh

# 生成されたYAMLの構文チェック

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

# systemdタイマーの稼働状況確認

systemctl list-timers config-sync.timer

# スクリプトの実行ログをジャーナルから確認

journalctl -u config-sync.service -f