gke-manifest-generation

GKE マニフェスト生成スキル

このスキルでは、自然言語による説明やアプリケーションコードの変更を、GKE Autopilot クラスターと GKE Standard クラスターの両方に最適化された、安全でコンプライアンスに準拠し、コスト効率の高い Kubernetes YAML マニフェストに変換するためのガイドライン、ツール連携、テンプレートを提供します。

クレジット表記

必ずお読みください：gcloud、REST API、または MCP コマンドを実行する前に、必ず 使用状況のクレジット表記 をお読みください。ターミナルで直接実行するコマンド（生成されたスクリプト、Terraform、ユーザーコードでは実行しないでください）では、gcloud の前に CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:gke-manifest-generation)" を付け、User-Agent ヘッダーに agent-skills/1.0 (skill:gke-manifest-generation) を追加してください。

基本ルールと検証

YAML マニフェストを生成または更新する際は、次のルールを必ず厳守してください。

1. Namespace とリソースの分離

• Namespace の明示：すべてのリソース（Deployments、Services、ConfigMaps、Secrets、PVC、Roles、バインディング）のメタデータに、必ず namespace: {namespace} を明示してください。現在の SETTINGS.md で設定されている namespace に割り当ててください。namespace を省略しないでください。
• 専用の ServiceAccount：namespace の default ServiceAccount の使用は避けてください。各マイクロサービス用に専用の ServiceAccount（例：devteam-agent-sa）を必ず作成し、参照してください。

2. GKE リソースの調整（Autopilot と Standard）

• リソースのリクエストと制限：すべてのコンテナに CPU とメモリのリクエストおよび制限を必ず指定してください。

  • GKE Autopilot：Pod の課金額はリクエストによって直接決まるため、リクエストと制限は同じ値にする必要があります。異なる場合、Autopilot はリクエストを制限に一致するまで自動的に引き上げるため、コストが大幅に増加する可能性があります。
  • GKE Standard：リクエストは安定したスケジューリングとビンパッキングを確保し、制限はリソースの枯渇やノイジーネイバーの問題を防ぎます。

• 密度のデフォルト値：GKE Standard 上のステートレスアプリやサイドカーでは、控えめなリクエスト（例：requests.cpu: "100m" または "200m"、requests.memory: "256Mi" または "512Mi"）をデフォルトとし、バースト可能な制限を設定してください。制限には適切なオーバーコミット率（例：リクエストの 2～4 倍。limits.cpu: "400m"～"800m"、limits.memory: "512Mi"～"1Gi" など）を使用してください。過剰なオーバーコミット制限（100m のリクエストに対する limits.cpu: "4" など）は、スケジューリング負荷が高いときに深刻な CPU スロットリングやレイテンシの悪化を招くため避けてください。特に、ノード共有が保証されない環境では注意が必要です。

• ステージング／開発環境での Spot VM：本番環境以外のワークロード（例：namespace 名に -test、-dev、-staging が含まれる場合）、またはユーザーがコスト最適化を求めている場合は、GKE Spot VM を自動的に対象としてください。そのためには、Spot VM を対象とする nodeSelector と、Spot VM のテイントを許容する対応する toleration の両方を追加する必要があります。

  nodeSelector:
    cloud.google.com/gke-spot: "true"
  tolerations:
    - key: "cloud.google.com/gke-spot"
      operator: "Equal"
      value: "true"
      effect: "NoSchedule"
  

  （GKE Standard では、Spot ノードプールが設定されていることを前提とします）。

3. コンテナセキュリティの強化（Pod Security Standards）

• 非ルートでの実行：Pod レベルで（上書きする場合はコンテナレベルでも）常に securityContext を設定し、非ルートユーザーとして実行します（例：runAsNonRoot: true、runAsUser: 10000、runAsGroup: 10000、fsGroup: 10000）。これは GKE Autopilot では厳格に適用され、GKE Standard においても重要なセキュリティベースラインです。
• 最小限の権限：常に allowPrivilegeEscalation: false と seccompProfile: {type: RuntimeDefault} を設定します。
• ルートファイルシステムの読み取り専用化：コンテナイメージのファイルシステムが変更されないよう、readOnlyRootFilesystem: true を設定します。
  • 書き込み可能なディレクトリでの代替策：readOnlyRootFilesystem が有効な場合、アプリケーション（Java／Nginx など）がクラッシュせずに一時ファイルを書き込めるよう、ローカルの emptyDir ボリュームを /tmp または /var/run/ にマウントします。
