All Products
Search
Document Center

Resource Orchestration Service:Overview of ROS CDK commands

Last Updated:Jan 16, 2024

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

Description of ROS CDK commands

Command

Description

ros-cdk init

Initializes a ROS CDK project.

ros-cdk config

Configures an Alibaba Cloud account in interactive mode.

ros-cdk load-config

Queries information about 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 a project in synchronous mode.

ros-cdk config-set

Configures an Alibaba Cloud account in non-interactive mode.

Use ROS CDK commands

ros-cdk init

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

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

ros-cdk config

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 load-config

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!

ros-cdk list (ls)

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

ros-cdk synthesize(synth)

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

ros-cdk deploy

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.

  • -- json, -j: prints the template to STDOUT by using the JSON format instead of the YAML format.

  • -- ignore-errors: ignores composition errors, which may produce invalid outputs.

  • -- detail-log: displays more error messages when a stack deployment error occurs.

  • -- disable-rollback: disables rollback when stack creation fails.

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 CdkTestStack CdkDemoStack --disable-rollback=true # Disables rollback when stack creation fails. 
 ros-cdk deploy CdkDemoStack --parameters uploadBucketName=UploadBucket
 ros-cdk deploy CdkDemoStack CdkTestStack --parameters CdkDemoStack:uploadBucketName=UploadBucket --parameters CdkTestStack:uploadBucketName=UpBuckett

ros-cdk list-stacks

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 per page. Maximum value: 50. Default value: 10.

  • -- app: queries the stack details in a specified application.

  • -- ignore-errors: ignores composition errors, which may produce invalid outputs.

  • -- json, -j: prints the template to STDOUT by using the JSON format instead of the YAML format.

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

ros-cdk event

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

ros-cdk output

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

ros-cdk resource

After you create a stack, you can run the ros-cdk resource command to query the details about the 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****"
         }
 ]

ros-cdk diff

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 proceed with the creation.

 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-vsw-modify

ros-cdk destroy

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

ros-cdk generate-stack-file

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!

ros-cdk config-set

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 Elastic Compute Service (ECS) instance. 
 
 ros-cdk config-set --region cn-beijing --mode AK --ak LTAI5t884amF1U********** --sk hmwX2uq7kZ5mBw*************
 
  ✅ Your cdk configuration has been saved successfully!
Note

You can use the ros-cdk CAMMAND --help command to view more command parameters.