This topic describes Resource Orchestration Service (ROS) Cloud Development Kit (CDK) commands and how to use the ROS CDK commands.

Description of ROS CDK commands

Command Description
ros-cdk init Initializes an ROS CDK project.
ros-cdk config Configures an Alibaba Cloud account in interactive mode.
ros-cdk load-config Obains Alibaba Cloud credentials by using Alibaba Cloud CLI.
ros-cdk list (ls) Lists all stacks in a project.
ros-cdk synthesize (synth) Uses code to generate a stack template.
ros-cdk deploy Creates a stack.
ros-cdk list-stacks Queries stacks.
ros-cdk event Queries stack events.
ros-cdk output Queries the output information about a stack.
ros-cdk resource Queries resources in a stack.
ros-cdk diff Compares templates.
ros-cdk destroy Deletes a stack.
ros-cdk generate-stack-file Generates the stack.info.json file in the project in synchronous mode.
ros-cdk config-set Configures an Alibaba Cloud account in non-interactive mode.

Use ROS CDK commands

When you initialize a CDK project, you can set the --language parameter to javascript, typescript, java, or python to specify the language that is used for the project. You can set the --generate-only parameter to true or false to determine whether to only create a project file. Other operations, such as Git repository configuration, dependency installation, and project compilation are not performed. 

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

After you initialize the project, you can run the ros-cdk config command to configure an Alibaba Cloud account in interactive mode. The following authentication methods are supported: AK, StsToken, RamRoleArn, and EcsRamRole. You can also specify the --global parameter for global authentication settings. 

 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. If you want to import authentication information to CDK, select an authentication mode and an authentication profile. Only authentication information that you configured is displayed. You can specify the --file-path parameter to obtain the authentication information of the profile in a specified path, or specify the --global parameter for global authentication settings. 

 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 you initialize the project, you can query stacks in the project and view the status of the stacks. 

 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. If the project contains multiple stacks, you must specify the name of the stack that you want to use. 

 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"
       }
     }
   }
 }

If the project directory contains multiple custom project files of applications or if you want to pass custom parameters to the code that is run by the applications, you can use the --App configuration item to run the specified application project. 

 ros-cdk synth NewStack --json --app "npx ts-node bin/new.app.ts"
 {
   "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 new app test",
        "EnableIpv6": false,
        "VpcName": "new-app-test"
       }
     }
   }
 }

You must specify a stack name when you create a stack in a project that contains multiple stacks. You can specify the following commands based on your business requirements:

  • --timeoutMinutes: the timeout period in which the stack must be created.
  • --parameters: the parameters that are defined in the template.
  • --region: the region in which the stack is created.
  • --app: the application that you want to use to create the stack.
  • --sync: the synchronous mode that you use to create the stack.
  • --outputs-file: the stack.outputs.json file that contains the information about the Outputs section in the template.
  • --skip-if-no-changes: If the stack template is not changed, run the deploy command again without the need to check resource creation changes.
  • --resource-group-id: the resource group ID specified when you create a stack. If you do not specify this parameter, the stack is added to the default resource group. 
    • ros-cdk deploy        # The following example shows how to use the commands in a project that contains only one stack. 
 ros-cdk deploy NewStack --app "npx ts-node bin/new.app.ts" # Specifies the application that is run by the project. 
 ros-cdk deploy --sync=true NewStack # Deploys the stack in synchronous mode and generates resource details. 
 ros-cdk deploy --sync=true --outputs-file=true NewStack # Deploys the stack in synchronous mode and synchronizes the information in the Outputs section of the template to the stack.outputs.json file. 
 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=UpBuckett

    After you create a stack, you can run the ros-cdk list-stacks command to query the details and states of all stacks in a project.

  • --all: queries details of all stacks in the current region.
  • --resource-group-id: queries details of stacks in a specified resource group.
  • --page-number: the number of the page to return. Pages start from page 1. Default value: 1.
  • --page-size: the number of entries to return on each page. Maximum value: 50. Default value: 10. 
    •  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 you create a stack, you can run the ros-cdk event command to query the information about the stack creation event. You must specify the stack name when you run the command. You can specify the --logical-resource-id parameter to query the events of a resource. If a large number of stack events exist, you can specify the --page-number and -page-size parameters to limit the number of stack events that are 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 you create a stack, you can run the ros-cdk output command to query the output information about 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 you create the stacks, you can run the ros-cdk resource command to query the details about the resources in each 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 that is created within a project, you can run the ros-cdk diff command to compare the details about the stack before and after the modification. Make sure that the modification is correct before you create a stack. 

     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. You can specify the following commands based on your business requirements:

  • --all: deletes all stacks.
  • -quiet: deletes stacks without the need of confirmation.
  • --sync: deletes stacks in synchronous mode. 
    • ros-cdk destroy CdkDemoStack
ros-cdk destroy --all
ros-cdk destroy --quiet=true
ros-cdk destroy --sync=true

    If the stack.info.json file of your project is deleted or lost, you can run the ros-cdk generate-stack-file command to generate a new stack.info.json file in synchronous mode.

  • --resource-group-id: queries information about stacks in a specified resource group and generates the stack.info.json file in synchronous mode. 
    •  
 ros-cdk generate-stack-file   ✅ The generate stack info has completed!

    After you initialize the project, you can run the ros-cdk config-set command to configure an Alibaba Cloud account in non-interactive mode. Common configuration items: 

     
 [1] region: the ID of the region in which the specified stack is created. You must configure this parameter. 
 [2] mode: the credential type of the configuration. You must configure this parameter. The following authentication methods are supported: AK, StsToken, RamRoleArn, and EcsRamRole. 
 [3] ak: your AccessKey ID. 
 [4] sk: your AccessKey secret. 
 [5] sts-token: the information that is required for StsToken authentication. 
 [6] ram-role-arn: the information that is required for RamRoleArn authentication. 
 [7] role-session-name: the value of RoleSessionName. 
 [8] ram-role-name: the name of the role that is assigned to your ECS instance. 
 
 ros-cdk config-set --region cn-beijing --mode AK --ak LTAI5t884amF1U********** --sk hmwX2uq7kZ5mBw*************
 
  ✅ Your cdk configuration has been saved successfully!