kubernetes-deployment

Kubernetes のデプロイ

このスキルを使用すると、エージェントは Kubernetes クラスター上でアプリケーションをデプロイおよび管理できます。エージェントは、デプロイメントマニフェスト、サービス、Ingress ルール、Helm チャート、自動スケーリング設定を生成できます。リソース管理、セキュリティ、信頼性に関する本番環境のベストプラクティスに従い、初回デプロイからスケーリング、ローリングアップデート、トラブルシューティングまで、ライフサイクル全体に対応します。

ワークフロー

1. クラスターアクセスを設定する： エージェントは、kubectl が正しいクラスターコンテキストと名前空間で設定されていることを確認します。kubectl cluster-info で接続を確認し、対象の名前空間でリソースを作成および管理するために十分な RBAC 権限がユーザーにあることを確かめます。kubeconfig がない場合は、認証手順（例：aws eks update-kubeconfig、gcloud container clusters get-credentials）を案内します。

2. デプロイメントマニフェストを定義する： エージェントは、コンテナイメージ、レプリカ数、リソースのリクエストと上限、環境変数、ライブネスプローブとレディネスプローブ、ポッドのアンチアフィニティルールを指定する Kubernetes デプロイメントマニフェストを作成します。サービスディスカバリー、モニタリング、運用のために、ラベルとアノテーションを一貫して適用します。エージェントは具体的なイメージタグを使用し（latest は使用しません）、imagePullPolicy を適切に設定します。

3. サービスと Ingress を設定する： エージェントは、クラスター内部（ClusterIP）または外部（LoadBalancer、NodePort）にデプロイメントを公開する Service リソースを作成します。HTTP ワークロードでは、cert-manager による TLS 終端、パスベースルーティング、レート制限のアノテーションを使用して Ingress リソースを設定します。デプロイ環境とトラフィック要件に基づいて、適切なサービスタイプを選択します。

4. マニフェストを適用し、ロールアウトを確認する： エージェントは kubectl apply -f でマニフェストを適用し、kubectl rollout status でロールアウトを監視します。すべてのポッドが Running 状態になり、ヘルスチェックに合格し、サービスのエンドポイントが登録されていることを確認します。ロールアウトが停止した場合は、kubectl describe pod でポッドイベントを、kubectl logs でログを確認して問題を診断し、kubectl rollout undo を実行して前のバージョンに戻すこともできます。

5. 自動スケーリングを設定する： エージェントは、CPU 使用率、メモリー使用量、またはカスタムメトリクスに基づいてレプリカ数をスケーリングする Horizontal Pod Autoscaler（HPA）を設定します。最小および最大のレプリカ数、スケールアップとスケールダウンの動作、頻繁な変動を防ぐための安定化ウィンドウを定義します。リソース要件が変動するワークロードでは、Vertical Pod Autoscaler（VPA）も設定できます。

6. Helm チャートで管理する： 複数の環境にまたがる複雑なアプリケーションでは、エージェントはテンプレート化された値を使って Kubernetes マニフェストを Helm チャートにパッケージ化します。Helm を使用すると、バージョン管理されたリリース、失敗時に自動ロールバックするアトミックアップグレード、環境ごとの値の上書きが可能になります。エージェントは冪等なデプロイメントに helm upgrade --install を使用し、適用前の変更のプレビューには helm diff を使用します。

対応テクノロジー

• オーケストレーション： Kubernetes（EKS、GKE、AKS、セルフマネージド）、k3s、kind、minikube
• パッケージ管理： Helm 3、Kustomize
• 自動スケーリング： HPA、VPA、KEDA、Cluster Autoscaler
• ネットワーキング： Nginx Ingress Controller、Traefik、Istio、Cilium
• 証明書管理： cert-manager、Let's Encrypt
• CI/CD 統合： ArgoCD、Flux、GitHub Actions、GitLab CI

使用方法

アプリケーションのコンテナイメージ、リソース要件、希望するレプリカ数、対象の Kubernetes クラスターの詳細をエージェントに伝えてください。

