<p><style_prompt> [GENRE: SRE/DEVOPS_TECHNICAL_GUIDE] [TONE: PROFESSIONAL_STRICT_PRACTICAL] [FORMAT: MARKDOWN_ENHANCED] [VOCABULARY: JQ, YQ, IDEMPOTENCY, SYSTEMD, ROBUST_SHELL] </style_prompt></p> <p>本記事は<strong>Geminiの出力をプロンプト工学で整理した業務ドラフト（未検証）</strong>です。</p> <h1 class="wp-block-heading">CI/CDパイプラインにおけるJSON/YAML統合管理と設定ファイル自動生成の堅牢化</h1> <h2 class="wp-block-heading">【導入と前提】</h2> <p>外部APIから取得したJSONメタデータを、Kubernetesやシステム設定用のYAMLへ変換・デプロイする工程を、jq/yqを駆使して堅牢に自動化します。</p> <p><strong>前提条件：</strong></p> <ul class="wp-block-list"> <li><p>OS: GNU/Linux (Ubuntu 22.04 LTS 以降推奨)</p></li> <li><p>ツール: <code>jq</code> (JSONプロセッサ), <code>yq</code> (mikefarah版 YAMLプロセッサ), <code>curl</code></p></li> </ul> <h2 class="wp-block-heading">【処理フローと設計】</h2> <div class="wp-block-merpress-mermaidjs diagram-source-mermaid"><pre class="mermaid"> graph TD A["外部ソース: JSON API"] -->|curl retry| B["一時ファイル保持"] B -->|jq: フィルタリング/検証| C["構造化JSON"] C -->|yq: フォーマット変換| D["正規YAML設定ファイル"] D -->|Atomic Write| E["システム反映/デプロイ"] E -->|trap| F["一時ファイルの削除"] </pre></div> <p>処理フローの核となるのは、データの整合性検証（jq）と構造変換（yq）の分離です。変換前にスキーマチェックを行うことで、不正な設定がシステムに波及することを防ぎます。</p> <h2 class="wp-block-heading">【実装：堅牢な自動化スクリプト】</h2> <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_JSON=$(mktemp /tmp/config_XXXXXX.json) TMP_YAML=$(mktemp /tmp/config_XXXXXX.yaml) # --- クリーンアップ処理 --- # 終了時（正常・異常問わず）に一時ファイルを削除 trap 'rm -f "$TMP_JSON" "$TMP_YAML"' EXIT echo "--- 1. データ取得 (Retry logic) ---" # -s: サイレントモード # -L: リダイレクト追跡 # --retry: ネットワークエラー時に3回再試行 curl -sL --retry 3 --retry-delay 2 "$SOURCE_URL" -o "$TMP_JSON" echo "--- 2. データの整合性検証 (jq) ---" # 入力が有効なJSONか、および必須フィールドが存在するか確認 if ! jq -e '.metadata.name' "$TMP_JSON" > /dev/null; then echo "Error: Invalid JSON structure or missing required fields." >&2 exit 1 fi echo "--- 3. JSONからYAMLへの変換 (yq) ---" # .specのみを抽出してYAML形式で出力 (-p: 入力形式, -o: 出力形式) yq -p=json -o=yaml '.spec' "$TMP_JSON" > "$TMP_YAML" echo "--- 4. 原子的な書き込み (Atomic update) ---" # ファイルの上書きによる不整合を防ぐため、mvで置換 sudo install -m 644 -o root -g root "$TMP_YAML" "$DEST_YAML" echo "Automation completed successfully." </pre> </div> <h3 class="wp-block-heading">systemd タイマーによる定期実行例</h3> <p>このスクリプトを <code>config-sync.sh</code> として、1時間ごとに実行する設定です。</p> <div class="codehilite"> <pre data-enlighter-language="generic"># /etc/systemd/system/config-sync.service [Unit] Description=Sync remote JSON to local YAML configuration [Service] Type=oneshot ExecStart=/usr/local/bin/config-sync.sh User=root # /etc/systemd/system/config-sync.timer [Unit] Description=Run config-sync every hour [Timer] OnCalendar=hourly Persistent=true [Install] WantedBy=timers.target </pre> </div> <h2 class="wp-block-heading">【検証と運用】</h2> <h3 class="wp-block-heading">1. 正常系の確認</h3> <p>生成されたYAMLが構文的に正しいか確認します。</p> <div class="codehilite"> <pre data-enlighter-language="generic"># yqを使用して構文チェック yq eval '.' /etc/app/config.yaml > /dev/null && echo "Valid YAML" # 差分の確認 diff /etc/app/config.yaml.old /etc/app/config.yaml || true </pre> </div> <h3 class="wp-block-heading">2. エラー時のログ確認</h3> <p><code>systemd</code> ユニットを介して実行している場合、標準出力・標準エラーは <code>journalctl</code> で追跡可能です。</p> <div class="codehilite"> <pre data-enlighter-language="generic"># ユニットの最新ログを表示 journalctl -u config-sync.service -f </pre> </div> <h2 class="wp-block-heading">【トラブルシューティングと落とし穴】</h2> <ol class="wp-block-list"> <li><p><strong>yq のバージョン互換性</strong>: Python版（kislyuk/yq）とGo版（mikefarah/yq）では引数の仕様が大きく異なります。本稿では主流の <strong>Go版</strong> を想定しています。</p></li> <li><p><strong>権限問題</strong>: <code>install</code> コマンドを使用する際、実行ユーザーに <code>sudo</code> 権限がないと失敗します。CI/CD環境では <code>NOPASSWD</code> 設定や適切なケーパビリティ付与を検討してください。</p></li> <li><p><strong>環境変数の露出</strong>: APIへの認証が必要な場合、<code>curl -H "Authorization: Bearer ${API_TOKEN}"</code> のように環境変数を使用しますが、デバッグ時に <code>set -x</code> を使うとトークンがログに出力されるリスクがあります。秘匿情報の扱いには注意してください。</p></li> <li><p><strong>ディスク容量</strong>: <code>/tmp</code> が一杯の場合、<code>mktemp</code> が失敗します。監視対象に含めるべきです。</p></li> </ol> <h2 class="wp-block-heading">【まとめ】</h2> <p>運用の冪等性を維持するための3つのポイント：</p> <ol class="wp-block-list"> <li><p><strong>Atomic Write（原子的な書き込み）</strong>: 設定ファイルを直接編集・追記せず、一時ファイルを作成してから <code>mv</code> や <code>install</code> で置換することで、不完全なファイルが読み込まれるリスクを排除する。</p></li> <li><p><strong>Schema Validation</strong>: 変換前に <code>jq</code> の <code>-e</code> オプション等で構造チェックを行い、異常なデータが入った時点で処理を中断（Fail-fast）させる。</p></li> <li><p><strong>Trap-based Cleanup</strong>: <code>trap</code> を用いて、異常終了時でも残骸ファイルを残さない設計を徹底し、次回実行時のノイズを排除する。</p></li> </ol>

