DEV Community: Louis Dussarps

Orchestrating a stack of services across multiple environments

Louis Dussarps — Fri, 26 Sep 2025 13:23:04 +0000

In our previous blog post, we introduced the basics of orchestration and showed how to write a deployment workflow for a backend service.
Now, let’s take it further.
Imagine our web agencies manage web services across multiple tenants : one cloud instance per client. The stack includes several services, such as frontend, authentication, and backend. And it must support multi-tenant deployment.
This brings new challenges:

coordinating deployments across environments
sharing common resources (like a cloud account, a VPC, a database...) between services in the stack
handling failures and rollbacks
keeping each tenant isolated yet manageable To address this, we need to go beyond simple workflows and start managing state, transitions, shared resources, and deployment strategies. Let’s see how simple this becomes with Orbits.

From workflows to resources

In Orbits, a Workflow is a one-time execution: it runs, performs its actions, and then it's done. While this is useful, it's not enough when you want to manage stateful, reusable services across multiple environments or tenants.

Instead, Orbits introduces the concept of a Resource.

A Resource encapsulates both the identity of what you’re deploying and the logic for how to install, update, or manage it. Resources can be reused, composed, and tracked.

Defining a BaseResource

Giving an identity to our services

To manage multiple services per tenant, such as frontend and backend, we start by defining a BaseResource. This base class provides a common identity mechanism using the tenantId and a service-specific name. The identity() method uniquely identifies each resource instance, which allows Orbits to track, reconcile, and avoid duplicating shared resources.

export class BaseResource extends Resource{
  IArgument: {
    tenantId: string;
  };

  serviceName = 'base'

  identity() {
    return `${this.serviceName}-${this.argument.tenantId}`;
  }
}

Sharing a common installation step

Orbits ressources distinguish between the installation phase and the update phase. This allows precise control over what happens during first-time deployment versus subsequent updates.

We can implement shared setup, such as Git repository creation and cloud account provisioning, in the defineInstall() method of BaseResource:

export class BaseResource extends Resource{

  async defineInstall(){
    const createGit = new GitResource().setArgument({
      name : this.serviceName
    });
    const createAWS = new AWSResource().setArgument({
      id: this.tenantId
    });

    await Promise.all([
      this.do("git-install", createGit),
      this.do("aws-install", createAWS),
    ]);
  }
}

In this setup:

GitResource uses serviceName, so each service (frontend, backend) gets its own Git repository.
AWSResource uses tenantId, ensuring every services share the same cloud account for a given tenant : no duplicate account will be created.

Differentiating frontend and backend

Once the shared installation is abstracted, each service can implement its own logic tailored to its infrastructure and operational needs.
Here we modify the update step.

Backend resource

export class BackendResource extends BaseResource{

  declare serviceName = 'backend'

  async defineUpdate(){

    // Step 1: Deploy Infrastructure-as-Code
    const deploymentOutput = await this.do("iac-deploy", new BackCDKStack());

    // Step 2: Run SQL migrations inside the provisioned environment
    const migration = new RunSQLMigrations();
    migration.executor = new CloudExecutor(deploymentOutput.env);
    await this.do("sql-migrate", migration);
  }
}

Frontend resource

export class FrontendResource extends BaseResource{

  declare serviceName = 'frontend'

  async defineUpdate(){
    // Step 1: Deploy Infrastructure-as-Code
    const deploymentOutput = await this.do("iac-deploy", new FrontCDKStack());

    // Step 2: clear caches inside the provisioned environment
    await this.do("clear-cdn-cache", new CdnClearCacheAction().setArgument({
      cdnArn : deploymentOutput.cdnArn
    }));
  }
}

This pattern offers:

clear separation of concerns between services
reusability of common setup logic
flexibility for specialized behavior per service

Scaling to multiple tenants

Managing a stack

Now let’s define an application stack that orchestrates both frontend and backend services. This approach gives us control over the deployment order, error handling, and rollback strategy.
Below is a schematic version of what this orchestration might look like:

