k8s-manifest-generator

Kubernetes マニフェストジェネレーター

Deployment、Service、ConfigMap、Secret、PersistentVolumeClaim など、本番環境に対応した Kubernetes マニフェストを作成するためのステップごとのガイダンスです。

目的

このスキルでは、クラウドネイティブのベストプラクティスと Kubernetes の規約に従って、適切に構成され、安全で、本番環境に対応した Kubernetes マニフェストを生成するための包括的なガイダンスを提供します。

このスキルを使用するタイミング

次の作業が必要な場合に、このスキルを使用してください。

• 新しい Kubernetes Deployment マニフェストを作成する
• ネットワーク接続用の Service リソースを定義する
• 構成管理用の ConfigMap および Secret リソースを生成する
• ステートフルなワークロード用の PersistentVolumeClaim マニフェストを作成する
• Kubernetes のベストプラクティスと命名規則に従う
• リソース制限、ヘルスチェック、セキュリティコンテキストを実装する
• マルチ環境デプロイメント向けのマニフェストを設計する

ステップごとのワークフロー

1. 要件を収集する

ワークロードを把握します。

• アプリケーションの種類（ステートレス／ステートフル）
• コンテナイメージとバージョン
• 環境変数と構成の要件
• ストレージの要件
• ネットワーク公開の要件（内部／外部）
• リソースの要件（CPU、メモリ）
• スケーリングの要件
• ヘルスチェックのエンドポイント

確認する質問：

• アプリケーションの名前と目的は何ですか？
• 使用するコンテナイメージとタグは何ですか？
• アプリケーションに永続ストレージは必要ですか？
• アプリケーションが公開するポートは何ですか？
• 必要な Secret や構成ファイルはありますか？
• CPU とメモリの要件はどのくらいですか？
• アプリケーションを外部に公開する必要はありますか？

2. Deployment マニフェストを作成する

次の構造に従います。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: <app-name>
  namespace: <namespace>
  labels:
    app: <app-name>
    version: <version>
spec:
  replicas: 3
  selector:
    matchLabels:
      app: <app-name>
  template:
    metadata:
      labels:
        app: <app-name>
        version: <version>
    spec:
      containers:
        - name: <container-name>
          image: <image>:<tag>
          ports:
            - containerPort: <port>
              name: http
          resources:
            requests:
              memory: '256Mi'
              cpu: '250m'
            limits:
              memory: '512Mi'
              cpu: '500m'
          livenessProbe:
            httpGet:
              path: /health
              port: http
            initialDelaySeconds: 30
            periodSeconds: 10
          readinessProbe:
            httpGet:
              path: /ready
              port: http
            initialDelaySeconds: 5
            periodSeconds: 5
          env:
            - name: ENV_VAR
              value: 'value'
          envFrom:
            - configMapRef:
                name: <app-name>-config
            - secretRef:
                name: <app-name>-secret

適用するベストプラクティス：

• 必ずリソースのリクエストと制限を設定する
• liveness probe と readiness probe の両方を実装する
• 具体的なイメージタグを使用する（:latest は使用しない）
• 非 root ユーザー向けのセキュリティコンテキストを適用する
• 整理と選択にラベルを使用する
• 可用性の要件に基づいて適切なレプリカ数を設定する

参考資料： Deployment の詳細なオプションについては、references/deployment-spec.md を参照してください。

3. Service マニフェストを作成する

適切な Service タイプを選択します。

ClusterIP（内部のみ）：

apiVersion: v1
kind: Service
metadata:
  name: <app-name>
  namespace: <namespace>
  labels:
    app: <app-name>
spec:
  type: ClusterIP
  selector:
    app: <app-name>
  ports:
    - name: http
      port: 80
      targetPort: 8080
      protocol: TCP

LoadBalancer（外部アクセス）：

apiVersion: v1
kind: Service
metadata:
  name: <app-name>
  namespace: <namespace>
  labels:
    app: <app-name>
  annotations:
    service.beta.kubernetes.io/aws-load-balancer-type: nlb
spec:
  type: LoadBalancer
  selector:
    app: <app-name>
  ports:
    - name: http
      port: 80
      targetPort: 8080
      protocol: TCP

