cdk8s-image

library0.2.770jsnpmunverified

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.

devops aws

npm install cdk8s-image

github ↗package ↗

INSTALL

IMPORT

SIG · CDK8S-IMAGE

cdk8s-image

devopsjavascriptv0.2.770

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Image

✓ import { Image } from 'cdk8s-image';

✗ const Image = require('cdk8s-image');

cdk8s-image is primarily designed for TypeScript and ESM environments. While CommonJS might technically work with transpilation, the idiomatic usage is ESM.

ImageProps

✓ import { ImageProps } from 'cdk8s-image';

Type import for configuring the Image construct. Always prefer type-only imports when possible to avoid bundling unnecessary code.

✓ import * as cdk8sImage from 'cdk8s-image';

✗ const cdk8sImage = require('cdk8s-image');

Wildcard import can be used to access all exported members under a namespace. Still, prefer named imports for better tree-shaking and clarity.

This example demonstrates how to build and push a local Docker image using the `Image` construct and then reference it in a Kubernetes `Deployment`.

import { App, Chart } from 'cdk8s'; import { Deployment, Container } from 'cdk8s-plus-27'; // Assuming cdk8s-plus-27 for Deployment/Container import { Image } from 'cdk8s-image'; import * as path from 'path'; const app = new App(); const chart = new Chart(app, 'my-chart'); // Create a dummy Dockerfile in a local directory for demonstration // In a real app, this directory would contain your actual application code and Dockerfile. const appDir = path.join(__dirname, 'my-app'); require('fs').mkdirSync(appDir, { recursive: true }); require('fs').writeFileSync(path.join(appDir, 'Dockerfile'), 'FROM alpine\nCMD echo "Hello from Docker!"'); const image = new Image(chart, 'my-app-image', { dir: appDir, registry: process.env.DOCKER_REGISTRY ?? 'localhost:5000', // Use localhost:5000 for local testing repository: 'my-org/my-app', tag: 'latest' }); new Deployment(chart, 'my-app-deployment', { replicas: 1, containers: [ new Container({ image: image.url, name: 'my-app-container', port: 8080 }) ], }); app.synth();

Debug

Known issues

breakingAs 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.

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.

affects: >=0.0.0

gotchaThe `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.

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.

affects: >=0.0.0

gotchaWhen `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.

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.

affects: >=0.0.0

gotchaThe `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.

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.

affects: >=0.0.0

Errors

Common errors & fixes

Error: Command failed: docker build -t ...

The Docker daemon is not running, or there's an issue with the Dockerfile or build context.

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.

Error: Command failed: docker push ... Get "http://localhost:5000/v2/": dial tcp 127.0.0.1:5000: connect: connection refused

The local Docker registry specified (e.g., `localhost:5000`) is not running or is inaccessible.

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.

Error: Cannot find module 'cdk8s-image'

The `cdk8s-image` package is not installed or not correctly linked in your project.

fix

Install the package: `npm install cdk8s-image` or `yarn add cdk8s-image`. Ensure your `tsconfig.json` paths are correctly configured if using aliases.

Upgrade

Version history

0.2.770latest on npm

Audit

Dependencies

cdk8srequiredPeer dependency for core CDK8s application constructs.

constructsrequiredPeer dependency for AWS Construct Library constructs.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/cdk8s-team/cdk8s-image ↗

packagehttps://www.npmjs.com/package/cdk8s-image ↗