alibabacloud-ecs-patch-management

ECS パッチ管理

OOS の ACS-ECS-BulkyApplyPatchBaseline テンプレートを使用して、Alibaba Cloud ECS インスタンスの OS パッチをスキャンしてインストールします。

アーキテクチャ

ECS + OOS + Cloud Assistant + スナップショット（任意）

• OOS テンプレート：ACS-ECS-BulkyApplyPatchBaseline — バッチパッチ操作用の組み込みパブリックテンプレート
• Cloud Assistant：ECS インスタンスでパッチコマンドを実行します（Cloud Assistant クライアントのインストールが必要です）
• スナップショットサービス：ロールバックに備えて、パッチ適用前にディスクのスナップショットを作成します（任意）
• パッチベースライン：スキャン／インストールするパッチを定義します（デフォルトのシステムベースラインまたはカスタムのものを使用します）

事前確認：Aliyun CLI >= 3.3.3 が必要です

aliyun version を実行して、バージョンが 3.3.3 以上であることを確認します。未インストールの場合、またはバージョンが古い場合は、 curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash を実行してインストール／更新するか、 インストール手順については references/cli-installation-guide.md を参照してください。

事前確認：Aliyun CLI プラグインの更新が必要です

[MUST] aliyun configure set --auto-plugin-install true を実行して、プラグインの自動インストールを有効にします。 [MUST] aliyun plugin update を実行して、既存のプラグインを常に最新の状態にします。

事前確認：Alibaba Cloud の認証情報が必要です

セキュリティルール：

• AK／SK の値を読み取ったり、エコーしたり、出力したりすることは絶対にしないでください
• 会話中またはコマンドラインで、AK／SK を直接入力するようユーザーに求めることは絶対にしないでください
• 文字列の認証情報を指定して aliyun configure set を使用することは絶対にしないでください
• 認証情報の状態確認には aliyun configure list のみを使用してください

aliyun configure list

出力を確認し、有効なプロファイル（AK、STS、または OAuth ID）があることを確認します。

有効なプロファイルがない場合は、ここで停止してください。

1. Alibaba Cloud Console から認証情報を取得します
2. このセッションの外部で認証情報を設定します（ターミナルで aliyun configure を実行するか、シェルプロファイルで環境変数を設定します）
3. aliyun configure list に有効なプロファイルが表示された後、戻って再実行します

AI モードのライフサイクル管理

コアワークフローの開始時（CLI の呼び出し前）に： [MUST] AI モードを有効にする — エージェントスキルの実行には AI モードが必要です。 CLI を呼び出す前に、次のコマンドを実行します：

aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-ecs-patch-management"

[MUST] すべての終了時に AI モードを無効にする — どのような理由であっても、最終応答を返す前に必ず AI モードを無効にします。これは、ワークフローの成功、ワークフローの失敗、エラー／例外、ユーザーによるキャンセル、セッション終了、またはそれ以上 CLI コマンドを実行しないその他すべての状況を含む、すべての終了経路に適用されます。 AI モードはエージェントスキルの呼び出しシナリオでのみ使用し、スキルの実行停止後に有効なままにしてはいけません。

aliyun configure ai-mode disable

RAM ポリシー

このスキルに必要な権限：

サービス	アクション	目的
OOS	StartExecution, ListExecutions, CancelExecution, ListTemplates, GetTemplate	パッチ実行の管理
OOS	ListPatchBaselines, GetPatchBaseline, ListInstancePatches, ListInstancePatchStates	パッチベースラインとステータスのクエリ
ECS	DescribeInstances, DescribeInvocations, DescribeInvocationResults, InvokeCommand	インスタンスの検証と Cloud Assistant
ECS	CreateSnapshot, DescribeSnapshots	スナップショットの管理（任意）

詳細：references/ram-policies.md

[MUST] 権限エラーへの対応： 実行中のいずれかの時点で、コマンドまたは API 呼び出しが権限エラーにより失敗した場合は、次の手順に従ってください：

1. references/ram-policies.md を読み、この SKILL に必要な権限の全一覧を確認します
2. ram-permission-diagnose スキルを使用して、必要な権限を申請する手順をユーザーに案内します
3. 必要な権限が付与されたことをユーザーが確認するまで待機します

ユーザーによる確認が必要なパラメーター

重要：パラメーターの確認 — コマンドまたは API 呼び出しを実行する前に、 ユーザーがカスタマイズできるすべてのパラメーター（例：RegionId、インスタンス ID、アクションの種類、 スナップショットの設定など）をユーザーに確認する必要があります。明示的な承認なしに、 値を推測したり、デフォルト値を使用したりしないでください。

