k8s-yaml-generator

Kubernetes YAML ジェネレーター

決定的な手順、範囲を限定した CRD 調査、完全なリソース出力に対する必須の検証を行って、Kubernetes マニフェストを生成します。

使用する状況

ユーザーから Kubernetes YAML の作成または更新を依頼された場合に、このスキルを使用します。たとえば、次のような依頼です。

• 「アプリ用の Deployment と Service のマニフェストを生成してください。」
• 「Argo CD の Application CRD を作成してください。」
• 「PVC テンプレートを含む StatefulSet を作成してください。」
• 「ベストプラクティスに沿った、本番環境向けの Kubernetes YAML を作成してください。」

検証のみの依頼には、このスキルを使用しないでください。検証のみの場合は、k8s-yaml-validator を使用してください。

実行モデル

規範的なキーワード：

• MUST：必須です
• SHOULD：ユーザーから別の指定がない限り、既定の動作です
• MAY：任意です

決定的な手順：

1. 依頼内容と、パスおよびレンダリングの妥当性を事前確認します。
2. 必要最小限の入力情報を収集します。
3. CRD 参照を解決します（CRD またはカスタム API が関係する場合に限り、範囲を限定したワークフローを実行します）。
4. 基本的な品質チェックを行いながら YAML を生成します。
5. 必須の検証を実行します（ツールが利用できない場合は、文書化された代替手順を実行します）。
6. YAML と、明示的な検証レポートおよび前提条件を提示します。

環境上の制約によりいずれかの手順を実行できない場合は、その手順の代替処理を実行して続行します。

1) 事前確認

生成前に、次の項目を確認します。

• 出力が完全なマニフェスト一式か、スニペットのみかを確認します。
• 指定されている場合は、対象の Kubernetes バージョンを確認します。
• 参照されているローカルファイルのパスが、使用前に存在することを確認します。
• 該当する場合は、リソース名を DNS-1123 互換の形式に正規化します。

事前確認の停止条件：

• 必須の基本情報（リソースの種類、Pod ベースのリソースの場合はワークロードのイメージ、または CRD の kind/apiVersion）が不足している場合は、まずそれらを確認します。

2) 必須入力情報の収集

次の情報を収集します。

• リソースの種類（Deployment、Service、ConfigMap、CRD の kind など）
• apiVersion と kind
• Namespace とスコープに関する要件
• ポート、レプリカ数、イメージ、プローブ、ストレージ、シークレット／設定の要件
• 環境に関する前提（dev/staging/prod）
• CRD の場合：プロジェクト名と、判明していれば対象の CRD バージョン

安全な既定値（出力で明示します）：

• Namespace：default（Namespace スコープのリソース）
• Deployment のレプリカ数：2
• Service の種類：ClusterIP
• イメージのプルポリシー：IfNotPresent（ユーザーが強制プルを必要としている場合を除く）

3) CRD 検索ワークフロー（範囲限定）

Kubernetes 組み込みグループ以外のカスタム API に限り、この手順を実行します。

3.1 CRD の対象を特定

次の項目を抽出します。

• API グループ、バージョン、kind（例：argoproj.io/v1alpha1、Application）
• 指定された製品／バージョン（例：Argo CD v2.9.x）

3.2 Context7 の優先手順

適切な Context7 ツールとペイロードを使用します。

1. mcp__context7__resolve-library-id
2. mcp__context7__query-docs

ペイロードの例：

Tool: mcp__context7__resolve-library-id
libraryName: "argo-cd"
query: "Find Argo CD documentation for Application CRD schema compatibility"

Tool: mcp__context7__query-docs
libraryId: "/argoproj/argo-cd/v2.9.0"
query: "Application CRD required spec fields for apiVersion argoproj.io/v1alpha1 with minimal valid example"

選択ルール：

• プロジェクト名／ライブラリ名が完全に一致するものを優先します。
• ユーザーがバージョンを指定している場合は、バージョン付きの libraryId を優先します。
• それ以外の場合は、バージョンなしの ID を使用し、バージョンが不確かなことを明記します。

3.3 上限と停止条件

際限のない再試行を防ぐため、検索の範囲を制限します。

• resolve-library-id：最大 2 回（優先する名前で 1 回、別名で 1 回）。
• query-docs：焦点を絞ったクエリを合計最大 3 回。
• Web 検索へのフォールバック：バージョンを指定した検索を最大 2 回。

次のすべてを満たした時点で、早期に終了します。

• 必須の CRD フィールドを特定できている。
• 信頼できる例を少なくとも 1 つ確認できている。
• バージョンの互換性が判明しているか、不明であることを明示している。

上限に達した場合の強制終了：

• ソースで確認できたフィールドのみを生成します。
• 残りのフィールドには Needs confirmation と記載します。
• 残存リスクを報告し、次のいずれかを依頼します。
  • 正確な CRD ドキュメントの URL、または
  • クラスターのイントロスペクション出力（利用可能な場合は、たとえば kubectl explain <kind>.spec）。

3.4 フォールバックの順序

次の順序で使用します。

1. Context7（resolve-library-id -> query-docs）
2. Web 検索による公式プロジェクトドキュメント
3. クラスター内のイントロスペクション（クラスターにアクセスできる場合は kubectl explain）

いずれも利用できない場合は、最小限のドラフトを提示して、ドラフトであることを明確に示します。また、CRD の完全な正確性を保証する表現は使用しません。

