All Products
Search

This Product

    Resource Orchestration Service:Use ROS CDK for resource orchestration

    Document Center

    Resource Orchestration Service:Use ROS CDK for resource orchestration

    Last Updated:Jun 16, 2026

    ROS Cloud Development Toolkit (CDK) lets you define and orchestrate Alibaba Cloud resources programmatically, replacing complex templates with minimal code.

    Background

    • ROS CDK is open-source on GitHub.

    • ROS CDK supports 276 resource types across 60 Alibaba Cloud services.

    • ROS CDK supports three programming languages: JavaScript, TypeScript, and Java.

    Install the CLI

    ROS CDK provides a command-line interface (CLI) for managing CDK projects. The following steps install the CLI on a CentOS 8.2 64-bit system.

    1. Run the following commands to install the CLI.

      # ROS CDK is developed in TypeScript, so you need to install the related packages.
# Install Node.js, npm, tsc, and lerna.
sudo yum install -y nodejs
sudo npm install typescript -g
sudo npm install lerna -g
# Install ros-cdk-cli.
sudo npm install @alicloud/ros-cdk-cli -g

    2. Run the following command to view the ROS CDK commands.

      sudo ros-cdk

      The command returns the following output:

      Usage: ros-cdk COMMAND

Commands:
  ros-cdk init [TEMPLATE]         Create a new, empty CDK project from a
                                  template. Invoked without TEMPLATE, the app
                                  template will be used.
  ros-cdk list [STACKS..]         Lists all stacks in the app      [aliases: ls]
  ros-cdk synthesize [STACKS..]   Synthesizes and prints the ROS template for
                                  this stack                    [aliases: synth]
  ros-cdk deploy [STACKS..]       Deploys the stack(s) named STACKS to ROS into
                                  your Alibaba Cloud account
  ros-cdk diff [STACKS..]         Compares the specified stack with the deployed
                                  stack or a local template file, and returns
                                  with status 1 if any difference is found
  ros-cdk destroy [STACKS..]      Destroy the stack(s) named STACKS
  ros-cdk event [STACK..]         Get resource events within the resource STACK
  ros-cdk resource [STACKS..]     Get resources in the resource STACKS
  ros-cdk list-stacks [STACKS..]  Get resources in the resource STACKS
  ros-cdk load-config             Load Alibaba Cloud CLI config to CDK.
  ros-cdk config                  Set your Alibaba Cloud account configuration.

Options:
  --json, -j       Use JSON output instead of YAML when templates are printed to
                   STDOUT                             [boolean] [default: false]
  --ignore-errors  Ignores synthesis errors, which will likely produce an
                   invalid output                     [boolean] [default: false]
  --trace          Print trace for stack warnings                      [boolean]
  --strict         Do not construct stacks with warnings               [boolean]
  --version        Show version number                                 [boolean]
  -h, --help       Show help                                           [boolean]

If your app has a single stack, there is no need to specify the stack name

If one of cdk.json or ~/.cdk.json exists, options specified there will be used
as defaults. Settings in cdk.json take precedence.

      The following table describes the commands.

      Command

      Description

      init

      Initializes a ROS CDK project.

      list (ls)

      Lists all stacks in the project.

      synthesize (synth)

      Generates a stack template from code.

      deploy

      Deploys a stack using ROS.

      diff

      Compares a specified stack with a deployed stack or local template file.

      destroy

      Deletes a stack.

      event

      Queries stack events.

      resource

      Queries resources in a stack.

      list-stacks

      Lists all stacks.

      load-config

      Loads Alibaba Cloud account information from the Alibaba Cloud CLI.

      config

      Configures Alibaba Cloud account information.

    Usage example

    The following example uses TypeScript to add a Virtual Private Cloud (VPC) to a stack with ROS CDK.

    1. Initialize the project.

      1. Run the following commands to create a project directory and initialize the project.

        # Create a project directory. The directory name is the project name.
sudo mkdir demo
cd demo
# Initialize the project by using TypeScript.
sudo ros-cdk init --language=typescript --generate-only=true

      2. Run the following command to install dependencies for the project.

        # Install the dependencies required by the project.
sudo npm install

      3. Run the following command to view the project structure.

        sudo tree -I "node_modules"

        The command returns the following output:

        .
├── bin
│   └── demo.ts
├── cdk.json
├── jest.config.js
├── lib
│   └── demo-stack.ts
├── package.json
├── package-lock.json
├── README.md
├── test
│   └── demo.test.ts
└── tsconfig.json

