Resource Orchestration Service (ROS) Cloud Development Toolkit (CDK) lets you define cloud resources in TypeScript and deploy them as stacks. A single project can contain multiple stacks in one application, or multiple applications that each manage their own stacks.
How it works
A ROS CDK project is a directory containing your source code, dependencies, and configuration. Within a project, you organize resources into stacks -- each stack maps to a single ROS template and deploys independently.
There are two ways to manage multiple stacks in one project:
Multiple stacks in one application -- Define all stacks in a single entry point file (
bin/demo.ts). All stacks share the same application context and are visible to each other. Deploy individual stacks by name withros-cdk deploy <StackName>.Multiple applications in one project -- Create separate entry point files (for example,
bin/demo.tsandbin/test.ts). Each application is independent. Use the--appflag to tellros-cdkwhich entry point to run.
| Aspect | Multiple stacks, one app | Multiple apps, one project |
|---|---|---|
| Entry point | Single file (for example, bin/demo.ts) | Separate file per app |
| Stack visibility | All stacks visible to each other | Apps are independent |
| Deploy command | ros-cdk deploy <StackName> | ros-cdk deploy <StackName> --app "npx ts-node bin/test.ts" |
| Common use case | Related resources that share configuration | Independent resource groups with separate lifecycles |
Prerequisites
Before you begin, make sure you have:
Node.js and npm installed
The ROS CDK CLI (
ros-cdk) installedAn Alibaba Cloud account with a valid AccessKey pair
TypeScript tooling (
typescript,ts-node)
Step 1: Initialize the project
Each ROS CDK application must be created in a separate project directory. The application uses the dependencies of modules in the directory.
Run the following commands to create and initialize a project:
mkdir demo
cd demo
ros-cdk init --language=typescript --generate-only=trueStep 2: Configure an Alibaba Cloud credential
Run the following command:
ros-cdk configEnter the configuration values when prompted. The following example uses AccessKey (AK) authentication with the
cn-beijingregion:ros-cdk config endpoint(optional, default:https://ros.aliyuncs.com): defaultRegionId(optional, default:cn-hangzhou):cn-beijing [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!
Step 3: Install dependencies
Open
package.jsonand add the ROS CDK packages for the services you need. This example addsros-cdk-ecsfor Elastic Compute Service (ECS) andros-cdk-ossfor Object Storage Service (OSS):{ "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.4.0" }, "dependencies": { "@alicloud/ros-cdk-core": "^1.4.0", "@alicloud/ros-cdk-ecs": "^1.4.0", "@alicloud/ros-cdk-oss": "^1.4.0" } }Install the dependencies:
npm install
Step 4: Define and deploy multiple stacks in one application
This section shows how to define two stacks in a single application: one that creates a virtual private cloud (VPC) and another that creates an OSS bucket.
Define the stacks
Edit
lib/demo-stack.tsto define both stack classes:import * as ros from '@alicloud/ros-cdk-core'; import * as ecs from '@alicloud/ros-cdk-ecs'; import * as oss from '@alicloud/ros-cdk-oss'; // DemoStack: creates a VPC 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' }); } } // DemoStack2: creates an OSS bucket export class DemoStack2 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 oss.Bucket(this, 'oss-from-ros-cdk', { bucketName: 'oss-from-ros-cdk' } ) } }Edit
bin/demo.tsto register both stacks with the application:#!/usr/bin/env node import * as ros from '@alicloud/ros-cdk-core'; import { DemoStack } from '../lib/demo-stack'; import { DemoStack2 } from '../lib/demo-stack'; const app = new ros.App({outdir: './cdk.out'}); new DemoStack(app, 'DemoStack'); // Registers the VPC stack new DemoStack2(app, 'DemoStack2'); // Registers the OSS bucket stack app.synth();
Synthesize the templates
Generate the ROS template for each stack to verify the output before deploying.
Generate the template for DemoStack:
ros-cdk synth DemoStack -jExpected output:
{
"Description": "This is the simple ros cdk app example.",
"Metadata": {
"ALIYUN::ROS::Interface": {
"TemplateTags": [
"Create by ROS CDK"
]
}
},
"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"
}
}
}
}Generate the template for DemoStack2:
ros-cdk synth DemoStack2 -jExpected output:
{
"Description": "This is the simple ros cdk app example.",
"Metadata": {
"ALIYUN::ROS::Interface": {
"TemplateTags": [
"Create by ROS CDK"
]
}
},
"ROSTemplateFormatVersion": "2015-09-01",
"Resources": {
"oss-from-ros-cdk": {
"Type": "ALIYUN::OSS::Bucket",
"Properties": {
"BucketName": "oss-from-ros-cdk",
"AccessControl": "private",
"DeletionForce": false
}
}
}
}Deploy the stacks
Deploy DemoStack:
ros-cdk deploy DemoStack --sync=trueExpected output:
DemoStack: deploying...
|DemoStack |2021-12-29T06:56:00 | CREATE_COMPLETE | ALIYUN::ECS::VPC | vpc-2ze18c8hsomme5ps**** | vpc-from-ros-cdk
✅ The deployment(sync deploy stack) has finished!
status: CREATE_COMPLETE
StatusReason: Stack CREATE completed successfully
StackId: e002686b-d269-41df-bdf4-27221b1****Deploy DemoStack2:
ros-cdk deploy DemoStack2 --sync=trueExpected output:
DemoStack2: deploying...
|DemoStack2 |2021-12-29T06:56:24 | CREATE_COMPLETE | ALIYUN::OSS::Bucket | oss-from-ros-cdk | oss-from-ros-cdk
✅ The deployment(sync deploy stack) has finished!
status: CREATE_COMPLETE
StatusReason: Stack CREATE completed successfully
StackId: 502a2cbe-3ab2-49fa-bcaf-602c3b88****(Optional) Delete the stacks
To delete a stack, run ros-cdk destroy <StackName> --sync=true and confirm when prompted.
Delete DemoStack:
Run the following command:
ros-cdk destroy DemoStack --sync=trueConfirm the deletion when prompted: Expected output:
The following stack(s) will be destroyed(Only deployed stacks will be displayed). DemoStack Please confirm.(Y/N) yDemoStack: destroying... |DemoStack | DELETE_COMPLETE | ALIYUN::ECS::VPC | | vpc-from-ros-cdk ✅ The task(sync destroy stack) has finished! status: DELETE_COMPLETE StatusReason: Stack DELETE completed successfully StackId: e002686b-d269-41df-bdf4-27221****
Delete DemoStack2:
Run the following command:
ros-cdk destroy DemoStack2 --sync=trueConfirm the deletion when prompted: Expected output:
The following stack(s) will be destroyed(Only deployed stacks will be displayed). DemoStack2 Please confirm.(Y/N) yDemoStack2: destroying... |DemoStack2 | DELETE_COMPLETE | ALIYUN::OSS::Bucket | | oss-from-ros-cdk ✅ The task(sync destroy stack) has finished! status: DELETE_COMPLETE StatusReason: Stack DELETE completed successfully StackId: 502a2cbe-3ab2-49fa-bcaf-602c3b88****
Step 5: Use the --app flag to run a different application
By default, ros-cdk uses the entry point defined in cdk.json (typically bin/demo.ts). The --app flag overrides this default and points ros-cdk to a different TypeScript file as the application entry point. This lets you maintain independent applications within a single project directory, each with its own stacks.
Create a new application
Create
bin/test.tsto define a new application that manages a stack namedTestStack:#!/usr/bin/env node import * as ros from '@alicloud/ros-cdk-core'; import { TestStack } from '../lib/test-stack'; const app = new ros.App({outdir: './cdk.out'}); new TestStack(app, 'TestStack'); app.synth();Create
lib/test-stack.tsto define a stack that creates an ECS security group:import * as ros from '@alicloud/ros-cdk-core'; import * as ecs from '@alicloud/ros-cdk-ecs'; export class TestStack 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 sg = new ecs.SecurityGroup(this, 'ros-cdk-test-sg'); } }
Synthesize, deploy, and manage the stack
Pass the --app flag to every ros-cdk command to use the new application entry point.
Synthesize the template:
ros-cdk synth TestStack -j --app "npx ts-node bin/test.ts"Expected output:
{
"Description": "This is the simple ros cdk app example.",
"Metadata": {
"ALIYUN::ROS::Interface": {
"TemplateTags": [
"Create by ROS CDK"
]
}
},
"ROSTemplateFormatVersion": "2015-09-01",
"Resources": {
"ros-cdk-test-sg": {
"Type": "ALIYUN::ECS::SecurityGroup"
}
}
}Deploy the stack:
ros-cdk deploy TestStack --sync=true --app "npx ts-node bin/test.ts"Expected output:
TestStack: deploying...
|TestStack |2021-12-28T09:41:58 | CREATE_COMPLETE | ALIYUN::ECS::SecurityGroup | sg-2ze7zn4sk5i9fgmg**** | ros-cdk-test-sg
✅ The deployment(sync deploy stack) has finished!
status: CREATE_COMPLETE
StatusReason: Stack CREATE completed successfully
StackId: 1ef89784-a728-46b2-8ec0-bc0f14c9****(Optional) Delete the TestStack stack:
Run the following command:
ros-cdk destroy --sync=true --app "npx ts-node bin/test.ts"Confirm the deletion when prompted: Expected output:
The following stack(s) will be destroyed(Only deployed stacks will be displayed). TestStack Please confirm.(Y/N) yTestStack: destroying... |TestStack |2021-12-28T09:41:58 | DELETE_COMPLETE | ALIYUN::ECS::SecurityGroup | sg-2ze7zn4sk5i9fgmg**** | ros-cdk-test-sg ✅ The task(sync destroy stack) has finished! status: DELETE_COMPLETE StatusReason: Stack DELETE completed successfully StackId: 1ef89784-a728-46b2-8ec0-bc0f14c9****
References
API reference page: The CDK construct library provides a collection of API operations for you to build your CDK applications. For more information about how to use the API operations and the features of the API operations, see Ros Cdk References.
CDK command: For more information about how to use CDK commands and the usage examples, see ROS CDK commands.
CDK feature: For more information about how to use CDK features such as outputs and pseudo parameters and the usage examples, see ROS CDK features.
GitHub repository: For more information about the official GitHub repository of ROS CDK, visit Resource-Orchestration-Service-Cloud-Development-Kit. On the website, you can submit issues and view the service license and release notes.