Alibabacloud Elasticsearch Network Manage

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.

# 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:

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

[MUST] Plugin Update

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

[MUST] CLI Installation (if not already installed or version < 3.3.3):

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 > >

> aliyun configure list
> 

RAM Policy

RAM permissions required for Elasticsearch instance network configuration operations. See 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. > >

> # 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  \
>     --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) |

# Example: Enable Kibana public network access
aliyun elasticsearch trigger-network \
  --instance-id  --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  --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.

# Pre-check: architecture + current network status
instance_info=$(aliyun elasticsearch describe-instance \
  --instance-id  --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.

# Check current Kibana PVL status and config
instance_info=$(aliyun elasticsearch describe-instance \
  --instance-id  \
  --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" == "" ] && [ "$current_vswitch" == "" ]; 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  \
  --body '{
    "endpointName": "-kibana-endpoint",
    "securityGroups": [""],
    "vSwitchIdsZone": [{"vswitchId": "", "zoneId": ""}],
    "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.

aliyun elasticsearch disable-kibana-pvl-network \
  --instance-id  \
  --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 |

# Modify ES public network white list (overwrite Default group)
aliyun elasticsearch modify-white-ips \
  --instance-id  --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 |

# Overwrite specified white group (Cover mode)
aliyun elasticsearch modify-white-ips \
  --instance-id  --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  --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.

# Check current HTTPS status
protocol=$(aliyun elasticsearch describe-instance \
  --instance-id  \
  --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  \
    --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.

# Check current HTTPS status
protocol=$(aliyun elasticsearch describe-instance \
  --instance-id  \
  --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  \
    --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 |

# Update Kibana private network security group
aliyun elasticsearch update-kibana-pvl-network \
  --instance-id  \
  --pvl-id -kibana-internal-internal \
  --body '{"securityGroups": [""]}' \
  --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 for full details.

# Enable Kibana SSO for public network
aliyun elasticsearch update-kibana-sso \
  --instance-id  \
  --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  \
  --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. 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 | API and CLI command reference table | | references/ram-policies.md | RAM permission policies | | references/cli-installation-guide.md | CLI installation guide | | references/verification-method.md | Verification methods | | references/acceptance-criteria.md | Acceptance criteria |

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.