gcloud-compare

gcloud-compare は、gcloud ... --format=json で取得した Google Cloud リソースの JSON を比較し、人間が差分をレビューするためのローカル Web ツールです。

完全自動の OK / NG 判定では扱いにくい移行確認や環境差分レビューを想定しています。リソースの対応付け、環境固有値の正規化、フィールド単位の差分表示、OK / NG とコメントの記録、PDF レポート出力までを一画面で行えます。

主な機能

• expected.json と actual.json の比較
• $.name や $.metadata.name など任意の JSON path によるリソース対応付け
• 比較前のマッチング候補プレビュー
• YAML ルールによる揮発フィールドの除外
• 文字列または正規表現による環境差分の置換
• 全フィールドに対する OK / NG レビュー
• 完全一致フィールドの自動 OK
• フィールド単位のコメント入力
• リソース単位の折り畳み表示
• rules.yaml、review.json、テキストレポート、PDF レポートの出力

ディレクトリ構成

cmd/server          Go HTTP サーバのエントリポイント
internal/compare    比較、マッチング、正規化、レポート生成
internal/jsonpath   ルール指定用の最小 JSON path 実装
internal/rules      YAML ルールの読み書き
internal/server     Gin API ルート
web                 Next.js 製レビュー UI
samples             動作確認用のサンプル JSON とルール

必要なもの

• Go 1.24 以上
• Node.js 22 以上
• npm

クイックスタート

フロントエンドの依存関係をインストールします。

cd web
npm install
cd ..

バックエンド API を起動します。

make dev-api

別ターミナルでフロントエンドを起動します。

make dev-web

ブラウザで開きます。

http://localhost:3000

Next.js の /api/* は Go バックエンドの http://127.0.0.1:8080 にプロキシされます。

サンプルデータで試す

samples/ に動作確認用のファイルがあります。

• samples/expected.json
• samples/actual.json
• samples/rules.yaml

UI で 3 ファイルをアップロードし、マッチング候補を解析してから比較してください。

rules.yaml

例:

match:
  mode: name
  namePath: $.name
  normalize:
    - mode: regex
      pattern: ^(.+)-stg$
      value: $1

ignore:
  - $.updateTime
  - $.metadata.fingerprint

replace:
  - path: $.name
    mode: literal
    pattern: dev-project
    value: PROJECT
  - path: $.selfLink
    mode: regex
    pattern: projects/[^/]+
    value: projects/PROJECT

match

match.namePath は、expected と actual のリソースを対応付けるためのフィールドです。

match.normalize は対応付けキーだけを正規化します。比較対象の値そのものは変更しません。

ignore

ignore は、比較前に expected と actual の両方から指定 path を削除します。更新時刻、生成 ID、fingerprint など、今後もレビュー対象にしないフィールドに使います。

replace

replace は、比較前に指定 path の値を置換します。プロジェクト ID、リージョン、サービス名、-a / -b のような面差分など、環境差分として吸収したい値に使います。

レビューの流れ

1. expected、actual、rules をアップロードする
2. マッチング候補を解析する
3. 対応付けフィールドと必要な正規化ルールを選ぶ
4. 比較を実行する
5. レビューが必要なリソースを展開する
6. フィールドごとに OK / NG を設定し、必要ならコメントを書く
7. 継続的に許容する差分は ignore または replace ルールに追加する
8. 再比較する
9. ルールとレビュー結果を出力する

API

ヘルスチェック

GET /api/healthz

比較

POST /api/compare
Content-Type: application/json

{
  "expected": [],
  "actual": [],
  "rulesYaml": "match:\n  mode: name\n  namePath: $.name\n"
}

マッチング候補

POST /api/match-candidates
Content-Type: application/json

{
  "expected": [],
  "actual": []
}

開発

バックエンドのテスト:

go test ./...

フロントエンドのビルド:

cd web
npm run build

補足

• 現時点ではステートレスです。アップロードした JSON とレビュー判断は、出力しない限りブラウザセッション内だけに保持されます。
• PDF 出力はブラウザの印刷ダイアログを使います。出力先で「PDF に保存」を選んでください。
• レビューの OK と ignore ルールは別物です。OK は今回の確認結果であり、ignore は次回以降の比較対象から外すための恒久ルールです。