パラメーター	必須	説明	デフォルト
regionId	はい	Alibaba Cloud のリージョン ID（例：cn-hangzhou、cn-shanghai）	なし
instanceIds	はい	対象の ECS インスタンス ID（例：["i-bp1example0000000001"]）	なし
action	はい	操作の種類：scan（スキャンのみ）または install（スキャン＋インストール）	なし
rebootIfNeed	いいえ（install のみ）	パッチの適用に必要な場合、インスタンスを再起動するかどうか	false
whetherCreateSnapshot	いいえ（install のみ）	パッチのインストール前にスナップショットを作成するかどうか	false
retentionDays	いいえ（install のみ）	スナップショットの保持日数。推奨：7～30（API の範囲：1～65536）	7

上記のパラメーター名は、--parameters で使用する JSON フィールド名と一致します（トップレベルのキーは camelCase です）。ネストされた targets オブジェクトでは、PascalCase のキー（ResourceIds、RegionId、Type）を使用します。以下のステップ 3 の例を参照してください。

主なワークフロー

ステップ 0：AI モードを有効にする

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

ステップ 1：CLI と認証情報を確認する

aliyun version
aliyun configure list

ステップ 2：対象インスタンスを確認する

対象の ECS インスタンスが存在し、Running ステータスであることを確認します。

aliyun ecs describe-instances \
  --region <RegionId> \
  --instance-ids '<InstanceIds_JSON>' \
  --cli-query 'Instances.Instance[].{InstanceId:InstanceId, Status:Status, OSName:OSName}'

前提条件：対象の ECS インスタンスには、Cloud Assistant クライアントがインストールされ、実行されている必要があります。Alibaba Cloud のほとんどのパブリックイメージには、デフォルトで含まれています。

ステップ 3：パッチ適用を開始する

[必須] ユーザーが指定したアクションに従ってください。 ユーザーが明示的にパッチのインストールを依頼した場合（例：「装补丁」、「安装补丁」、「install patches」）、action=install を必ず実行してください。以前のスキャンで未適用のパッチが 0 件と返されたことを理由に、インストールの呼び出しを省略しないでください。スキャン結果は参考情報にすぎません。インストールアクションには独自の検出ロジックがあり、ユーザーの明示的な意図が常に優先されます。

[必須] StartExecution は非同期です。 レスポンスで確認できるのは実行が送信されたことだけであり、完了したことではありません。レスポンスには exec-xxx 形式の ExecutionId（例：exec-example0000000001）が含まれます。この ExecutionId を必ず取得し、操作が完了したと判断する前に、Status が終端値（Success または Failed）に達するまで ListExecutions（ステップ 4）をポーリングしてください。StartExecution が成功したというレスポンスを、パッチ適用操作が成功した証拠として扱わないでください。

[必須] ClientToken による冪等性。 StartExecution は書き込み操作です。ネットワークタイムアウト、トランスポート層のエラー、またはエージェントの再試行ループによって、同じ呼び出しが複数回実行されることがあり、その場合は重複した実行が作成されます（install の場合、スナップショットや再起動も重複します）。同じ入力での再試行が同一の実行に収束するよう、リクエストの入力から決定論的に生成した --client-token を必ず渡してください。

生成ルール — 正規化した入力（action、region、ソート済みのインスタンス ID、動作を変える install 専用の設定）に基づいて、安定したハッシュを計算します。

# 正規化した入力から決定論的な ClientToken（64 文字以下）を生成します。
# 再試行でも同じ数式を使用してください。サーバーは約 24 時間、重複を排除します。
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)"
# 出力例：patch-9f3c1a8b7e6d5c4f3a2b1d0e9c8b7a6f

生成した値を、すべての start-execution 呼び出しで --client-token "$CLIENT_TOKEN" として渡してください。一時的な失敗の後に再試行する場合は、同じトークンを再利用してください。再生成しないでください。

オプション A：スキャンのみ

aliyun oos start-execution \
  --region <RegionId> \
  --biz-region-id <RegionId> \
  --template-name ACS-ECS-BulkyApplyPatchBaseline \
  --client-token "$CLIENT_TOKEN" \
  --parameters '{"regionId":"<RegionId>","action":"scan","targets":{"ResourceIds":<InstanceIds_JSON>,"RegionId":"<RegionId>","Type":"ResourceIds"}}'

オプション B：パッチをインストールする

🚨 危険 — ユーザーによる明示的な確認が必要な破壊的操作です。 action=install は対象インスタンス上のシステムパッケージを変更します。また、 rebootIfNeed=true の場合、サービス停止を伴う 再起動 が発生する可能性があります。

