Claude Code Kubernetes Deployment Guide: Safe YAML, Rollouts, and Rollbacks

Make Kubernetes Output Reviewable

Kubernetes runs containerized applications across a cluster, but the first real obstacle is not the cluster itself. It is the number of resource types a beginner has to understand at once: Deployment, Service, Ingress, ConfigMap, Secret, probes, resource requests, rollout history, and rollback. If you ask Claude Code to “generate Kubernetes YAML” without boundaries, it may produce something that looks plausible but misses health checks, uses latest, exposes the wrong Service type, or places fake secrets directly in Git.

The practical goal is different: use Claude Code to scaffold a safe beginner deployment, then review the diff like production infrastructure. This guide uses a tiny NGINX app with a ConfigMap-backed page, so you can copy the manifest into kind, minikube, Docker Desktop Kubernetes, or a disposable test cluster without building a private image first. Once the flow is clear, replace the image and probes with your real app.

Keep the official Kubernetes docs open while adapting the example: Deployments, Services, Ingress, liveness and readiness probes, resource management, ConfigMaps, Secrets, and kubectl rollout. For adjacent ClaudeCodeLab material, pair this with Docker integration, CI/CD setup, Claude Code code review, and permissions guide.

Real Use Cases

Start with a small, reversible deployment before designing a large platform. The point is to learn what Kubernetes will do when the manifest is correct, when the image is broken, and when you need to roll back under pressure.

Use case	Business goal	What Claude Code should draft
First internal tool deployment	Put one web app behind a stable Service	Deployment, ClusterIP Service, probes, requests and limits
Training cluster or workshop	Let every learner run the same commands	Namespaced manifest, verification commands, failure exercise
Pre-production manifest review	Catch risky YAML before release	Selector checks, Secret checks, probe checks, Ingress notes
Pull Request review gate	Stop broken infrastructure changes early	kubectl --dry-run, CI workflow, review checklist

This is also a monetizable article topic because the reader is not only looking for definitions. They want to avoid a production mistake. ClaudeCodeLab connects this kind of guide to the free cheatsheet, implementation templates, and Claude Code training and consultation for teams that want the same workflow adapted to their repository.

Prompt Claude Code With Constraints

Give Claude Code both the target and the boundaries. In Kubernetes, unclear prompts often create unsafe defaults: LoadBalancer where you only wanted local testing, plaintext Secret examples, cluster-wide RBAC, or Ingress annotations that match somebody else’s environment.

Create a beginner-friendly Kubernetes deployment that can be tested locally.

Requirements:
- namespace: claude-k8s-demo
- use nginx:1.27-alpine, not a private registry image
- include a ConfigMap that provides one HTML page
- Deployment has replicas 2, RollingUpdate, readinessProbe, livenessProbe, and resources
- Service is ClusterIP
- Ingress is optional and uses host claude-k8s.local
- explain the Secret policy without committing a real Secret
- include kubectl apply, rollout status, port-forward, failure, and rollback commands

Constraints:
- do not use NodePort or LoadBalancer
- do not write real Secret values into YAML
- do not create ClusterRole, ClusterRoleBinding, or destructive namespace cleanup commands

The value of this prompt is not its length. It names the review surface. A reviewer can check whether the selectors match, whether probes point to real ports, whether resources are present, and whether the Secret policy avoids Git leaks. If you repeat this often, move the stable parts into CLAUDE.md; see CLAUDE.md best practices for that operating pattern.

Copy-Paste Starter Manifest

Save the following as k8s/claude-k8s-demo.yaml. The Ingress object can be applied even if you do not use it immediately, but browser access through claude-k8s.local requires an Ingress controller such as nginx and local DNS or hosts-file setup. The Service path works everywhere through 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="en">
      <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

The most important beginner check is label matching. spec.selector.matchLabels, the Pod template labels, and the Service selector must point to the same app. If those values drift, the Deployment cannot manage the intended Pods or the Service has no endpoints. Ask Claude Code to review those three fields explicitly.

Verify Locally

Apply the file only after kubectl cluster-info points at the cluster you intend to use. Then run the workflow in this order.

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

Open another terminal and check the response.

curl http://localhost:8080/

If your cluster has an Ingress controller, inspect the Ingress separately. Do not debug Ingress first. Prove the Pod works, prove the Service reaches it, then debug host routing.

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

