Use Cases (更新: 2026/6/2)

Claude CodeでKubernetesデプロイ入門：Deploymentからロールバックまで安全に進める

Claude CodeでKubernetesのDeployment、Service、Ingress、ロールバックを安全に作る実装ガイド。

Claude CodeでKubernetesデプロイ入門：Deploymentからロールバックまで安全に進める

Kubernetesデプロイを生成だけで終わらせない

Kubernetesは、コンテナ化したアプリを複数のサーバー上で動かすための仕組みです。便利な一方で、Deployment、Service、Ingress、ConfigMap、Secret、probe、resource requestなど、初心者が一度に覚えるには用語が多すぎます。Claude Codeに「KubernetesのYAMLを作って」とだけ頼むと、動くように見えても、ヘルスチェックがない、ロールバックできない、SecretをGitに置いてしまう、といった危ないマニフェストになりがちです。

この記事では、Claude Codeを「YAML自動生成ツール」ではなく「安全な足場を作り、差分をレビューする相棒」として使います。題材は、ローカルのKubernetesクラスタにも貼り付けて試せる小さなNGINXアプリです。自社アプリのDockerイメージをまだ用意していない人でも、Deployment、Service、Ingress、ConfigMap、probe、resources、rollout、rollbackの流れを手で確認できます。

公式仕様は必ず一次情報で確認してください。特に Kubernetes Deployments、Service、Ingress、Liveness/Readiness/Startup probes、Resource management、ConfigMap、Secret、kubectl rolloutはブックマークしておくと安心です。コンテナ作成から見直したい場合は Claude CodeとDocker連携、本番反映の自動化は Claude CodeでCI/CDパイプラインを構築、レビュー観点は Claude Codeコードレビューも合わせて読むとつながります。

3つの実用ユースケース

Kubernetes入門で最初に作るべきものは、巨大な本番構成ではありません。小さく動く単位を作り、壊し、戻せることを確認するほうが学習効率も実務価値も高くなります。

ユースケース目的Claude Codeに任せる作業
社内ツールの初回デプロイ1つのWebアプリを安全に公開するDeployment、Service、readinessProbe、resourcesの草案作成
研修・検証用クラスタ受講者が同じ手順でapplyとrollbackを体験するnamespace付きの最小マニフェスト、確認コマンド、失敗例の整理
既存アプリの本番前レビューYAMLの抜け漏れを減らすSecret混入、probe不足、requests未設定、Ingress設定のレビュー
CIでのマニフェスト確認Pull Requestで危ない変更を止めるkubectl --dry-runや差分レビューのチェックリスト作成

収益化を考えるブログや教材サイトでは、このテーマは読者の課題に直結します。「Kubernetesが怖い」という状態の読者に、コピペで動く最小例、落とし穴、相談先をセットで渡せるからです。ClaudeCodeLabでは、個人向けには無料チートシート、チーム向けには Claude Code研修・導入相談 で、こうしたデプロイ手順を実リポジトリに合わせて整えています。

Claude Codeに渡す前提メモ

Claude Codeには、最初から「何を作るか」だけでなく「何を作らないか」も渡します。特にKubernetesでは、勝手にLoadBalancerを作る、Secretを平文で書く、クラスタ固有のIngress Controller名を決め打ちする、といった出力を避ける必要があります。

Kubernetes初心者向けに、ローカルでも検証できるDeployment一式を作ってください。

前提:
- namespaceは claude-k8s-demo
- private registryは使わず nginx:1.27-alpine を使う
- ConfigMapでHTMLを1つ差し替える
- Deploymentはreplicas 2、RollingUpdate、readinessProbe、livenessProbe、resourcesを含める
- ServiceはClusterIPにする
- Ingressは任意利用として claude-k8s.local を使う
- SecretはサンプルをGitにコミットしない方針だけ説明する
- kubectl apply、rollout status、port-forward、rollbackの確認コマンドも書く

制約:
- NodePortやLoadBalancerは使わない
- Secretの実値をYAMLに書かない
- クラスタ全体に影響するClusterRoleやNamespace削除コマンドは出さない

