CLI reference

Use Alibaba Cloud CLI

Install and configure Alibaba Cloud CLI

Use Alibaba Cloud CLI to call ECS API operations

After you install and configure Alibaba Cloud CLI, you can run commands in the following format to call ECS API operations:

aliyun ecs <API operation name> --<Parameter 1 Value 1> --<Parameter 2 Value 2> ...

Usage examples

The following example describes how to use Alibaba Cloud CLI to call ECS API operations.

Create an ECS instance

The following example describes how to create a subscription ECS instance from an Alibaba Cloud Linux image in the China (Hangzhou) region by using Alibaba Cloud CLI.

1. Make preparations.

   Before you create an ECS instance, create a virtual private cloud (VPC), a vSwitch, and a security group, and obtain the IDs of the preceding resources.

   Note

   If you already created the preceding resources and the resources meet your business requirements, skip this step.

   1. Call the CreateVpc operation to create a VPC.

      In this example, a VPC is created in the China (Hangzhou) region and associated with the CIDR block 192.168.0.0/16.

      • Sample command

        aliyun vpc CreateVpc \
        --RegionId cn-hangzhou \
        --CidrBlock 192.168.0.0/16 

      • Sample command output

        {
          "RequestId": "EC94C73B-8103-4B86-B353-E65C7C9E****",
          "ResourceGroupId": "rg-acfmzw2jz2z****",
          "RouteTableId": "vtb-bp1jxpr9ji5wcn4yv****",
          "VRouterId": "vrt-bp1dyxemup2q4ouga****",
          "VpcId": "vpc-bp1d9v4763ym2hlzt****"
        }

   2. Call the CreateVSwitch operation to create a vSwitch in the VPC.

      In this example, a vSwitch is created in the VPC whose ID is vpc-bp1d9v4763ym2hlzt**** and is associated with the CIDR block 192.168.0.0/24.

      • Sample command

        aliyun vpc CreateVSwitch \
        --CidrBlock 192.168.0.0/24 \
        --VpcId vpc-bp1d9v4763ym2hlzt**** \
        --ZoneId=cn-hangzhou-i

      • Sample command output

        {
                "RequestId": "AF1787C4-0D81-44F0-A324-D5C54EA0****",
                "VSwitchId": "vsw-bp11hf5r945gewysp****"
        }

   3. Call the CreateSecurityGroup operation to create a security group in the VPC.

      • Sample command

        aliyun ecs CreateSecurityGroup \
        --RegionId cn-hangzhou \
        --VpcId vpc-bp1d9v4763ym2hlzt****

      • Sample command output

        {
                "RequestId": "B1C25C34-9B84-49E3-9E50-FB7D7970****",
                "SecurityGroupId": "sg-bp18z2q1jg4gq95t****"
        }

   4. Call the AuthorizeSecurityGroup operation to create a security group rule in the security group.

      In this example, an inbound security group rule that allows TCP traffic on port 22 is added to the security group whose ID is sg-bp18z2q1jg4gq95t****.

      • Sample command

        aliyun ecs AuthorizeSecurityGroup \
        --RegionId cn-hangzhou \
        --SecurityGroupId sg-bp18z2q1jg4gq95t**** \
        --IpProtocol tcp \
        --SourceCidrIp 0.0.0.0/0 \
        --PortRange 22/22

      • Sample command output

        {
         "RequestId": "FA8B1E61-C9C9-4D91-9628-64B8E2F4****"
        }

2. Create an ECS instance.

   Call the RunInstances operation to create a subscription ECS instance.

   1. Example scenario

      Parameter	Description and example
      RegionId	The ID of the region in which you want to create the ECS instance. Example: cn-hangzhou.
      ImageId	The ID of the image. We recommend that you select the Alibaba Cloud Linux image whose ID is aliyun_3_x64_20G_alibase_20240528.vhd.
      InstanceType	The instance type. Examples: For personal applications, we recommend that you select the ecs.e-c1m1.large instance type that has 2 vCPUs and 2 GiB of memory. For the applications of small and medium-sized enterprises, we recommend that you select the ecs.c7.large instance type that has 2 vCPUs and 4 GiB of memory.
      SecurityGroupId	The ID of the security group. Obtain the value from the response of the CreateSecurityGroup operation. Example: sg-bp18z2q1jg4gq95t****.
      VSwitchId	The ID of the vSwitch. Obtain the value from the response of the CreateVSwitch operation. Example: vsw-bp11hf5r945gewysp****.
      InstanceName	The name of the ECS instance. Example: ecs_cli_demo.
      InstanceChargeType	The billing method of the ECS instance. To create a subscription ECS instance, set the value to PrePaid. Note Make sure that your account balance is sufficient.
      PeriodUnit	The unit of the subscription duration. Example: Month.
      Period	The subscription duration. Example: 1.
      InternetMaxBandwidthOut	The maximum outbound public bandwidth. Example: 1.
      Password	The logon password of the ECS instance. Example: <yourPassword>. Note To ensure instance security, you must specify a complex password.
      SystemDisk.Category	The category of the system disk. Example: cloud_essd.
      SystemDisk.Size	The size of the system disk. Example: 40.

   2. Sample command

      aliyun ecs RunInstances \
      --RegionId cn-hangzhou \
      --ImageId aliyun_3_x64_20G_alibase_20240528.vhd \
      --InstanceType ecs.c7.large \
      --SecurityGroupId sg-bp18z2q1jg4gq95t**** \
      --VSwitchId vsw-bp11hf5r945gewysp**** \
      --InstanceName ecs_cli_demo \
      --InstanceChargeType PrePaid \
      --PeriodUnit Month \
      --Period 1 \
      --InternetMaxBandwidthOut 1 \
      --Password <yourPassword>  \
      --SystemDisk.Category cloud_essd \
      --SystemDisk.Size 40

   3. Sample command output

      { 
              "InstanceIdSets": {
                      "InstanceIdSet": [
                              "i-bp1de173dp87k5uv****"
                      ]
              },
              "OrderId": 23577729747****,
              "RequestId": "B0855F1A-279F-5153-BAA9-C245E073****",
              "TradePrice": ****
      }

