Snapshot Service: Creates pre-patch disk snapshots for rollback safety (optional)
Patch Baseline: Defines which patches to scan/install (uses default system baseline or custom)
Pre-check: Aliyun CLI >= 3.3.3 Required
Run aliyun version to verify >= 3.3.3. If not installed or version too low,
run curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash to install/update,
or see references/cli-installation-guide.md for installation instructions.
Pre-check: Aliyun CLI plugin update required
[MUST] run aliyun configure set --auto-plugin-install true to enable automatic plugin installation.
[MUST] run aliyun plugin update to ensure that any existing plugins are always up-to-date.
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 in the conversation or command line
NEVER use aliyun configure set with literal credential values
ONLY use aliyun configure list to check credential status
bash
aliyun configure list
Check the output for a valid profile (AK, STS, or OAuth identity).
Configure credentials outside of this session (via aliyun configure in terminal or environment variables in shell profile)
Return and re-run after aliyun configure list shows a valid profile
AI-Mode Lifecycle Management
At the start of the Core Workflow (before any CLI invocation):
[MUST] Enable AI-Mode — AI-mode is required for Agent Skill execution.
Run the following commands before any CLI invocation:
[MUST] Disable AI-Mode at EVERY exit point — Before delivering the final response for ANY reason, always disable AI-mode first. This applies to ALL exit paths: workflow success, workflow failure, error/exception, user cancellation, session end, or any other scenario where no further CLI commands will be executed.
AI-mode is only used for Agent Skill invocation scenarios and MUST NOT remain enabled after the skill stops running.
[MUST] Permission Failure Handling: When any command or API call fails due to permission errors at any point during execution, follow this process:
Read references/ram-policies.md to get the full list of permissions required by this SKILL
Use ram-permission-diagnose skill to guide the user through requesting the necessary permissions
Pause and wait until the user confirms that the required permissions have been granted
Parameters Requiring User Confirmation
IMPORTANT: Parameter Confirmation — Before executing any command or API call,
ALL user-customizable parameters (e.g., RegionId, instance IDs, action type,
snapshot settings, etc.) MUST be confirmed with the user. Do NOT assume or use
default values without explicit user approval.
Parameter
Required
Description
Default
regionId
Yes
Alibaba Cloud region ID (e.g., cn-hangzhou, cn-shanghai)
Operation type: scan (scan only) or install (scan + install)
None
rebootIfNeed
No (install only)
Whether to reboot the instance if patches require it
false
whetherCreateSnapshot
No (install only)
Whether to create a snapshot before installing patches
false
retentionDays
No (install only)
Snapshot retention in days. Recommended: 7–30 (API range: 1–65536)
7
Parameter names above match the JSON field names used in --parameters (top-level keys are camelCase). Note that the nested targets object uses PascalCase keys (ResourceIds, RegionId, Type) — see the examples in Step 3 below.
Core Workflow
Step 0: Enable AI-Mode
bash
aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-ecs-patch-management"
# [MUST] Register a shell trap so AI-mode is disabled on EVERY exit path
# (success, error, signal, Ctrl-C, abnormal termination). This is the
# fail-safe complement to the explicit `disable` call in Step 7.
trap 'aliyun configure ai-mode disable' EXIT
Step 1: Verify CLI and Credentials
bash
aliyun version
aliyun configure list
Step 2: Verify Target Instances
Confirm the target ECS instances exist and are in Running status:
Prerequisite: Target ECS instances must have the Cloud Assistant client installed and running. Most Alibaba Cloud public images include it by default.
Step 3: Start Patch Execution
[MUST] Honor the user's requested action. If the user explicitly asks to install patches (e.g., "装补丁", "安装补丁", "install patches"), you MUST execute action=install. Do NOT skip the install call because a prior scan returned zero missing patches. The scan is advisory only — the install action has its own detection logic and the user's explicit intent always takes precedence.
[MUST] StartExecution is asynchronous. The response only confirms that the execution has been submitted, not that it has finished. The response returns an ExecutionId in the format exec-xxx (e.g., exec-example0000000001). You MUST capture this ExecutionId and poll ListExecutions (Step 4) until Status reaches a terminal value (Success or Failed) before considering the operation complete. Do NOT treat a successful StartExecution response as proof that the patch operation succeeded.
[MUST] Idempotency via ClientToken.StartExecution is a write operation. A network timeout, a transport-layer error, or an Agent retry loop can cause the same call to be issued more than once, which would otherwise create duplicate executions (and, for install, duplicate snapshots/reboots). You MUST pass a --client-token derived deterministically from the request inputs so that retries with the same inputs converge on the same execution.
Generation rule — compute a stable hash over the canonical inputs (action, region, sorted instance IDs, and the install-only knobs that change behavior):
bash
# Generate a deterministic ClientToken (≤ 64 chars) from the canonical inputs.
# Use the SAME formula across retries — the server deduplicates within ~24h.
CLIENT_TOKEN="patch-$(printf '%s|%s|%s|%s|%s|%s' \
"<action>" "<RegionId>" "<sorted_comma_joined_InstanceIds>" \
"<rebootIfNeed_or_empty>" "<whetherCreateSnapshot_or_empty>" "<retentionDays_or_empty>" \
| shasum -a 256 | cut -c1-32)"
# Example output: patch-9f3c1a8b7e6d5c4f3a2b1d0e9c8b7a6f
Pass the resulting value as --client-token "$CLIENT_TOKEN" on every start-execution call. If you must retry after a transient failure, reuse the same token; do NOT regenerate it.
🚨 DANGER — Destructive operation requiring explicit user confirmation.action=install will modify system packages on the target instance(s) and, if
rebootIfNeed=true, may reboot them, causing service downtime.
Before executing the command below, you MUST:
Display the full execution plan to the user — regionId, the exact list of
target instance IDs (and count), rebootIfNeed, whetherCreateSnapshot,
retentionDays — in a single confirmation message.
State explicitly: "About to install patches on N instance(s) in .
Reboot=<true/false>. Snapshot=<true/false>. Proceed?"
Wait for the user to reply with an affirmative (yes / 确认 / proceed).
Do NOT infer consent from earlier turns or default to yes on silence.
If the user changes any parameter, regenerate CLIENT_TOKEN and re-confirm.
Terminal statuses (stop polling when Status matches one of these):
Status
Meaning
Next action
Success
Execution finished successfully
Proceed to Step 5 (logs) and Step 6 (verify patches)
Failed
Execution failed
Inspect logs in Step 5 to diagnose the failure
Cancelled
Execution was cancelled
No further action; re-run if needed
Non-terminal statuses (keep polling): Started, Running, Queued, Waiting. Continue polling at a reasonable interval (e.g., every 10–30 seconds) until a terminal status is reached. Only consider the patch operation complete once Status is Success or Failed.
After a scan or install execution reaches Success, two complementary APIs report patch state on each instance:
6a. ListInstancePatches — per-patch detail on a single instance
Returns the full list of individual patches detected on the instance, with metadata such as patch name/KB, classification, severity, and per-patch status (e.g., Installed, Missing, NotApplicable). Use this to inspect which patches are present, missing, or failed.
6b. ListInstancePatchStates — per-state count summary across instances
Returns aggregate counts of patches grouped by state for each instance (e.g., InstalledCount, MissingCount, FailedCount, NotApplicableCount). Use this to quickly assess how many patches fall into each category without enumerating individual patches.
Snapshots created with whetherCreateSnapshot=true are automatically deleted
when their retentionDays window expires. Do not delete them manually —
relying on the retention window keeps the cleanup deterministic and avoids
accidentally removing a snapshot that another rollback workflow still needs.
Always scan before install — Run action: scan first to understand what patches are available before committing to installation. However, if the user explicitly requests patch installation, you MUST still execute action=install regardless of scan results. A scan showing zero missing patches does NOT mean you can skip the install — the user's explicit intent takes priority. The install action performs its own internal scan and may detect patches the standalone scan did not. Never substitute a scan for an install when the user asked for installation.
Enable snapshots for production — Set whetherCreateSnapshot: true with an appropriate retentionDays for production instances to enable rollback. Snapshots auto-expire — no manual cleanup needed.
Schedule during maintenance windows — Patch installation may require reboots. Coordinate with business stakeholders.
Test on non-production first — Always validate patches on a staging/dev instance before applying to production.
Monitor execution logs — Use list-execution-logs to track real-time progress and troubleshoot failures.
Handle reboot carefully — Set rebootIfNeed: true only when you can tolerate instance downtime. For critical services, use rebootIfNeed: false and reboot manually.