参考資料： Service タイプとネットワークについては、references/service-spec.md を参照してください。

4. ConfigMap を作成する

アプリケーションの構成用：

apiVersion: v1
kind: ConfigMap
metadata:
  name: <app-name>-config
  namespace: <namespace>
data:
  APP_MODE: production
  LOG_LEVEL: info
  DATABASE_HOST: db.example.com
  # For config files
  app.properties: |
    server.port=8080
    server.host=0.0.0.0
    logging.level=INFO

ベストプラクティス：

• ConfigMap は機密性のないデータのみに使用する
• 関連する構成をまとめる
• キーには意味のある名前を付ける
• コンポーネントごとに ConfigMap を 1 つ使用することを検討する
• 変更を加えるときは ConfigMap をバージョン管理する

参考資料： 例については、assets/configmap-template.yaml を参照してください。

5. Secret を作成する

機密データ用：

apiVersion: v1
kind: Secret
metadata:
  name: <app-name>-secret
  namespace: <namespace>
type: Opaque
stringData:
  DATABASE_PASSWORD: 'changeme'
  API_KEY: 'secret-api-key'
  # For certificate files
  tls.crt: |
    -----BEGIN CERTIFICATE-----
    ...
    -----END CERTIFICATE-----
  tls.key: |
    -----BEGIN PRIVATE KEY-----
    ...
    -----END PRIVATE KEY-----

セキュリティ上の考慮事項：

• Secret を平文のまま Git にコミットしないでください
• Sealed Secrets、External Secrets Operator、または Vault を使用してください
• Secret を定期的にローテーションしてください
• RBAC を使用して Secret へのアクセスを制限してください
• TLS Secret には Secret タイプ kubernetes.io/tls の使用を検討してください

6. PersistentVolumeClaim を作成する（必要な場合）

ステートフルアプリケーション用：

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: <app-name>-data
  namespace: <namespace>
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: gp3
  resources:
    requests:
      storage: 10Gi

Deployment でマウントする：

spec:
  template:
    spec:
      containers:
        - name: app
          volumeMounts:
            - name: data
              mountPath: /var/lib/app
      volumes:
        - name: data
          persistentVolumeClaim:
            claimName: <app-name>-data

ストレージに関する考慮事項：

• パフォーマンス要件に適した StorageClass を選択する
• 単一 Pod からのアクセスには ReadWriteOnce を使用する
• 複数 Pod での共有ストレージには ReadWriteMany を使用する
• バックアップ戦略を検討する
• 適切な保持ポリシーを設定する

7. セキュリティのベストプラクティスを適用する

Deployment にセキュリティコンテキストを追加します。

spec:
  template:
    spec:
      securityContext:
        runAsNonRoot: true
        runAsUser: 1000
        fsGroup: 1000
        seccompProfile:
          type: RuntimeDefault
      containers:
        - name: app
          securityContext:
            allowPrivilegeEscalation: false
            readOnlyRootFilesystem: true
            capabilities:
              drop:
                - ALL

セキュリティチェックリスト：

• 非 root ユーザーとして実行する
• すべてのケーパビリティを削除する
• 読み取り専用のルートファイルシステムを使用する
• 権限昇格を無効にする
• seccomp プロファイルを設定する
• Pod Security Standards を使用する

8. ラベルとアノテーションを追加する

標準ラベル（推奨）：

metadata:
  labels:
    app.kubernetes.io/name: <app-name>
    app.kubernetes.io/instance: <instance-name>
    app.kubernetes.io/version: '1.0.0'
    app.kubernetes.io/component: backend
    app.kubernetes.io/part-of: <system-name>
    app.kubernetes.io/managed-by: kubectl

便利なアノテーション：

metadata:
  annotations:
    description: 'Application description'
    contact: '[email protected]'
    prometheus.io/scrape: 'true'
    prometheus.io/port: '9090'
    prometheus.io/path: '/metrics'

9. 複数リソースのマニフェストを整理する

ファイル構成の選択肢：

オプション 1：--- 区切りを使用した単一ファイル

# app-name.yaml
---
apiVersion: v1
kind: ConfigMap
...
---
apiVersion: v1
kind: Secret
...
---
apiVersion: apps/v1
kind: Deployment
...
---
apiVersion: v1
kind: Service
...