Connect to an ECS instance

1. Obtain the public IP address of an ECS instance.

   Call the DescribeInstances operation with the ID of an ECS instance to query the public IP address of the instance. In this example, the ID of the ECS instance is i-bp1ducce5hs1jm98****.

   • Sample command

     aliyun ecs DescribeInstances \
     --RegionId cn-hangzhou \
     --InstanceIds '["i-bp1ducce5hs1jm98****"]'

   • Sample command output

     The PublicIpAddresses parameter indicates the public IP address of the ECS instance.

     

2. Connect to the ECS instance.

   ssh <Username>@<Public IP address>

   

Start an ECS instance

Call the StartInstance operation to start an ECS instance.

• Example scenario: Start an ECS instance whose ID is i-bp1aq39j2yul5y01**** in the China (Hangzhou) region (cn-hangzhou) after a dry run, and do not perform troubleshooting during instance startup.

• Sample command

  aliyun ecs StartInstance \
  --RegionId cn-hangzhou \
  --InstanceId i-bp1aq39j2yul5y01**** \
  --InitLocalDisk false \
  --DryRun false

• Sample command output

  {
   "RequestId": "2DD09CBD-1F4D-4923-94C7-F3BD67137BBE"
  }

Query the details of ECS instances

Call the DescribeInstances operation to query the details of one or more ECS instances.

Create a snapshot

Call the CreateSnapshot operation to create a snapshot for a disk.

• Example scenario: Create a snapshot for an Enterprise SSD (ESSD) whose ID is d-bp14bjlwo3t3owin****. Set the snapshot name to demoname, the description to demo, and the retention period to three days.

• Sample command

  aliyun ecs CreateSnapshot \
  --DiskId d-bp14bjlwo3t3owin**** \
  --SnapshotName demoname \
  --Description demo \
  --RetentionDays 3

• Sample command output

  {
   "RequestId": "DFB0B01F-420D-4932-911E-7328920C2012",
   "SnapshotId": "s-bp1eyr9nxxoo9icj****"
  }

Create a custom image from an ECS instance

Call the CreateImage operation to create a custom image from an ECS instance.

• Example scenario

  Parameter	Description and example
  InstanceId	The ID of the ECS instance. Example: i-bp1aq39j2yul5y01****.
  Platform	The operating system distribution for the system disk in the custom image. Example: Aliyun, which indicates Alibaba Cloud Linux.
  RegionId	The ID of the region in which to create the custom image. Example: cn-hangzhou.

• Sample command

  aliyun ecs CreateImage \
  --RegionId cn-hangzhou \
  --InstanceId i-bp1aq39j2yul5y01**** \
  --ImageName demoimage \
  --Description demoimage \
  --Platform Aliyun

• Sample command output

  {
   "ImageId": "m-bp1503ydxxrppctb****",
   "RequestId": "011AE447-20CE-4043-81AC-7AF2BBC4****"
  }

Stop an ECS instance

Call the StopInstance operation with ForceStop parameter set to false and StoppedMode set to KeepCharging to stop an ECS instance in the Running (Running) state after a dry run. The ECS instance is stopped in standard mode, and billing for the ECS instance continues.

• Example scenario: Stop an ECS instance whose ID is i-bp1aq39j2yul5y01**** in the China (Hangzhou) (cn-hangzhou) region.

• Sample command

  aliyun ecs StopInstance \
  --RegionId cn-hangzhou \
  --InstanceId i-bp1aq39j2yul5y01**** \
  --ForceStop false \
  --StoppedMode KeepCharging \
  --DryRun false

• Sample command output

  {
      "RequestId": "121B5745-4983-57B1-BC97-C3A3536E****"
  }

References

This topic describes specific API operations. For information about other API operations, see List of operations by function.

In Alibaba Cloud CLI, you can specify command line options to change the behaviors of commands or implement the extended features of commands based on your business requirements. For more information, see Command-line options.