alicloud-ecs

# Alibaba Cloud ECS Skill

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

## Prerequisites

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

```bash
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](scripts/setup_client.ts) for a reusable client factory, and [references/quickstart.md](references/quickstart.md) for full setup including regions, instance types, charge types, and pagination.

## Client Initialization

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

## Core Patterns

### RPC-Style API

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

```typescript
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:

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

### Page-Based Pagination

Most Describe/List APIs use `pageNumber` + `pageSize`:

```typescript
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:

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

### Error Handling

```typescript
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](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](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