export class MyStack extends Resource{
  async defineUpdate(){
    //choose a deployment strategy
    //here we first deploy the frontend and then the backend.
    //could have done this in parellel
    const backendResource = new BackendResource().setArgument(this.argument);
    const frontendResource = new FrontendResource().setArgument(this.argument);
    try{
      await this.do("update-backend", backendResource);
      await this.do("update-frontend", frontendResource);
    }
    catch(err){
      //rollback to previous working commit
      await this.do("rollback-frontend", frontendResource.setCommand("rollback"))
      await this.do("rollback-backend", backendResource.setCommand("rollback"));
    }
  }
}

You could easily parallelize both deployments using Promise.all if the order doesn’t matter.

Managing multiple tenants

To scale across tenants, we define a Tenants resource that loops over each tenant and applies the stack. Failures are isolated and can be reported via Slack, email, or any other channel.


export class Tenants extends Resource{

  // you would likely fetch this from a database
  tenants = ["clientA", "clientB", "clientC"]

  async defineUpdate() {
    const failed = [];

    for (const tenantId of this.argument.tenants) {
      try {
        await this.do("update-tenant", new MyStack().setArgument({ tenantId }));
      } catch (err) {
        failed.push({ tenantId, error: err });
        // Optionally notify immediately, or collect all and notify later
      }
    }

    if (failed.length > 0) {
      await this.do("notify-failures", new SlackNotification().setArgument({ failures: failed }));
    }
  }

}

What Orbits takes care of under the hood

This simple syntax addresses common pain points in managing cloud services under the hood:

avoiding duplication: when multiple executions of a resource run in parallel, Orbits ensures the same final state without recreating resources unnecessarily. The orchestrator intelligently determines what needs updating, skipping, or preserving.
running scripts in different contexts : The concept of an executor provides a clean way to run specific actions within the right environment or context. Since infrastructure and scripts are managed together, it’s easy to target the exact environment where a command should execute.
safe error handling: Encapsulating orchestration logic in Resource enables rollback strategies when something fails mid-deployment.
multi-Tenant scalability: The Tenants resource allows applying the same stack logic across many clients, while isolating failures and surfacing them clearly.

Possible enhancements

This example provides a basic overview of how we manage multi-tenant deployments. Looking ahead, there are several potential improvements that can be explored:

we could implement more complex rollback strategies
we could implement drift detection via the cycle hook
we could share some resources accross tenants with the same concept of Resource

Wanna try Orbits? The complete documentation with samples and examples is available here. The source code is available in the github repository. Give it a spin!

Write your CI/CD in TypeScript

Louis Dussarps — Wed, 27 Aug 2025 14:25:52 +0000

If most CI/CD tools today are robust, the way we define scripts in them comes with a few drawbacks:

they have strong vendor lock-ins;
they are difficult to test and debug locally;
they all use a different syntax in YAML, which is difficult to extend and compose. For all these reasons, when the person who wrote them is not around, it’s not uncommon that teams don’t know what scripts do. They rarely evolve and their maintenance is hard.

Using code and native Node.js modules to write CI/CD could solve all these problems and comes with a lot of benefits:

it’s possible to debug locally. To avoid regressions, it's even possible to test the CI/CD with a normal testing framework;
it offers better reusability across projects and greater composability;
it uses code instead of configuration, making it easy to catch errors, manage retries, loops, and conditional logic;
it integrates seamlessly with the rich Node.js ecosystem.

Example: handle your CI/CD in Node.js with Orbits

This blog post will follow the simple deployment pipeline sample available on the github repository of orbits.

This sample deploys an AWS Lambda that will respond to a GET request with this architecture:

┌────────────────┐    ┌────────────────┐    ┌────────────────┐
│   cloudfront   │◄──►│   api gateway  │◄──►│   lambda       │
└────────────────┘    └────────────────┘    └────────────────┘

Our complete workflow is:

Format, lint and test our Lambda code
Deploy it to AWS using CDK and the orbits CDK helper
Clear the CloudFront cache
Check the deployed endpoint

Prerequisites

You'll need:

Access to one AWS account
Node.js and npm installed
MongoDB instance for orbits state management

Project Setup

# Clone the repository
git clone https://github.com/LaWebcapsule/orbits.git
cd samples/simple-deployment-pipeline

# Install dependencies
npm install

# Configure environment
export AWS_REGION=you-aws-region
export AWS_ACCOUNT=you-aws-account

# Install the CLI either globally or in your project
## globally
npm i @orbi-ts/cli -g