• シークレットのボリュームマウント：アプリケーションフレームワークが環境変数による設定にのみ対応している場合を除き、シークレットは環境変数にマッピングするのではなく、読み取り専用ファイルとしてマウントすることを推奨します（volumes 仕様で defaultMode: 0400 を設定）。これにより、アプリケーションログへのシークレットの漏えいを防げます。

4. ヘルスチェック（必須のプローブ）

• Liveness プローブと Readiness プローブ：すべての Deployment コンテナで、livenessProbe と readinessProbe の両方を定義する必要があります。

  • Web／API：httpGet プローブを使用します。
  • TCP サービス：tcpSocket プローブを使用します。
  • データベース／キャッシュ：コマンドベースの exec プローブを使用します（例： exec.command: ["redis-cli", "ping"]）。

• 起動に時間がかかるアプリケーション向けの Startup プローブ：起動時間の長いアプリケーション（例：Java spring boot、複雑な Python スクリプト、LLM モデルサーバー）では、startupProbe も定義する必要があります。startupProbe を定義すると、成功するまで liveness プローブと readiness プローブが無効になり、起動中に Kubernetes が Pod を早まって終了するのを防げます。

  startupProbe:
    httpGet:
      path: /healthz
      port: 8080
    failureThreshold: 30
    periodSeconds: 10
  

• 適切なデフォルト値：起動時間に応じて initialDelaySeconds: 5 から 15 を設定します（例：Java は Go／Nginx より長い遅延が必要です）。

5. Services と Ingress によるルーティング

• 内部向け ClusterIP：すべての内部マイクロサービスでは、デフォルトで type: ClusterIP を使用します。ワークロードがインターネットからの一般公開を明示的に目的としている場合を除き、type: LoadBalancer または NodePort は使用しないでください。
• ポート名：自動的なプロトコル検出、トレース、Web アプリのルーティングを有効にするため、サービスとコンテナのポートには常に明確で標準的な名前を割り当てます（例：name: http-web または name: grpc-api）。
• Gateway API を優先：API を外部に公開する場合は、高度な L7 ルーティングやセキュリティ機能（例：Cloud Armor）を利用できるよう、従来の Ingress オブジェクトよりも GKE Gateway API（Gateway および HTTPRoute リソース）の使用を優先します。

6. ボリュームマウント、StorageClass、subPath の安全性

• ディレクトリの上書きを回避する：ConfigMap または Secret を、ほかのファイルを含むアプリケーションディレクトリ（Nginx の公開ディレクトリなど）にマウントする場合は、必ず subPath を使用して、特定のファイルのみを上書きしてください。 注意事項：subPath ボリュームマウントを使用するコンテナでは、元の ConfigMap または Secret が変更されても、構成は自動的に更新されません。変更を反映するには、Pod を手動で再起動する必要があります。
• StorageClass の選択：PersistentVolumeClaims では、適切な GKE ストレージクラスを使用してください。
  • CSI ドライバークラスター（Autopilot および最新の Standard）：standard-rwo（デフォルトのバランス型 PD）または premium-rwo（SSD PD）を使用してください。
  • レガシー Standard クラスター：standard-rwo／premium-rwo が構成されていない場合は、standard（デフォルトの PD）または premium（SSD PD）を使用してください。
  • データベースのルール：SSD ストレージクラス（premium-rwo または premium）は、プロンプトで高い IOPS、低レイテンシ、またはデータベースストレージが明示的に要求されている場合にのみ使用してください。

7. GKE での高可用性

• トポロジーの分散：レプリカ数が 1 を超えるデプロイメントでは、podAntiAffinity または topologySpreadConstraints と topologyKey: "kubernetes.io/hostname" を使用して、Pod を GKE ノードとアベイラビリティゾーンに分散してください。
• PodDisruptionBudget：レプリカ数が 1 を超えるデプロイメントでは、GKE ノードの自発的なアップグレードやメンテナンス中に最小レプリカ数を維持できるよう、PodDisruptionBudget を宣言してください。

