# 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](https://cdk8s.io/docs/latest/getting-started/#prerequisites).
Install the CDK8s CLI globally through npm:
```shell
$ 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:
```shell
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:
```shell
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`:
```python
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`:
```python
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`:
```json
{
"apiVersion": "samples.cdk8s.org/v1alpha1",
"kind": "PodCollection",
"metadata": {
"name": "my-collection"
},
"spec": {
"image": "paulbouwer/hello-kubernetes",
"count": 5
}
}
```
Compile your code:
```shell
# delete `main.test.ts` since it has some code that won't compile
$ rm -f main.test.*
# compile
$ npm run compile
```
And run:
```shell
$ node main.js input.json
```
<details>
<summary>STDOUT</summary>
```yaml
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: []
```
</details>
## `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).
```shell
$ 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:
```shell
$ curl -d @input.json http://localhost:8080
MANIFEST...
```
## License
Apache 2.0
Raw data
{
"_id": null,
"home_page": "https://github.com/cdk8s-team/cdk8s-operator.git",
"name": "cdk8s-operator",
"maintainer": null,
"docs_url": null,
"requires_python": "~=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Amazon Web Services",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/15/ad/37a0ed3d528cb46a9bfb42169503538bb1f0180fb64af51e822aacee7bd3/cdk8s_operator-0.1.325.tar.gz",
"platform": null,
"description": "# cdk8s-operator\n\n> Create Kubernetes CRD Operators using CDK8s Constructs\n\nThis is a multi-language (jsii) library and a command-line tool that allows you\nto create Kubernetes operators for CRDs (Custom Resource Definitions) using\nCDK8s.\n\n## Getting Started\n\nLet's create our first CRD served by a CDK8s construct using TypeScript.\n\n### Install CDK8s\n\nMake sure your system has the required CDK8s [prerequisites](https://cdk8s.io/docs/latest/getting-started/#prerequisites).\n\nInstall the CDK8s CLI globally through npm:\n\n```shell\n$ npm i -g cdk8s-cli\nInstalling...\n\n# Verify installation\n$ cdk8s --version\n1.0.0-beta.3\n```\n\n### Create a new CDK8s app\n\nNow, let's create a new CDK8s typescript app:\n\n```shell\nmkdir hello-operator && cd hello-operator\ngit init\ncdk8s init typescript-app\n```\n\n### Install cdk8s-operator\n\nNext, let's install this module as a dependency of our TypeScript project:\n\n```shell\nnpm install cdk8s-operator\n```\n\n### Construct\n\nWe will start by creating the construct that implements the abstraction. This is\nis just a normal CDK8s custom construct:\n\nLet's create a construct called `PodCollection` which represents a collection of\npods:\n\n`pod-collection.ts`:\n\n```python\nimport { Pod } from 'cdk8s-plus-17';\nimport { Construct } from 'constructs';\n\nexport interface PodCollectionProps {\n /** Number of pods */\n readonly count: number;\n /** The docker image to deploy */\n readonly image: string;\n}\n\nexport class PodCollection extends Construct {\n constructor(scope: Construct, id: string, props: PodCollectionProps) {\n super(scope, id);\n\n for (let i = 0; i < props.count; ++i) {\n new Pod(this, `pod-${i}`, {\n containers: [ { image: props.image } ]\n });\n }\n }\n}\n```\n\n### Operator App\n\nNow, we will need to replace out `main.ts` file with an \"operator app\", which is\na special kind of CDK8s app designed to be executed by the `cdk8s-server` CLI\nwhich is included in this module.\n\nThe `Operator` app construct can be used to create \"CDK8s Operators\" which are\nCDK8s apps that accept input from a file (or STDIN) with a Kubernetes manifest,\ninstantiates a construct with the `spec` as its input and emits the resulting\nmanifest to STDOUT.\n\nReplace the contents of `main.ts` with the following. We initialize an\n`Operator` app and then register a provider which handles resources of API\nversion `samples.cdk8s.org/v1alpha1` and kind `PodCollection`.\n\n`main.ts`:\n\n```python\nimport { Operator } from 'cdk8s-operator';\nimport { PodCollection } from './pod-collection';\n\nconst app = new Operator();\n\napp.addProvider({\n apiVersion: 'samples.cdk8s.org/v1alpha1',\n kind: 'PodCollection',\n handler: {\n apply: (scope, id, props) => new PodCollection(scope, id, props)\n }\n})\n\napp.synth();\n```\n\n> A single operator can handle any number of resource kinds. Simply call\n> `addProvider()` for each apiVersion/kind.\n\n## Using Operators\n\nTo use this operator, create an `input.json` file, e.g:\n\n`input.json`:\n\n```json\n{\n \"apiVersion\": \"samples.cdk8s.org/v1alpha1\",\n \"kind\": \"PodCollection\",\n \"metadata\": {\n \"name\": \"my-collection\"\n },\n \"spec\": {\n \"image\": \"paulbouwer/hello-kubernetes\",\n \"count\": 5\n }\n}\n```\n\nCompile your code:\n\n```shell\n# delete `main.test.ts` since it has some code that won't compile\n$ rm -f main.test.*\n\n# compile\n$ npm run compile\n```\n\nAnd run:\n\n```shell\n$ node main.js input.json\n```\n\n<details>\n <summary>STDOUT</summary>\n\n```yaml\napiVersion: \"v1\"\nkind: \"Pod\"\nmetadata:\n name: \"my-collection-pod-0-c8735c52\"\nspec:\n containers:\n - env: []\n image: \"paulbouwer/hello-kubernetes\"\n imagePullPolicy: \"Always\"\n name: \"main\"\n ports: []\n volumeMounts: []\n volumes: []\n---\napiVersion: \"v1\"\nkind: \"Pod\"\nmetadata:\n name: \"my-collection-pod-1-c89f58d7\"\nspec:\n containers:\n - env: []\n image: \"paulbouwer/hello-kubernetes\"\n imagePullPolicy: \"Always\"\n name: \"main\"\n ports: []\n volumeMounts: []\n volumes: []\n---\napiVersion: \"v1\"\nkind: \"Pod\"\nmetadata:\n name: \"my-collection-pod-2-c88d4268\"\nspec:\n containers:\n - env: []\n image: \"paulbouwer/hello-kubernetes\"\n imagePullPolicy: \"Always\"\n name: \"main\"\n ports: []\n volumeMounts: []\n volumes: []\n---\napiVersion: \"v1\"\nkind: \"Pod\"\nmetadata:\n name: \"my-collection-pod-3-c86866b1\"\nspec:\n containers:\n - env: []\n image: \"paulbouwer/hello-kubernetes\"\n imagePullPolicy: \"Always\"\n name: \"main\"\n ports: []\n volumeMounts: []\n volumes: []\n---\napiVersion: \"v1\"\nkind: \"Pod\"\nmetadata:\n name: \"my-collection-pod-4-c8b74b1d\"\nspec:\n containers:\n - env: []\n image: \"paulbouwer/hello-kubernetes\"\n imagePullPolicy: \"Always\"\n name: \"main\"\n ports: []\n volumeMounts: []\n volumes: []\n```\n\n</details>\n\n## `cdk8s-server`\n\nThis library is shipped with a program called `cdk8s-server` which can be used\nto host your operator inside an HTTP server. This server can be used as a\nsidecar container with a generic CRD operator (TBD).\n\n```shell\n$ PORT=8080 npx cdk8s-server\nListening on 8080\n- App command: node main.js\n- Request body should include a single k8s resource in JSON format\n- Request will be piped through STDIN to \"node main.js\"\n- Response is the STDOUT and expected to be a multi-resource yaml manifest\n```\n\nNow, you can send `input.json` over HTTP:\n\n```shell\n$ curl -d @input.json http://localhost:8080\nMANIFEST...\n```\n\n## License\n\nApache 2.0\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Create Kubernetes CRD Operators using CDK8s Constructs",
"version": "0.1.325",
"project_urls": {
"Homepage": "https://github.com/cdk8s-team/cdk8s-operator.git",
"Source": "https://github.com/cdk8s-team/cdk8s-operator.git"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ba4e219d8e7ec07b960b0f353043f28b6a878c111de03e272874fb3053975967",
"md5": "a99a6ec90604987af3841ea69f99b094",
"sha256": "61f2d564e6fb057ac0c759a2f8907a29245d667632fa3b1e5dcbd7c496fa4fe0"
},
"downloads": -1,
"filename": "cdk8s_operator-0.1.325-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a99a6ec90604987af3841ea69f99b094",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "~=3.8",
"size": 140041,
"upload_time": "2024-12-24T12:13:14",
"upload_time_iso_8601": "2024-12-24T12:13:14.727178Z",
"url": "https://files.pythonhosted.org/packages/ba/4e/219d8e7ec07b960b0f353043f28b6a878c111de03e272874fb3053975967/cdk8s_operator-0.1.325-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "15ad37a0ed3d528cb46a9bfb42169503538bb1f0180fb64af51e822aacee7bd3",
"md5": "a4f5c0d2003d93582dc01932755b3987",
"sha256": "a47971155808dd2fc21930c039e6e12b5683c38414c0836ba90fc0d36854034e"
},
"downloads": -1,
"filename": "cdk8s_operator-0.1.325.tar.gz",
"has_sig": false,
"md5_digest": "a4f5c0d2003d93582dc01932755b3987",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "~=3.8",
"size": 141183,
"upload_time": "2024-12-24T12:13:16",
"upload_time_iso_8601": "2024-12-24T12:13:16.565959Z",
"url": "https://files.pythonhosted.org/packages/15/ad/37a0ed3d528cb46a9bfb42169503538bb1f0180fb64af51e822aacee7bd3/cdk8s_operator-0.1.325.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-24 12:13:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cdk8s-team",
"github_project": "cdk8s-operator",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "cdk8s-operator"
}
JSON
