Docker and Kubernetes with Claude Code

Containerization configuration is high-boilerplate, low-creativity work. Writing a production-quality Dockerfile for a Node.js application involves the same decisions in almost every project:

• Base image selection and version pinning
• Multi-stage build setup to minimize final image size
• Non-root user configuration for security
• Layer caching optimization for faster builds
• Health check endpoint wiring

Claude Code handles that boilerplate reliably. The configuration that does require judgment is infrastructure-specific: cluster resource limits, network policies, storage class selection, and secret management strategies.

This guide covers what Claude Code generates, the correct workflow (application first, then containerize), and common patterns for production container setups.

What Claude Code generates

Dockerfiles

Claude Code generates Dockerfiles from a description of the application and its runtime requirements. The output quality is high for common stacks (Node.js, Python, Go, Java, Ruby).

A prompt like:

Generate a production Dockerfile for a Node.js 20 Express API:
- TypeScript source compiled to JavaScript
- Non-root user for runtime
- Multi-stage build (build stage, production stage)
- Health check endpoint at /health
- No dev dependencies in final image
- Node_modules cached separately from source

Produces a complete, production-appropriate Dockerfile with correct layer ordering for cache efficiency, a dedicated non-root user, and a HEALTHCHECK instruction.

docker-compose files

For local development and integration testing, Claude Code generates docker-compose.yml configurations that wire together application services, databases, and supporting infrastructure:

Generate a docker-compose.yml for local development with:
- API service (this Dockerfile)
- PostgreSQL 16 with persistent volume
- Redis 7 for session storage
- Adminer for database inspection
- Health check dependencies (API waits for PostgreSQL)
- Environment variable configuration via .env file

The depends_on with condition: service_healthy pattern is generated correctly when health checks are specified for database services.

Kubernetes manifests

Claude Code generates Kubernetes YAML for standard deployment patterns:

• Deployment, replica count, container spec, resource requests and limits
• Service, ClusterIP, LoadBalancer, or NodePort as specified
• HorizontalPodAutoscaler, CPU and memory targets
• ConfigMap, non-sensitive configuration
• Secret references, structure only. Actual secret values are yours to manage
• Ingress, TLS termination and host routing rules
• PersistentVolumeClaim, for stateful services

Helm charts

For teams using Helm for Kubernetes package management, Claude Code generates complete chart structures:

Generate a Helm chart for this application:
- Chart.yaml with appropriate metadata
- values.yaml with image, replicas, resources, ingress as configurable values
- Deployment, Service, and Ingress templates with values references
- _helpers.tpl with name and label helpers
- NOTES.txt with post-install instructions

The generated chart follows Helm best practices: values-driven templates, name helpers for consistent labeling, and appropriate use of .Release.Name for multi-instance deployability.

The workflow: application first, then containerize

The most common mistake when using Claude Code for containerization is asking it to generate Docker configuration before the application code is stable.

Containerization configuration reflects application requirements. If the application changes, the configuration changes.

Writing the Dockerfile first creates a second artifact to maintain in parallel with application development.

Step 1: Stabilize the application

The application should run locally without containers. Before moving to Step 2, confirm:

• Dependencies are declared (e.g., package.json, requirements.txt, go.mod)
• Environment variables are documented
• Start command is defined
• Health check endpoint exists and returns a 200 response

This is the minimum viable application contract that Claude Code translates into a container configuration.

Step 2: Generate the Dockerfile

With a running application, generate the Dockerfile:

The application is a [framework] [language] app with these characteristics:
- Entry point: [command]
- Port: [port]
- Environment variables: [list]
- Build step: [command]
- Runtime dependencies: [list]

Generate a production Dockerfile with multi-stage build, non-root user, and health check.

Run docker build on the generated Dockerfile and verify the resulting image starts correctly before proceeding.

Step 3: Generate docker-compose for development

Add the docker-compose.yml file for local development, wiring in databases and services the application requires. Test the full local stack with docker compose up before proceeding.

Step 4: Generate Kubernetes manifests

With working container images, generate the Kubernetes deployment configuration. Specify your cluster context in the prompt:

• Cloud provider (EKS, GKE, AKS, k3s)
• Ingress controller (nginx, traefik, etc.)
• Storage class name
• Deployment method (kubectl apply or helm upgrade)

Step 5: Generate environment-specific overlays

Production Kubernetes configurations differ from staging. Claude Code generates Kustomize overlays or Helm values files for each environment:

