CDK8s Applications

Define Kubernetes applications using Python instead of YAML. cdk8s (Cloud Development Kit for Kubernetes) is a CNCF Sandbox project that provides type-safe, programmable infrastructure for Kubernetes.

Overview

What is cdk8s?

• Define K8s resources using Python, TypeScript, JavaScript, Java, or Go
• Synthesizes to standard Kubernetes YAML manifests
• Works with any Kubernetes cluster (cloud-agnostic)
• Built on the same concepts as AWS CDK
• CNCF Sandbox project (GA since October 2021)

Key Benefits:

• Type Safety: Catch configuration errors at development time
• IDE Support: Autocomplete, inline docs, refactoring
• Reusability: Create custom constructs for common patterns
• Testability: Unit test infrastructure code
• Reduced Boilerplate: Intent-driven APIs vs verbose YAML

When to Use cdk8s:

• Complex applications with multiple microservices
• Multi-environment deployments (dev/staging/prod)
• Reusable component libraries
• Teams preferring code over YAML
• EKS deployments integrated with AWS CDK

Quick Start

Installation

# Install cdk8s CLI (requires Node.js 18+)
npm install -g cdk8s-cli

# Initialize Python project
cdk8s init python-app
cd my-cdk8s-app

# Install dependencies
pip install -r requirements.txt

Your First Application

#!/usr/bin/env python3
from constructs import Construct
from cdk8s import App, Chart
from cdk8s_plus_27 import Deployment, ContainerProps

class WebApp(Chart):
    def __init__(self, scope: Construct, id: str):
        super().__init__(scope, id)

        # Create deployment with 3 replicas
        deployment = Deployment(
            self, "web",
            replicas=3,
            containers=[
                ContainerProps(
                    image="nginx:1.21",
                    port=80
                )
            ]
        )

        # Expose as LoadBalancer service
        deployment.expose_via_service(port=80)

# Synthesize to YAML
app = App()
WebApp(app, "my-app")
app.synth()

Synthesize and Deploy

# Generate Kubernetes manifests
cdk8s synth

# Review generated YAML
cat dist/my-app.k8s.yaml

# Deploy to cluster
kubectl apply -f dist/

Core Concepts

Constructs Hierarchy

cdk8s uses three levels of constructs:

L1 Constructs (Low-Level)

• Auto-generated from Kubernetes API
• Direct mapping to K8s resources
• Full control, verbose syntax

from imports import k8s

k8s.KubeDeployment(
    self, "deployment",
    spec=k8s.DeploymentSpec(
        replicas=3,
        selector=k8s.LabelSelector(match_labels={"app": "web"}),
        template=k8s.PodTemplateSpec(...)
    )
)

L2 Constructs (High-Level - cdk8s-plus)

• Hand-crafted, intent-driven APIs
• Automatic relationship management
• Reduced boilerplate

from cdk8s_plus_27 import Deployment, ContainerProps

Deployment(
    self, "deployment",
    replicas=3,
    containers=[ContainerProps(image="nginx", port=80)]
)

L3 Constructs (Custom Abstractions)

• Your own reusable components
• Encapsulate organizational patterns

class WebService(Construct):
    def __init__(self, scope, id, image, replicas=3):
        super().__init__(scope, id)
        # Compose deployment + service + ingress

Apps and Charts

App: Root container for all charts Chart: Represents a single Kubernetes manifest file

app = App()

# Each chart → separate YAML file
dev_chart = MyChart(app, "dev", namespace="development")
prod_chart = MyChart(app, "prod", namespace="production")

app.synth()  # Generates dist/dev.k8s.yaml and dist/prod.k8s.yaml

Import Custom Resources

Import CRDs, Helm charts, and external definitions:

# Import Kubernetes API
cdk8s import k8s

# Import CRD from URL
cdk8s import https://raw.githubusercontent.com/aws-controllers-k8s/s3-controller/main/helm/crds/s3.services.k8s.aws_buckets.yaml

# Import Helm chart
cdk8s import helm:https://charts.bitnami.com/bitnami/redis@18.2.0

# Import from GitHub
cdk8s import github:crossplane/crossplane@0.14.0

Common Workflows

Workflow 1: Simple Web Application

from cdk8s import App, Chart
from cdk8s_plus_27 import Deployment, ConfigMap, EnvValue, ContainerProps

class WebApp(Chart):
    def __init__(self, scope, id):
        super().__init__(scope, id)

        # Configuration
        config = ConfigMap(
            self, "config",
            data={
                "DATABASE_HOST": "postgres.default.svc",
                "LOG_LEVEL": "info"
            }
        )

        # Deployment
        deployment = Deployment(
            self, "web",
            replicas=3,
            containers=[
                ContainerProps(
                    image="myapp:v1.0",
                    port=8080,
                    env_variables={
                        "DATABASE_HOST": EnvValue.from_config_map(
                            config, "DATABASE_HOST"
                 

...