agents-infrastructure/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