## in your project
npm i @orbi-ts/cli

# define your mongo_url
## default is mongodb://localhost:27017/orbits
export ORBITS_DB__MONGO__URL=your-mongo-url

Run the deployment workflow

From peeking at orbi.ts we see that DeployHelloWorkflow takes two arguments:

region: the AWS region
account: the AWS account

So running it is as easy as typing this command:

orbits-cli actions run -f src/orbits/orbi.ts --local-worker \
  DeployHelloWorkflow \
  region=$AWS_REGION \
  account=$AWS_ACCOUNT

Here is a video of the deployment:

We can get the result of the deploy action using the get method (provided its ID is 689de1b3fcb667fee45a4bfe):

➜ orbits-cli actions get 689de1b3fcb667fee45a4bfe
ID                       ┆ ACTION REF     ┆ STATE   ┆ RESULT                                                                                                                                                             ┆ LAST ACTIVITY ┆ NEXT ACTIVITY ┆ PARENT > REF
┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈
689de1b3fcb667fee45a4bfe ┆ LambdaResource ┆ SUCCESS ┆ {"CfId":"E28NIDFX6OEEC6","HelloAPIEndpointA3FBFD89":"https://fueo1zarcg.execute-api.eu-west-3.amazonaws.com/prod/","CfDomainName":"d16q083cvq1ymk.cloudfront.net"} ┆ —             ┆ in 7min 45s   ┆ 689de1b1fcb667fee45a4bc1 > deploy

With its ID, you can get the graphical view of an Action / Workflow at any moment:

orbits-cli actions watch <ACTION_ID>

With this in mind, you have a complete history of your deployment and can see precisely where it failed.

Debugging part of the workflow

In this section, we’ll introduce a failure in the Code Quality workflow and see how it shows up during execution.

First, here’s how our deployment workflow is defined:

import { Workflow } from '@orbi-ts/core';
import { CodeQualityWorkflow } from './code-quality';
import { InvalidateCacheAction } from './invalidate-cache';
import { LambdaResource } from './lambda-resource';
import { VerifyLambdaDeploymentAction } from './verify';

export class DeployHelloWorkflow extends Workflow {
    declare IArgument: Workflow['IArgument'] & {
        region: string;
        account: string;
    };

    async define() {
        await this.do('quality', new CodeQualityWorkflow());
        const result = await this.do(
            'deploy',
            new LambdaResource({
                region: this.argument.region,
                account: this.argument.account,
            })
        );

        await this.do(
            'invalidate cache',
            new InvalidateCacheAction().setArgument({
                distributionId: result.CfId,
                env: { region: this.argument.region },
            })
        );

        await this.do(
            'verify',
            new VerifyLambdaDeploymentAction().setArgument({
                endpoint: `https://${result.CfDomainName}`,
            })
        );
    }
}

Because we know the name of an action and its arguments, running it directly is very simple.

Let’s try running the Code Quality workflow. Since the DeployHelloWorkflow action doesn’t require arguments, we can run:

orbits-cli actions run CodeQualityWorkflow -f src/orbits/orbi.ts --local-worker

We get the following graphical view of the workflow — everything is green, no errors!

Now let’s make the handler fail the tests. We’ll modify the code as follows:

type HelloEvent = {
    queryStringParameters: {
        first_name?: string;
        last_name?: string;
    };
};

export const handler = async (
    event: HelloEvent
): Promise<{
    statusCode: number;
    body: string;
}> => {
    // const firstName = event.queryStringParameters.first_name;
    const firstName = 'Alice';
    const lastName = event.queryStringParameters.last_name;
    const now = new Date();
    return {
        statusCode: 200,
        body:
            `Hello ${[firstName, lastName].filter(Boolean).join(' ') || 'Guest'}, ` +
            `time is ${now.getUTCHours()}:${now.getUTCMinutes()}:${now.getUTCSeconds()} (UTC)`,
    };
};

When we re-run without exiting the process, the workflow fails and moves into the ERROR state. We can inspect the error in the logs, or view the result in the dedicated panel:

Let’s fix the test by restoring the original line:

const firstName = event.queryStringParameters.first_name;
// const firstName = 'Alice'; <-- remove this line

Now, in another terminal, we can replay the test action by its ID:

orbits-cli actions replay $ACTION_ID

Or replay the entire workflow starting from the test step:

orbits-cli actions replay $WORKFLOW_ID -p test

This time everything passes again — back to green ✅.

See it in action:

Going further

You can now write and integrate CI/CD workflows directly into your own project.
More than just workflows, orbits is especially useful when you want to share workflows across projects and tenants. Read our blog series about orchestration.
As the project grows, we plan to add more helper functions to quickly build your CI/CD. Stay up to date by following the github repository.

Wanna try it yourself? The complete example code and setup instructions are available in the github repository. Give it a spin!

Orchestrating end-to-end service deployment using TypeScript workflows

Louis Dussarps — Wed, 06 Aug 2025 11:01:21 +0000

In modern platform engineering, building a developer self-service portal isn’t just about provisioning — it’s about ensuring the entire golden path reliably completes, from infrastructure to runtime configuration.
Whether you're spinning up environments for feature previews or onboarding a new client, orchestration is the logic that holds everything together — especially when things go wrong.
Your orchestrator should let you observe state transitions and trigger specific commands accordingly—whether it's provisioning, reconciling drift, or handling failures.

Example: deploying a backend from scratch

Let’s walk through a typical use case for an agency or SaaS company: deploying a new backend environment for a client or project. This often involves:

Creating a dedicated cloud account
Creating a Git repository
Deploying infrastructure-as-code (e.g., CDK or Terraform)
Running SQL migrations in the target environment
Notifying the team of success or failure

Here’s how you would orchestrate that using Orbits, an openSource orchestration framework :

A Simple declarative workflow in TypeScript

export class DeployBackend extends Workflow {
    async define() {
        try {
            // Step 1: Create Git and Cloud resources in parallel
            const createGit = new CreateGitRepo();
            const createAWS = new CreateAWSAccount();

            await Promise.all([
                this.do('git-create', createGit),
                this.do('aws-create', createAWS),
            ]);

            // Step 2: Deploy Infrastructure-as-Code
            const deploymentOutput = await this.do(
                'iac-deploy',
                new DeployCDKStack()
            );

            // Step 3: Run SQL migrations inside the newly provisioned environment
            const migration = new RunSQLMigrations();
            migration.executor = new CloudExecutor(deploymentOutput.env);
            await this.do('sql-migrate', migration);
        } catch (err) {
            // Step 4: Handle errors with a notification
            await this.do(
                'notify-slack',
                new SendSlackAlert().setArgument(err)
            );
        }
    }
}

Advantages

Inheritance and code reuse

When managing multiple services (e.g., backend, frontend, authentication), it's common to share infrastructure logic—like creating a Git repository or provisioning a cloud account.

Orbits makes this easy by allowing you to extract shared logic into a base class:

export class BaseWorkflow extends Workflow {
    defineCreation() {
        const createGit = new CreateGitRepo();
        const createAWS = new CreateAWSAccount();

        await Promise.all([
            this.do('git-create', createGit),
            this.do('aws-create', createAWS),
        ]);
    }
}

You can then extend this base in specific workflows:

export class FrontendWorkflow extends BaseWorkflow {
    // Additional frontend-specific steps
}

By properly modeling shared resources, you can also ensure that different services (like frontend and backend) reuse the same AWS account rather than creating duplicates.

TypeScript ecosystem

Since Orbits is written in TypeScript, you can directly use SDKs from your providers (like the AWS SDK).
For example, in order to create an AWS account, you can just call:

const client = new OrganizationsClient();
client.send(
    new CreateAccountCommand({
        AccountName: name,
        Email: email,
    })
);

Test on local

All the orchestrator run inside your node.js process.
As a consequence, you can run and test your workflows locally, just like any other TypeScript code — enabling fast iteration and simplified debugging during development.

Going further

Check the orbits github repository
Explore the orbits documentation

Want to go further and orchestrate multiple tenants or environments? Check out our next post on managing a fleet of stacks with Orbits.

A lightweight alternative to Temporal for node.js applications

Louis Dussarps — Wed, 23 Jul 2025 12:17:36 +0000

Temporal is a great tool for building resilient applications, but it can be challenging to host and operate. Today, we’re introducing a Node.js framework, orbiTS, that installs like any other npm package and lets you build crash-resilient apps in TypeScript—with zero infrastructure overhead.

