{"id":6559,"library":"cdk8s","title":"CDK for Kubernetes (cdk8s)","description":"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.","status":"active","version":"2.70.55","language":"en","source_language":"en","source_url":"https://github.com/cdk8s-team/cdk8s-core.git","tags":["kubernetes","cdk","iac","infrastructure-as-code","declarative","cloud-native","devops"],"install":[{"cmd":"pip install cdk8s","lang":"bash","label":"Install core library"},{"cmd":"npm install -g cdk8s-cli","lang":"bash","label":"Install cdk8s CLI (requires Node.js)"}],"dependencies":[{"reason":"Core building block library for CDK applications.","package":"constructs","optional":false},{"reason":"Provides higher-level, opinionated abstractions for Kubernetes resources. 'XX' denotes the Kubernetes API version (e.g., cdk8s-plus-34).","package":"cdk8s-plus-XX","optional":true}],"imports":[{"symbol":"App","correct":"from cdk8s import App"},{"symbol":"Chart","correct":"from cdk8s import Chart"},{"symbol":"Construct","correct":"from constructs import Construct"},{"note":"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.","wrong":"from cdk8s import KubeDeployment","symbol":"KubeDeployment","correct":"from imports import k8s"}],"quickstart":{"code":"import os\nfrom constructs import Construct\nfrom cdk8s import App, Chart, IntOrString\nfrom imports import k8s # This directory is generated by 'cdk8s import k8s'\n\nclass MyChart(Chart):\n    def __init__(self, scope: Construct, id: str):\n        super().__init__(scope, id)\n\n        # Define a Kubernetes Deployment\n        k8s.KubeDeployment(self, \"my-deployment\",\n            spec=k8s.DeploymentSpec(\n                replicas=1,\n                selector=k8s.LabelSelector(\n                    match_labels={\"app\": \"my-app\"}\n                ),\n                template=k8s.PodTemplateSpec(\n                    metadata=k8s.ObjectMeta(\n                        labels={\"app\": \"my-app\"}\n                    ),\n                    spec=k8s.PodSpec(\n                        containers=[k8s.Container(\n                            name=\"my-container\",\n                            image=\"nginx:latest\",\n                            ports=[k8s.ContainerPort(container_port=80)]\n                        )]\n                    )\n                )\n            )\n        )\n\n        # Define a Kubernetes Service\n        k8s.KubeService(self, \"my-service\",\n            spec=k8s.ServiceSpec(\n                type=\"LoadBalancer\",\n                ports=[k8s.ServicePort(port=80, target_port=IntOrString.from_number(80))],\n                selector={\"app\": \"my-app\"}\n            )\n        )\n\napp = App()\nMyChart(app, \"my-cdk8s-app\")\napp.synth()","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<1.0"},{"fix":"Ensure Node.js and npm are installed globally via your preferred package manager (e.g., `npm install -g cdk8s-cli`).","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always install the `cdk8s-plus-XX` package that matches your target Kubernetes cluster's major API version to ensure compatibility.","message":"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.","severity":"breaking","affected_versions":"All versions of `cdk8s-plus`"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Update calls from `Duration.toISOString()` to `Duration.toIsoString()`.","message":"The deprecated API `Duration.toISOString()` has been removed. Use `Duration.toIsoString()` instead.","severity":"breaking","affected_versions":"Introduced in v1.0"},{"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.","message":"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`.","severity":"breaking","affected_versions":"cdk8s-plus < 2.0.0 to >= 2.0.0"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}