alibabacloud-elasticsearch-instance-manage

Elasticsearch インスタンスと設定の管理

Aliyun CLI を使って Alibaba Cloud Elasticsearch インスタンスとインスタンス側の設定を管理します。インスタンスのライフサイクル（作成／詳細表示／一覧表示／再起動／アップグレード／ダウングレード／ノード情報）と、インスタンス設定（スナップショットバックアップ、アナライザー辞書）を管理できます。

このスキルではインテントルーティングを使用します。このファイルでユーザーのインテントを特定し、該当するモジュールドキュメントに振り分けます。CLI コマンドを生成する前に、該当するモジュールドキュメントを最後まで読んでください。

アーキテクチャ

Alibaba Cloud Elasticsearch Management
├── Instance Lifecycle           --> references/instance-manage.md
│   ├── createInstance           (Create Instance)
│   ├── DescribeInstance         (Query Instance Details)
│   ├── ListInstance             (List Instances)
│   ├── RestartInstance          (Restart Instance)
│   ├── UpdateInstance           (Upgrade / Downgrade)
│   ├── ListAllNode              (Query Cluster Node Info)
│   ├── UpdateAdminPassword      (Update Admin Password)
│   ├── UpdateDescription        (Update Instance Name)
│   ├── UpdateInstanceChargeType (Convert pay-as-you-go to subscription)
│   ├── UpgradeInfo              (Query available upgrade versions)
│   ├── UpgradeEngineVersion     (Upgrade ES version / kernel patch)
│   ├── ListActionRecords        (Query change records / upgrade progress)
│   └── ContinueEsVersionUpgrade (Continue gray upgrade of remaining nodes)
├── Instance Config              --> references/config-manage.md
│   ├── Snapshot Management
│   │   ├── UpdateSnapshotSetting    (Set auto-snapshot policy)
│   │   ├── DescribeSnapshotSetting  (Query auto-snapshot policy)
│   │   └── CreateSnapshot           (Trigger one-shot snapshot)
│   ├── Dict Management
│   │   ├── ListDicts                (List analyzer dicts)
│   │   ├── UpdateDict               (Cold-update IK dict)
│   │   ├── UpdateHotIkDicts         (Hot-update IK dict)
│   │   ├── UpdateSynonymsDicts      (Update synonyms dict)
│   │   └── UpdateAliwsDict          (Update AliNLP dict)
│   ├── Kibana Settings
│   │   ├── DescribeKibanaSettings   (Query Kibana config)
│   │   └── UpdateKibanaSettings     (Update Kibana language)
│   └── ES Cluster YML
│       └── UpdateInstanceSettings   (Update YML config — triggers restart)
└── Plugin Management            --> references/plugin-manage.md
    ├── ListPlugins              (List system plugins)
    ├── ListUserPlugin           (List user custom plugins)
    ├── InstallSystemPlugin      (Install system plugin)
    ├── UninstallPlugin          (Uninstall system plugin)
    ├── PluginAnalysis           (Upload custom plugin to library)
    └── InstallUserPlugins       (Install user custom plugins)

---

インテントルーティング

ユーザーのリクエストに最初に一致する行を特定し、記載されたモジュールドキュメントを読み込んで、その API 仕様に従ってください。

ユーザーの要望（キーワード）	モジュール	必読ドキュメント	主要 API
インスタンスの作成／詳細表示／一覧表示／再起動、設定のアップグレード／ダウングレード、ノードの照会、スケール、サイズ変更、クラスターのステータス照会、パスワード変更、パスワードのリセット、インスタンス名の変更、説明の更新、課金タイプの変換、従量課金からサブスクリプションへの変更、後払いから前払いへの変更、バージョンのアップグレード、エンジンのアップグレード、カーネルパッチ、aliVersion、利用可能なバージョンの確認、アップグレード情報、変更記録、アクション記録、アップグレードの進捗、変更履歴、アップグレードの続行、アップグレードの再開、段階的アップグレード、段階的アップグレードの続行、段階的アップグレードの完了	インスタンスのライフサイクル	references/instance-manage.md	createInstance, DescribeInstance, ListInstance, RestartInstance, UpdateInstance, ListAllNode, UpdateAdminPassword, UpdateDescription, UpdateInstanceChargeType, UpgradeInfo, UpgradeEngineVersion, ListActionRecords, ContinueEsVersionUpgrade
スナップショット、自動バックアップ、手動バックアップ、スナップショットの cron の設定／表示／実行	設定 — スナップショット	references/config-manage.md#snapshot-management	UpdateSnapshotSetting, DescribeSnapshotSetting, CreateSnapshot
アナライザー辞書の管理：IK のメイン辞書／ストップワード辞書（コールドまたはホット更新）、同義語、AliWS／AliNLP	設定 — 辞書	references/config-manage.md#dict-management	ListDicts, UpdateDict, UpdateHotIkDicts, UpdateSynonymsDicts, UpdateAliwsDict
Kibana の設定、構成、言語の照会／表示／更新	設定 — Kibana	references/config-manage.md#kibana-settings	DescribeKibanaSettings, UpdateKibanaSettings
ES の YML 設定、elasticsearch.yml、CORS、reindex のホワイトリスト、スレッドプールのキューサイズ、監査ログ、watcher、自動インデックス作成、更新戦略の更新	設定 — ES クラスター YML	references/config-manage.md#es-cluster-yml-configuration	UpdateInstanceSettings
プラグイン、システムプラグイン、ユーザープラグイン、カスタムプラグイン、プラグインのステータスの一覧表示／照会、プラグインのインストール／アンインストール／削除／アップロード、プラグイン分析	プラグイン管理	references/plugin-manage.md	ListPlugins, ListUserPlugin, InstallSystemPlugin, UninstallPlugin, PluginAnalysis, InstallUserPlugins