以下のコマンドを実行する前に、必ず次のことを行ってください。

1. 完全な実行計画（regionId、対象インスタンス ID の正確な一覧と 件数、 rebootIfNeed、whetherCreateSnapshot、retentionDays）を、1 つの確認メッセージでユーザーに提示します。
2. 次の内容を明示します。"リージョン の N 個のインスタンスにパッチをインストールします。 再起動=<true/false>。スナップショット=<true/false>。続行しますか？"
3. ユーザーから肯定的な返答（yes／确认／proceed）があるまで待ちます。 以前のターンから同意を推測したり、返答がない場合にデフォルトで「はい」としたりしてはいけません。
4. ユーザーがパラメーターを変更した場合は、CLIENT_TOKEN を再生成して、再度確認します。

aliyun oos start-execution \
  --region <RegionId> \
  --biz-region-id <RegionId> \
  --template-name ACS-ECS-BulkyApplyPatchBaseline \
  --client-token "$CLIENT_TOKEN" \
  --parameters '{"regionId":"<RegionId>","action":"install","rebootIfNeed":<true/false>,"whetherCreateSnapshot":<true/false>,"retentionDays":<number>,"targets":{"ResourceIds":<InstanceIds_JSON>,"RegionId":"<RegionId>","Type":"ResourceIds"}}'

例 — cn-hangzhou のインスタンス i-bp1example0000000001 をスキャンする場合：

CLIENT_TOKEN="patch-$(printf 'scan|cn-hangzhou|i-bp1example0000000001|||' | shasum -a 256 | cut -c1-32)"

aliyun oos start-execution \
  --region cn-hangzhou \
  --biz-region-id cn-hangzhou \
  --template-name ACS-ECS-BulkyApplyPatchBaseline \
  --client-token "$CLIENT_TOKEN" \
  --parameters '{"regionId":"cn-hangzhou","action":"scan","targets":{"ResourceIds":["i-bp1example0000000001"],"RegionId":"cn-hangzhou","Type":"ResourceIds"}}'

例 — スナップショットを作成し、自動再起動を行ってパッチをインストールする場合：

CLIENT_TOKEN="patch-$(printf 'install|cn-hangzhou|i-bp1example0000000001|true|true|7' | shasum -a 256 | cut -c1-32)"

aliyun oos start-execution \
  --region cn-hangzhou \
  --biz-region-id cn-hangzhou \
  --template-name ACS-ECS-BulkyApplyPatchBaseline \
  --client-token "$CLIENT_TOKEN" \
  --parameters '{"regionId":"cn-hangzhou","action":"install","rebootIfNeed":true,"whetherCreateSnapshot":true,"retentionDays":7,"targets":{"ResourceIds":["i-bp1example0000000001"],"RegionId":"cn-hangzhou","Type":"ResourceIds"}}'

ステップ 4：実行ステータスを監視する

ステップ 3 の応答から ExecutionId（形式：exec-xxx）を取得し、実行が終端ステータスに達するまで ListExecutions をポーリングします。

aliyun oos list-executions \
  --region <RegionId> \
  --biz-region-id <RegionId> \
  --execution-id <ExecutionId> \
  --cli-query 'Executions.Execution[0].{ExecutionId:ExecutionId, Status:Status, StartDate:StartDate, EndDate:EndDate}'

終端ステータス（Status が次のいずれかに一致したらポーリングを停止します）：

ステータス	意味	次のアクション
Success	実行が正常に完了しました	ステップ 5（ログ）とステップ 6（パッチの検証）に進みます
Failed	実行に失敗しました	ステップ 5 でログを確認し、失敗の原因を診断します
Cancelled	実行がキャンセルされました	以降の操作は不要です。必要に応じて再実行します

非終端ステータス（ポーリングを続けます）：Started、Running、Queued、Waiting。終端ステータスに達するまで、適切な間隔（例：10～30 秒ごと）でポーリングを続けます。パッチ操作が完了したと判断するのは、Status が Success または Failed になった場合のみです。

ステップ 5：実行ログを表示する

aliyun oos list-execution-logs \
  --region <RegionId> \
  --biz-region-id <RegionId> \
  --execution-id <ExecutionId>

ステップ 6：パッチの結果を検証する

scan または install の実行が Success に達した後、2 つの補完的な API で各インスタンスのパッチ状態を確認できます。

6a. ListInstancePatches — 単一インスタンスのパッチごとの詳細

