back
loading skill details...
Alibaba Cloud Elasticsearch Instance Network Management Skill. Use for managing ES instance network configurations including triggering network, Kibana PVL n...
---
name: alibabacloud-elasticsearch-network-manage
description: |
Alibaba Cloud Elasticsearch Instance Network Management Skill. Use for managing ES instance network configurations including triggering network, Kibana PVL network, white IP list, HTTPS settings, and Kibana SSO authentication.
Triggers: "elasticsearch network", "ES network", "kibana pvl", "white ip", "https", "trigger network", "modify white ips", "kibana sso", "kibana authentication".
---
# Elasticsearch Instance Network Management
A skill for managing Alibaba Cloud Elasticsearch instance network configurations, including network triggering, Kibana PVL network, white IP list, HTTPS settings, and Kibana SSO authentication.
## Architecture
```
Alibaba Cloud Account → Elasticsearch Service → ES Instance(s) → Network Configuration
├── Public Network Access
├── Kibana PVL Network
├── White IP List
├── HTTPS Settings
└── Kibana SSO Authentication
```
---
## Installation
> **Pre-check: Aliyun CLI >= 3.3.3 required**
> Run `aliyun version` to verify >= 3.3.3. If not installed or version too low,
> run `curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash` to update,
> or see `references/cli-installation-guide.md` for installation instructions.
**[MUST] AI-Mode Configuration**
Before executing any CLI commands, enable AI-Mode and set User-Agent. After the workflow completes, disable AI-Mode.
```bash
# 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"
```
After all CLI operations are complete:
```bash
# Step 3: Disable AI-Mode (after workflow ends)
aliyun configure ai-mode disable
```
**[MUST] Plugin Update**
```bash
aliyun configure set --auto-plugin-install true
aliyun plugin update
```
**[MUST] CLI Installation** (if not already installed or version < 3.3.3):
```bash
curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash
aliyun version
```
---
## Environment Variables
| Variable | Required | Description |
|----------|----------|-------------|
| `ALIBABA_CLOUD_ACCESS_KEY_ID` | Yes | Alibaba Cloud AccessKey ID |
| `ALIBABA_CLOUD_ACCESS_KEY_SECRET` | Yes | Alibaba Cloud AccessKey Secret |
| `ALIBABA_CLOUD_REGION_ID` | No | Default Region ID (e.g., cn-hangzhou) |
---
## CLI User-Agent Requirement
**[MUST] CLI User-Agent** — The user-agent is set globally via `aliyun configure ai-mode set-user-agent` during installation.
As a fallback, every `aliyun` CLI command invocation must also include:
`--user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage`
---
## Parameter Confirmation
> **IMPORTANT: Parameter Confirmation** — Before executing any command or API call,
> ALL user-customizable parameters (e.g., RegionId, instance names, white IPs,
> VPC IDs, security groups, etc.) MUST be confirmed with the user.
> Do NOT assume or use default values without explicit user approval.
| Parameter Name | Required/Optional | Description | Default Value |
|---------------|-------------------|-------------|---------------|
| `InstanceId` | Required (for all operations) | Elasticsearch Instance ID | - |
| `RegionId` | Optional | Region ID | cn-hangzhou |
| `nodeType` | Required (TriggerNetwork) | Instance Type: KIBANA/WORKER | - |
| `networkType` | Required (TriggerNetwork) | Network Type: PUBLIC/PRIVATE | - |
| `actionType` | Required (TriggerNetwork) | Action Type: OPEN/CLOSE | - |
| `resourceGroupId` | Optional | Resource Group ID | - |
| `whiteIpGroup` | Required (ModifyWhiteIps) | White IP Group Configuration | - |
| `whiteIpType` | Optional (ModifyWhiteIps) | White IP Type: PRIVATE_ES/PUBLIC_KIBANA | PRIVATE_ES |
---
## Authentication
> **Pre-check: Alibaba Cloud Credentials Required**
>
> **Security Rules:**
> - **NEVER** read, echo, or print AK/SK values
> - **NEVER** ask user to input AK/SK in conversation or command line
> - **ONLY** use `aliyun configure list` to check credential status
>
> ```bash
> aliyun configure list
> ```
>
> If no valid credentials, guide user to run `aliyun configure` in terminal (never accept plaintext AK/SK in chat).
> Credential portal: [Alibaba Cloud RAM Console](https://ram.console.aliyun.com/manage/ak)
---
## RAM Policy
RAM permissions required for Elasticsearch instance network configuration operations. See [references/ram-policies.md](references/ram-policies.md) for details.
---
## Core Workflow
> **Prerequisite: Instance Status Check**
>
> Before executing any network configuration operation, verify that the instance status is `active`.
> Network configuration changes **cannot be executed** when instance status is `activating`, `invalid`, or `inactive`.
>
> ```bash
> # Check instance status with retry logic
> 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 "✅ Instance status is active, proceeding..."
> break
> else
> echo "⚠️ Instance status is $status, waiting 30s before retry..."
> sleep 30
> retry_count=$((retry_count + 1))
> fi
> done
>
> if [ $retry_count -eq $max_retries ]; then
> echo "❌ Instance did not become active after $max_retries retries, aborting"
> exit 1
> fi
> ```
### Task 1: Trigger Network (Enable/Disable Public/Private Network Access)
Enable or disable public or private network access for Elasticsearch or Kibana clusters.
> **Scope**: Supports all network types on basic management instances. On cloud-native instances, supports cluster public/private network and Kibana public network. For **Kibana private network on cloud-native instances**, use EnableKibanaPvlNetwork / DisableKibanaPvlNetwork instead.
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `nodeType` | String | Yes | Instance Type: KIBANA (Kibana cluster) / WORKER (Elasticsearch cluster) |
| `networkType` | String | Yes | Network Type: PUBLIC / PRIVATE |
| `actionType` | String | Yes | Action Type: OPEN (enable) / CLOSE (disable) |
```bash
# 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
```
**Pre-check (Required):**
> **Network Status Fields** (via DescribeInstance):
> - `Result.enablePublic`: ES public network (private network is always on, cannot be disabled)
> - `Result.enableKibanaPublicNetwork`: Kibana public network
> - `Result.enableKibanaPrivateNetwork`: Kibana private network
>
> If the target network is already in the desired state, **skip the TriggerNetwork call** and inform the user.
```bash
# 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
```
---
### Task 2: Enable Kibana PVL Network (Enable Kibana Private Network Access)
Enable Kibana private network access (PrivateLink) for an Elasticsearch instance.
> **Prerequisites**: Only supports cloud-native instances (archType=public), Kibana spec must be > 1 core 2GB. For basic management instances, use TriggerNetwork.
**Request Parameters (Body):**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `endpointName` | String | Yes | Endpoint name, recommended format: `{InstanceId}-kibana-endpoint` |
| `securityGroups` | Array | Yes | Security group ID array |
| `vSwitchIdsZone` | Array | Yes | VSwitch and availability zone information |
| `vSwitchIdsZone[].vswitchId` | String | Yes | Virtual switch ID |
| `vSwitchIdsZone[].zoneId` | String | Yes | Availability zone ID |
| `vpcId` | String | Yes | VPC instance ID |
> **Pre-check**: Call DescribeInstance first to check `Result.enableKibanaPrivateNetwork`. If already enabled, compare current config (vpcId, vswitchId, securityGroups) with user requirements. If they match, skip and inform user config is already correct.
```bash
# 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
```
---
### Task 3: Disable Kibana PVL Network (Disable Kibana Private Network Access)
Disable Kibana private network access for an Elasticsearch instance.
> **Prerequisites**: This API **only supports cloud-native instances** (archType=public). For basic management instances, use TriggerNetwork.
```bash
aliyun elasticsearch disable-kibana-pvl-network \
--instance-id <InstanceId> \
--read-timeout 30 \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage
```
---
### Task 4: Modify White IPs (Modify White IP List)
Update the access white IP list for the specified instance. Two update methods are supported (cannot be used simultaneously):
1. **IP White List Method**: Use `whiteIpList` + `nodeType` + `networkType`
2. **IP White Group Method**: Use `modifyMode` + `whiteIpGroup`
> **Notes**:
> - Cannot update when instance status is activating, invalid, or inactive
> - Public network white list does not support private IPs; private network white list does not support public IPs
> - **Kibana private network white list for cloud-native instances (archType=public) cannot be modified via this API**. Use UpdateKibanaPvlNetwork API to modify security groups instead (see Task 7)
**Method 1: IP White List (Update Default Group)**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `whiteIpList` | Array | Yes | IP white list, will overwrite Default group |
| `nodeType` | String | Yes | Node Type: WORKER (ES cluster) / KIBANA |
| `networkType` | String | Yes | Network Type: PUBLIC / PRIVATE |
```bash
# 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
```
**Method 2: IP White Group (Supports Incremental/Overwrite/Delete)**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `modifyMode` | String | No | Modify mode: Cover (overwrite, default) / Append / Delete |
| `whiteIpGroup.groupName` | String | Yes | White IP group name |
| `whiteIpGroup.ips` | Array | Yes | IP address list |
| `whiteIpGroup.whiteIpType` | String | No | White IP type (see table below) |
**whiteIpType Values:**
| Value | Description |
|-------|-------------|
| `PRIVATE_ES` | Elasticsearch private network white list |
| `PUBLIC_ES` | Elasticsearch public network white list |
| `PRIVATE_KIBANA` | Kibana private network white list |
| `PUBLIC_KIBANA` | Kibana public network white list |
```bash
# 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 Description:**
| Mode | Description |
|------|-------------|
| `Cover` | Overwrite mode (default). Empty ips deletes group; non-existent groupName creates new |
| `Append` | Append mode. Group must exist, otherwise NotFound error |
| `Delete` | Delete mode. Remove specified IPs, at least one IP must remain |
> **IMPORTANT: modifyMode Selection Guidelines**
> - Use `Append` for incremental addition, `Cover` for full replacement, `Delete` for removal
> - **If user intent is unclear, MUST ask user** which mode to use before executing
> - If Append fails with NotFound: inform user, suggest Cover mode to create group. Do NOT silently switch modes.
---
### Task 5: Open HTTPS (Enable HTTPS)
Enable HTTPS access for an Elasticsearch instance.
> **Pre-check**: Call DescribeInstance first to check `Result.protocol`. If already `HTTPS`, skip OpenHttps and inform user HTTPS is already enabled.
```bash
# 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
```
---
### Task 6: Close HTTPS (Disable HTTPS)
Disable HTTPS access for an Elasticsearch instance.
> **Pre-check**: Call DescribeInstance first to check `Result.protocol`. If already `HTTP`, skip CloseHttps and inform user HTTPS is already disabled.
```bash
# 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
```
---
### Task 7: Update Kibana PVL Network (Update Kibana Private Network Configuration)
Update Kibana private network access configuration, primarily used for modifying security groups.
> **Prerequisites**:
> 1. This API **only supports cloud-native instances** (archType=public). For basic management instances, use TriggerNetwork.
> 2. Kibana specification must be **greater than 1 core 2GB**.
> 3. Instance must have Kibana private network access enabled.
**Use Case**: Use this API when cloud-native instances need to modify Kibana private network access security groups (whitelist control).
**Request Parameters:**
| Parameter | Type | Location | Required | Description |
|-----------|------|----------|----------|-------------|
| `InstanceId` | String | Path | Yes | Instance ID |
| `pvlId` | String | Query | Yes | Kibana private link ID, format: `{InstanceId}-kibana-internal-internal` |
| `endpointName` | String | Body | No | Endpoint name |
| `securityGroups` | Array | Body | No | Security group ID array |
```bash
# 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
```
---
### Task 8: Update Kibana SSO (Enable/Disable Kibana Alibaba Cloud Account Authentication)
Enable or disable Kibana Alibaba Cloud account SSO authentication. When enabled, users must log in with their Alibaba Cloud account before using Kibana.
> **Prerequisites**: This API **only supports cloud-native instances** (archType=public).
> **Pre-check**: Call DescribeInstance to check `Result.enableKibanaPublicSSO` / `Result.enableKibanaPrivateSSO`. If desired state already achieved, skip the call.
**Parameters:** See [references/related-apis.md](references/related-apis.md) for full details.
```bash
# 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
```
---
## Success Verification Method
For detailed verification steps, see [references/verification-method.md](references/verification-method.md). After each operation, check `RequestId` in response and call DescribeInstance to confirm changes.
---
## Best Practices
1. **Cloud-native Kibana**: Private network uses EnableKibanaPvlNetwork/DisableKibanaPvlNetwork. Whitelist via UpdateKibanaPvlNetwork. SSO via UpdateKibanaSso (archType=public only).
2. **Security**: Use 0.0.0.0/0 with caution. Enable HTTPS in production.
3. **Reliability**: Use clientToken for idempotency. Retry on `InstanceStatusNotSupportCurrentAction`/`ConcurrencyUpdateInstanceConflict` (wait 30-60s). Check current state before changes, skip if desired state already achieved.
---
## Reference Links
| Reference | Description |
|-----------|-------------|
| [references/related-apis.md](references/related-apis.md) | API and CLI command reference table |
| [references/ram-policies.md](references/ram-policies.md) | RAM permission policies |
| [references/cli-installation-guide.md](references/cli-installation-guide.md) | CLI installation guide |
| [references/verification-method.md](references/verification-method.md) | Verification methods |
| [references/acceptance-criteria.md](references/acceptance-criteria.md) | Acceptance criteria |don't have the plugin yet? install it then click "run inline in claude" again.