Skip to main content

CDK8S simple deployment

A practical example demonstrating how to manage kube resources through CDK8S and orbits.

Problem statement​

CDK8S is powerful for defining Kubernetes resources, but it lacks built-in support for programmatic deployment, rollback mechanisms, or exposing outputs. The Orbits CDK8S integration adds a model-driven orchestration layer, making CDK8S fully operational in automated workflows. With Cdk8sAgent from Orbits, you gain:

  • Programmatic deployment of your CDK8S charts;
  • Automatic rollback in case of deployment failure;
  • Pruning of obsolete resources removed from your charts;
  • Output support to expose selected resource values for use in other stacks or systems;
  • Fully customizable model-driven orchestrator.

Beyond deployment, Orbits enables you to:

  • Consistently deploy your charts with built-in rollback mechanisms → Example: If a deployment fails due to a misconfigured resource, Orbits will automatically revert to the previous stable state.

  • Extend your IaC logic, for example, by fetching the IP of a load balancer via SDK and updating your DNS provider → Example: After deploying an Ingress, Orbits can retrieve the LoadBalancer IP and automatically update a Route53 DNS record.

  • Trigger redeployments automatically in response to specific events → Example: When a secret in AWS Secrets Manager is rotated, Orbits can detect the change and redeploy affected charts to refresh the credentials.

This sample demonstrates the use of Orbits on a minimal CDK8S use case.

Prerequisites​

Clone this repository​

cd samples/cdk8s-deployment
  • Install node.js dependencies:
  npm i

Setup kube environment​

You'll need access to a Kubernetes environment.

  • kubectl must be installed and properly configured.

This sample will use your current Kubernetes context, so ensure you're connected to the correct cluster before running any commands.

Deployment​

  • Define your mongo url:
export ORBITS_DB__MONGO__URL=your-mongo-url
  • Deploy Cdk8s basic stack with the CLI:
orbits-cli actions run BasicAgent stackName=cdk8s-basic -f src/orbits/orbi.ts --local-worker

or run:

npx tsx src/orbits/orbi.ts

This command will:

  • Create a new Kubernetes namespace
  • Deploy a scheduled Job named hello-world that runs daily at 10:00 AM
  • Output the namespace and job names in the console

Verify the result​

Get the namespace:

kubectl get namespaces -l orbits/stackName=cdk8s-basic

Get the job:

export NS=$(kubectl get ns -l orbits/stackName=cdk8s-basic -o jsonpath='{.items[0].metadata.name}')

kubectl get all --namespace $NS -l orbits/stackName=cdk8s-basic

Note​

You can get the created namespace and job names using the CLI:

orbits-cli actions get -f '{"identity":"{\"stackName\":\"cdk8s-basic\"}", "actionRef":"BasicAgent"}' -o '{"createdAt":1}' -j | jq '.[0].result.namespace'
orbits-cli actions get -f '{"identity":"{\"stackName\":\"cdk8s-basic\"}", "actionRef":"BasicAgent"}' -o '{"createdAt":1}' -j | jq '.[0].result.cronJobName'

Cleanup​

To remove all deployed resources from both accounts:

export CDK8S_COMMAND=uninstall
orbits-cli actions run BasicAgent commandName=$CDK8S_COMMAND stackName=cdk8s-basic -f src/orbits/orbi.ts --local-worker

or run:

npx tsx src/orbits/orbi.ts

Project Structure​

├── src/
│   ├── orbits/
│   │   ├── orbi.ts # Main orchestration script
│   │   └── basic-agent.ts # Basic agent definition
│   └── cdk/ # CDK8S chart definitions
│       └── basic-cdk8s.ts # basic chart definition
├── package.json
└── README.md