/alibabacloud-ecs-patch-management

name: alibabacloud-ecs-patch-management
description: |
  Alibaba Cloud ECS Patch Management Skill. Use for scanning and installing OS patches on ECS instances via OOS (Operation Orchestration Service).
  Triggers: "patch management", "scan patches", "install patches", "OS update", "security patches", "ACS-ECS-BulkyApplyPatchBaseline", "oos patch", "系统补丁扫描", "系统补丁安装".

ECS Patch Management

Scan and install operating system patches on Alibaba Cloud ECS instances using the OOS `ACS-ECS-BulkyApplyPatchBaseline` template.

Architecture

**ECS + OOS + Cloud Assistant + Snapshot (optional)**

• **OOS Template**: `ACS-ECS-BulkyApplyPatchBaseline` — built-in public template for batch patch operations
• **Cloud Assistant**: Executes patch commands on ECS instances (requires Cloud Assistant client installed)
• **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). > > **If no valid profile exists, STOP here.** > 1. Obtain credentials from [Alibaba Cloud Console](https://ram.console.aliyun.com/manage/ak) > 2. Configure credentials **outside of this session** (via `aliyun configure` in terminal or environment variables in shell profile) > 3. 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: > ```bash > aliyun configure ai-mode enable > aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-ecs-patch-management" > ``` > **[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. > ```bash > aliyun configure ai-mode disable > ```

RAM Policy

Required permissions for this skill:

| Service | Actions | Purpose | |---------|---------|---------| | OOS | `StartExecution`, `ListExecutions`, `CancelExecution`, `ListTemplates`, `GetTemplate` | Manage patch executions | | OOS | `ListPatchBaselines`, `GetPatchBaseline`, `ListInstancePatches`, `ListInstancePatchStates` | Patch baseline and status queries | | ECS | `DescribeInstances`, `DescribeInvocations`, `DescribeInvocationResults`, `InvokeCommand` | Instance verification and Cloud Assistant | | ECS | `CreateSnapshot`, `DescribeSnapshots` | Snapshot management (optional) |

Full details: [references/ram-policies.md](references/ram-policies.md)

> **[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

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`) | None | | `instanceIds` | Yes | Target ECS instance IDs (e.g., `["i-bp1example0000000001"]`) | None | | `action` | Yes | 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

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). Th