How CDK8s Works: A Client-Side Rendering Engine

Not What You Might Expect

CDK8s is easy to misunderstand at first. It is not an Infrastructure as Code tool like Terraform or Pulumi that talks to cloud APIs and manages remote state. It does not connect to your Kubernetes cluster. It does not create, update, or delete any resources.

CDK8s is a purely client-side code-to-YAML compiler. Think of it like a template engine, but instead of a templating language like Jinja or Helm's Go templates, you use a full programming language.

The workflow has four distinct phases:

1. Code: You write infrastructure definitions in Python, TypeScript, Go, or Java using object-oriented classes provided by CDK8s.
2. Synthesize: You run cdk8s synth. CDK8s executes your code locally and renders the output.
3. Artifact: The tool writes standard Kubernetes YAML files into a dist/ directory. These files are identical to what you would write by hand—CDK8s adds no proprietary annotations or runtime dependencies.
4. Apply: You deploy those manifests using any standard tool: kubectl apply -f dist/, ArgoCD, Flux, or any CI/CD pipeline that accepts YAML.

This separation is architecturally significant. CDK8s owns the definition phase. Your existing deployment tooling owns the delivery phase. You do not need to replace anything—you just replace handwritten YAML with generated YAML.

The Power of Strong Typing

Because you are using a real programming language, you gain capabilities that are impossible in YAML:

• Autocomplete: Your IDE knows the exact shape of a DeploymentSpec. It will suggest valid fields and warn you about unknown ones.
• Type validation at write time: You cannot pass a string where an integer is expected. The code will fail before you ever run synth.
• Logic and loops: Need to create 10 ConfigMaps with slightly different values? Write a for loop. In YAML, you would copy-paste 10 times.
• Unit testing: You can write PyTest or Jest tests that assert "every Deployment in this chart has a liveness probe" and run them in CI before any YAML is generated.
• Reusable libraries: Package your infrastructure patterns as versioned Python packages or npm modules and share them across teams.

The App and Chart Model

CDK8s organizes code around two core concepts:

• App: The root of your CDK8s program. It represents the entire synthesis run and can contain multiple Charts.
• Chart: A logical grouping of Kubernetes resources that will be synthesized into a single YAML file. Think of it as the equivalent of a Helm chart, but defined in code. Each Chart maps to one output file in dist/.

A minimal CDK8s program always ends with app.synth(), which triggers the rendering of all Charts into their YAML files.