alibabacloud-elasticsearch-network-manage

What this skill does

# 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 "$instanc