alibabacloud-elasticsearch-network-manage：管理阿里云 Elasticsearch 的网络配置，包括：开启/关闭实例与 Kibana 的公网或私网访问、设置网络白名单，以及启用HTTPS 安全访问。

Elasticsearch 实例网络管理

用于管理阿里云 Elasticsearch 实例网络配置的 Skill，包括网络触发、Kibana PVL 网络、白 IP 列表、HTTPS 设置和 Kibana SSO 认证。

架构

阿里云账号 → Elasticsearch 服务 → ES 实例 → 网络配置
                                                        ├── 公网访问
                                                        ├── Kibana PVL 网络
                                                        ├── 白 IP 列表
                                                        ├── HTTPS 设置
                                                        └── Kibana SSO 认证

安装

预检查：需要 Aliyun CLI >= 3.3.3
运行 aliyun version 验证 >= 3.3.3。如果未安装或版本过低，
运行 curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash 更新，
或参阅 references/cli-installation-guide.md 获取安装说明。

[必须] AI-Mode 配置

在执行任何 CLI 命令之前，启用 AI-Mode 并设置 User-Agent。工作流完成后，禁用 AI-Mode。

步骤 1：启用 AI-Mode（CLI 操作之前）

aliyun configure ai-mode enable

步骤 2：设置 User-Agent 以便追踪

aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage"

所有 CLI 操作完成后：

步骤 3：禁用 AI-Mode（工作流结束后）

aliyun configure ai-mode disable

**[必须] 插件更新**

aliyun configure set --auto-plugin-install true

aliyun plugin update

**[必须] CLI 安装**（如果尚未安装或版本 < 3.3.3）：

curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash

aliyun version

---

环境变量

CLI User-Agent 要求

[必须] CLI User-Agent —— user-agent 在安装期间通过 aliyun configure ai-mode set-user-agent 全局设置。

作为兜底，每次 aliyun CLI 命令调用也必须包含：

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage

参数确认

重要：参数确认 —— 在执行任何命令或 API 调用之前，
所有用户可自定义参数（例如 RegionId、实例名、白 IP、
VPC ID、安全组等）都必须与用户确认。
未经用户明确批准，不要假设或使用默认值。

认证

预检查：需要阿里云凭证
安全规则：
- 绝不读取、回显或打印 AK/SK 值
- 绝不要求用户在对话或命令行中输入 AK/SK
- 只能使用 aliyun configure list 检查凭证状态
```bash
aliyun configure list
```
如果无有效凭证，引导用户在终端中运行 aliyun configure（绝不接受聊天中的明文 AK/SK）。
凭证门户：阿里云 RAM 控制台

RAM 策略

Elasticsearch 实例网络配置操作所需的 RAM 权限。详情见 references/ram-policies.md。

核心工作流

前置条件：实例状态检查
在执行任何网络配置操作之前，验证实例状态为 active。
当实例状态为 activating、invalid 或 inactive 时，不能执行网络配置更改。
```bash
# 带重试逻辑检查实例状态
max_retries=10
retry_count=0
while [ $retry_count -lt $max_retries ]; do
status=$(aliyun elasticsearch describe-instance \
--instance-id <InstanceId> \
--read-timeout 30 \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage | jq -r '.Result.status')
if [ "$status" == "active" ]; then
echo "✅ 实例状态为 active，继续..."
break
else
echo "⚠️ 实例状态为 $status，等待 30 秒后重试..."
sleep 30
retry_count=$((retry_count + 1))
fi
done
if [ $retry_count -eq $max_retries ]; then
echo "❌ 实例在 $max_retries 次重试后仍未变为 active，中止"
exit 1
fi
```

任务 1：触发网络（启用/禁用公网/私网访问）

为 Elasticsearch 或 Kibana 集群启用或禁用公网或私网访问。

范围：支持基础管理实例上的所有网络类型。在云原生实例上，支持集群公网/私网和 Kibana 公网。对于云原生实例的 Kibana 私网，改用 EnableKibanaPvlNetwork / DisableKibanaPvlNetwork。

参数：

示例：启用 Kibana 公网访问

aliyun elasticsearch trigger-network \

--instance-id <InstanceId> --read-timeout 30 \

--body '{"nodeType":"KIBANA","networkType":"PUBLIC","actionType":"OPEN"}' \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage

示例：禁用 Elasticsearch 公网访问

aliyun elasticsearch trigger-network \

--instance-id <InstanceId> --read-timeout 30 \