オプション 2：ファイルを分割する

manifests/
├── configmap.yaml
├── secret.yaml
├── deployment.yaml
├── service.yaml
└── pvc.yaml

オプション 3：Kustomize の構成

base/
├── kustomization.yaml
├── deployment.yaml
├── service.yaml
└── configmap.yaml
overlays/
├── dev/
│   └── kustomization.yaml
└── prod/
    └── kustomization.yaml

10. 検証とテスト

検証手順：

# Dry-run validation
kubectl apply -f manifest.yaml --dry-run=client

# Server-side validation
kubectl apply -f manifest.yaml --dry-run=server

# Validate with kubeval
kubeval manifest.yaml

# Validate with kube-score
kube-score score manifest.yaml

# Check with kube-linter
kube-linter lint manifest.yaml

テストチェックリスト：

• マニフェストがドライラン検証に合格する
• 必須フィールドがすべて設定されている
• リソース制限が適切である
• ヘルスチェックが設定されている
• セキュリティコンテキストが設定されている
• ラベルが規則に従っている
• Namespace が存在するか、作成されている

よくあるパターン

パターン 1：シンプルなステートレス Web アプリケーション

用途： 標準的な Web API またはマイクロサービス

必要なコンポーネント：

• Deployment（高可用性のために 3 レプリカ）
• ClusterIP Service
• 設定用の ConfigMap
• API キー用の Secret
• HorizontalPodAutoscaler（任意）

参考： assets/deployment-template.yaml を参照してください。

パターン 2：ステートフルなデータベースアプリケーション

用途： データベースまたは永続ストレージを使用するアプリケーション

必要なコンポーネント：

• StatefulSet（Deployment ではありません）
• Headless Service
• PersistentVolumeClaim テンプレート
• DB 設定用の ConfigMap
• 認証情報用の Secret

パターン 3：バックグラウンドジョブまたは Cron

用途： スケジュールされたタスクまたはバッチ処理

必要なコンポーネント：

• CronJob または Job
• ジョブパラメーター用の ConfigMap
• 認証情報用の Secret
• RBAC を設定した ServiceAccount

パターン 4：マルチコンテナ Pod

用途： サイドカーコンテナを含むアプリケーション

必要なコンポーネント：

• 複数のコンテナを含む Deployment
• コンテナ間で共有するボリューム
• セットアップ用の Init コンテナ
• Service（必要な場合）

テンプレート

assets/ ディレクトリには、次のテンプレートがあります。

• deployment-template.yaml - ベストプラクティスに沿った標準的な Deployment
• service-template.yaml - Service の設定（ClusterIP、LoadBalancer、NodePort）
• configmap-template.yaml - さまざまなデータ型を使用した ConfigMap の例
• secret-template.yaml - Secret の例（生成するものであり、コミットしません）
• pvc-template.yaml - PersistentVolumeClaim テンプレート

参考ドキュメント

• references/deployment-spec.md - Deployment の詳細な仕様
• references/service-spec.md - Service の種類とネットワークの詳細

ベストプラクティスのまとめ

1. 必ずリソースのリクエストと制限を設定する - リソースの枯渇を防ぎます
2. ヘルスチェックを実装する - Kubernetes によるアプリケーション管理を確実にします
3. 具体的なイメージタグを使用する - 予測できないデプロイを避けます
4. セキュリティコンテキストを適用する - root 以外のユーザーとして実行し、ケイパビリティを削除します
5. ConfigMap と Secret を使用する - 設定をコードから分離します
6. すべてにラベルを付ける - フィルタリングと整理ができるようにします
7. 命名規則に従う - Kubernetes の標準ラベルを使用します
8. 適用前に検証する - ドライランと検証ツールを使用します
9. マニフェストをバージョン管理する - Git に保存してバージョン管理します
10. アノテーションでドキュメント化する - 他の開発者向けに背景情報を追加します

トラブルシューティング

Pod が起動しない場合：

• イメージのプルエラーを確認します：kubectl describe pod <pod-name>
• リソースの利用状況を確認します：kubectl get nodes
• イベントを確認します：kubectl get events --sort-by='.lastTimestamp'

