cdk8s-operator
Create Kubernetes CRD Operators using CDK8s Constructs
This is a multi-language (jsii) library and a command-line tool that allows you to create Kubernetes operators for CRDs (Custom Resource Definitions) using CDK8s.
Getting Started
Let's create our first CRD served by a CDK8s construct using TypeScript.
Install CDK8s
Make sure your system has the required CDK8s prerequisites.
Install the CDK8s CLI globally through npm:
$ npm i -g cdk8s-cli
Installing...
# Verify installation
$ cdk8s --version
1.0.0-beta.3
Create a new CDK8s app
Now, let's create a new CDK8s typescript app:
mkdir hello-operator && cd hello-operator
git init
cdk8s init typescript-app
Install cdk8s-operator
Next, let's install this module as a dependency of our TypeScript project:
npm install cdk8s-operator
Construct
We will start by creating the construct that implements the abstraction. This is is just a normal CDK8s custom construct:
Let's create a construct called PodCollection which represents a collection of
pods:
pod-collection.ts:
import { Pod } from 'cdk8s-plus-17';
import { Construct } from 'constructs';
export interface PodCollectionProps {
/** Number of pods */
readonly count: number;
/** The docker image to deploy */
readonly image: string;
}
export class PodCollection extends Construct {
constructor(scope: Construct, id: string, props: PodCollectionProps) {
super(scope, id);
for (let i = 0; i < props.count; ++i) {
new Pod(this, `pod-${i}`, {
containers: [ { image: props.image } ]
});
}
}
}
Operator App
Now, we will need to replace out main.ts file with an "operator app", which is
a special kind of CDK8s app designed to be executed by the cdk8s-server CLI
which is included in this module.
The Operator app construct can be used to create "CDK8s Operators" which are
CDK8s apps that accept input from a file (or STDIN) with a Kubernetes manifest,
instantiates a construct with the spec as its input and emits the resulting
manifest to STDOUT.
Replace the contents of main.ts with the following. We initialize an
Operator app and then register a provider which handles resources of API
version samples.cdk8s.org/v1alpha1 and kind PodCollection.
main.ts:
import { Operator } from 'cdk8s-operator';
import { PodCollection } from './pod-collection';
const app = new Operator();
app.addProvider({
apiVersion: 'samples.cdk8s.org/v1alpha1',
kind: 'PodCollection',
handler: {
apply: (scope, id, props) => new PodCollection(scope, id, props)
}
})
app.synth();
A single operator can handle any number of resource kinds. Simply call
addProvider()for each apiVersion/kind.
Using Operators
To use this operator, create an input.json file, e.g:
input.json:
{
"apiVersion": "samples.cdk8s.org/v1alpha1",
"kind": "PodCollection",
"metadata": {
"name": "my-collection"
},
"spec": {
"image": "paulbouwer/hello-kubernetes",
"count": 5
}
}
Compile your code:
# delete `main.test.ts` since it has some code that won't compile
$ rm -f main.test.*
# compile
$ npm run compile
And run:
$ node main.js input.json
STDOUT
apiVersion: "v1"
kind: "Pod"
metadata:
name: "my-collection-pod-0-c8735c52"
spec:
containers:
- env: []
image: "paulbouwer/hello-kubernetes"
imagePullPolicy: "Always"
name: "main"
ports: []
volumeMounts: []
volumes: []
---
apiVersion: "v1"
kind: "Pod"
metadata:
name: "my-collection-pod-1-c89f58d7"
spec:
containers:
- env: []
image: "paulbouwer/hello-kubernetes"
imagePullPolicy: "Always"
name: "main"
ports: []
volumeMounts: []
volumes: []
---
apiVersion: "v1"
kind: "Pod"
metadata:
name: "my-collection-pod-2-c88d4268"
spec:
containers:
- env: []
image: "paulbouwer/hello-kubernetes"
imagePullPolicy: "Always"
name: "main"
ports: []
volumeMounts: []
volumes: []
---
apiVersion: "v1"
kind: "Pod"
metadata:
name: "my-collection-pod-3-c86866b1"
spec:
containers:
- env: []
image: "paulbouwer/hello-kubernetes"
imagePullPolicy: "Always"
name: "main"
ports: []
volumeMounts: []
volumes: []
---
apiVersion: "v1"
kind: "Pod"
metadata:
name: "my-collection-pod-4-c8b74b1d"
spec:
containers:
- env: []
image: "paulbouwer/hello-kubernetes"
imagePullPolicy: "Always"
name: "main"
ports: []
volumeMounts: []
volumes: []
cdk8s-server
This library is shipped with a program called cdk8s-server which can be used
to host your operator inside an HTTP server. This server can be used as a
sidecar container with a generic CRD operator (TBD).
$ PORT=8080 npx cdk8s-server
Listening on 8080
- App command: node main.js
- Request body should include a single k8s resource in JSON format
- Request will be piped through STDIN to "node main.js"
- Response is the STDOUT and expected to be a multi-resource yaml manifest
Now, you can send input.json over HTTP:
$ curl -d @input.json http://localhost:8080
MANIFEST...
License
Apache 2.0
Release files for cdk8s-operator 0.1.468
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| cdk8s_operator-0.1.468.tar.gz | 128.1 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| cdk8s_operator-0.1.468-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 254.6 kB
Release files / cdk8s_operator-0.1.468.tar.gz
| Download URL | cdk8s_operator-0.1.468.tar.gz |
|---|---|
| Size | 128.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2a02e82ea7eb60dacb015f3592764e557705495aae3bbe6780d83111c8fe5fb1
|
|
BLAKE2b-256 checksum How to use checksums |
83ccd954c3daecac0f2b914d6913bf35eddc07e651518c177e476cd16e07fe70
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.14.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 1, 2026.
Transparency logRelease files / cdk8s_operator-0.1.468-py3-none-any.whl
| Download URL | cdk8s_operator-0.1.468-py3-none-any.whl |
|---|---|
| Size | 126.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4760a2ba98b09d003c229c1bb387ec66bd8a5e32edddfc0bcf8f60f1059d0621
|
|
BLAKE2b-256 checksum How to use checksums |
56d8d10c2090c3666a049b0194f748aacf7aff6b52cb6f7f7ef7b82c42d2a8a1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.14.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 1, 2026.
Transparency log