ConfigMap and Secret Rules

A ConfigMap stores non-sensitive configuration. In the demo it carries APP_ENV and the static index.html. It is acceptable for text that can live in Git. It is not acceptable for database passwords, API tokens, session keys, signing secrets, or private webhook secrets.

A Kubernetes Secret is intended for sensitive values, but it is not a reason to commit secrets. Standard Secret manifests often contain base64-encoded values; base64 is encoding, not encryption. For production, use the secret-management approach your platform supports, such as a cloud Secret Manager, External Secrets, Sealed Secrets, SOPS, or an internal vault process. Make the policy explicit before Claude Code writes any YAML.

For local practice, generate a local-only Secret file and ignore it.

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

The instruction to Claude Code should say: do not generate real Secret values, do not commit .env or secret.local.yaml, and document how production secrets are injected. Without that boundary, an AI assistant may helpfully create an unsafe example that later gets copied into a repository.

Practice Rollout and Rollback

A Deployment is useful because it controls updates. First run a harmless image update and inspect history.

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

Then create a controlled failure by pointing the Deployment at a tag that does not exist.

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

When you see ImagePullBackOff, undo the rollout.

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

This exercise matters because rollback is not only a command. You also need to know whether the bad change included ConfigMaps, Secrets, database migrations, feature flags, or DNS changes. Ask Claude Code to write the rollback note with both “what rolls back” and “what does not roll back.”

Add a CI Review Gate

Infrastructure failures often enter through ordinary Pull Requests. A small CI gate catches syntax mistakes, and a Claude Code review prompt catches risky intent.

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/

Use this review prompt after CI.

Review only the k8s/ changes in this Pull Request.
Check for:
- real or base64-encoded secrets committed to Git
- Deployment selector, Pod labels, and Service selector mismatch
- missing readinessProbe or livenessProbe
- probes that point to the wrong path or port
- missing resources.requests or unreasonable limits
- Ingress annotations that assume the wrong controller
- missing rollout and rollback instructions
Return findings first, ordered by severity, with file and line references.

Common Failure Cases

The first failure is using latest in production. It makes the running version unclear and weakens rollback. Prefer immutable tags such as a release number or Git SHA.

The second failure is treating readiness and liveness as the same probe. Readiness decides whether the Pod should receive traffic. Liveness decides whether the container should restart. If a temporary database issue fails liveness, you can trigger repeated restarts instead of simply removing the Pod from Service endpoints.

The third failure is omitting resources. Without requests, scheduling is harder to reason about. With limits that are too tight, you get OOMKilled or CPU throttling. Start conservative, measure, then adjust.

The fourth failure is assuming base64 equals security. It does not. Review the secret-generation process, not only the YAML.

The fifth failure is debugging Ingress before proving the Service works. Follow the path: Pod, Service, port-forward, then Ingress. If port-forward fails, Ingress cannot fix it.

The sixth failure is shipping Claude Code output without human review. The assistant does not know your budget, cluster policy, compliance rules, or existing controller setup unless you give that context.

Training and Consultation Path

The manifest in this article is intentionally small. Real production work adds Docker image builds, image tags, namespaces, TLS, controller-specific Ingress rules, secret management, observability, RBAC, CI/CD, incident notes, and team permissions. Solo developers can start with the free Claude Code cheatsheet and the linked articles. Teams should standardize prompts, CLAUDE.md, review checklists, rollback drills, and CI gates.

ClaudeCodeLab offers Claude Code training and implementation consultation for teams that want this workflow mapped to an actual repository. The useful deliverable is not a single YAML file. It is a repeatable way for the team to ask Claude Code for infrastructure changes, review them, test them, and roll them back safely.

What I Verified

The workflow in this guide is designed to be verified in this order: apply the manifest, wait for rollout status, list Pods, port-forward the Service, curl the page, change the image to a bad tag, observe the rollout failure, and undo the Deployment. In practice, the most common beginner mistakes are not advanced Kubernetes topics. They are selector and label mismatches, probe paths that do not exist, missing resources, and unsafe Secret examples. Writing those constraints into the first Claude Code prompt produces a much cleaner result than asking for generic Kubernetes YAML and fixing it later.