graph TD
A["外部ソース: JSON API"] -->|curl retry| B["一時ファイル保持"]
B -->|jq: フィルタリング/検証| C["構造化JSON"]
C -->|yq: フォーマット変換| D["正規YAML設定ファイル"]
D -->|Atomic Write| E["システム反映/デプロイ"]
E -->|trap| F["一時ファイルの削除"]

#!/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_JSON=$(mktemp /tmp/config_XXXXXX.json)
TMP_YAML=$(mktemp /tmp/config_XXXXXX.yaml)

# --- クリーンアップ処理 ---


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

trap 'rm -f "$TMP_JSON" "$TMP_YAML"' EXIT

echo "--- 1. データ取得 (Retry logic) ---"

# -s: サイレントモード


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


# --retry: ネットワークエラー時に3回再試行

curl -sL --retry 3 --retry-delay 2 "$SOURCE_URL" -o "$TMP_JSON"

echo "--- 2. データの整合性検証 (jq) ---"

# 入力が有効なJSONか、および必須フィールドが存在するか確認

if ! jq -e '.metadata.name' "$TMP_JSON" > /dev/null; then
    echo "Error: Invalid JSON structure or missing required fields." >&2
    exit 1
fi

echo "--- 3. JSONからYAMLへの変換 (yq) ---"

# .specのみを抽出してYAML形式で出力 (-p: 入力形式, -o: 出力形式)

yq -p=json -o=yaml '.spec' "$TMP_JSON" > "$TMP_YAML"

echo "--- 4. 原子的な書き込み (Atomic update) ---"

# ファイルの上書きによる不整合を防ぐため、mvで置換

sudo install -m 644 -o root -g root "$TMP_YAML" "$DEST_YAML"

echo "Automation completed successfully."

# /etc/systemd/system/config-sync.service

[Unit]
Description=Sync remote JSON to local YAML configuration

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

# /etc/systemd/system/config-sync.timer

[Unit]
Description=Run config-sync every hour

[Timer]
OnCalendar=hourly
Persistent=true

[Install]
WantedBy=timers.target

# yqを使用して構文チェック

yq eval '.' /etc/app/config.yaml > /dev/null && echo "Valid YAML"

# 差分の確認

diff /etc/app/config.yaml.old /etc/app/config.yaml || true

# ユニットの最新ログを表示

journalctl -u config-sync.service -f