プロンプトの例：

Deploy my app to the production EKS cluster:
- Image: myregistry.io/myapp:v2.1.0
- 3 replicas with CPU/memory limits
- Liveness and readiness probes on /health
- Expose via Ingress at api.example.com with TLS
- HPA scaling between 3-10 replicas based on CPU

例

例 1：サービスと Ingress を使った本番環境へのデプロイ

deployment.yaml：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
  namespace: production
  labels:
    app: myapp
    version: v2.1.0
spec:
  replicas: 3
  revisionHistoryLimit: 5
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0
  selector:
    matchLabels:
      app: myapp
  template:
    metadata:
      labels:
        app: myapp
        version: v2.1.0
    spec:
      serviceAccountName: myapp
      terminationGracePeriodSeconds: 60
      affinity:
        podAntiAffinity:
          preferredDuringSchedulingIgnoredDuringExecution:
            - weight: 100
              podAffinityTerm:
                labelSelector:
                  matchExpressions:
                    - key: app
                      operator: In
                      values: [myapp]
                topologyKey: kubernetes.io/hostname
      containers:
        - name: myapp
          image: myregistry.io/myapp:v2.1.0
          ports:
            - containerPort: 3000
              name: http
          env:
            - name: NODE_ENV
              value: "production"
            - name: DATABASE_URL
              valueFrom:
                secretKeyRef:
                  name: myapp-secrets
                  key: database-url
          resources:
            requests:
              cpu: 250m
              memory: 256Mi
            limits:
              cpu: "1"
              memory: 512Mi
          livenessProbe:
            httpGet:
              path: /health
              port: http
            initialDelaySeconds: 30
            periodSeconds: 10
            timeoutSeconds: 5
            failureThreshold: 3
          readinessProbe:
            httpGet:
              path: /health
              port: http
            initialDelaySeconds: 5
            periodSeconds: 5
            timeoutSeconds: 3
            failureThreshold: 3
          lifecycle:
            preStop:
              exec:
                command: ["/bin/sh", "-c", "sleep 15"]

service.yaml：

apiVersion: v1
kind: Service
metadata:
  name: myapp
  namespace: production
spec:
  selector:
    app: myapp
  ports:
    - protocol: TCP
      port: 80
      targetPort: http
  type: ClusterIP

ingress.yaml：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: myapp
  namespace: production
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
    nginx.ingress.kubernetes.io/rate-limit: "100"
spec:
  ingressClassName: nginx
  tls:
    - hosts:
        - api.example.com
      secretName: myapp-tls
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: myapp
                port:
                  number: 80

例 2：Helm デプロイでの Horizontal Pod Autoscaler

カスタム値を使用して Helm でインストールまたはアップグレードします：

helm upgrade --install myapp ./charts/myapp \
  --namespace production \
  --set image.tag=v2.1.0 \
  --set replicaCount=3 \
  --set autoscaling.enabled=true \
  --values values-production.yaml \
  --wait --timeout 5m \
  --atomic

hpa.yaml — Horizontal Pod Autoscaler：

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: myapp
  namespace: production
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: myapp
  minReplicas: 3
  maxReplicas: 10
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70
    - type: Resource
      resource:
        name: memory
        target:
          type: Utilization
          averageUtilization: 80
  behavior:
    scaleUp:
      stabilizationWindowSeconds: 60
      policies:
        - type: Percent
          value: 50
          periodSeconds: 60
    scaleDown:
      stabilizationWindowSeconds: 300
      policies:
        - type: Percent
          value: 25
          periodSeconds: 120

デプロイ手順：

1. kubectl create namespace production（存在しない場合）
2. kubectl apply -f deployment.yaml -f service.yaml -f ingress.yaml
3. kubectl apply -f hpa.yaml
4. kubectl rollout status deployment/myapp -n production
5. kubectl get hpa myapp -n production を実行して、オートスケーラーのターゲットを確認します

ベストプラクティス

