This topic describes Cloud Development Toolkit (CDK) commands and how to use them. CDK is a command line tool available with Resource Orchestration Service (ROS).

Description of ROS CDK commands

Command Description
ros-cdk init Initializes an ROS CDK project.
ros-cdk list (ls) Lists all stacks in a project.
ros-cdk synthesize (synth) Uses code to create a stack template.
ros-cdk deploy Creates a stack by using ROS.
ros-cdk diff Compares templates.
ros-cdk destroy Deletes a stack by using ROS.
ros-cdk config Configures an Alibaba Cloud account.
ros-cdk list-stacks Queries a list of stacks by using ROS.
ros-cdk event Queries stack events by using ROS.
ros-cdk output Queries the output information of a stack by using ROS.
ros-cdk resource Queries a list of resources in a stack by using ROS.
ros-cdk load-config Queries information of an Alibaba Cloud credential by using Alibaba Cloud CLI.

Methods to use ROS CDK commands

When you initialize a CDK project, you can specify the language of the project by setting the --language parameter to javascript, typescript, java, or python. You can set the --generate-only parameter to true or false to specify whether to perform other operations in addition to creating the project file, such as configuring Git repositories, installing dependencies, and compiling the project.

ros-cdk init --language=typescript --generate-only=true

After the project is initialized, you can run the ros-cdk config command to configure an Alibaba Cloud account. AK, StsToken, RamRoleArn, and EcsRamRole are supported for authentication. You can also specify the --global parameter for global configuration.

 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!

ROS CDK allows you to obtain Alibaba Cloud credentials by using Alibaba Cloud CLI. You can import authentication information to CDK by selecting the corresponding authentication mode and authentication profile. Only information that you have configured is prompted. You can specify the --file-path parameter to obtain the authentication information of the profile in a specific path or specify the --global parameter for global configuration.

 ros-cdk load-config
 [1] AK
 [2] StsToken
 [3] RamRoleArn
 [4] EcsRamRole
 [0] CANCEL
 
 Select authenticate mode [1...4 / 0]: 1
 
 [1] default
 [2] akProfile
 [0] CANCEL
 
 Select Authenticate profile name [1, 2, 0]: 2
 
  ✅ Your cdk configuration has been load from Aliyun Cli configuration saved successfully AK akProfile!

After the project is initialized, you can query a list of stacks in the project and view their states.

 ros-cdk list 
 CdkDemoStack synth
 CdkTestStack deploy

You can run the ros-cdk synth command to preview the ROS templates in the project. You can also specify the --json parameter to preview the templates in the JSON format. When multiple stacks exist in the project, you must specify the name of the stack to be created.

 ros-cdk synth CdkTestStack --json
 {
   "ROSTemplateFormatVersion": "2015-09-01",
   "Resources": {
     "VPC": {
       "Type": "ALIYUN::ECS::VPC",
       "Properties": {
         "CidrBlock": "10.0.0.0/8",
         "Description": "This is ros cdk test",
         "EnableIpv6": false,
         "VpcName": "test-ros-cdk-javascript"
       }
     }
   }
 }

When you create a stack, you must specify the stack name if multiple stacks exist in the project. You can specify the --timeoutMinutes parameter to set the timeout period of the stack. The default value is 20. You can also specify the --parameters parameter to configure the parameters of the stack. You can set the --region parameter to the ID of the region where you want the stack to be created. If you do not specify --region, the stack is created in the default region configured by ros-cdk config.

 ros-cdk deploy        #The following example shows how to use the commands when the project contains only a single stack. 
 ros-cdk deploy CdkTestStack --timeoutMinutes 60 --region cn-beijing
 ros-cdk deploy CdkTestStack CdkDemoStack 
 ros-cdk deploy CdkDemoStack --parameters uploadBucketName=UploadBucket
 ros-cdk deploy CdkDemoStack CdkTestStack --parameters CdkDemoStack:uploadBucketName=UploadBucket --parameters CdkTestStack:uploadBucketName=UpBucket

After the stack is created, you can run the ros-cdk list-stacks command to query the details and states of all stacks in the project. You can also specify the --all parameter to query the details of all stacks of the Alibaba Cloud account within a specific region. If a large number of stacks are anticipated, you can specify the --page-number and -page-size parameters to limit the number of stacks to be returned.

 ros-cdk list-stacks --all
  ✅ The Stacks list is:
  [
         {
                 "Status": "CREATE_COMPLETE",
                 "StackType": "ROS",
                 "StatusReason": "Stack CREATE completed successfully",
                 "CreateTime": "2021-01-14T09:28:09",
                 "RegionId": "cn-beijing",
                 "DisableRollback": false,
                 "StackName": "CdkTestStack",
                 "StackId": "ceb59a66-b2e8-4b30-9da6-59a66****",
                 "TimeoutInMinutes": 20
         },
         {
                 "Status": "CREATE_COMPLETE",
                 "StackType": "ROS",
                 "StatusReason": "Stack CREATE completed successfully",
                 "CreateTime": "2021-01-13T03:10:42",
                 "RegionId": "cn-beijing",
                 "DisableRollback": false,
                 "StackName": "stack_2021-01-13",
                 "StackId": "37e697cc-3ea6-4a79-9dcd-59a66****",
                 "TimeoutInMinutes": 60
         }
 ]

