CDK for Kubernetes (cdk8s)

2.70.55 · active · verified Wed Apr 15

This is the core library of Cloud Development Kit (CDK) for Kubernetes (cdk8s). cdk8s is an open-source software development framework for defining Kubernetes applications using rich object-oriented APIs in languages like Python, TypeScript, Java, and Go. cdk8s apps synthesize into standard Kubernetes manifests which can be applied to any Kubernetes cluster. The project is actively maintained, with frequent releases.

Warnings

breaking Auto-generated resource names changed between v0.x and v1.0/v2.x. Deploying new manifests with different hashing could cause existing Kubernetes resources to be replaced, leading to downtime or unexpected behavior.
Fix: During migration, you can temporarily opt into the legacy hashing mechanism by setting the environment variable `CDK8S_LEGACY_HASH=1`. It is recommended to update resource names and remove this temporary fix once migrated.
gotcha The `cdk8s-cli` tool, essential for project initialization (`init`), generating API constructs (`import`), and synthesizing manifests (`synth`), is written in TypeScript and requires Node.js and npm to be installed globally on your system, even for Python projects.
Fix: Ensure Node.js and npm are installed globally via your preferred package manager (e.g., `npm install -g cdk8s-cli`).
gotcha Kubernetes API objects (e.g., `KubeDeployment`, `KubeService`) are not directly available from the `cdk8s` library package. They are generated into a local `imports` directory by running the `cdk8s import k8s` command. This `imports` directory must be committed to your source control.
Fix: After initializing a project, run `cdk8s import k8s` in your project directory. This will create an `imports` folder with the generated type-safe Kubernetes API constructs. Then, import them with `from imports import k8s`.
breaking The `cdk8s-plus` library, which provides higher-level abstractions, is versioned per Kubernetes API version (e.g., `cdk8s-plus-34` for Kubernetes 1.34) and is only actively maintained for the three latest Kubernetes releases. Using a `cdk8s-plus` version incompatible with your target cluster can lead to invalid manifests.
Fix: Always install the `cdk8s-plus-XX` package that matches your target Kubernetes cluster's major API version to ensure compatibility.
gotcha A significant portion of the official `cdk8s` documentation and examples are written for TypeScript. When working with Python, this can lead to confusion regarding property naming (TypeScript's camelCase vs. Python's snake_case) and API structure.
Fix: When in doubt, consult the Python API reference generated by `pydoc` (after `cdk8s import k8s`) or directly inspect the generated `imports/__init__.py` file for precise Python API details.
breaking The deprecated API `Duration.toISOString()` has been removed. Use `Duration.toIsoString()` instead.
Fix: Update calls from `Duration.toISOString()` to `Duration.toIsoString()`.
breaking The `cdk8s-plus` library introduced several breaking changes in its 2.0.0 release, including removal of `service.addDeployment`, renaming `service.serve` to `service.bind`, and changing `container.addEnv` to `container.env.addVariable`.
Fix: Refer to the specific `cdk8s-plus` changelog for detailed migration steps when upgrading to version 2.x or higher of the `cdk8s-plus` library.

Install

pip install cdk8s Install core library
npm install -g cdk8s-cli Install cdk8s CLI (requires Node.js)

Imports

App
```
from cdk8s import App
```
Chart
```
from cdk8s import Chart
```
Construct
```
from constructs import Construct
```
KubeDeployment
wrong:
```
from cdk8s import KubeDeployment
```
correct:
```
from imports import k8s
```
Kubernetes API objects like KubeDeployment are generated into an 'imports' directory by running `cdk8s import k8s` and are not directly part of the `cdk8s` PyPI package.

Quickstart

This quickstart demonstrates how to define a basic Kubernetes Deployment and Service using `cdk8s`. It requires installing the `cdk8s-cli` (via npm), initializing a project with `cdk8s init python-app`, running `cdk8s import k8s` to generate Kubernetes API constructs, and then placing this code in `main.py`. The `app.synth()` call generates the Kubernetes YAML manifests, which can then be applied to any Kubernetes cluster.

import os
from constructs import Construct
from cdk8s import App, Chart, IntOrString
from imports import k8s # This directory is generated by 'cdk8s import k8s'

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

        # Define a Kubernetes Deployment
        k8s.KubeDeployment(self, "my-deployment",
            spec=k8s.DeploymentSpec(
                replicas=1,
                selector=k8s.LabelSelector(
                    match_labels={"app": "my-app"}
                ),
                template=k8s.PodTemplateSpec(
                    metadata=k8s.ObjectMeta(
                        labels={"app": "my-app"}
                    ),
                    spec=k8s.PodSpec(
                        containers=[k8s.Container(
                            name="my-container",
                            image="nginx:latest",
                            ports=[k8s.ContainerPort(container_port=80)]
                        )]
                    )
                )
            )
        )

        # Define a Kubernetes Service
        k8s.KubeService(self, "my-service",
            spec=k8s.ServiceSpec(
                type="LoadBalancer",
                ports=[k8s.ServicePort(port=80, target_port=IntOrString.from_number(80))],
                selector={"app": "my-app"}
            )
        )

app = App()
MyChart(app, "my-cdk8s-app")
app.synth()

view raw JSON →