複数のインテントがある場合は、順番に処理してください：ルーティング → 実行 → 検証 → 次のルーティング。 インテントがどの行にも一致しない場合は、推測して API を選ばず、ユーザーに詳細を確認してください。

---

前提条件

事前確認：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 を実行してください。

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

---

可観測性

[MUST] ビジネス用の aliyun CLI コマンドを実行する際は、必ずコマンドごとに次のフラグを指定してください。

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/{session-id}

ここでの {session-id} は、以下で定義するスキルセッションごとの識別子です。このスキルの識別には、ビジネス用 CLI コマンドごとの --user-agent フラグのみを使用します。CLI レベルまたはセッションレベルで user-agent を注入する仕組みは使用しません。

session-id の生成ルール

スキルセッションの開始時に {session-id} を一度だけ生成し、そのセッション内のすべてのビジネス用 CLI コマンドで再利用してください。

形式の要件：小文字の 16 進数 32 文字（ハイフンなし） — 例：0123456789abcdef0123456789abcdef。

# Preferred (macOS / Linux, openssl is universally available):
SESSION_ID=$(openssl rand -hex 16)

# Fallback 1 — Python:
SESSION_ID=$(python3 -c 'import uuid; print(uuid.uuid4().hex)')

# Fallback 2 — pure shell (no external tool):
SESSION_ID=$(head -c 16 /dev/urandom | od -An -tx1 | tr -d ' \n')

• 形式：小文字の 16 進数 32 文字、ハイフンなし、接頭辞なし。uuidgen の出力（ハイフンあり）は使用できません。代わりに使用する場合は、tr -d '-' | tr 'A-Z' 'a-z' でハイフンを削除してください。
• このセッションで実行するすべてのビジネス用 CLI コマンドの --user-agent に、同じ SESSION_ID を含める必要があります。
• 再試行時に SESSION_ID を再生成しないでください。再生成はセッションの境界（新しいスキルの呼び出しが新しいセッションを開始するとき）でのみ行います。

コマンドごとの --user-agent の形式

コマンドの種類	--user-agent?	値
ビジネス API CLI（例：aliyun elasticsearch create-instance、aliyun elasticsearch list-dicts、…）	必須	AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}
システム／ツール CLI（例：aliyun configure、aliyun configure list、aliyun version、aliyun plugin update、aliyun help）	禁止	これらのコマンドは --user-agent に対応していません。フラグを付けないでください。

---

認証

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

セキュリティルール（必ず遵守）：

• 絶対に AK／SK の値を読み取ったり、エコーしたり、出力したりしないでください
• 絶対に 会話内で AK／SK を直接入力するようユーザーに求めないでください
• 絶対に aliyun configure set に認証情報の値を直接指定しないでください
• 絶対に 会話内でユーザーから直接提供された AK／SK を受け取らないでください
• 認証情報の読み取りには、環境変数または設定済みの CLI プロファイルのみを使用してください

重要：ユーザーから提供された認証情報の取り扱い

ユーザーが AK／SK を直接提供しようとした場合（例：「私の AK は xxx、SK は yyy です」）：

1. ただちに停止してください。コマンドを実行してはいけません。
2. 次のメッセージを使用して、丁寧に依頼をお断りしてください。

   アカウントのセキュリティを守るため、Alibaba Cloud の AccessKey ID と AccessKey Secret を会話内で直接提供しないでください。
   
   認証情報の設定には、次の安全な方法のいずれかを使用してください。
   
   方法 1：aliyun configure による対話形式での設定（推奨）
       aliyun configure
       # プロンプトに従って AK／SK を入力してください。認証情報はローカルの設定ファイルに安全に保存されます。
   
   方法 2：環境変数による設定
       export ALIBABA_CLOUD_ACCESS_KEY_ID=<your-access-key-id>
       export ALIBABA_CLOUD_ACCESS_KEY_SECRET=<your-access-key-secret>
   
   設定後、リクエストを再試行してください。
   

3. 認証情報が正しく設定されるまで、Alibaba Cloud の操作を実行しないでください。

CLI の設定を確認する：

aliyun configure list

