Alicloud ecs

Alibaba Cloud ECS Skill

Manage cloud servers, disks, images, networks, security, and operations via the @alicloud/ecs20140526 TypeScript SDK.

Prerequisites

npm install @alicloud/ecs20140526 @alicloud/openapi-core @darabonba/typescript

export ALIBABA_CLOUD_ACCESS_KEY_ID="<your-key-id>"
export ALIBABA_CLOUD_ACCESS_KEY_SECRET="<your-key-secret>"
export ALIBABA_CLOUD_REGION_ID="cn-hangzhou"

See scripts/setup_client.ts for a reusable client factory, and references/quickstart.md for full setup including regions, instance types, charge types, and pagination.

Client Initialization

import Client from '@alicloud/ecs20140526';
import { Config } from '@alicloud/openapi-core';

const client = new Client(new Config({
  accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID,
  accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET,
  regionId: 'cn-hangzhou',
  endpoint: 'ecs.cn-hangzhou.aliyuncs.com',
}));

API Overview (374 APIs in 14 Domains)

Domain	APIs	Key Operations	Reference
Instance	71	runInstances, startInstance, stopInstance, describeInstances	references/instance.md
Disk & Snapshot	46	createDisk, attachDisk, createSnapshot, createAutoSnapshotPolicy	references/disk.md
Image	23	createImage, copyImage, importImage, describeImages	references/image.md
Security Group	15	createSecurityGroup, authorizeSecurityGroup, revokeSecurityGroup	references/security-group.md
Network & EIP	91	createVpc, createVSwitch, allocateEipAddress, createNetworkInterface	references/network.md
SSH Key Pair	6	createKeyPair, attachKeyPair, describeKeyPairs	references/key-pair.md
Dedicated Host	15	allocateDedicatedHosts, describeDedicatedHosts	references/dedicated-host.md
Auto Provisioning	20	createAutoProvisioningGroup, createElasticityAssurance	references/auto-scaling.md
Launch Template	7	createLaunchTemplate, describeLaunchTemplates	references/launch-template.md
Cloud Assistant	22	runCommand, describeInvocationResults, createActivation	references/command.md
Tag & Resource	18	tagResources, describeRegions, describeZones	references/tag-resource.md
System Events	20	describeInstancesFullStatus, createDiagnosticReport	references/system-event.md
Storage & Deployment	16	createStorageSet, createDeploymentSet, createSavingsPlan	references/storage-capacity.md
Prefix List	5	createPrefixList, describePrefixLists	references/prefix-list.md

Core Patterns

RPC-Style API

ECS uses RPC-style APIs. All parameters are flat fields in a Request object:

import * as models from '@alicloud/ecs20140526/dist/models';

const { body } = await client.describeInstances(new models.DescribeInstancesRequest({
  regionId: 'cn-hangzhou',
  instanceIds: JSON.stringify(['i-xxx1', 'i-xxx2']),
  pageSize: 10,
  pageNumber: 1,
}));

regionId is Required

Almost all ECS APIs require regionId. Always include it:

const request = new models.DescribeDisksRequest({
  regionId: 'cn-hangzhou',  // Required!
  diskIds: JSON.stringify(['d-xxx']),
});

Page-Based Pagination

Most Describe/List APIs use pageNumber + pageSize:

let pageNumber = 1;
let all: any[] = [];
while (true) {
  const { body } = await client.describeInstances(new models.DescribeInstancesRequest({
    regionId: 'cn-hangzhou', pageSize: 100, pageNumber,
  }));
  all.push(...(body.instances?.instance || []));
  if (all.length >= (body.totalCount || 0)) break;
  pageNumber++;
}

JSON-Encoded Array Parameters

Some parameters accept JSON-encoded arrays:

// instanceIds, diskIds, etc. are JSON strings
instanceIds: JSON.stringify(['i-xxx1', 'i-xxx2']),
diskIds: JSON.stringify(['d-xxx1']),

Error Handling

try {
  await client.describeInstances(request);
} catch (err: any) {
  console.error(`Code: ${err.code}, Message: ${err.message}, RequestId: ${err.data?.RequestId}`);
}

Common Workflows

1. Launch Instance

describeRegions → describeInstanceTypes → describeImages → createSecurityGroup → authorizeSecurityGroup → runInstances

2. Disk & Snapshot

createDisk → attachDisk → createSnapshot → createAutoSnapshotPolicy → applyAutoSnapshotPolicy

3. Image Management

createImage → copyImage → describeImages → importImage / exportImage

4. Security Group Rules

createSecurityGroup → authorizeSecurityGroup → authorizeSecurityGroupEgress → describeSecurityGroupAttribute

5. Instance Scaling

stopInstance → modifyInstanceSpec → startInstance

6. Remote Command Execution

describeCloudAssistantStatus → runCommand → describeInvocationResults

7. Network Interface

createNetworkInterface → attachNetworkInterface → assignPrivateIpAddresses

8. Key Pair Login

createKeyPair → runInstances (keyPairName) → attachKeyPair

9. Dedicated Host

describeDedicatedHostTypes → allocateDedicatedHosts → runInstances (dedicatedHostId)

10. Tag-Based Management

tagResources → describeInstances (tag filter) → untagResources

See references/workflows.md for detailed workflow examples with full code.

API Reference Quick Index

Load the corresponding reference file for parameter details:

• Instance lifecycle/types/pricing: references/instance.md
• Disk/snapshot/auto-snapshot: references/disk.md
• Image/pipeline/share: references/image.md
• Security group/rules: references/security-group.md
• VPC/VSwitch/EIP/ENI/NAT/Route: references/network.md
• SSH key pairs: references/key-pair.md
• Dedicated hosts/clusters: references/dedicated-host.md
• Auto provisioning/elasticity/capacity: references/auto-scaling.md
• Launch templates: references/launch-template.md
• Cloud Assistant commands: references/command.md
• Tags/regions/zones/tasks: references/tag-resource.md
• System events/diagnostics: references/system-event.md
• Storage sets/deployment sets/savings: references/storage-capacity.md
• Prefix lists: references/prefix-list.md

Each reference file contains per-API documentation with method signatures and parameter tables.

Code Examples

See scripts/examples.ts for ready-to-use code covering:

• Instance CRUD and lifecycle management
• Security group creation and rule management
• Disk creation, attachment, and snapshot
• Image creation and listing
• SSH key pair management
• Cloud Assistant remote command execution
• Tag-based resource management
• Region and zone queries