Service にアクセスできない場合：

• セレクターが Pod のラベルと一致することを確認します：kubectl get endpoints <service-name>
• Service の種類とポートの設定を確認します
• クラスター内からテストします：kubectl run debug --rm -it --image=busybox -- sh

ConfigMap／Secret が読み込まれない場合：

• Deployment 内の名前が一致していることを確認します
• Namespace を確認します
• リソースが存在することを確認します：kubectl get configmap,secret

次のステップ

マニフェストを作成した後：

1. Git リポジトリに保存する
2. デプロイ用の CI/CD パイプラインをセットアップする
3. テンプレート化に Helm または Kustomize を使用することを検討する
4. ArgoCD または Flux で GitOps を実装する
5. モニタリングとオブザーバビリティを追加する

絶対に守るべき原則

1. 必ず すべてのコンテナに CPU とメモリのリソース requests および limits を設定してください。リソース制限のない Pod はノードのリソースを無制限に消費し、ノードのリソース逼迫による退避を引き起こし、隣接するワークロードのリソースを奪います。
2. 本番環境では、決して コンテナを root として実行しないでください（runAsNonRoot: false または未設定）。root コンテナはカーネルの脆弱性を利用してコンテナの隔離を突破する可能性があります。必ず securityContext.runAsNonRoot: true と特定の runAsUser を設定してください。
3. 必ず すべてのワークロードに liveness プローブと readiness プローブを定義してください。プローブがないと、Kubernetes はデッドロックしたコンテナと正常なコンテナを区別できません。また、プローブの失敗によりデプロイがブロックされたり、トラフィックが誤って処理されたりします。
4. 決して ConfigMap にシークレットを保存しないでください。ConfigMap は etcd に平文で保存されます。Kubernetes Secrets（保存時の etcd 暗号化を有効にしてください）または外部シークレットマネージャー（Vault、AWS Secrets Manager）を使用してください。
5. 本番環境のワークロードには 必ず PodDisruptionBudget を設定してください。PDB がないと、アップグレード時のノードドレインですべてのレプリカが同時に終了し、サービスが完全に停止する可能性があります。

アンチパターン

アンチパターン	問題点	正しい方法
リソース制限なし	Pod がノードのメモリをすべて消費し、ノードの OOM によって他の Pod が強制終了され、クラスターが不安定になります	すべてのコンテナで CPU とメモリの requests（スケジューリング）および limits（制限）を設定します
root として実行	カーネルの脆弱性によりコンテナの隔離が突破され、root によるファイルシステムへの書き込みでホストが破損します	runAsNonRoot: true、runAsUser: 1000、readOnlyRootFilesystem: true を設定します
liveness／readiness プローブの欠如	デッドロックした Pod がトラフィックを処理し、起動したばかりの Pod が準備完了前にトラフィックを受け取ります	適切な initialDelaySeconds を指定して、/health の liveness プローブと /ready の readiness プローブを追加します
ConfigMap にシークレットを保存	etcd に平文で保存され、kubectl get configmap で表示でき、監査ログに値が記録されます	base64 エンコードを使用した kind: Secret を使用し、etcd 暗号化を有効にしてください。外部シークレットの使用を推奨します
本番環境でレプリカが 1 つのみ	Pod の再起動でサービスが停止し、ノード障害への許容度がゼロになります	最低 2 つのレプリカを設定し、PodAntiAffinity ルールでノード間に分散させ、PodDisruptionBudget を設定します

関連スキル

• helm-chart-scaffolding - テンプレート化とパッケージ化に使用します
• gitops-workflow - デプロイの自動化に使用します
• k8s-security-policies - 高度なセキュリティ設定に使用します

メモリプロトコル（必須）

開始前：

cat C:\dev\projects\agent-studio\.claude\context\memory\learnings.md

完了後：

• 新しいパターン -> C:\dev\projects\agent-studio\.claude\context\memory\learnings.md
• 問題の発見 -> C:\dev\projects\agent-studio\.claude\context\memory\issues.md
• 決定事項 -> C:\dev\projects\agent-studio\.claude\context\memory\decisions.md

中断を想定してください。メモリに記録されていないことは、実行されていないのと同じです。