3 directories, 9 files

        The project contains the following key files:

        • bin/demo.ts: The entry point of the project.

          This example creates an application (type: ros.App) and a stack (type: DemoStack, name: DemoStack), then adds the stack to the application. The demo.ts file contains the following content:

          Note

          A project can have only one application.

          #!/usr/bin/env node
import * as ros from '@alicloud/ros-cdk-core';
import { DemoStack } from '../lib/demo-stack';
const app = new ros.App({outdir: './cdk.out'});
new DemoStack(app, 'DemoStack');

        • lib/demo-stack.ts: The definition of DemoStack.

          Add resources to the stack to build it dynamically. The generated starter code adds only a description. The demo-stack.ts file contains the following content:

          import * as ros from '@alicloud/ros-cdk-core';
export class DemoStack extends ros.Stack {
  constructor(scope: ros.Construct, id: string, props?: ros.StackProps) {
    super(scope, id, props);
    new ros.RosInfo(this, ros.RosInfo.description, "This is the simple ros cdk app example.");
    // The code that defines your stack goes here
  }
}

        • test/demo.test.ts: The unit test.

          The unit test verifies that the stack-building logic is correct. The demo.test.ts file contains the following content:

          import { expect as expectCDK, matchTemplate, MatchStyle } from '@alicloud/ros-cdk-assert';
import * as ros from '@alicloud/ros-cdk-core';
import * as Demo from '../lib/demo-stack';
test('Stack with version.', () => {
  const app = new ros.App();
  // WHEN
  const stack = new Demo.DemoStack(app, 'MyTestStack');
  // THEN
  expectCDK(stack).to(
    matchTemplate(
      {
        ROSTemplateFormatVersion: '2015-09-01',
        Description: "This is the simple ros cdk app example."
      },
      MatchStyle.EXACT,
    ),
  );
});

    2. Add a VPC to the stack.

      1. Modify the package.json file to add the @alicloud/ros-cdk-ecs dependency to dependencies.

        {
  "name": "demo",
  "version": "0.1.0",
  "bin": {
    "demo": "bin/demo.js"
  },
  "scripts": {
    "build": "tsc",
    "test": "jest"
  },
  "devDependencies": {
    "@types/jest": "^25.2.1",
    "@types/node": "10.17.5",
    "typescript": "^3.9.7",
    "jest": "^25.5.0",
    "ts-jest": "^25.3.1",
    "ts-node": "^8.1.0",
    "babel-jest": "^26.6.3",
    "@babel/core": "^7.12.9",
    "@babel/preset-env": "7.12.7",
    "@babel/preset-typescript": "^7.12.7",
    "@alicloud/ros-cdk-assert": "^1.0.0"
  },
  "dependencies": {
    "@alicloud/ros-cdk-core": "^1.0.0",
    "@alicloud/ros-cdk-ecs": "^1.0.0"
  }
}

      2. Run the following command to install the new dependency.

        # Install the dependencies required by the project.
sudo npm install

      3. Modify the lib/demo-stack.ts file to add a VPC.

        import * as ros from '@alicloud/ros-cdk-core';
import * as ecs from '@alicloud/ros-cdk-ecs';
export class DemoStack extends ros.Stack {
  constructor(scope: ros.Construct, id: string, props?: ros.StackProps) {
    super(scope, id, props);
    new ros.RosInfo(this, ros.RosInfo.description, "This is the simple ros cdk app example.");
    // The code that defines your stack goes here
    new ecs.Vpc(this, 'vpc-from-ros-cdk', {
      vpcName: 'test-ros-cdk',
      cidrBlock: '10.0.0.0/8',
      description: 'This is ros cdk test'
   });
  }
}

      4. Run the following command to view the template.

        sudo ros-cdk synth --json

        The command returns the following output:

        {
  "Description": "This is the simple ros cdk app example.",
  "ROSTemplateFormatVersion": "2015-09-01",
  "Resources": {
    "vpc-from-ros-cdk": {
      "Type": "ALIYUN::ECS::VPC",
      "Properties": {
        "CidrBlock": "10.0.0.0/8",
        "Description": "This is ros cdk test",
        "EnableIpv6": false,
        "VpcName": "test-ros-cdk"
      }
    }
  }
}

      5. Modify the test/demo.test.ts file to reflect the code changes in the unit test.

        import { expect as expectCDK, matchTemplate, MatchStyle } from '@alicloud/ros-cdk-assert';
