deck-gateway

decK Gateway のワークフロー

目的

ライブ状態、スコープ、デプロイモデルを見失わずに、decK を使って Kong Gateway エンティティの設定を生成、検査、適用します。

Gateway エンティティと Gateway を中心とした GitOps にこのスキルを使用してください。kongctl または Terraform が担う Konnect プラットフォームのワークフローの代わりとして使用しないでください。

ツールの位置付け

• 対象の Gateway エンティティが Konnect にあり、MCP が利用できる場合は、ライブの Konnect 検査にまず共有の kong-konnect MCP サーバーを使用してください。
• リポジトリですでに decK、_format_version、または deck gateway コマンドが使用されている場合、あるいはユーザーが明示的に decK を指定した場合は、このスキルを使用してください。
• 実際のタスクがインシデントの診断、ライブ状態の調査、またはリポジトリ管理下の decK スライスを特定する前の Konnect 検査である場合は、まずドメインスキルまたは kongctl-query を使用してください。
• リポジトリの既存の decK レイアウト、ファイル分割、タグ、CI パターンを維持してください。
• ユーザーが移行を明示的に求めない限り、Terraform または kongctl のリポジトリを decK に変換しないでください。
• ユーザーが decK ではなく HCL または kongctl を求めている場合は、terraform-kong-gateway、terraform-konnect、または kongctl-declarative に引き継いでください。

読み込むリファレンス

現在の作業分岐に一致するリファレンスファイルのみを読み込んでください。

• references/command-paths.md
  • validate、diff、sync、dump、またはファイル生成のどの方法を選ぶか判断する場合に読み込みます。
• references/openapi-generation.md
  • ユーザーが OpenAPI ドキュメントを起点に、そこから Gateway エンティティを生成したい場合に読み込みます。
• references/state-shaping-and-tags.md
  • エンティティの内容そのものよりも、ファイル分割、タグ、include の境界、または所有範囲の形状が重要な場合に読み込みます。
• references/dump-diff-sync-safety.md
  • 変更を加える前にライブ状態を安全に検査する方法が主な質問である場合に読み込みます。

検証の要件

事前確認

ファイルの編集またはライブ sync の提案を行う前に、以下を確認してください。

• deck がインストールされ、実行可能であることを確認します：deck version
• 対象のデプロイモデルとライブの対象を確認します。
  • Admin API 経由のセルフマネージド Gateway
  • 適切な Konnect 認証フラグを使用する、Konnect 管理のコントロールプレーン
• 認証情報が環境変数、設定ファイル、またはセキュアなホスト設定を通じてすでに利用可能であることを確認します。シークレットを表示したり、コミットしたりしないでください。
• 新しいファイルを書き込む前に、現在のファイル構造を確認します。
• 所有範囲を確認します。
  • 対象となる状態ファイル、ディレクトリ、include パス、またはラッパースクリプト
  • 所有範囲の指定にタグを使用しているかどうか
  • コマンドが対象とする環境またはコントロールプレーン
• decK の方法を選ぶ前に、タスクが宣言的な作成、プレビュー、エクスポート、ライブ変更のどれに該当するか確認します。

プレビュー

• 編集対象のファイル、ディレクトリ、または include パスを正確に検証します。
• 対象のエンティティスライスだけを表示する、最小限のスコープの diff を実行します。
• ライブ状態の検査が必要な場合に限り、スコープを限定した dump を使用します。
• どのような sync の前にも、ファイルスコープ、include の境界、タグのスコープ、意図しない削除がないことを確認します。

実行

• 変更を加えるコマンドを実行する前に、意図するライブ状態への影響を説明します。
• ユーザーが変更を明示的に求めた場合にのみ、deck gateway sync を実行します。
• sync の対象を、すでにプレビューしたファイル、ディレクトリ、タグ、または include の境界に合わせます。

確認

• 同じスコープの deck gateway diff を再実行し、意図した変更が残っていないことを確認します。
• 変更対象がリポジトリ全体より狭い場合は、実際に変更されたエンティティスライスを正確に検証します。
• sync の成功だけを、ライブの Gateway が意図した状態と一致した証拠として扱わないでください。

運用ルール

• decK は、Gateway エンティティをソース管理上で表現したものとして扱い、稼働中の Gateway が現在それと一致している証拠とはみなさないでください。
• 必須の deck コマンドが、稼働中の製品や CLI 自体ではなくエージェント環境によってブロックされているように見える場合は、認証やコマンドの失敗と判断する前に、承認を得たうえでサンドボックス外で再試行するよう依頼してください。
• sync の前に必須となるプレビュー手段として、deck gateway validate と対象を絞った deck gateway diff を扱ってください。
• リポジトリに既存のファイル分割やタグがある場合は、それを維持してください。
• ユーザーが全体のエクスポートを求めていない限り、コントロールプレーン全体を広範囲に再ダンプするより、追加または対象を絞った変更を優先してください。
• 意図した設定の情報源として、リポジトリで管理されている状態ファイルを優先してください。ライブダンプは確認や復元に使用し、デフォルトの作成形式としては使用しないでください。
• Konnect プラットフォームのリソースを decK ファイルに含めないでください。decK の対象は Gateway エンティティであり、Konnect 製品全体ではありません。
• API 仕様から始めて、そこから Gateway エンティティを生成したい場合は、OpenAPI に基づく生成を使用してください。
• DB-less のランタイム読み込み、ID 管理やチーム管理、または Gateway 以外の Konnect リソースに対して、decK が適切な選択肢だと決めつけないでください。