Why explicitly orchestrate workflows?

Databases follow the principle of transactions — a set of changes that must either all succeed or all fail. But when an application interacts with multiple databases or connects to various APIs (as is the case for most applications today), the guarantees of ACID are lost. Workflows, state machines, and the saga pattern help achieve a similar level of reliability, often at the cost of more complex code.

Use case

In this post, we revisit a classic example: orchestrating a banking transaction.. This canonical example was provided by AWS Step Functions and Temporal. Readers can refer to these articles to compare the syntax and ease of implementation offered by each tool.

Problem

Let’s walk through a typical business logic: handling a stock trade.

Here are the typical steps:

Check the price of a stock
Generate a buy or sell recommendation
Execute the recommended action
On the surface, these are simple asynchronous calls that could be chained in a function:

async function trade() {
  const stockPrice = await checkPrice();
  const recommendation = await generateRecommendation(stockPrice);
  return recommendation === 'buy' ? await buyStock(stockPrice) : await sellStock(stockPrice);
}

But in reality, problems accumulate:

What to do if a third-party service fails?
What if a network error occurs?
If the Node.js process is interrupted, the trade stops halfway, with no memory of the ongoing buy/sell operation.

These issues, far from being theoretical, can have financial consequences. For example, a buy or sell action that is forgotten or left halfway through can lead to losses for the company.

The Saga Orchestration Pattern

The Saga Orchestration Pattern effectively addresses these challenges. By centralizing workflow management in an orchestrator, this pattern mimics the transaction principle of a database. It allows a series of atomic actions, executed sequentially and under control, to be linked together into a global transaction.

The orchestrator:

Explicitly manages state transitions between each step.
Persists workflow state to ensure recovery after crashes.
Can replay actions in case of transient failure.
Provides detailed traceability through clear naming of each step. Thus, the Saga orchestration pattern not only guarantees resilience and consistency of operations but also facilitates maintenance, monitoring, and evolution of complex workflows in a distributed environment.

The Orbits implementation

Requirements

You can find the full example used in this blog post in this github folder
To try it out, follow this step-by-step guide on how to run and explore the workflow locally.
To install Orbits in your own project, refer to the install guide. It only takes a few lines to get started.

Workflow

Orbits proposes writing workflows in a structured and declarative manner.
Here is the concrete example :

export class TradingWorkflow extends Workflow{

 declare IResult:StockTransaction

 async define(){
  const checkPrice = await this.do("check-price", new CheckStockPriceAction());
  const stockPrice = checkPrice.stockPrice;

  const buyOrSell = await this.do("recommandation", 
    new GenerateBuySellRecommendationAction()
    .setArgument(
        {
            price:stockPrice.stock_price
        })
    ); 


  if (buyOrSell.buyOrSellRecommendation === 'sell') {
    const sell = await this.do("sell", new SellStockeAction().setArgument({
            price:stockPrice.stock_price
    }));
    return sell.stockData;
  } else {
    const buy = await this.do("buy", new BuyStockAction().setArgument({
            price:stockPrice.stock_price
    }));
    return buy.stockData;
  }
 };
}

This central workflow orchestrates each step by calling autonomous Actions, while maintaining branching logic and intermediate states.

Explicit orchestration: The Orbits engine handles workflow state persistence, ensuring the process can recover and resume from the exact step it failed—no matter when or why the crash occurred
Atomic actions: Each business step is an independent and testable action
Conditional branching: The workflow flow can diverge based on data (buy or sell). It does not differ from standard TypeScript code.
Extensibility: We can easily add steps, compensation logic, monitoring
Resilience: Handles crash recovery, workflow state, and observability Each step is defined as an Orbits Action.

Action

export class BuyStockAction extends Action {
    async main() {
        const response = await fetch(API_ADDRESS + 'buyStock', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ stock_price: this.argument.price })
        });
        this.result.stockData = await response.json();
        return ActionState.SUCCESS;
    }
}

This action:

Takes a typed input (price)
Calls a remote API in an encapsulated manner
Returns a state - ActionState.SUCCESS, ready to be recorded and resumed
Handles errors by default via a state - ActionState.ERROR