このように頼むと、Claude Codeの出力をレビューしやすくなります。namespace、公開方法、イメージ、probe、resources、Secret方針を先に決めるだけで、危ない自動生成をかなり減らせます。プロジェクトで何度も使うなら、この前提を CLAUDE.md に移してください。CLAUDE.mdの考え方は Claude.mdベストプラクティス で詳しく整理しています。

コピペで動く最小マニフェスト

次の内容を k8s/claude-k8s-demo.yaml として保存します。ローカルのkind、minikube、Docker Desktop Kubernetes、または検証用クラスタで試せます。IngressはControllerが入っている環境だけで有効に使えますが、Serviceまでは port-forward で確認できます。

apiVersion: v1
kind: Namespace
metadata:
  name: claude-k8s-demo
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: demo-page
  namespace: claude-k8s-demo
data:
  APP_ENV: "demo"
  index.html: |
    <!doctype html>
    <html lang="ja">
      <head>
        <meta charset="utf-8" />
        <title>Claude Code Kubernetes Demo</title>
      </head>
      <body>
        <h1>Claude Code Kubernetes Demo</h1>
        <p>Deployment, Service, ConfigMap, probes are running.</p>
      </body>
    </html>
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: demo-web
  namespace: claude-k8s-demo
  labels:
    app: demo-web
spec:
  replicas: 2
  revisionHistoryLimit: 5
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0
  selector:
    matchLabels:
      app: demo-web
  template:
    metadata:
      labels:
        app: demo-web
    spec:
      containers:
        - name: nginx
          image: nginx:1.27-alpine
          imagePullPolicy: IfNotPresent
          ports:
            - name: http
              containerPort: 80
          env:
            - name: APP_ENV
              valueFrom:
                configMapKeyRef:
                  name: demo-page
                  key: APP_ENV
          resources:
            requests:
              cpu: "50m"
              memory: "64Mi"
            limits:
              cpu: "250m"
              memory: "128Mi"
          readinessProbe:
            httpGet:
              path: /
              port: http
            initialDelaySeconds: 3
            periodSeconds: 5
            timeoutSeconds: 2
            failureThreshold: 3
          livenessProbe:
            httpGet:
              path: /
              port: http
            initialDelaySeconds: 10
            periodSeconds: 10
            timeoutSeconds: 2
            failureThreshold: 3
          volumeMounts:
            - name: demo-page
              mountPath: /usr/share/nginx/html/index.html
              subPath: index.html
              readOnly: true
      volumes:
        - name: demo-page
          configMap:
            name: demo-page
---
apiVersion: v1
kind: Service
metadata:
  name: demo-web
  namespace: claude-k8s-demo
spec:
  type: ClusterIP
  selector:
    app: demo-web
  ports:
    - name: http
      port: 80
      targetPort: http
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: demo-web
  namespace: claude-k8s-demo
spec:
  ingressClassName: nginx
  rules:
    - host: claude-k8s.local
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: demo-web
                port:
                  name: http

初心者が見落としやすいポイントは、selector.matchLabels と Pod templateの labels を一致させることです。ここがズレるとDeploymentはPodを管理できず、Serviceも通信先を見つけられません。Claude Codeにレビューさせるときは「selector、labels、Service selectorが一致しているかを確認して」と明示してください。

ローカルで検証する手順

マニフェストを保存したら、次の順番で確認します。kubectl がクラスタにつながっていることは kubectl cluster-info で先に確認してください。

kubectl apply -f k8s/claude-k8s-demo.yaml
kubectl -n claude-k8s-demo rollout status deployment/demo-web
kubectl -n claude-k8s-demo get pods -l app=demo-web
kubectl -n claude-k8s-demo get service demo-web
kubectl -n claude-k8s-demo port-forward service/demo-web 8080:80

別のターミナルで確認します。

curl http://localhost:8080/

