{"id":12948,"library":"cdk8s-image","title":"CDK8s Image Builder & Pusher","description":"cdk8s-image is a library that provides a CDK8s construct for building Docker images from a local Dockerfile and pushing them to a specified container registry, all within the context of a CDK8s application. This allows developers to define container images as part of their Kubernetes application infrastructure using familiar programming languages. The current stable version is `0.2.746`, with releases occurring frequently, often multiple times a month, indicating active development. Its key differentiator is the seamless integration of Docker image lifecycle management directly into the CDK8s synthesis process, eliminating the need for separate CI/CD steps for image building when defining Kubernetes resources.","status":"active","version":"0.2.746","language":"javascript","source_language":"en","source_url":"https://github.com/cdk8s-team/cdk8s-image","tags":["javascript","cdk8s","containers","docker","kubernetes","typescript"],"install":[{"cmd":"npm install cdk8s-image","lang":"bash","label":"npm"},{"cmd":"yarn add cdk8s-image","lang":"bash","label":"yarn"},{"cmd":"pnpm add cdk8s-image","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for core CDK8s application constructs.","package":"cdk8s","optional":false},{"reason":"Peer dependency for AWS Construct Library constructs.","package":"constructs","optional":false}],"imports":[{"note":"cdk8s-image is primarily designed for TypeScript and ESM environments. While CommonJS might technically work with transpilation, the idiomatic usage is ESM.","wrong":"const Image = require('cdk8s-image');","symbol":"Image","correct":"import { Image } from 'cdk8s-image';"},{"note":"Type import for configuring the Image construct. Always prefer type-only imports when possible to avoid bundling unnecessary code.","symbol":"ImageProps","correct":"import { ImageProps } from 'cdk8s-image';"},{"note":"Wildcard import can be used to access all exported members under a namespace. Still, prefer named imports for better tree-shaking and clarity.","wrong":"const cdk8sImage = require('cdk8s-image');","symbol":"*","correct":"import * as cdk8sImage from 'cdk8s-image';"}],"quickstart":{"code":"import { App, Chart } from 'cdk8s';\nimport { Deployment, Container } from 'cdk8s-plus-27'; // Assuming cdk8s-plus-27 for Deployment/Container\nimport { Image } from 'cdk8s-image';\nimport * as path from 'path';\n\nconst app = new App();\nconst chart = new Chart(app, 'my-chart');\n\n// Create a dummy Dockerfile in a local directory for demonstration\n// In a real app, this directory would contain your actual application code and Dockerfile.\nconst appDir = path.join(__dirname, 'my-app');\nrequire('fs').mkdirSync(appDir, { recursive: true });\nrequire('fs').writeFileSync(path.join(appDir, 'Dockerfile'), 'FROM alpine\\nCMD echo \"Hello from Docker!\"');\n\nconst image = new Image(chart, 'my-app-image', {\n  dir: appDir,\n  registry: process.env.DOCKER_REGISTRY ?? 'localhost:5000', // Use localhost:5000 for local testing\n  repository: 'my-org/my-app',\n  tag: 'latest'\n});\n\nnew Deployment(chart, 'my-app-deployment', {\n  replicas: 1,\n  containers: [\n    new Container({\n      image: image.url,\n      name: 'my-app-container',\n      port: 8080\n    })\n  ],\n});\n\napp.synth();","lang":"typescript","description":"This example demonstrates how to build and push a local Docker image using the `Image` construct and then reference it in a Kubernetes `Deployment`."},"warnings":[{"fix":"Always pin to exact versions or thoroughly test when upgrading `cdk8s-image` within the same minor version. Refer to the GitHub changelog for specific changes.","message":"As a 0.x.x version package, `cdk8s-image` does not adhere to semantic versioning guarantees. Minor and patch releases can introduce breaking changes without a major version bump.","severity":"breaking","affected_versions":">=0.0.0"},{"fix":"Ensure Docker is running and properly configured (e.g., login to private registries) in the environment where `cdk8s synth` is executed. Verify network connectivity to your target container registry.","message":"The `Image` construct requires a running Docker daemon and connectivity to the specified registry during the CDK8s synthesis process. Failures in Docker operations (e.g., daemon not running, registry inaccessible, build errors) will cause the `cdk8s synth` command to fail.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"For production, use a fully qualified domain name (FQDN) for the registry that is accessible from your Kubernetes cluster and CI/CD environment. Ensure authentication is handled for private registries.","message":"When `registry` is set to `localhost:5000`, it implies a local Docker registry is expected. This setup is common for local development but may not be suitable for production CI/CD pipelines without proper configuration.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Double-check the `dir` path to ensure it correctly points to the directory containing your `Dockerfile`. Ensure the user executing `cdk8s synth` has read access to this directory.","message":"The `dir` property for the `Image` construct specifies the context directory for the Docker build. Incorrectly pointing this to a directory without a valid `Dockerfile` or with permission issues will lead to build failures.","severity":"gotcha","affected_versions":">=0.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure your Docker daemon is running (`systemctl start docker` or `open --background /Applications/Docker.app`). Check the specified `dir` for a valid `Dockerfile` and review Docker build logs for specific errors.","cause":"The Docker daemon is not running, or there's an issue with the Dockerfile or build context.","error":"Error: Command failed: docker build -t ..."},{"fix":"Start your local Docker registry (`docker run -d -p 5000:5000 --restart always --name registry registry:2`) or ensure the specified registry is correct and accessible.","cause":"The local Docker registry specified (e.g., `localhost:5000`) is not running or is inaccessible.","error":"Error: Command failed: docker push ... Get \"http://localhost:5000/v2/\": dial tcp 127.0.0.1:5000: connect: connection refused"},{"fix":"Install the package: `npm install cdk8s-image` or `yarn add cdk8s-image`. Ensure your `tsconfig.json` paths are correctly configured if using aliases.","cause":"The `cdk8s-image` package is not installed or not correctly linked in your project.","error":"Error: Cannot find module 'cdk8s-image'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}