This structuring makes the action not only easy to test in isolation but also reusable in different workflows, while simplifying its instrumentation for monitoring or debugging.

Benefit summary

Adopting Orbits offers:

Standard TypeScript

Orbits is a standard TypeScript framework. You write promises and asynchronous functions just like you would anywhere else.

Clear separation of responsibilities

Workflow = orchestration
Action = unit business logic

Flexibility & Scalability

We can modify the flow without touching business components
Actions are reusable in multiple workflows

Resilience and recovery

Orbits manages state persistence
Automatic recovery from the last valid point

Native observability

Each action is traceable, named, monitorable

Going further

Using lambda async invocations

For the sake of hypothesis, let’s assume our Lambda function runs for an extended period of time (which is not the case here). In such scenarios, there’s a high chance that the initial HTTP call triggering the Lambda might fail unexpectedly—due to a network issue or timeout, for example.

To prevent such failures from disrupting the overall workflow, you can configure retry policies.

Orbits also supports asynchronous APIs and allows you to track execution status over time. When dealing with long-running Lambda functions, an Orbits action can return with an ActionState.IN_PROGRESS, and then delegate the follow-up logic to the watcher() method, which periodically checks the progress of the async process.

This approach requires a bit of additional setup, as you’ll need to interact with the AWS Lambda API to track the specific invocation’s result.

We’ll cover how Orbits makes it easy to manage long-running processes in a dedicated blog post soon.

Using resources to manage concurrency

In our example, if we trigger the same order twice, it will be processed twice—this isn’t always the desired behavior. Orbits provides an opinionated way to handle concurrency through a concept called resources. Resources allow you to control and limit the execution of actions to prevent unintended duplication.

Conclusion

With the simplicity of Orbits in Node.js, we can build systems that are reliable, readable, and maintainable, without changing your coding practices.

For your critical processes — e-commerce, finance, logistics, etc. — adopting such an approach will significantly reduce your bug rate and inconsistencies.

Learn more about Orbits and its capabilities in our documentation

Automate deployments of cdk8s template

Louis Dussarps — Wed, 16 Jul 2025 09:27:02 +0000

Cdk8s is a great tool to write your Kubernetes IaC templates using standard programming languages. But unlike the AWS cdk, which is tightly integrated with CloudFormation to manage stack deployment, cdk8s has no native deployment mechanism.

By default, it allows you to synthesize manifests and deploy them using kubectl apply, or optionally through Helm. While both approaches can work, they often fall short for more advanced use cases — for example, when you want to programmatically chain deployments, export values from the chart, or implement a custom rollback and prune strategy.

In this blog post, we’ll explain how we built a model-driven orchestrator for cdk8s using Orbits — a lightweight framework for orchestrating cloud resources and workflows. We’ll show how you can use it, adapt it to your own needs, or even build your own orchestrator based on the same principles. If Orbits fits your use case, you can directly reuse what we’ve built.

The Need for cdk8s orchestration

There is no built-in way to programmatically and reliably deploy a cdk8s stack — especially outside of the AWS ecosystem.

The current options are:

Synthesize the stack and apply it with kubectl apply
Deploy the stack as a Helm chart

But both of these have shortcomings:

They are not easily orchestrated programmatically
Helm has known limitations when integrating with cdk8s
There’s no native support for retries, failover, or rollback
There is no built-in mechanism to chain the deployment of multiple charts, especially if some charts are on one kube cluster and other on another kube cluster

In our case — building internal platforms for highly regulated environments — we needed more control. Our deployment flow had to:

Configure cloud provider resources via API calls
Deploy multiple charts programmatically in a precise order
Use the results of deployments (like IPs or service names) to configure other infrastructure components Also, helm’s rollback model didn’t align with our platform needs

Given these needs, existing options were not enough.
What we were looking for resembled the CloudFormation model:

Attempt a deployment
Rollback to the previous state on failure
On success, prune obsolete resources
Output values that could be reused in subsequent steps

Additionally, we needed:

Safe concurrent executions, to allow multiple deployments at the same time without conflict
Built-in retry policies for transient failures

These requirements led us to build a dedicated orchestrator for cdk8s using Orbits — a model-driven orchestration engine designed for reliability and composability.

Final result - orchestration of cdk8s charts

