alibabacloud-elasticsearch-instance-manage

Elasticsearch 实例与配置管理

通过 Aliyun CLI 管理阿里云 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 配置、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 命令中重复使用。

格式要求：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')

• 格式：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 身份）。如果不存在，请立即停止。

---

全局约定

无论路由到哪个模块，这些约定都适用于此技能生成的每条 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}（参见可观测性）。系统 / 工具命令（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 产品页面	官方产品页面
Elasticsearch API 参考	官方 API 参考