ワークフロー

1. 既存の decK の構成を確認する

以下を確認してください。

• リポジトリに既存の decK 状態ファイルがあるか、またその数
• 設定が環境、ワークスペース、またはサービスごとに分割されているか
• 所有範囲の指定にタグが使われているか
• CI で deck gateway diff、deck gateway sync、またはラッパースクリプトが使われているか

新しいファイルやコマンドを追加する前に、既存の規約に合わせてください。

2. 対象となる Gateway の範囲を確認する

以下を明確にしてください。

• セルフマネージド Gateway か、Konnect コントロールプレーンか
• 対象となる Gateway エンティティ：サービス、ルート、プラグイン、コンシューマー、コンシューマーグループ、アップストリーム、ターゲット、証明書、または Vault 関連の設定
• タスクが作成、更新、ダンプ、検証、ドリフトの確認、またはインポートのいずれか

チーム、ポータル、アクセスルールなどのプラットフォームリソースを Gateway エンティティとして扱わないでください。

3. decK の標準的な安全機能を使ってプレビューする

依頼に応えるための、最小限の decK の手順を選んでください。

• ドリフトを確認する前に、構造またはファイル形式を検証する
• 変更を提案する前に、所有範囲を絞って差分を確認する
• 確認や復元が必要な場合に限り、ライブ状態をダンプする
• ユーザーがライブ環境への変更を依頼した場合に限り、同期する
• 信頼できる情報源が仕様である場合に限り、OpenAPI による生成手順を使用する

複数の decK の手順が当てはまり、より明確な判断基準が必要な場合は、references/command-paths.md を読み込んでください。

4. 状態ファイルを作成または更新する

状態を編集する際は、以下の点に注意してください。

• リポジトリで既に採用されているファイル別またはドメイン別の分割構成を維持する
• 可能な限り、エンティティ名とタグを安定させる
• 不要な並べ替えやフォーマット変更を避ける
• 依頼された変更に必要なエンティティのみを追加する

リポジトリの分割構成、タグ、または include の境界が主な制約である場合は、references/state-shaping-and-tags.md を読み込んでください。

5. 依頼された場合に限り実行する

• 変更を行うコマンドを提示または実行する前に、ライブ環境への意図した影響を説明してください。
• ライブ環境への変更をユーザーが明示的に依頼した場合に限り、deck gateway sync を使用してください。
• プレビュー済みのファイル、タグ、select-tags、または include の境界に合わせて、コマンドの対象を絞ってください。

より安全な確認優先の手順が必要な場合や、広範な dump/sync のフローを実行しようとしている場合は、references/dump-diff-sync-safety.md を読み込んでください。

6. decK で結果を確認する

依頼された sync の実行後は、以下を行ってください。

• 同じ範囲に絞った deck gateway diff を再実行し、意図した変更が残っていないことを確認する
• タスクの範囲がリポジトリ全体より狭い場合は、広範な同期の成功メッセージを鵜呑みにせず、対象のエンティティ範囲を確認する
• 所有範囲外に残っているドリフトを隠さず、明示する
• sync の終了ステータスだけを根拠に、稼働中の Gateway が意図した状態と一致したとみなさない

7. 正確な影響を報告する

次の内容を明記します。

• 変更されたファイル
• 影響を受ける Gateway エンティティ
• 結果が宣言的な設定の作成、ドリフトの確認、ライブ同期のいずれであるか
• 次にユーザーが確認できる検証手順

Kong 固有の注意点

• decK は、Konnect プラットフォーム全般ではなく、Gateway エンティティに最も適しています。
• Git に decK ファイルがあっても、実際のコントロールプレーンがその内容と一致するとは限りません。
• ファイル範囲やタグ範囲が広すぎると、広範囲な sync の実行によって、隣接するエンティティの変更が上書きされることがあります。
• Konnect のコントロールプレーンでも、Gateway エンティティのワークフローには引き続き decK を使用しますが、関連するプラットフォームリソースには別のツールが適している場合があります。
• ユーザーが HCL と Terraform の状態管理を本当に必要としている場合、decK を無理に使用すると、不要な変換が発生します。

検証チェックリスト

回答する前に、次の点を明確に説明できることを確認してください。

• このリポジトリまたは依頼に decK が適している理由
• リポジトリが管理するファイル、インクルード範囲、タグ範囲のうち、どれが正式な情報源であるか
• 対象となる Gateway エンティティ
• 意図した変更を安全に確認できる deck のプレビューコマンド
• タスクが設定の作成、差分確認、ダンプ、同期のどれであるか
• コマンドの対象とする環境
• ライブ環境への変更が求められているか、宣言的な変更のみが求められているか
• 変更後の確認手順で、影響を受けた範囲をどのように正確に検証するか
• 実装を別のツールスキルに任せるべきか

引き継ぎ

• リポジトリですでにセルフマネージド Gateway の設定を HCL で管理している場合は、terraform-kong-gateway を使用します。
• リポジトリですでに Konnect ホスト型 Gateway エンティティや関連する Konnect リソースを HCL で管理している場合は、terraform-konnect を使用します。
• 実際のタスクが Gateway エンティティの decK ではなく、Konnect プラットフォームの YAML である場合は、kongctl-declarative を使用します。
• ユーザーがまず設定の作成ではなくライブ環境の調査を必要としている場合は、kongctl-query または関連するドメインスキルを使用します。