Ingress Controllerが入っている環境では、claude-k8s.local をローカルのhostsファイルへ向けます。ローカルクラスタの種類によりIPは違うため、まず kubectl get ingress とControllerのドキュメントを確認してください。ここを曖昧にしたままClaude Codeに任せると、環境に合わないIngress注釈が増えます。

kubectl -n claude-k8s-demo get ingress demo-web
kubectl -n claude-k8s-demo describe ingress demo-web

ConfigMapとSecretの扱い

ConfigMapは、秘密ではない設定をPodに渡すためのリソースです。今回の例では APP_ENV と index.html を入れています。DBパスワード、APIキー、セッショントークンはConfigMapに入れてはいけません。

Secretは秘密値向けのリソースですが、「Secretにしたから安全」という意味ではありません。標準のSecretはbase64表現で保存されるだけなので、Gitにコミットすれば漏えいです。実務ではクラウドのSecret Manager、External Secrets、Sealed Secrets、SOPSなどの方針をチームで決め、リポジトリには実値を置かない運用にします。

ローカル検証でSecretの形だけ作るなら、次のように生成し、secret.local.yaml を .gitignore に入れます。

kubectl -n claude-k8s-demo create secret generic demo-api-secret \
  --from-literal=API_TOKEN='replace-me-locally' \
  --dry-run=client \
  -o yaml > secret.local.yaml

kubectl apply -f secret.local.yaml

Claude Codeに依頼するなら「Secretの実値は生成しない」「.envやsecret.local.yamlはコミット対象外」「本番Secretは既存のSecret Managerを参照する」と書きます。この3点がないと、親切なつもりで危険なサンプル値をYAMLに埋め込むことがあります。

rolloutとrollbackを体で覚える

Deploymentの価値は、Podを増やすことだけではありません。変更を段階的に反映し、問題があれば戻せることにあります。まず正常な更新を試します。

kubectl -n claude-k8s-demo set image deployment/demo-web nginx=nginx:1.27-alpine
kubectl -n claude-k8s-demo rollout status deployment/demo-web
kubectl -n claude-k8s-demo rollout history deployment/demo-web

次に、あえて存在しないイメージへ変えて失敗を見ます。

kubectl -n claude-k8s-demo set image deployment/demo-web nginx=nginx:not-a-real-tag
kubectl -n claude-k8s-demo rollout status deployment/demo-web --timeout=30s
kubectl -n claude-k8s-demo get pods
kubectl -n claude-k8s-demo describe deployment demo-web

ImagePullBackOff が見えたら、rollbackします。

kubectl -n claude-k8s-demo rollout undo deployment/demo-web
kubectl -n claude-k8s-demo rollout status deployment/demo-web

この失敗練習は重要です。本番で初めてrollbackコマンドを打つチームは、どのrevisionへ戻るのか、ConfigMapやSecretの変更も戻るのか、監視アラートは止まるのかで迷います。Claude Codeには「rollback手順に、戻る対象と戻らない対象も書いて」と依頼してください。

CIでレビューする

Kubernetesの事故は、YAMLを手元で作った瞬間ではなく、Pull Requestで誰も気づかずに本番へ入った瞬間に起きます。最低限、CIで構文とdry-runを確認し、Claude Codeには差分レビューの観点を出させます。

name: Kubernetes manifest review

on:
  pull_request:
    paths:
      - "k8s/**"

jobs:
  dry-run:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: azure/setup-kubectl@v4
        with:
          version: "v1.30.0"
      - name: Client-side dry run
        run: kubectl apply --dry-run=client -f k8s/

CIの後にClaude Codeへ渡すレビュー指示は次のようにします。

このPull Requestのk8s/配下だけをレビューしてください。
特に以下を確認してください。
- Secretの実値やbase64化した秘密値がコミットされていないか
- Deploymentのselector、template labels、Service selectorが一致しているか
- readinessProbeとlivenessProbeがあり、pathとportが実際のアプリに合うか
- resources.requestsとlimitsが設定されているか
- Ingressが環境固有のannotationを勝手に増やしていないか
- rollout失敗時のrollback手順がREADMEにあるか

