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 type: 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

テストチェックリスト：

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

よくあるパターン

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

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

必要なコンポーネント：

• Deployment（HA のための 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 内の名前と一致しているか確認します
• 名前空間を確認します
• リソースが存在することを確認します：kubectl get configmap,secret

次のステップ

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

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

関連スキル

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