インスタンス上で検出された個々のパッチの全リストを、パッチ名／KB、分類、重要度、パッチごとのステータス（例：Installed、Missing、NotApplicable）などのメタデータとともに返します。どのパッチが適用済みか、不足しているか、失敗したかを調べるために使用します。

aliyun oos list-instance-patches \
  --region <RegionId> \
  --biz-region-id <RegionId> \
  --instance-id <InstanceId>

6b. ListInstancePatchStates — 複数インスタンスの状態別件数の概要

各インスタンスについて、状態別にグループ化されたパッチの集計件数（例：InstalledCount、MissingCount、FailedCount、NotApplicableCount）を返します。個々のパッチを列挙せず、各カテゴリに該当するパッチ数をすばやく評価するために使用します。

aliyun oos list-instance-patch-states \
  --region <RegionId> \
  --biz-region-id <RegionId> \
  --instance-ids '<InstanceIds_JSON>'

使い分け：

• コンプライアンスの概要（例：「インスタンス i-xxx にはまだ不足しているパッチが 3 件ある」）が必要ですか？ → ListInstancePatchStates
• 特定のパッチ（例：「不足している CVE はどれか」）を特定する必要がありますか？ → ListInstancePatches

ステップ 7：AI モードを無効にする

aliyun configure ai-mode disable

[MUST] 成功、失敗、エラー、キャンセルのいずれの場合も、終了時には必ず AI モードを無効にしてください。

成功の検証

詳しい検証手順については、references/verification-method.md を参照してください。

簡易検証チェックリスト：

ステップ	確認項目	コマンド
1	CLI バージョンが 3.3.3 以上	aliyun version
2	認証情報が有効	aliyun configure list
3	インスタンスが実行中	aliyun ecs describe-instances
4	実行が開始された	応答に ExecutionId が含まれている
5	実行が成功した	list-executions による Status = Success
6	パッチが適用された	list-instance-patches で Missing の件数が減少している

クリーンアップ

実行中の実行をキャンセルする

aliyun oos cancel-execution \
  --region <RegionId> \
  --execution-id <ExecutionId>

スナップショットのライフサイクル

whetherCreateSnapshot=true で作成されたスナップショットは、retentionDays の期間が過ぎると自動的に削除されます。手動で削除しないでください。保持期間に基づくことでクリーンアップの手順が一定になり、別のロールバックワークフローで必要なスナップショットを誤って削除するのを防げます。

既存のスナップショットを確認するには（読み取り専用）：

aliyun ecs describe-snapshots \
  --region <RegionId> \
  --instance-id <InstanceId>

ベストプラクティス

1. インストール前に必ずスキャンする — インストールを確定する前に、まず action: scan を実行して利用可能なパッチを確認してください。ただし、ユーザーがパッチのインストールを明示的に要求した場合は、スキャン結果にかかわらず、必ず action=install を実行してください。 不足しているパッチがゼロとスキャンで表示されても、インストールを省略してよいという意味ではありません。ユーザーの明示的な意図を優先してください。install アクションは内部でスキャンを実行するため、単独のスキャンでは検出されなかったパッチを検出する場合があります。ユーザーがインストールを要求した場合、インストールの代わりにスキャンを実行しないでください。
2. 本番環境ではスナップショットを有効にする — ロールバックを可能にするため、本番環境のインスタンスでは適切な retentionDays を設定して whetherCreateSnapshot: true にしてください。スナップショットは自動的に期限切れになるため、手動でクリーンアップする必要はありません。
3. メンテナンス時間帯にスケジュールする — パッチのインストールには再起動が必要になる場合があります。ビジネス関係者と調整してください。
4. まず本番以外の環境でテストする — 本番環境に適用する前に、必ずステージング環境または開発環境のインスタンスでパッチを検証してください。
5. 実行ログを監視する — list-execution-logs を使用して、リアルタイムの進捗を追跡し、失敗のトラブルシューティングを行ってください。
6. 再起動は慎重に扱う — インスタンスのダウンタイムを許容できる場合に限り、rebootIfNeed: true を設定してください。重要なサービスでは、rebootIfNeed: false に設定し、手動で再起動してください。
7. retentionDays を適切な期間にする — 7～30日を推奨します。保持期間を延ばすと、ストレージコストが増加します。

参考リンク

リソース	パス
CLI インストールガイド	references/cli-installation-guide.md
RAM ポリシー	references/ram-policies.md
関連コマンド	references/related-commands.md
検証方法	references/verification-method.md
受け入れ基準	references/acceptance-criteria.md

関連ドキュメント

• OOS 公式ドキュメント
• ACS-ECS-BulkyApplyPatchBaseline テンプレート
• パッチ管理の概要
• Cloud Assistant