よくある失敗と避け方

1つ目は、latest タグを本番に使うことです。どのイメージが動いているか追えなくなり、rollbackの意味が薄れます。Git SHAやリリース番号のタグを使いましょう。

2つ目は、readinessProbeとlivenessProbeを同じ意味で使うことです。readinessは「Serviceの通信先に入れてよいか」、livenessは「再起動すべきか」を判断します。DB一時障害でlivenessを落とすと、Pod再起動が連鎖することがあります。

3つ目は、resourcesを未設定にすることです。requestsがないとスケジューラは必要量を判断しにくく、limitsが極端だとOOMKilledやCPU throttlingを招きます。最初は小さく置き、実測で調整します。

4つ目は、Secretをbase64にしただけで安全だと思うことです。base64は暗号化ではありません。レビューでは「秘密値が見えないか」だけでなく「生成手順が安全か」も見ます。

5つ目は、Ingressを先に疑うことです。外から見えないときは、Pod、Service、port-forward、Ingressの順に切り分けます。Serviceで到達できないものはIngressでも直りません。

6つ目は、Claude Codeの生成物をそのまま本番へ入れることです。AIはクラスタの現実、予算、監査要件、既存のIngress Controllerを知りません。必ず公式ドキュメント、CI、レビュー、検証ログで補強してください。

研修・相談で実リポジトリへ落とし込む

この記事のYAMLは学習用の最小構成です。実務では、Dockerfile、イメージタグ、namespace設計、Ingress Controller、TLS、Secret管理、監視、権限、CI/CD、障害時の連絡フローまでつながります。個人で学ぶなら 無料チートシート と関連記事で十分始められます。チームで導入するなら、Claude Codeへの指示、CLAUDE.md、レビュー観点、CIゲート、rollback演習を同じルールにそろえる必要があります。

ClaudeCodeLabの Claude Code研修・導入相談 では、実際のリポジトリを見ながら、Kubernetesマニフェストの棚卸し、Secretの扱い、CIレビュー、Claude Codeプロンプト、チーム向けハンズオンまで整理できます。単発のYAML生成ではなく、チームが安全に変更を積み上げられる運用にすることが目的です。

実際に試した結果

この記事の手順は、ローカルクラスタで「apply、rollout status、Serviceへのport-forward、curl、存在しないイメージへの更新、rollout undo」という順番で確認する前提にしました。試してみると、初心者が一番つまずくのはIngressではなく、selectorとlabelの不一致、probeのpath間違い、Secretサンプルの扱いでした。Claude Codeには最初から「安全な公開範囲」「Secret禁止」「rollback確認」を書くほうが、後からYAMLを直すより速く、レビューもしやすくなります。

#Claude Code #Kubernetes #DevOps #コンテナオーケストレーション #インフラ
無料

無料PDF: Claude Code はじめてのチートシート

まずは無料PDFで基本コマンドと最初の使い方をまとめて確認してください。登録後はそのままテンプレート集や導入相談にも進めます。

スパムは送りません。登録情報は厳重に管理します。

Claude Codeを仕事で使える形にしませんか？

無料PDFで基礎を固めたあと、すぐ使えるテンプレート集で試し、必要なら業務自動化や導入相談まで進められます。

テンプレート集を見る 導入相談を見る
Masa

この記事を書いた人

Masa

Claude Codeの実務活用、導入設計、収益導線改善を検証しているエンジニア。10言語の技術メディアを運営中。

PR

関連書籍・参考図書

この記事のテーマに関連する書籍を楽天ブックスで探せます。

※ 当サイトは楽天市場のアフィリエイトプログラムに参加しています。上記リンクから商品をご購入いただくと、運営者に紹介料が支払われる場合があります。

関連記事

次に使える教材・相談

PROMPT 50
販売中 note

Claude Code プロンプトテンプレート集 50選

開発・レビュー・調査・資料作成ですぐ使える、コピペOKのプロンプト集です。

500円 noteで見る

教材一覧を見る

テンプレート・設定ガイド・Tips集