• リソースのリクエストと制限を必ず設定します： すべてのコンテナで、CPU とメモリのリクエスト（スケジューリング用）と制限（ノイジーネイバーの問題を防ぐため）を定義する必要があります。リクエストがないと、スケジューラーは適切な配置を判断できず、制限がないと、1 つのポッドがノードのすべてのリソースを消費する可能性があります。
• liveness プローブと readiness プローブを設定します： liveness プローブにより、停止またはデッドロックしたコンテナを Kubernetes が再起動できます。readiness プローブにより、リクエストを処理する準備ができていないポッドへのトラフィック転送を防げます。起動中にポッドが終了されないよう、適切な initialDelaySeconds を設定します。
• 分離には名前空間を使用します： 環境（dev、staging、production）とチームをそれぞれ別の名前空間に分けます。名前空間ごとに ResourceQuotas と LimitRanges を適用し、特定のチームや環境がクラスターリソースを過剰に消費しないようにします。
• 最小権限で RBAC を実装します： アプリケーションごとに、最小限の権限を持つサービスアカウントを作成します。default サービスアカウントの使用や、ワークロードへの cluster-admin の付与は避けてください。可能な場合は、ClusterRoles ではなく、名前空間の範囲に限定した Roles と RoleBindings を使用します。
• 再現可能なデプロイには Helm を使用します： Helm チャートは、テンプレート化された値とマニフェストをパッケージ化し、環境間で一貫したデプロイを可能にします。失敗時の自動ロールバックには --atomic を使用し、リソースが正常な状態になるまで処理を待つには --wait を使用します。
• ポッド中断予算を設定します： PodDisruptionBudgets（PDB）を定義し、ノードのドレインやクラスターのアップグレードなど、自発的な中断が発生しても、最低限のレプリカ数を維持できるようにします。たとえば、minAvailable: 2 を設定すると、常に 2 つ以上のポッドが稼働します。

エッジケース

• CrashLoopBackOff： Pod が繰り返しクラッシュし、Kubernetes は再起動の試行間隔を指数関数的に延長します。kubectl logs <pod> --previous でクラッシュ時の出力を確認し、kubectl describe pod <pod> でイベントを調べて原因を特定します。よくある原因として、環境変数の設定ミス、シークレットの不足、データベースへの接続失敗などがあります。
• ImagePullBackOff： コンテナランタイムが指定されたイメージを取得できません。イメージタグが存在しない、レジストリで認証が必要、またはネットワークに問題がある場合に発生します。docker pull でイメージが存在することを確認し、Pod の仕様にある imagePullSecrets を確認して、ノードからレジストリにネットワークアクセスできることを確かめてください。
• ノードのリソース不足による Pod の退避： ノードのメモリまたはディスクが不足すると、kubelet はリソースリクエストを超過している Pod から順に退避させます（最初に BestEffort Pod、次に Burstable Pod）。重要な Pod が Guaranteed QoS クラスに分類され、最後に退避されるよう、適切なリソースリクエストを設定してください。
• ロールアウトの停滞と期限： 新しい Pod が Readiness チェックに失敗すると、Deployment のロールアウトが停滞することがあります。デフォルトの progressDeadlineSeconds は 600 秒で、その後 Kubernetes はロールアウトを失敗と見なします。期限まで待つ代わりに、kubectl rollout undo deployment/myapp を使ってすぐに元に戻してください。
• 新しい名前空間での DNS 解決エラー： CoreDNS の内部レコードがまだ更新されていない場合、新しく作成した名前空間の Pod で一時的に DNS 解決エラーが発生することがあります。アプリケーションコンテナには、サービスの初期検出呼び出しに対するバックオフ付きの再試行ロジックを実装してください。
• Helm リリースの競合： 以前の helm upgrade が中断された場合（タイムアウトなど）、リリースが pending-upgrade または failed 状態になっていることがあります。helm history myapp で状態を確認し、別のアップグレードを試す前に helm rollback myapp <revision> で復旧してください。