gke-app-onboarding

GKE アプリのオンボーディング

このリファレンスでは、アプリケーションを初めてコンテナ化し、GKE にデプロイするワークフローを紹介します。

MCP ツール： apply_k8s_manifest、get_k8s_resource、 get_k8s_rollout_status、get_k8s_logs、describe_k8s_resource

帰属情報

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

ワークフロー

1. アプリの評価

コンテナ化する前に、アプリケーションを評価します。

• 言語とフレームワーク：技術スタックを特定します
• 依存関係：必要なライブラリと外部サービスを列挙します
• 構成：アプリの構成方法を確認します（環境変数、構成ファイル、シークレット）
• ステートフル性：永続ストレージが必要か確認します（データベース、ファイルストレージ）
• ネットワーキング：ポートマッピングとプロトコルを確認します（HTTP、gRPC、TCP）
• ヘルスエンドポイント：アプリがヘルスチェック用エンドポイントを公開しているか確認します

2. コンテナ化

コンテナイメージを作成します。ほとんどのアプリでは、マルチステージビルドを使用する Dockerfile を推奨します。実例については、references/go-example.md の Go 用 Dockerfile を参照してください。

ベストプラクティス：

• マルチステージビルドを使用して、本番環境のイメージを小さく保ちます
• 攻撃対象領域を減らすため、distroless または最小限のベースイメージを使用します
• root 以外のユーザーとして実行します
• Cloud Logging で収集できるよう、stdout と stderr にログを出力します

Node.js の完全な実例を assets/ に用意しています。内容は、Dockerfile（root 以外の node ユーザー）、index.js（/healthz と /readyz の個別のエンドポイントを実装）、package.json、および deployment.yaml（/healthz と /readyz に接続するプローブを備えた、セキュリティ強化済みの Deployment と ClusterIP Service）です。

Dockerfile の作成が望ましくないアプリケーションには、Cloud Native Buildpacks を使用して言語を自動検出し、コンテナイメージをビルドできます。

pack build <image> --builder gcr.io/buildpacks/builder:latest

3. イメージの管理

コンテナイメージをビルドして保存します。

# Configure Docker for Artifact Registry
gcloud auth configure-docker <REGION>-docker.pkg.dev --quiet

# Build and push
docker build -t <REGION>-docker.pkg.dev/<PROJECT>/<REPO>/<IMAGE>:<TAG> .
docker push <REGION>-docker.pkg.dev/<PROJECT>/<REPO>/<IMAGE>:<TAG>

脆弱性スキャン：Artifact Registry で自動スキャンを有効にし、ベースイメージと依存関係にある問題を検出します。

# Check scan results
gcloud artifacts docker images describe \
  <REGION>-docker.pkg.dev/<PROJECT>/<REPO>/<IMAGE>:<TAG> \
  --show-package-vulnerability \
  --quiet

4. マニフェストの生成

アプリケーションの Kubernetes マニフェストを生成します。プローブ、リソースのリクエストと上限、2 つのレプリカを備えた基本的な Deployment と ClusterIP Service のマニフェストは、references/go-example.md にあります。

マニフェストのチェックリスト：

• リソースのリクエストと上限が設定されている
• ライブネスプローブとレディネスプローブが構成されている
• 本番環境では少なくとも 2 つのレプリカがある
• 適切な Service タイプを使用している（内部向けには ClusterIP、外部向けには Gateway API を使用）

セキュリティを強化した実例については、assets/deployment.yaml を参照してください。本番環境向けにセキュリティを強化した Pod 仕様には、次のすべてを含める必要があります：runAsNonRoot: true、readOnlyRootFilesystem: true、allowPrivilegeEscalation: false、capabilities.drop: ["ALL"]、seccompProfile: {type: RuntimeDefault}、automountServiceAccountToken: false（Pod にトークンが必要な場合を除く。その場合は理由を記載してください）、リソースのリクエスト、ダイジェストで固定したイメージ、ClusterIP Service。

このチェックリストは、ここで作成するすべての Pod 仕様の基本です。これを超えるマニフェスト作業（Gateway API ルート、GCS FUSE とシークレットボリュームのマウント、subPath オーバーレイ、Spot VM のターゲティング、AI／推論サービング仕様）については、gke-manifest-generation を参照してください。

5. デプロイ

# MCP (preferred)
apply_k8s_manifest(parent="projects/<PROJECT>/locations/<REGION>/clusters/<CLUSTER>", yamlManifest="<manifest>")

# Verify
get_k8s_rollout_status(parent="...", resourceType="deployment", name="my-app")
get_k8s_resource(parent="...", resourceType="pod", labelSelector="app=my-app")

kubectl による代替手段：

kubectl apply -f manifests/
kubectl rollout status deployment/my-app
kubectl get pods -l app=my-app

ゴールデンパスのオンボーディングチェックリスト

GKE にオンボーディングするすべての本番アプリケーションで、次の項目を確認します。

1. コンテナセキュリティ：非 root ユーザー（runAsNonRoot: true）、ロックファイルを使用したインストール、最小構成または distroless のベースイメージ。
2. リソースリクエスト：CPU とメモリのリクエストを明示します（GKE Autopilot では必須です）。
3. ヘルスプローブ：liveness（livenessProbe）と readiness（readinessProbe）の両方のプローブを設定します。
4. 信頼性と可用性：レプリカを 2 つ以上にし、PodDisruptionBudget（minAvailable: 1 または 2）を設定します。
5. IAM と Workload Identity：静的なサービスアカウントキーの代わりに、Workload Identity（iam.gke.io/gcp-service-account）を使用します。

次のステップ

アプリケーションが GKE で稼働したら：

• オートスケーリングを設定します — gke-workload-scaling スキルを参照してください
• オブザーバビリティを設定します — gke-observability スキルを参照してください
• セキュリティを強化します — gke-workload-security スキルを参照してください
• 信頼性を設定します（PDB、トポロジーの分散）— gke-reliability スキルを参照してください