有効なプロファイル（AK、STS、または OAuth ID）があるか確認してください。見つからない場合は、ここで停止してください。

---

全般的な規約

これらの規約は、どのモジュールに振り分けられるかにかかわらず、このスキルが生成するすべての CLI コマンドに適用されます。

CLI の共通引数

項目	規約
タイムアウト	すべてのコマンドに --connect-timeout 3 --read-timeout 10 を追加します。書き込み操作（作成／更新／再起動／スナップショット／辞書の更新）では --read-timeout 30 を使用します。
--region	必須です。ユーザーが明示的に指定する必要があります。推測してはいけません。デフォルトのリージョンは使用しないでください。
--instance-id	インスタンス単位の操作には必須です。ユーザーが明示的に指定する必要があります。
--user-agent	対象：ビジネス API コマンドのみ（例：aliyun elasticsearch ...）。これらのコマンドでは、--user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID} を明示的に指定する必要があります（Observability を参照）。システム／ツールコマンド（aliyun configure、aliyun version、aliyun plugin update、aliyun help など）には、--user-agent を指定してはいけません。これらのコマンドはこのフラグをサポートしていません。
--body	すべての ROA API は、複雑なリクエスト本文に --body '<JSON>' を受け付けます。ファイルから読み込むには --body $(cat payload.json) を使用します。
--cli-query	リスト形式の API で出力を読みやすくするには、JMESPath の射影（--cli-query "Result[].{...}"）を優先してください。

書き込み操作の冪等性

書き込み API（createInstance、RestartInstance、UpdateInstance、CreateSnapshot、UpdateSnapshotSetting、UpdateDict、UpdateHotIkDicts、UpdateSynonymsDicts、UpdateAliwsDict、UpdateKibanaSettings、UpdateInstanceSettings、InstallSystemPlugin、UninstallPlugin、UpdateInstanceChargeType、UpgradeEngineVersion）では、--client-token を必ず使用してください。

• 形式：UUID。uuidgen（または PowerShell の [guid]::NewGuid()）で生成します。uuidgen が使用できない場合は、idem-<timestamp>-<semantic> を代わりに使用します。コマンドが使用できないことを理由にワークフローを中止しないでください。
• タイムアウトまたは失敗時は、同じ clientToken を使って再試行します。再試行の前に約 10 秒待ちます。
• 同じ clientToken を使った重複呼び出しでは、操作は再実行されません。

CLIENT_TOKEN=$(uuidgen)   # reuse on retry

---

RAM ポリシー

RAM プリンシパルには、使用するモジュールの権限をすべてまとめて付与する必要があります。完全なポリシー JSON については、references/ram-policies.md を参照してください。

最小限必要なアクション：

モジュール	アクション
インスタンスのライフサイクル	elasticsearch:CreateInstance、elasticsearch:DescribeInstance、elasticsearch:ListInstance、elasticsearch:RestartInstance、elasticsearch:UpdateInstance、elasticsearch:ListAllNode
スナップショット管理	elasticsearch:UpdateSnapshotSetting、elasticsearch:DescribeSnapshotSetting、elasticsearch:CreateSnapshot
辞書管理	elasticsearch:ListDicts、elasticsearch:UpdateDict、elasticsearch:UpdateHotIkDicts、elasticsearch:UpdateSynonymsDicts、elasticsearch:UpdateAliwsDict

スナップショット／辞書モジュールには、辞書ファイルを格納しているバケットへの OSS 読み取りアクセスも必要です。

---

成功の確認

モジュールごとの確認手順については、references/verification-method.md を参照してください。

インスタンスのライフサイクル変更後の簡易チェック：

aliyun elasticsearch describe-instance \
  --region <RegionId> \
  --instance-id <InstanceId> \
  --cli-query "Result.status" \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

想定されるステータス：active。

スナップショット／辞書の変更後の簡易チェック：

# Snapshot setting changed
aliyun elasticsearch describe-snapshot-setting \
  --region <RegionId> --instance-id <InstanceId> \
  --connect-timeout 3 --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

# Dict list refreshed (analyzerType: IK | IK_HOT | SYNONYMS | ALIWS)
aliyun elasticsearch list-dicts \
  --region <RegionId> --instance-id <InstanceId> \
  --analyzer-type <TYPE> \
  --connect-timeout 3 --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

---

参考リンク

参考資料	説明
references/instance-manage.md	インスタンスのライフサイクル API（作成／詳細表示／一覧表示／再起動／更新／ノード）
references/config-manage.md	インスタンス設定 API（スナップショット＋アナライザー辞書）
references/ram-policies.md	RAM 権限ポリシー
references/verification-method.md	検証手順
references/acceptance-criteria.md	正しいパターン／誤ったパターン
references/cli-installation-guide.md	CLI インストールガイド
references/node-specifications-by-region.md	リージョン別およびロール別のノード仕様
Elasticsearch Product Page	公式製品ページ
Elasticsearch API Reference	公式 API リファレンス