{"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":"python","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,"search_vec":"'activ':63 'api':36 'app':46 'appli':55 'applic':30 'cdk':1,14,69 'cdk8s':4,17,18,45 'cloud':11,77 'cloud-nat':76 'cluster':59 'code':74 'core':8 'declar':75 'defin':28 'develop':12,25 'devop':79 'framework':26 'frequent':66 'go':44 'iac':70 'infrastructur':72 'infrastructure-as-cod':71 'java':42 'kit':13 'kubernet':3,16,29,50,58,68 'languag':38 'librari':9 'like':39 'maintain':64 'manifest':51 'nativ':78 'object':34 'object-ori':33 'open':22 'open-sourc':21 'orient':35 'project':61 'python':40 'releas':67 'rich':32 'softwar':24 'sourc':23 'standard':49 'synthes':47 'typescript':41 'use':31","created_at":"2026-04-15T18:33:05.593962+00:00","updated_at":"2026-04-16T01:37:02.035369+00:00","problems":[{"fix":"As a workaround, configure your environment or `npm` to correctly route traffic through the proxy, or download the necessary Kubernetes API specifications manually and use them for local import. Ensure that Node.js and npm proxy configurations are correctly set up.","cause":"The `cdk8s import` command, which is part of the `cdk8s-cli` (written in TypeScript), often fails in environments requiring HTTP(S) requests to go through a network proxy because the underlying Node.js `http(s)` modules do not natively support standard `HTTP_PROXY` and `HTTPS_PROXY` environment variables.","error":"\"import\" does not work through a network proxy"},{"fix":"This was a known bug in older versions of `cdk8s` related to how `jsii-srcmak` generated package names. Ensure you are using the latest version of `cdk8s` and the `cdk8s-cli`. If the issue persists with custom CRDs, you might need to manually inspect the generated `package.json` files for name conflicts or consider importing CRDs individually with unique module names.","cause":"This error, often seen as 'Multiple Imports Fail To Synth', occurs when `cdk8s synth` fails due to name collisions within the generated Node.js packages, particularly when importing multiple Custom Resource Definitions (CRDs). The `jsii` kernel attempts to untar packages into a temporary directory, and a naming conflict (e.g., multiple packages named 'generated') causes the subsequent untar operations to fail silently or with an EBUSY error.","error":"jsii.errors.JavaScriptError: Caused by: Error: EBUSY: resource busy or locked, open '.../node_modules/generated/package.json'"},{"fix":"Verify the imported `constructs-go` module version. For example, if the error occurs with `v10`, try importing `github.com/aws/constructs-go/constructs/v3` or the version specified in the official `cdk8s` Go examples if it's different from the one you're using. Always refer to the official `cdk8s` documentation for the correct import paths and versions for your chosen language.","cause":"This specific error, often encountered when working with cdk8s in Go, indicates an incompatibility or missing type definition for `constructs.ConstructOptions`. This typically happens due to version mismatches between the `cdk8s` library, `constructs-go` library, or outdated documentation examples referencing types that have been moved or deprecated in newer versions.","error":"undefined: constructs.ConstructOptions"},{"fix":"Ensure that the `containers` property is correctly specified within the `spec.template.spec` object of your `Deployment` construct. If using `cdk8s-plus`, make sure to follow its API for defining containers, as the structure might abstract the underlying Kubernetes API slightly. Double-check the nesting of your resource definition.","cause":"This Kubernetes validation error occurs when a `Deployment` (or other workload resource) is defined without specifying any containers within its pod template. While the user might have intended to add containers, they might be placed incorrectly within the CDK8s construct's properties, or the API structure for defining containers in `cdk8s-plus` might be misunderstood.","error":"PodSpec must have at least 1 container"},{"fix":"This issue was addressed in `cdk8s` by improving the name generation logic to conform to DNS_LABEL standards. Ensure you are using an up-to-date version of `cdk8s`. If you encounter this with specific constructs, you might need to provide shorter, explicit names for your constructs or their parent scopes to reduce the length of the generated resource names.","cause":"This error occurs when automatically generated resource names (e.g., for Deployments, Services) by cdk8s exceed the Kubernetes DNS_LABEL character limit of 63 characters or contain invalid characters/patterns. This is particularly problematic for long construct paths which contribute to the generated resource name.","error":"a DNS-1123 label must consist of lower case alphanumeric characters or '-', and must start and end with an alphanumeric character"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"2.70.75","cli_name":"cdk8s","cli_version":"sh: 1: cdk8s: not found","type":"library","homepage":"https://cdk8s.io","github":"https://github.com/cdk8s-team/cdk8s-core.git","docs":null,"changelog":null,"pypi":"https://pypi.org/project/cdk8s/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops","aws"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":null}}