The result is an Orbits resource that manages your cdk8s deployment.
You can read the orbits documentation on how to install and use it.

You can use it by extending the base class:

export class BasicResource extends Cdk8sResource {
  StackConstructor = BasicChart ;
}

Or dynamically assign a custom stack generation method:

const myCdk8sResource = new Cdk8sResource();
myCdk8sResource.generateStack = ()=>{
    return new cdk8s.Chart(myCdk8sResource.app, 'empty-chart')
}

await this.do("update-stack", {dynamicAction: myCdk8sResource});

Outputs and chaining

You can export outputs, which allows you to chain charts or propagate values (like an IP address for DNS updates)

async setOutput(){
        const stack = await this.generateStack();
        const apiServiceInfo = await this.kubeApi.coreApi.readNamespacedService({
            name: stack.loadBalancerService.name,
            namespace: stack.loadBalancerService.metadata.namespace || 'default',
        })
        return apiServiceInfo.status.loadBalancer.ingress[0].ip;
}

Once you have configured your output, you can consume them in a workflow or in another resource.

async define(){
    const output = await this.do("deployBasic", new BasicCdk8sResource());
    await this.do("deploymentThatUsePreviousResourceOutput", new AdvancedCdk8sResource().setArgument(output));
}

Concurrency

Concurrency is also managed by Orbits. If a deployment is already running, concurrent executions will be serialized to prevent state corruption

    //somewhere
    this.do("deploy", new MyBasicChartResource())
    //elsewhere
    this.do("deploy", new MyBasicChartResource())

The two deployments will coalesce.

Crash-proof

Orbits is crash-proof.
If a crash occurs mid-deployment, Orbits will resume from the same step on restart.

Under the hood

From a cdk8s chart, we want to:

Deploy the chart reliably
Retry on failure
Rollback to the previous state if necessary
Prune obsolete resources

The orbits Cdk8s resources

In Orbits, resources are stateful units that define hooks like defineUpdate.
For the deployment of a cdk8s chart, we only need the update hook.
The high-level flow of the resource implementation is as follows:

export class Cdk8sResource{

    defineUpdate(){
        try{
            await this.do("deploy", ...)
        }
        catch(err){
            this.bag.rollBackNeeded = true;
            await this.do("rollback", ...)
        }
        finally{
            await this.do("prune", ...)
        }

        if(!this.bag.rollBackNeeded){
            await this.do("storeNewChart", ...)
        }
    }
}

The complete implementation is available here on github

Deploying the chart

There are multiple ways to deploy a stack, but we chose kubectl apply because it updates only the resources that changed. That means kubectl is required in the environment running the deployment.

Ensuring the deployment is a success

We don’t just fire and forget. We verify that critical resources are ready:

All Deployments reach a ready state
Certificates (e.g., from cert-manager) are marked as ready.

This check helps us ensure the cluster is in a stable and usable state before moving forward.

Storing the latest chart

We store the chart contents in a Kubernetes Secret. The secret’s name is generated based on the stack name:

private genSecretName(): string {
        return `orbits.deployment.${this.argument.stackName}`;
}

This allows the system to compare the current state with the previous one during rollback or pruning.

Pruning unused resources

Pruning depends on whether the deployment succeeded:

On success, we prune old resources
On failure, we prune newly created resources

We compare the list of objects in the stored stack with the current state and remove the unneeded ones.
We make sure to never delete:

Namespaces
PersistentVolumeClaims

Key Benefits

CloudFormation-like rollback for Cdk8s chart
Crash-safe and retryable deployments
Safe concurrent operations
Outputs and dependency chaining support
Multi-tenants deployment support

Looking Forward

Our orchestrator provides a robust and flexible foundation for managing cdk8s deployments in production. While it already solves some pain points, we plan to improve:

Improved diff tools to preview changes before applying them
Extended tracking and monitoring of additional Kubernetes resources Additionally, the resource offers a promising starting point for implementing drift detection, but that topic will be covered in a future post.

You can easily deploy cdk8s charts with orbits : see this tutorial to get-started.

The source code of the CDk8SResource is available here: https://github.com/LaWebcapsule/orbits/blob/main/helpers/src/standards-resource/cdk8s/cdk8s-resource.ts