--body '{"nodeType":"WORKER","networkType":"PUBLIC","actionType":"CLOSE"}' \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage

**预检查（必需）：**

> **网络状态字段**（通过 DescribeInstance）：
> - `Result.enablePublic`：ES 公网（私网始终开启，不能禁用）
> - `Result.enableKibanaPublicNetwork`：Kibana 公网
> - `Result.enableKibanaPrivateNetwork`：Kibana 私网
>
> 如果目标网络已处于期望状态，**跳过 TriggerNetwork 调用**并告知用户。

预检查：架构 + 当前网络状态

instance_info=$(aliyun elasticsearch describe-instance \

--instance-id <InstanceId> --read-timeout 30 \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage)

arch_type=$(echo "$instance_info" | jq -r '.Result.archType')

云原生 Kibana 私网：改用 EnableKibanaPvlNetwork/DisableKibanaPvlNetwork

if [ "$arch_type" == "public" ] && [ "$node_type" == "KIBANA" ] && [ "$network_type" == "PRIVATE" ]; then

echo "❌ 云原生 Kibana 私网请使用 EnableKibanaPvlNetwork/DisableKibanaPvlNetwork"

exit 1

fi

检查目标网络是否已处于期望状态

enable_public=$(echo "$instance_info" | jq -r '.Result.enablePublic')

enable_kibana_public=$(echo "$instance_info" | jq -r '.Result.enableKibanaPublicNetwork')

enable_kibana_private=$(echo "$instance_info" | jq -r '.Result.enableKibanaPrivateNetwork')

映射 nodeType+networkType 到状态字段（ES 私网始终开启）

WORKER+PUBLIC -> enablePublic | KIBANA+PUBLIC -> enableKibanaPublicNetwork | KIBANA+PRIVATE -> enableKibanaPrivateNetwork

如果 actionType=OPEN 且已为 true，或 actionType=CLOSE 且已为 false，跳过

---

### 任务 2：启用 Kibana PVL 网络（启用 Kibana 私网访问）

为 Elasticsearch 实例启用 Kibana 私网访问（PrivateLink）。

> **前置条件**：仅支持云原生实例（archType=public），Kibana 规格必须 > 1 核 2GB。对于基础管理实例，使用 TriggerNetwork。

**请求参数（Body）：**

| 参数 | 类型 | 必填 | 说明 |
|-----------|------|----------|-------------|
| `endpointName` | String | 是 | Endpoint 名称，推荐格式：`{InstanceId}-kibana-endpoint` |
| `securityGroups` | Array | 是 | 安全组 ID 数组 |
| `vSwitchIdsZone` | Array | 是 | VSwitch 和可用区信息 |
| `vSwitchIdsZone[].vswitchId` | String | 是 | 虚拟交换机 ID |
| `vSwitchIdsZone[].zoneId` | String | 是 | 可用区 ID |
| `vpcId` | String | 是 | VPC 实例 ID |

> **预检查**：先调用 DescribeInstance 检查 `Result.enableKibanaPrivateNetwork`。如果已启用，比较当前配置（vpcId、vswitchId、securityGroups）与用户要求。如果匹配，跳过并告知用户配置已正确。

检查当前 Kibana PVL 状态和配置

instance_info=$(aliyun elasticsearch describe-instance \

--instance-id <InstanceId> \

--read-timeout 30 \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage)

pvl_enabled=$(echo "$instance_info" | jq -r '.Result.enableKibanaPrivateNetwork')

current_vpc=$(echo "$instance_info" | jq -r '.Result.networkConfig.vpcId')

current_vswitch=$(echo "$instance_info" | jq -r '.Result.networkConfig.vswitchId')

if [ "$pvl_enabled" == "true" ]; then

# 检查当前配置是否匹配用户要求

if [ "$current_vpc" == "<VpcId>" ] && [ "$current_vswitch" == "<VswitchId>" ]; then

echo "✅ Kibana 私网已启用且配置匹配，无需操作"

exit 0

fi

fi

启用 Kibana 私网访问

aliyun elasticsearch enable-kibana-pvl-network \

--instance-id <InstanceId> \

--body '{

"endpointName": "<InstanceId>-kibana-endpoint",

"securityGroups": ["<SecurityGroupId>"],

"vSwitchIdsZone": [{"vswitchId": "<VswitchId>", "zoneId": "<ZoneId>"}],

"vpcId": "<VpcId>"

}' \

--read-timeout 30 \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage

---