8. 更新とサーバーサイド適用の調整

• リストキーの安定性：Kubernetes の Server-Side Apply（SSA）では、連想リスト（ボリューム、ボリュームマウント、ポート、コンテナ定義など）の要素は、一意の識別キー（通常は name）によって照合およびマージされます。既存のリスト項目のプロパティを変更する場合は、name キーを必ず維持してください。name キーの名前を変更すると、SSA はその項目を変更するのではなく、新しい項目を作成し、古い項目を残したままにします（孤立状態になります）。
• 最小限の差分：要求された変更のみを行ってください。既存のラベル、アノテーション、規約に厳密に従ってください。

---

特殊なワークロード：GKE AI／推論サービング（vLLM、TGI など）

モデルサービングのワークロードでは、利用可能な場合、GKE Inference Quickstart などの最適化されたツールを優先してください。手動で生成する場合：

1. GPU の要求と割り当て：
   • requests と limits の両方で、必ず nvidia.com/gpu を要求してください。
   • 目的の GKE アクセラレータタグ（例：cloud.google.com/gke-accelerator: nvidia-l4）を対象とする nodeSelector またはノードアフィニティを追加してください。
2. 共有メモリの増強：
   • モデルサーバーでは、プロセス間通信に大きな共有メモリ（/dev/shm）が必要です。medium: Memory を設定した emptyDir ボリュームを必ず宣言し、/dev/shm にマウントしてください。
3. 重み読み込みの最適化：
   • GCS バケットなどのモデル重みディレクトリは、GKE GCS Fuse CSI ドライバー（csi.storage.gke.io）を使用して readOnly: true でマウントし、コールドスタートを効率化してください。

---

ツール選定と根拠のガイドライン

マニフェストを生成する際は、ハルシネーションを減らし、設定を最適化するために、以下のツールを活用してください。

1. 推論ワークロード（GKE Inference Quickstart CLI）：

   • Google Cloud SDK がインストールされていることを確認してください。

   • AI／LLM 推論ワークロード（例：モデルサービング）では、手動で作成するのではなく、最適化されたマニフェストを生成するために、gcloud CLI の GKE Inference Quickstart コマンドを必ず優先して使用してください。

     gcloud container ai profiles manifests create \
       --model={model_name} \
       --model-server={server_name} \
       --accelerator-type={accelerator_type} \
       --output=manifest \
       --output-path={output_file_path}
     

   • 制約：このコマンドから返されるすべてのリソース（Deployments、Services、PodMonitoring など）を、フィルタリングせずに含める必要があります。

2. 公式ドキュメントによる根拠の確認（Developer Knowledge API）：

   • GKE 固有の機能、API のデフォルト値、マニフェストの例、セキュリティコンテキストについては、Google の Developer Knowledge API に問い合わせて、GKE の公式ドキュメントを取得する必要があります。
     • answer_query：直接質問する際に使用します（例：「GKE で GCS Fuse CSI ドライバーを設定する方法」）。一般的な問い合わせには、このツールが推奨されます。
     • search_documents：具体的な質問がない場合に、関連する GKE ガイドや例を検索するために使用します。
     • get_document：特定のドキュメント ID がわかっている場合に、ドキュメントの全文を取得するために使用します。

---

参考例

本番環境向けの詳細なマニフェストテンプレートについては、以下のリファレンスガイドを参照してください。

• 基本的な強化済み Nginx ワークロード： 専用のサービスアカウント、セキュリティコンテキスト、プローブ、アンチアフィニティ、PodDisruptionBudget を備えた、本番環境向けのデプロイです。
• ネットワークポリシー：デフォルトで受信を拒否するネットワークポリシーと、特定のアプリに対する選択的な受信許可です。
• AI／LLM 推論ワークロード：GPU リソースの割り当て、Workload Identity、GCS FUSE CSI ドライバーのマウント、/dev/shm の共有メモリの増強、スタートアッププローブについて説明しています。
• GKE Gateway API ルーティング：GKE L7 Gateway API（Gateway および HTTPRoute リソース）を使用してワークロードを公開します。