After the stack is created, you can run the ros-cdk event command to query information of stack creation events. You must specify the stack name when you run the command. You can specify the --logical-resource-id parameter to query the events corresponding to a resource. If a large number of stack events are anticipated, you can specify the --page-number and -page-size parameters to limit the number of stack events to be returned.

 ros-cdk event CdkTestStack -l ros-cdk-test-sg 
  ✅ The Stack CdkTestStack 
  Events is: 
  [
         {
                 "Status": "CREATE_COMPLETE",
                 "LogicalResourceId": "ros-cdk-test-sg",
                 "PhysicalResourceId": "sg-2ze7i61on1gb48zi****",
                 "StatusReason": "state changed",
                 "CreateTime": "2021-01-14T09:28:10",
                 "EventId": "fc10f59e-7dcc-492d-af5e-0f59e****",
                 "ResourceType": "ALIYUN::ECS::SecurityGroup",
                 "StackName": "CdkTestStack",
                 "StackId": "ceb59a66-b2e8-4b30-9da6-0f59e****"
         },
         {
                 "Status": "CREATE_IN_PROGRESS",
                 "LogicalResourceId": "ros-cdk-test-sg",
                 "StatusReason": "state changed",
                 "CreateTime": "2021-01-14T09:28:09",
                 "EventId": "4d7a4b33-9d5e-49e8-a2b4-0f59e****",
                 "ResourceType": "ALIYUN::ECS::SecurityGroup",
                 "StackName": "CdkTestStack",
                 "StackId": "ceb59a66-b2e8-4b30-9da6-0f59e****"
         }
 ]

After the stack is created, you can run the ros-cdk output command to query the output information of the stack.

 ros-cdk output cdk-demo
   ✅ The Stack cdk-demo 
  Output is: 
  [
         {
                 "Description": "No description given",
                 "OutputKey": "BucketDomainName",
                 "OutputValue": "bestros.oss-cn-beijing.aliyuncs.com"
         }
 ]

After the stack is created, you can run the ros-cdk resource command to query the details of resources in the stack. You can specify multiple stacks in a single command.

 ros-cdk resource CdkTestStack
 
 ✅ The Stack CdkTestStack 
  Resource is: 
  [
         {
                 "Status": "CREATE_COMPLETE",
                 "LogicalResourceId": "ros-cdk-test-sg-ingres****",
                 "PhysicalResourceId": "sg-2ze7i61on1gb48zi****",
                 "StatusReason": "state changed",
                 "CreateTime": "2021-01-14T09:28:09",
                 "UpdateTime": "2021-01-14T09:28:14",
                 "ResourceType": "ALIYUN::ECS::SecurityGroupIngress",
                 "StackName": "CdkTestStack",
                 "StackId": "ceb59a66-b2e8-4b30-9da6-59a66****"
         },
         {
                 "Status": "CREATE_COMPLETE",
                 "LogicalResourceId": "ros-cdk-tes****",
                 "PhysicalResourceId": "sg-2ze7i61on1gb48zi****",
                 "StatusReason": "state changed",
                 "CreateTime": "2021-01-14T09:28:09",
                 "UpdateTime": "2021-01-14T09:28:10",
                 "ResourceType": "ALIYUN::ECS::SecurityGroup",
                 "StackName": "CdkTestStack",
                 "StackId": "ceb59a66-b2e8-4b30-9da6-59a66****"
         },
         {
                 "Status": "CREATE_COMPLETE",
                 "LogicalResourceId": "ros-cdk-test-sg-ingres****",
                 "PhysicalResourceId": "sg-2ze7i61on1gb48zi****",
                 "StatusReason": "state changed",
                 "CreateTime": "2021-01-14T09:28:09",
                 "UpdateTime": "2021-01-14T09:28:14",
                 "ResourceType": "ALIYUN::ECS::SecurityGroupIngress",
                 "StackName": "CdkTestStack",
                 "StackId": "ceb59a66-b2e8-4b30-9da6-59a66****"
         }
 ]

After you modify the code of a stack created within a project, you can run the ros-cdk diff command to compare the stack before and after the modification.

 ros-cdk diff CdkDemoStack
 Stack CdkDemoStack
 Resources
 [~] ALIYUN::ECS::VPC vpc-from-ros-cdk/vpc-from-ros-cdk vpc-from-ros-cdk 
  └─ [~] VpcName
      ├─ [-] test-ros-cdk-vpc
      └─ [+] test-ros-cdk-vpc-modify
 [~] ALIYUN::ECS::VSwitch vsw-from-ros-cdk/vsw-from-ros-cdk vsw-from-ros-cdk 
  └─ [~] VSwitchName
      ├─ [-] test-ros-cdk-vsw
      └─ [+] test-ros-cdk-vpc-modify

You can run the ros-cdk destroy command to delete stacks. If the project contains multiple stacks, you can specify the --all parameter to delete all stacks. If you set --quiet to true, you are not required to confirm the operation after you run the command.

 ros-cdk destroy CdkDemoStack
 ros-cdk destroy --all
 ros-cdk destroy --quiet true