import * as ros from '@alicloud/ros-cdk-core';
import * as Demo from '../lib/demo-stack';
test('Stack with version.', () => {
  const app = new ros.App();
  // WHEN
  const stack = new Demo.DemoStack(app, 'MyTestStack');
  // THEN
  expectCDK(stack).to(
    matchTemplate(
      {
        "Description": "This is the simple ros cdk app example.",
        "ROSTemplateFormatVersion": "2015-09-01",
        "Resources": {
          "vpc-from-ros-cdk": {
            "Type": "ALIYUN::ECS::VPC",
            "Properties": {
              "CidrBlock": "10.0.0.0/8",
              "Description": "This is ros cdk test",
              "EnableIpv6": false,
              "VpcName": "test-ros-cdk"
            }
          }
        } 
      },
      MatchStyle.EXACT,
    ),
  );
});

      6. Run the following command to run a unit test.

        sudo npm test

        The command returns the following output:

        > demo@0.1.0 test /root/demo
> jest
 PASS  test/demo.test.ts
  ✓ Stack with version. (136ms)
Test Suites: 1 passed, 1 total
Tests:       1 passed, 1 total
Snapshots:   0 total
Time:        2.988s, estimated 3s
Ran all test suites.

    3. Deploy the stack using the ROS service.

      1. Configure your Alibaba Cloud account credentials for the ROS CDK.

        1. Run the ros-cdk config command.

          sudo ros-cdk config

        2. Enter the configuration information as prompted.

          endpoint(optional, default:https://ros.aliyuncs.com):
defaultRegionId(optional, default:cn-hangzhou):

[1] AK
[2] StsToken
[3] RamRoleArn
[4] EcsRamRole
[0] CANCEL

Authenticate mode [1...4 / 0]: 1
accessKeyId:****************
accessKeySecret:******************************

 ✅ Your cdk configuration has been saved successfully!

          Configuration parameters:

          • endpoint: The ROS service endpoint. The default value is https://ros.aliyuncs.com.

          • defaultRegionId: The region where the ROS stack is deployed. The default value is cn-hangzhou.

          • Authenticate mode: The authentication method. This example uses the AccessKey authentication method. You must enter your accessKeyId and accessKeySecret.

      2. Run the following command to deploy the stack using ROS.

        sudo ros-cdk deploy

        The command returns the following output:

         ✅ The deployment(create stack) has completed!
RequestedId: BC963C80-054D-41A0-87E7-001E0AB7B1BA
StackId: 0714be3a-0713-4b7d-b7aa-************

      3. Log on to the ROS console. In the left-side navigation pane, click Stacks to view the stack status.

        If the Status column shows The operation is successful., the stack named DemoStack has been created successfully.

    4. (Optional) Change the VPC name and create vSwitches in the VPC.

      ROS CDK supports more complex scenarios. The following example shows how to:

      • Change the VPC name from test-ros-cdk to test-ros-cdk-vpc.

      • Create three vSwitches in the VPC. The vSwitches have different names and are in different zones and CIDR blocks.

      1. Modify the lib/demo-stack.ts file.

        import * as ros from '@alicloud/ros-cdk-core';
import * as ecs from '@alicloud/ros-cdk-ecs';
export class DemoStack extends ros.Stack {
  constructor(scope: ros.Construct, id: string, props?: ros.StackProps) {
    super(scope, id, props);
    new ros.RosInfo(this, ros.RosInfo.description, "This is the simple ros cdk app example.");
    // The code that defines your stack goes here
   const vpc = new ecs.Vpc(this, 'vpc-from-ros-cdk', {
      vpcName: 'test-ros-cdk-vpc',
      cidrBlock: '10.0.0.0/8',
      description: 'This is ros cdk test'
    });
    for (let i = 0; i < 3; i++) {
      new ecs.VSwitch(this, `vsw-from-ros-cdk-${i}`, {
        vpcId: vpc.attrVpcId,
        zoneId: ros.Fn.select(`${i}`, ros.Fn.getAzs(ros.RosPseudo.region)),
        vSwitchName: `test-ros-cdk-vsw-${i}`,
        cidrBlock: `10.0.${i}.0/24`,
      });
    }
  }
}

        Key changes:

        • Change the VPC name by updating the value of vpcName.

        • A for loop creates the vSwitches, significantly reducing code.

        • Use vpc.attrVpcId to get the ID of the VPC.

        • Use the Fn.getAzs function with the RosPseudo.region pseudo parameter to get a list of zones.

      2. Modify the test/demo.test.ts file to keep the unit test consistent with the code, and then run the npm test command to run the unit test.

        For details, see Step 2.

      3. Run the ros-cdk diff command to view the changes.

        sudo ros-cdk diff

        The command returns the following output:

        Stack DemoStack
Resources
[+] ALIYUN::ECS::VSwitch vsw-from-ros-cdk-0/vsw-from-ros-cdk-0 vsw-from-ros-cdk-0 
[+] ALIYUN::ECS::VSwitch vsw-from-ros-cdk-1/vsw-from-ros-cdk-1 vsw-from-ros-cdk-1 
[+] ALIYUN::ECS::VSwitch vsw-from-ros-cdk-2/vsw-from-ros-cdk-2 vsw-from-ros-cdk-2 
[~] ALIYUN::ECS::VPC vpc-from-ros-cdk/vpc-from-ros-cdk vpc-from-ros-cdk 
 └─ [~] VpcName
     ├─ [-] test-ros-cdk
     └─ [+] test-ros-cdk-vpc

      4. Run the following command to deploy the stack using ROS.

        sudo ros-cdk deploy

        The command returns the following output:

         ✅ The deployment(update stack) has completed!
RequestedId: 15E99FD6-968E-47AA-9CD2-82FA6E87C08E
StackId: 0714be3a-0713-4b7d-b7aa-************

      5. Log on to the ROS console. In the left-side navigation pane, click Stacks to check the stack status.

        If the Status column shows Update Succeeded, the stack named DemoStack has been updated successfully.

        Click the Resources tab to view the resource list. This example includes one VPC resource and three vSwitch resources.

    5. (Optional) Delete the stack.

      1. Run the following command to list all stacks in the project.

        sudo ros-cdk list

        The command returns the following output:

        DemoStack

      2. Run the following command to delete the stack.

        sudo ros-cdk destroy

        The command returns the following output:

        The following stack(s) will be destroyed(Only deployed stacks will be displayed).
DemoStack
Please confirm.(Y/N)
Y
 ✅ Deleted
RequestedId: 1BF864E1-7965-4148-A302-E6ABFF806641

    npm packages for resources

    Each npm package corresponds to an Alibaba Cloud service. For example, @alicloud/ros-cdk-ecs covers all ECS resource types supported by ROS.

    Log on to the ROS console. In the left-side navigation pane, click Resource Types to view the resources supported by each service.

    @alicloud/ros-cdk-acm
@alicloud/ros-cdk-actiontrail
@alicloud/ros-cdk-apigateway
@alicloud/ros-cdk-arms
@alicloud/ros-cdk-bss
@alicloud/ros-cdk-cas
@alicloud/ros-cdk-cdn
@alicloud/ros-cdk-cen
@alicloud/ros-cdk-cloudfw
@alicloud/ros-cdk-cms
@alicloud/ros-cdk-cr
@alicloud/ros-cdk-cs
@alicloud/ros-cdk-datahub
@alicloud/ros-cdk-dbs
@alicloud/ros-cdk-dms
@alicloud/ros-cdk-dns
@alicloud/ros-cdk-drds
@alicloud/ros-cdk-dts
@alicloud/ros-cdk-eci
@alicloud/ros-cdk-ecs
@alicloud/ros-cdk-edas
@alicloud/ros-cdk-ehpc
@alicloud/ros-cdk-elasticsearch
@alicloud/ros-cdk-emr
@alicloud/ros-cdk-ens
@alicloud/ros-cdk-ess
@alicloud/ros-cdk-fc
@alicloud/ros-cdk-fnf
@alicloud/ros-cdk-foas
@alicloud/ros-cdk-ga
@alicloud/ros-cdk-gws
@alicloud/ros-cdk-hbr
@alicloud/ros-cdk-iot
@alicloud/ros-cdk-kafka
@alicloud/ros-cdk-kms
@alicloud/ros-cdk-marketplace
@alicloud/ros-cdk-memcache
@alicloud/ros-cdk-mns
@alicloud/ros-cdk-mongodb
@alicloud/ros-cdk-mse
@alicloud/ros-cdk-nas
@alicloud/ros-cdk-oos
@alicloud/ros-cdk-oss
@alicloud/ros-cdk-ots
@alicloud/ros-cdk-polardb
@alicloud/ros-cdk-pvtz
@alicloud/ros-cdk-ram
@alicloud/ros-cdk-rds
@alicloud/ros-cdk-redis
@alicloud/ros-cdk-resourcemanager
@alicloud/ros-cdk-rocketmq
@alicloud/ros-cdk-ros
@alicloud/ros-cdk-sae
@alicloud/ros-cdk-sag
@alicloud/ros-cdk-slb
@alicloud/ros-cdk-sls
@alicloud/ros-cdk-uis
@alicloud/ros-cdk-vpc
@alicloud/ros-cdk-vs
@alicloud/ros-cdk-waf