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

Tech

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

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

【導入と前提】 API等から取得したJSONデータをYAML形式の設定ファイルへ安全に自動変換・生成し、運用作業を効率化します。

  • OS: Linux (Ubuntu 22.04 LTS / RHEL 9 動作確認)

  • 必要ツール: bash (4.4+), jq (1.6+), yq (mikefarah/yq v4+), curl (7.68+)

【処理フローと設計】 リモートAPIまたはローカルから取得したJSON構造データを jq で抽出・加工し、yq を用いてYAMLに変換した上でターゲット設定ファイルへ安全（アトミック）に反映します。

graph TD
    A["外部API / JSONデータ"] -->|curl -f -s| B("一時JSONファイル")
    B -->|jq 抽出・フィルタ| C("整形済みJSON")
    C -->|yq eval -P| D("一時YAMLファイル")
    D -->|cmp -s 比較 & mv| E["本番設定ファイル .yaml"]

処理の過程で中間ファイルを安全に生成し、アトミック（不可分）にファイルを置き換えることで、生成途中の不完全なファイルが参照されるリスクを排除します。

【実装：堅牢な自動化スクリプト】 以下は、エラーハンドリング・クリーンアップ処理・差分適用を盛り込んだ自動生成スクリプトおよびsystemd連携例です。

#!/usr/bin/env bash

set -euo pipefail

# -----------------------------------------------------------------------------


# 設定ファイル自動更新スクリプト


# -----------------------------------------------------------------------------

# スクリプトの絶対パスと各種定数の定義

readonly TARGET_CONFIG="/etc/app/config.yaml"
readonly API_URL="https://api.internal.example.com/v1/config"
readonly SECURE_TOKEN="${CONFIG_API_TOKEN:-}"

# 作業用一時ディレクトリの安全な作成

TMP_DIR=$(mktemp -d "/tmp/config_gen.XXXXXX")

# スクリプト終了時に必ず一時ディレクトリを削除するトラップを設定

cleanup() {
    rm -rf "${TMP_DIR}"
}
trap cleanup EXIT INT TERM

# 依存コマンドの存在チェック

for cmd in jq yq curl cmp chmod; do
    if ! command -v "${cmd}" &>/dev/null; then
        echo "Error: 必須コマンド '${cmd}' が見つかりません。" >&2
        exit 1
    fi
done

# 1. APIからJSONを取得 (-s: 静音, -S: エラー表示, -f: HTTPエラー時失敗, --retry: 失敗時リトライ)

TMP_JSON="${TMP_DIR}/raw.json"
curl -sSfL \
    --retry 3 \
    --retry-delay 2 \
    --max-time 10 \
    -H "Authorization: Bearer ${SECURE_TOKEN}" \
    "${API_URL}" \
    -o "${TMP_JSON}"

# 2. jqによるJSON構造の検証とフィルタリング (-e: 条件不一致時に終了ステータス1を返す)

TMP_FILTERED_JSON="${TMP_DIR}/filtered.json"
jq -e '.data | {server: .server_name, port: .listen_port, features: .enabled_features}' \
    "${TMP_JSON}" > "${TMP_FILTERED_JSON}"

# 3. yqを用いたJSONからYAMLへの変換 (-P / --prettyPrint: 整形出力)

TMP_YAML="${TMP_DIR}/output.yaml"
yq eval -P "${TMP_FILTERED_JSON}" > "${TMP_YAML}"

# パーミッション設定 (600: 所有者のみ読み書き可能)

chmod 600 "${TMP_YAML}"

# 4. アトミックな更新（変更がある場合のみ置き換え）

if [ -f "${TARGET_CONFIG}" ] && cmp -s "${TARGET_CONFIG}" "${TMP_YAML}"; then
    echo "Info: 変更はありません。設定ファイルは最新です。"
else
    echo "Info: 設定ファイルの変更を検知しました。更新を適用します。"
    mkdir -p "$(dirname "${TARGET_CONFIG}")"

    # アトミックなファイル置換

    mv "${TMP_YAML}" "${TARGET_CONFIG}"
    echo "Success: 設定ファイルを更新しました: ${TARGET_CONFIG}"
fi

（任意）systemd ユニット構成例

定期実行および失敗時の自動ログ収集を行うための設定例です。

/etc/systemd/system/config-updater.service:

[Unit]
Description=App Configuration Generator Service
After=network-online.target
Wants=network-online.target

[Service]
Type=oneshot
ExecStart=/usr/local/bin/generate-config.sh
Environment="CONFIG_API_TOKEN=your_token_here"
User=root
Group=root

# サービス保護設定

ProtectSystem=full
PrivateTmp=true

/etc/systemd/system/config-updater.timer:

[Unit]
Description=Run Config Generator Daily

[Timer]
OnCalendar=*-*-* 03:00:00
Persistent=true

[Install]
WantedBy=timers.target

【検証と運用】 スクリプトおよび変換プロセスの実行確認手順です。

  1. スクリプトの手動実行テスト

    # 環境変数を渡して正常終了（終了ステータス 0）するか確認

CONFIG_API_TOKEN="test-token" sudo -E /usr/local/bin/generate-config.sh

  2. 生成ファイルの検証

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

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

  3. systemd タイマーの確認とログ照会

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

systemctl list-timers config-updater.timer

# 実行ログの確認

journalctl -u config-updater.service -n 50 --no-pager

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

  • yqコマンドの実装相違 Python実装の yq (PyYAMLベース) と Go言語実装の mikefarah/yq では構文が大幅に異なります。本記事では普及している Go言語実装 (v4+) を前提としています。yq --version でバージョン表記を確認してください。

  • 一時ファイルの消し忘れとセキュリティリスク mktemp で作成した一時ファイルに機密情報（APIキーやパスワード等）が含まれる場合、エラー終了時にファイルが残ると脆弱性になります。必ず trap cleanup EXIT INT TERM を定義し、スクリプト停止時に自動破棄される構造にしてください。

  • 環境変数の漏洩防止 set -x（デバッグ実行）を有効にすると、curl のヘッダーに含まれるトークンや環境変数が標準エラー出力（ログ）へプレーンテキストで記録されます。本番運用スクリプト内では set -x の常用を避け、トークン取得ログを隠蔽してください。

  • sudo実行時の環境変数引き継ぎ失敗 sudo でスクリプトを実行する際、セキュリティ設定（env_reset）により呼び出し元の環境変数 CONFIG_API_TOKEN が破棄される場合があります。必要に応じて sudo -E を使用するか、systemd の EnvironmentFile / Secrets 管理メカニズムを利用してください。

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

  1. アトミック更新の徹底：設定ファイルを直接書き換えず、一時ファイル生成後に cmp で差分確認のうえ mv 置換を行う。

  2. strictモードとクリーンアップの自動化：set -euo pipefail と trap により、異常検知時の早期停止と一時リソースの完全消去を保障する。

  3. データ構造の事前バリデーション：jq -e などを挟み、APIから不正なJSONや空データが返却された際に不完全なYAMLが生成されない防壁を築く。

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

コメント

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