### 任务 3：禁用 Kibana PVL 网络（禁用 Kibana 私网访问）

禁用 Elasticsearch 实例的 Kibana 私网访问。

> **前置条件**：此 API **仅支持云原生实例**（archType=public）。对于基础管理实例，使用 TriggerNetwork。

aliyun elasticsearch disable-kibana-pvl-network \

--instance-id <InstanceId> \

--read-timeout 30 \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage

---

### 任务 4：修改白 IP（修改白 IP 列表）

更新指定实例的访问白 IP 列表。支持两种更新方式（不能同时使用）：

1. **IP 白名单方式**：使用 `whiteIpList` + `nodeType` + `networkType`
2. **IP 白分组方式**：使用 `modifyMode` + `whiteIpGroup`

> **注意**： 
> - 实例状态为 activating、invalid 或 inactive 时不能更新
> - 公网白名单不支持私网 IP；私网白名单不支持公网 IP
> - **云原生实例（archType=public）的 Kibana 私网白名单不能通过此 API 修改**。改用 UpdateKibanaPvlNetwork API 修改安全组（见任务 7）

**方式 1：IP 白名单（更新默认分组）**

| 参数 | 类型 | 必填 | 说明 |
|-----------|------|----------|-------------|
| `whiteIpList` | Array | 是 | IP 白名单，将覆盖 Default 分组 |
| `nodeType` | String | 是 | 节点类型：WORKER（ES 集群）/ KIBANA |
| `networkType` | String | 是 | 网络类型：PUBLIC / PRIVATE |

修改 ES 公网白名单（覆盖 Default 分组）

aliyun elasticsearch modify-white-ips \

--instance-id <InstanceId> --read-timeout 30 \

--body '{"nodeType":"WORKER","networkType":"PUBLIC","whiteIpList":["59.0.0.0/8","120.0.0.0/8"]}' \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage

**方式 2：IP 白分组（支持增量/覆盖/删除）**

| 参数 | 类型 | 必填 | 说明 |
|-----------|------|----------|-------------|
| `modifyMode` | String | 否 | 修改模式：Cover（覆盖，默认）/ Append / Delete |
| `whiteIpGroup.groupName` | String | 是 | 白 IP 分组名称 |
| `whiteIpGroup.ips` | Array | 是 | IP 地址列表 |
| `whiteIpGroup.whiteIpType` | String | 否 | 白 IP 类型（见下表） |

**whiteIpType 取值：**

| 值 | 说明 |
|-------|-------------|
| `PRIVATE_ES` | Elasticsearch 私网白名单 |
| `PUBLIC_ES` | Elasticsearch 公网白名单 |
| `PRIVATE_KIBANA` | Kibana 私网白名单 |
| `PUBLIC_KIBANA` | Kibana 公网白名单 |

覆盖指定白分组（Cover 模式）

aliyun elasticsearch modify-white-ips \

--instance-id <InstanceId> --read-timeout 30 \

--body '{"modifyMode":"Cover","whiteIpGroup":{"groupName":"default","ips":["59.0.0.0/8","120.0.0.0/8"],"whiteIpType":"PUBLIC_ES"}}' \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage

向白分组追加 IP（Append 模式，分组必须存在）

aliyun elasticsearch modify-white-ips \

--instance-id <InstanceId> --read-timeout 30 \

--body '{"modifyMode":"Append","whiteIpGroup":{"groupName":"default","ips":["172.16.0.0/12"],"whiteIpType":"PRIVATE_ES"}}' \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage

**modifyMode 说明：**

| 模式 | 说明 |
|------|-------------|
| `Cover` | 覆盖模式（默认）。空 ips 删除分组；不存在的 groupName 创建新分组 |
| `Append` | 追加模式。分组必须存在，否则报 NotFound 错误 |
| `Delete` | 删除模式。移除指定 IP，至少必须保留一个 IP |

> **重要：modifyMode 选择指南**
> - 增量添加用 `Append`，全量替换用 `Cover`，移除用 `Delete`
> - **如果用户意图不明确，执行前必须询问用户**使用哪种模式
> - 如果 Append 失败报 NotFound：告知用户，建议用 Cover 模式创建分组。不要静默切换模式。

---

### 任务 5：开启 HTTPS（启用 HTTPS）

为 Elasticsearch 实例启用 HTTPS 访问。

> **预检查**：先调用 DescribeInstance 检查 `Result.protocol`。如果已是 `HTTPS`，跳过 OpenHttps 并告知用户 HTTPS 已启用。