4) YAML 生成ルール

次のチェックを適用します。

• 明示的で、非推奨ではない API バージョンを使用します。
• 関連するリソース間で、一貫したラベル（app.kubernetes.io/*）を含めます。
• 名前空間スコープのリソースには、名前空間を指定します。
• ユーザーが指定を省略する場合を除き、Pod ワークロードにリソースのリクエストと制限を追加します。
• 該当する場合、長時間稼働するサービスに readiness/liveness プローブを追加します。
• デフォルトで root 実行を避けるため、securityContext を使用します。
• 複数リソースの順序は、依存関係に問題が生じないようにします（たとえば、Deployment の参照先となる ConfigMap を先に配置します）。

最小限のラベル基準：

labels:
  app.kubernetes.io/name: myapp
  app.kubernetes.io/instance: myapp-prod
  app.kubernetes.io/part-of: myplatform
  app.kubernetes.io/managed-by: codex

5) 必須の検証と代替手段

マニフェスト全体を生成する場合、検証は必須です。

優先手順：

• k8s-yaml-validator を呼び出します。
• ブロッキング問題がなくなるまで、「修正 → 再検証」を繰り返します。

各検証後に必ず報告する項目：

• Validation mode：k8s-yaml-validator | script fallback | manual fallback
• Syntax：pass/fail
• Schema：pass/fail/partial
• CRD check：pass/fail/partial
• Dry-run：server/client/skipped
• Blocking issues remaining：yes/no

代替手段 A：バリデータースキルを利用できない場合

次のコマンドを直接実行します。

bash devops-skills-plugin/skills/k8s-yaml-validator/scripts/setup_tools.sh
yamllint -c devops-skills-plugin/skills/k8s-yaml-validator/assets/.yamllint <file.yaml>
kubeconform -schema-location default -strict -ignore-missing-schemas -summary <file.yaml>
server_out="$(mktemp)"
client_out="$(mktemp)"
trap 'rm -f "$server_out" "$client_out"' EXIT

if kubectl apply --dry-run=server -f <file.yaml> >"$server_out" 2>&1; then
  echo "server_validation=passed"
elif grep -Eqi "connection refused|no such host|i/o timeout|tls handshake timeout|unable to connect to the server|no configuration has been provided|the server doesn't have a resource type" "$server_out"; then
  echo "server_validation=skipped"
  if kubectl apply --dry-run=client -f <file.yaml> >"$client_out" 2>&1; then
    echo "client_validation=passed"
  else
    echo "client_validation=failed"
    cat "$client_out"
    exit 1
  fi
else
  echo "server_validation=failed"
  cat "$server_out"
  exit 1
fi

代替手段 B：ローカルツールを一部利用できない場合

• 利用可能なチェックを実行します。
• スキップしたチェックを明示的に記録します。
• スキップしたチェックごとに、残存リスクを追加します。

代替手段 C：検証に繰り返し失敗する場合

• 修正・再検証のサイクルは最大 3 回です。
• それでも失敗する場合は処理を停止し、次を返します。
  • 現在の YAML
  • 失敗したエラーの正確な内容
  • 処理を進めるためにユーザーに必要な最小限の判断・入力

検証の例外：

• スニペットのみ、またはドキュメントのみの依頼では、検証全体を省略してもかまいません。ただし、出力に Validation status: Skipped (reason) を必ず記載します。

6) 納品要件

最終出力には、次の内容を必ず含めます。

1. 生成した YAML。
2. 生成した内容（リソース一覧、名前空間／スコープ）。
3. 指定の形式での検証レポート。
4. 使用した前提とデフォルト設定。
5. 使用した参照情報：
   • 使用した Context7 の ID／検索クエリ（CRD 用）
   • 使用した外部ドキュメント／検索
   • 省略・未確認の項目とその影響

次に実行するコマンドの例：

kubectl apply -f <filename>.yaml
kubectl get <resource-type> <name> -n <namespace>
kubectl describe <resource-type> <name> -n <namespace>

7) 標準的な実行例

例 A：組み込みリソース（Deployment + Service）

1. アプリのイメージ、ポート、レプリカ数、名前空間を確認します。
2. 一貫したラベルとセレクターを使用して Deployment と Service を生成します。
3. k8s-yaml-validator で検証します。
4. YAML、検証レポート、前提を返します。

例 B：CRD リソース（Argo CD Application）

1. argoproj.io/v1alpha1 と Application を特定します。
2. 範囲を限定した Context7 検索を実行します（resolve-library-id の後に query-docs）。
3. 必要に応じて、範囲を限定したウェブ検索に切り替えます。
4. 検証済みのフィールドのみを使用して CRD YAML を生成します。
5. 検証し、部分的な確認がある場合は報告したうえで、残存リスクを返します。

8) 完了の定義

該当するすべてのチェックに合格した場合にのみ、実行は完了です。

• トリガーとなったユースケースが正しい（検証のみではなく生成である）。
• 必須の入力が揃っているか、明示的な前提が文書化されている。
• CRD の検索が、上限と停止条件の範囲内で行われている。
• ツール名とコマンドパスが有効で、一貫している。
• マニフェスト全体が検証されている（または、残存リスクを記載した代替手順が文書化されている）。
• 最終回答に YAML、検証レポート、前提、参照情報が含まれている。