Generate Kustomize overlays for staging and production that differ in:
- Replica count (staging: 1, production: 3)
- Resource limits (staging: 256Mi/0.25 CPU, production: 1Gi/1 CPU)
- Ingress host (staging.example.com vs example.com)
- Environment-specific ConfigMap values

Common generated patterns

Multi-stage builds

Multi-stage builds are generated correctly when requested. The pattern separates build dependencies from the runtime image, reducing final image size significantly for compiled languages.

Claude Code generates the builder stage with the full build toolchain and the runtime stage with only the compiled artifacts and runtime dependencies. For a TypeScript API, this means the TypeScript compiler and devDependencies exist only in the build stage and are not present in the final image.

Health checks

HEALTHCHECK instructions in Dockerfiles and Kubernetes livenessProbe/readinessProbe configurations are generated together when requested.

The distinction matters in production:

• livenessProbe failure → pod is restarted (a restart loop is an incident)
• readinessProbe failure → pod is removed from load balancer rotation (safer, non-destructive)

Claude Code generates appropriate probe configurations when given the health check endpoint path and expected response code.

Resource limits and requests

Kubernetes resource management (requests and limits) is one of the most commonly skipped configurations in manually written manifests. Claude Code generates both when asked.

A prompt that includes "use appropriate resource limits for a low-to-medium traffic API" produces reasonable starting values with a comment noting they should be adjusted based on observed metrics from your actual workload.

Non-root users

Running containers as root is a security anti-pattern. Claude Code generates non-root user setup, creating a dedicated user in the Dockerfile and switching to it before the CMD instruction, when requested explicitly or when "production" is mentioned in the prompt.

Generated vs manual comparison

What needs human judgment

• Secret management architecture. Claude Code generates Kubernetes Secret references and can generate SealedSecret or External Secrets Operator configurations when specified. The decision of which secrets management system fits your organization, HashiCorp Vault, AWS Secrets Manager, GCP Secret Manager, Sealed Secrets, is architectural and must be made before generation.

• Network policies. Default Kubernetes installations allow all pod-to-pod communication. Network policies restricting east-west traffic require understanding your service dependency graph. Claude Code generates NetworkPolicy YAML from a specified dependency list, but the list must be accurate.

• Storage class selection. PersistentVolumeClaim configurations reference a storage class. The available storage classes depend on your cluster provider. Specify the storageClassName explicitly. Claude Code does not know which storage classes exist in your cluster.

• Registry and image pull secret configuration. Generated manifests reference image names. For private registries, imagePullSecrets must be configured and referenced. Claude Code generates the imagePullSecrets reference structure but the actual credentials are infrastructure-specific.

Frequently asked questions

Can Claude Code generate GitHub Actions workflows for Docker builds and Kubernetes deployments?

Yes. CI/CD pipeline generation is well within Claude Code’s capability. Specify your registry (Docker Hub, ECR, GCR, GHCR), your deployment method (kubectl apply, helm upgrade, Argo CD sync), and your environment promotion strategy.

Claude Code generates the workflow YAML including build, tag, push, and deploy steps. The CI/CD pipeline guide covers this topic in full detail.

Does Claude Code handle Docker Compose version differences?

Claude Code generates docker-compose files in the current Compose file format (no version key required as of Compose v2). If your environment requires a specific older format, specify the version constraint in the prompt.

How does Claude Code handle stateful services in Kubernetes?

StatefulSets, headless services, and PersistentVolumeClaims for stateful workloads (databases, message queues, caches) are generated correctly when the stateful nature of the service is specified. Include the storage requirements, replica count, and whether the service requires stable network identities in the prompt.

What Kubernetes distributions does Claude Code generate for?

Generated manifests target standard Kubernetes API versions and work across distributions (EKS, GKE, AKS, k3s, OpenShift). OpenShift has additional security constraints (SecurityContextConstraints) that are not generated by default.

Specify "OpenShift" in the prompt to get SecurityContext and SCC-appropriate configurations.

Ready to containerize your application?

The workflow above applies to most containerization projects. The generated vs manual table tells you where generated output needs additional review.

For security considerations specific to containerized applications, the security best practices guide covers container security alongside application-level patterns. Teams running production container infrastructure at scale should also see the enterprise development guide.

Path one: containerize it yourself. Follow the application-first workflow, generate configuration in the order above, and use the comparison table to identify which generated components need the most review before production deployment.

Path two: work with Phos AI Labs. We set up production container infrastructure using Claude Code as part of a structured engagement. Application analysis, Dockerfile generation, Kubernetes manifest creation, CI/CD pipeline setup, and deployment verification are handled together. Book a discovery call.