检查当前 HTTPS 状态

protocol=$(aliyun elasticsearch describe-instance \

--instance-id <InstanceId> \

--read-timeout 30 \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage | jq -r '.Result.protocol')

if [ "$protocol" == "HTTPS" ]; then

echo "✅ HTTPS 已启用，无需操作"

else

# 启用 HTTPS

aliyun elasticsearch open-https \

--instance-id <InstanceId> \

--read-timeout 30 \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage

fi

---

### 任务 6：关闭 HTTPS（禁用 HTTPS）

禁用 Elasticsearch 实例的 HTTPS 访问。

> **预检查**：先调用 DescribeInstance 检查 `Result.protocol`。如果已是 `HTTP`，跳过 CloseHttps 并告知用户 HTTPS 已禁用。

检查当前 HTTPS 状态

protocol=$(aliyun elasticsearch describe-instance \

--instance-id <InstanceId> \

--read-timeout 30 \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage | jq -r '.Result.protocol')

if [ "$protocol" == "HTTP" ]; then

echo "✅ HTTPS 已禁用，无需操作"

else

# 禁用 HTTPS

aliyun elasticsearch close-https \

--instance-id <InstanceId> \

--read-timeout 30 \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage

fi

---

### 任务 7：更新 Kibana PVL 网络（更新 Kibana 私网配置）

更新 Kibana 私网访问配置，主要用于修改安全组。

> **前置条件**：
> 1. 此 API **仅支持云原生实例**（archType=public）。对于基础管理实例，使用 TriggerNetwork。
> 2. Kibana 规格必须**大于 1 核 2GB**。
> 3. 实例必须已启用 Kibana 私网访问。

**使用场景**：当云原生实例需要修改 Kibana 私网访问安全组（白名单控制）时使用此 API。

**请求参数：**

| 参数 | 类型 | 位置 | 必填 | 说明 |
|-----------|------|----------|----------|-------------|
| `InstanceId` | String | Path | 是 | 实例 ID |
| `pvlId` | String | Query | 是 | Kibana 私有链接 ID，格式：`{InstanceId}-kibana-internal-internal` |
| `endpointName` | String | Body | 否 | Endpoint 名称 |
| `securityGroups` | Array | Body | 否 | 安全组 ID 数组 |

更新 Kibana 私网安全组

aliyun elasticsearch update-kibana-pvl-network \

--instance-id <InstanceId> \

--pvl-id <InstanceId>-kibana-internal-internal \

--body '{"securityGroups": ["<NewSecurityGroupId>"]}' \

--read-timeout 30 \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage

---

### 任务 8：更新 Kibana SSO（启用/禁用 Kibana 阿里云账号认证）

启用或禁用 Kibana 阿里云账号 SSO 认证。启用后，用户必须使用阿里云账号登录才能使用 Kibana。

> **前置条件**：此 API **仅支持云原生实例**（archType=public）。

> **预检查**：调用 DescribeInstance 检查 `Result.enableKibanaPublicSSO` / `Result.enableKibanaPrivateSSO`。如果已达到期望状态，跳过调用。

**参数：** 完整详情见 [references/related-apis.md](references/related-apis.md)。

为公网启用 Kibana SSO

aliyun elasticsearch update-kibana-sso \

--instance-id <InstanceId> \

--body '{"enable":true,"networkType":"PUBLIC"}' \

--read-timeout 30 \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage

为私网禁用 Kibana SSO

aliyun elasticsearch update-kibana-sso \

--instance-id <InstanceId> \

--body '{"enable":false,"networkType":"PRIVATE"}' \

--read-timeout 30 \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage

---

成功验证方法

详细验证步骤见 references/verification-method.md。每次操作后，检查响应中的 RequestId 并调用 DescribeInstance 确认更改。

最佳实践

1. 云原生 Kibana：私网使用 EnableKibanaPvlNetwork/DisableKibanaPvlNetwork。白名单通过 UpdateKibanaPvlNetwork。SSO 通过 UpdateKibanaSso（仅 archType=public）。
2. 安全：谨慎使用 0.0.0.0/0。生产环境启用 HTTPS。
3. 可靠性：使用 clientToken 保证幂等性。对 InstanceStatusNotSupportCurrentAction/ConcurrencyUpdateInstanceConflict 重试（等待 30-60 秒）。更改前检查当前状态，已达到期望状态则跳过。

参考链接

文档 5 / 5：alibabacloud-emr-spark-manage