alibabacloud-elasticsearch-network-manage

Elasticsearch 实例网络管理

用于管理 Alibaba Cloud Elasticsearch 实例网络配置的技能，包括网络触发、Kibana PVL 网络、白名单 IP 列表、HTTPS 设置和 Kibana SSO 身份验证。

架构

Alibaba Cloud Account → Elasticsearch Service → ES Instance(s) → Network Configuration
                                                        ├── Public Network Access
                                                        ├── Kibana PVL Network
                                                        ├── White IP List
                                                        ├── HTTPS Settings
                                                        └── Kibana SSO Authentication

---

安装

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

[MUST] AI-Mode 配置

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

# Step 1: Enable AI-Mode (before CLI operations)
aliyun configure ai-mode enable

# Step 2: Set User-Agent for traceability
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage"

完成所有 CLI 操作后：

# Step 3: Disable AI-Mode (after workflow ends)
aliyun configure ai-mode disable

[MUST] 插件更新

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

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

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

---

环境变量

变量	必需	说明
ALIBABA_CLOUD_ACCESS_KEY_ID	是	Alibaba Cloud AccessKey ID
ALIBABA_CLOUD_ACCESS_KEY_SECRET	是	Alibaba Cloud AccessKey Secret
ALIBABA_CLOUD_REGION_ID	否	默认区域 ID（例如 cn-hangzhou）

---

CLI User-Agent 要求

[MUST] CLI User-Agent — 安装期间通过 aliyun configure ai-mode set-user-agent 全局设置 user-agent。 作为备用方案，每次调用 aliyun CLI 命令时也必须包含： --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage

---

参数确认

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

参数名称	必需/可选	说明	默认值
InstanceId	必需（所有操作均需）	Elasticsearch 实例 ID	-
RegionId	可选	区域 ID	cn-hangzhou
nodeType	必需（TriggerNetwork）	实例类型：KIBANA/WORKER	-
networkType	必需（TriggerNetwork）	网络类型：PUBLIC/PRIVATE	-
actionType	必需（TriggerNetwork）	操作类型：OPEN/CLOSE	-
resourceGroupId	可选	资源组 ID	-
whiteIpGroup	必需（ModifyWhiteIps）	白名单 IP 组配置	-
whiteIpType	可选（ModifyWhiteIps）	白名单 IP 类型：PRIVATE_ES/PUBLIC_KIBANA	PRIVATE_ES

---

身份验证

安装前检查：需要 Alibaba Cloud 凭据

安全规则：

• 绝不读取、回显或打印 AK/SK 值
• 绝不要求用户在对话或命令行中输入 AK/SK
• 仅使用 aliyun configure list 检查凭据状态

aliyun configure list

如果没有有效凭据，请引导用户在终端运行 aliyun configure（绝不接受在聊天中输入明文 AK/SK）。 凭据门户：Alibaba Cloud RAM 控制台

---

RAM 策略

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

---

核心工作流

前提条件：检查实例状态

执行任何网络配置操作之前，请确认实例状态为 active。 实例状态为 activating、invalid 或 inactive 时，无法执行网络配置更改。

# 使用重试逻辑检查实例状态
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，等待 30s 后重试..."
    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。

参数：

参数	类型	必填	说明
nodeType	String	是	实例类型：KIBANA（Kibana 集群）/ WORKER（Elasticsearch 集群）
networkType	String	是	网络类型：PUBLIC / PRIVATE
actionType	String	是	操作类型：OPEN（启用）/ CLOSE（禁用）

# Example: Enable Kibana public network access
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

# Example: Disable Elasticsearch public network access
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 调用并告知用户。

# Pre-check: architecture + current network status
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')

# Cloud-native Kibana private network: use EnableKibanaPvlNetwork/DisableKibanaPvlNetwork instead
if [ "$arch_type" == "public" ] && [ "$node_type" == "KIBANA" ] && [ "$network_type" == "PRIVATE" ]; then
  echo "❌ Use EnableKibanaPvlNetwork/DisableKibanaPvlNetwork for cloud-native Kibana private network"
  exit 1
fi

# Check if target network already in desired state
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')

# Map nodeType+networkType to status field (ES private is always on)
# WORKER+PUBLIC -> enablePublic | KIBANA+PUBLIC -> enableKibanaPublicNetwork | KIBANA+PRIVATE -> enableKibanaPrivateNetwork
# If actionType=OPEN and already true, or actionType=CLOSE and already false, skip

---

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

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

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

请求参数（Body）：

参数	类型	必填	说明
endpointName	String	是	端点名称，建议格式：{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）与用户要求进行比较。如果一致，则跳过并告知用户配置已正确。

# Check current Kibana PVL status and config
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
  # Check if current config matches user requirements
  if [ "$current_vpc" == "<VpcId>" ] && [ "$current_vswitch" == "<VswitchId>" ]; then
    echo "✅ Kibana private network already enabled with matching config, no action needed"
    exit 0
  fi
fi

# Enable Kibana private network access
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
• cloud-native 实例（archType=public）的 Kibana 私网白名单无法通过此 API 修改。请改用 UpdateKibanaPvlNetwork API 修改安全组（参见任务 7）

方式 1：IP 白名单列表（更新默认组）

参数	类型	必填	描述
whiteIpList	Array	是	IP 白名单列表，将覆盖 Default 组
nodeType	String	是	节点类型：WORKER（ES 集群）/ KIBANA
networkType	String	是	网络类型：PUBLIC / PRIVATE

# Modify ES public network white list (overwrite Default group)
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 公网白名单

# Overwrite specified white group (Cover mode)
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

# Append IPs to white group (Append mode, group must exist)
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 已启用。

# Check current HTTPS status
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 is already enabled, no action needed"
else
  # Enable 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 已禁用。

# Check current HTTPS status
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 is already disabled, no action needed"
else
  # Disable 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	否	端点名称
securityGroups	Array	Body	否	安全组 ID 数组

# Update Kibana private network security group
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。

# Enable Kibana SSO for public network
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

# Disable Kibana SSO for private network
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 配置白名单。使用 UpdateKibanaSso 配置 SSO（仅限 archType=public）。
2. 安全性：谨慎使用 0.0.0.0/0。在生产环境中启用 HTTPS。
3. 可靠性：使用 clientToken 实现幂等性。遇到 InstanceStatusNotSupportCurrentAction/ConcurrencyUpdateInstanceConflict 时重试（等待 30-60s）。更改前检查当前状态；如果已达到期望状态，则跳过。

---

参考链接

参考资料	描述
references/related-apis.md	API 和 CLI 命令参考表
references/ram-policies.md	RAM 权限策略
references/cli-installation-guide.md	CLI 安装指南
references/verification-method.md	验证方法
references/acceptance-criteria.md	验收标准