alibabacloud-ecs-instance-ops

name	alibabacloud-ecs-instance-ops
description	Alibaba Cloud ECS instance lifecycle operations. Use for creating, starting, stopping, restarting, releasing, and querying ECS instances. Covers instance status management, batch operations, and instance attribute modification. Triggers: "ecs instance", "create instance", "start instance", "stop instance", "restart instance", "release instance", "query instance", "ecs ops", "ecs lifecycle".
source	alibabacloud-ecs-ops

ECS Instance Lifecycle Operations

Manage the full lifecycle of Alibaba Cloud ECS instances: create, start, stop, restart, release, and query.

Pre-check: Alibaba Cloud CLI must be installed and at least version 3.3.3.

aliyun version   # must be >= 3.3.3; if not installed:
/bin/bash -c "$(curl -fsSL --connect-timeout 10 --max-time 120 https://aliyuncli.alicdn.com/setup.sh)"

Pre-check: Alibaba Cloud Credentials Required

Security Rules:

• NEVER read, echo, or print AK/SK values
• NEVER ask the user to input AK/SK directly
• NEVER use aliyun configure set with literal credential values
• ONLY use aliyun configure list to check credential status

aliyun configure list

If no valid profile exists, STOP and guide user to configure credentials.

Pre-check: Aliyun CLI plugin update required

aliyun configure set --auto-plugin-install true
aliyun plugin update

Observability (MUST follow for every aliyun command)

Upon loading this skill, generate a random session ID (32-char lowercase hex string) once for the entire session. Use it as {session-id} below.

Rule: Every aliyun CLI command that calls a cloud API MUST include the --user-agent flag.

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-instance-ops/{session-id}

Cost Estimation (MUST before chargeable operations)

Before executing any chargeable instance operation (run-instances, modify-instance-spec, modify-instance-charge-type), you MUST follow the alibabacloud-cli-cost-estimation skill to evaluate the cost impact at the user task level:

1. Single operation — Append --estimate-cost to the exact command before execution, present the quoted amount, and wait for user confirmation.
2. Multi-step task (e.g. stop + change spec + start) — Quote all chargeable steps up front using --estimate-cost and --estimate-cost-context as needed, present one consolidated cost plan, then ask for a single confirmation of the whole task before executing step 1.
3. Never silently execute a chargeable instance operation when a cost quote was obtainable.

The cost evaluation output must include a clearly labelled cost summary section so the user can identify it before confirming.

See the alibabacloud-cli-cost-estimation SKILL.md for the full cost plan format, quote JSON parsing, and multi-step workflow quoting rules.

Core Workflow

IMPORTANT: Parameter Confirmation — Before executing any command or API call, ALL user-customizable parameters (e.g., RegionId, instance names, CIDR blocks, passwords, domain names, resource specifications, etc.) MUST be confirmed with the user. Do NOT assume or use default values without explicit user approval.

1. Query Instances

List instances in a region with optional filters:

# List all instances in a region
aliyun ecs describe-instances --biz-region-id <RegionId> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-instance-ops/{session-id}

# Query specific instance by ID
aliyun ecs describe-instances --biz-region-id <RegionId> \
  --instance-ids '["<InstanceId>"]' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-instance-ops/{session-id}

# Filter by status (Running, Stopped, Starting, Stopping, Pending)
aliyun ecs describe-instances --biz-region-id <RegionId> \
  --status Running \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-instance-ops/{session-id}

# Filter by instance name
aliyun ecs describe-instances --biz-region-id <RegionId> \
  --instance-name "<InstanceName>" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-instance-ops/{session-id}

2. Create and Start Instance

Cost estimation: Before executing run-instances, run with --estimate-cost to get a quote. Present the cost to the user (e.g. "Estimated instance cost: ¥X/month (PostPaid) or ¥X (PrePaid). Proceed?").

# Create and start instance (RunInstances)
aliyun ecs run-instances \
  --biz-region-id <RegionId> \
  --security-group-id <SecurityGroupId> \
  --v-switch-id <VSwitchId> \
  --image-id <ImageId> \
  --instance-type <InstanceType> \
  --instance-name <InstanceName> \
  --system-disk.category cloud_essd \
  --system-disk.size 40 \
  --instance-charge-type PostPaid \
  --internet-max-bandwidth-out 0 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-instance-ops/{session-id}

3. Start / Stop / Restart Instance

# Start instance
aliyun ecs start-instance --instance-id <InstanceId> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-instance-ops/{session-id}

# Stop instance (graceful)
aliyun ecs stop-instance --instance-id <InstanceId> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-instance-ops/{session-id}

# Stop instance (force)
aliyun ecs stop-instance --instance-id <InstanceId> \
  --force-stop true \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-instance-ops/{session-id}

# Restart instance
aliyun ecs reboot-instance --instance-id <InstanceId> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-instance-ops/{session-id}

4. Release Instance

# Release a Pay-As-You-Go instance
aliyun ecs delete-instance --instance-id <InstanceId> --force true \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-instance-ops/{session-id}

WARNING: Instance release is irreversible. Always confirm with the user before executing.

5. Modify Instance Attributes

Cost estimation: Before executing modify-instance-spec, run with --estimate-cost to get a quote for the spec change delta. Present the cost to the user (e.g. "Estimated spec change delta: ¥X. Proceed?").

# Modify instance name
aliyun ecs modify-instance-attribute --instance-id <InstanceId> \
  --instance-name "<NewName>" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-instance-ops/{session-id}

# Modify instance type (requires stop first)
aliyun ecs modify-instance-spec --instance-id <InstanceId> \
  --instance-type <NewInstanceType> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-instance-ops/{session-id}

RAM Policy

Action	Resource
ecs:DescribeInstances	*
ecs:RunInstances	*
ecs:StartInstance	acs:ecs:*:*:instance/<InstanceId>
ecs:StopInstance	acs:ecs:*:*:instance/<InstanceId>
ecs:RebootInstance	acs:ecs:*:*:instance/<InstanceId>
ecs:DeleteInstance	acs:ecs:*:*:instance/<InstanceId>
ecs:ModifyInstanceAttribute	acs:ecs:*:*:instance/<InstanceId>
ecs:ModifyInstanceSpec	acs:ecs:*:*:instance/<InstanceId>

[MUST] Permission Failure Handling: When any command or API call fails due to permission errors at any point during execution, follow this process:

1. Read references/ram-policies.md to get the full list of permissions required by this SKILL
2. Use ram-permission-diagnose skill to guide the user through requesting the necessary permissions
3. Pause and wait until the user confirms that the required permissions have been granted

Success Verification

# Verify instance status after operations
aliyun ecs describe-instances --biz-region-id <RegionId> \
  --instance-ids '["<InstanceId>"]' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ecs-instance-ops/{session-id}
# Check Status field: Running, Stopped, Starting, Stopping

Related Commands Reference

See references/related-commands.md for the complete ECS instance CLI command reference.