alibabacloud-elasticsearch-network-manage

Name: alibabacloud-elasticsearch-network-manage
Author: aliyun

github.com/aliyunクラウド・DevOps281125 回インストール1 日前に更新

リポジトリ

alibabacloud-elasticsearch-network-manage について

Aliyun CLIでAlibaba Cloud Elasticsearchのネットワーク設定を管理する、クラウド運用者向けスキルです。ネットワークアクセス、Kibana PVL、IP許可リスト、HTTPS、SSOを扱います。

主な機能

01パブリック／プライベートアクセスの切り替え
02Kibana PVLネットワークの管理
03IP許可リストの更新
04HTTPSの設定
05Kibana SSO認証の管理

活用シーン

01Elasticsearchインスタンスのネットワークアクセスを調整
02クラウドネイティブ環境でKibanaプライベートアクセスを有効化
03インスタンスのIP許可リストを更新
04Kibanaのログイン認証を設定

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/aliyun/alibabacloud-aiops-skills --skill alibabacloud-elasticsearch-network-manage

インストール後、Claude Code で/alibabacloud-elasticsearch-network-manageを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/

acceptance-criteria.md

cli-installation-guide.md

ram-policies.md

related-apis.md

verification-method.md

詳細

Elasticsearch インスタンスのネットワーク管理

ネットワークの切り替え、Kibana PVL ネットワーク、ホワイト IP リスト、HTTPS 設定、Kibana SSO 認証など、Alibaba Cloud Elasticsearch インスタンスのネットワーク設定を管理するスキルです。

アーキテクチャ

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 を参照してください。

[必須] 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

[必須] プラグインの更新

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

環境変数

変数	必須	説明
`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 要件

[必須] CLI User-Agent — インストール時に aliyun configure ai-mode set-user-agent を使用して、User-Agent をグローバルに設定します。フォールバックとして、aliyun CLI コマンドを実行するたびに、次のオプションも指定する必要があります： --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage

パラメーターの確認

重要：パラメーターの確認 — コマンドまたは 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 "✅ 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

タスク 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 リストを更新します。次の 2 つの更新方法に対応しています（同時には使用できません）。

IP ホワイトリスト方式：whiteIpList + nodeType + networkType を使用します
IP ホワイトグループ方式：modifyMode + whiteIpGroup を使用します

注意事項：

インスタンスのステータスが activating、invalid、または inactive の場合は更新できません

パブリックネットワークのホワイトリストではプライベート IP を使用できません。プライベートネットワークのホワイトリストではパブリック IP を使用できません

クラウドネイティブインスタンス（archType=public）の Kibana プライベートネットワークホワイトリストは、この API では変更できません。代わりに UpdateKibanaPvlNetwork API を使用してセキュリティグループを変更してください（タスク 7 を参照）

方法 1：IP ホワイトリスト（デフォルトグループを更新）

パラメーター	型	必須	説明
`whiteIpList`	Array	はい	IP ホワイトリスト。デフォルトグループを上書きします
`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 を削除します。少なくとも 1 つの 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 のプライベートネットワークアクセス設定を更新します。主にセキュリティグループの変更に使用します。

前提条件：

この API はクラウドネイティブインスタンスのみをサポートします（archType=public）。基本管理インスタンスでは、TriggerNetwork を使用してください。

Kibana の仕様は1 コア 2 GB を超える必要があります。

インスタンスで Kibana のプライベートネットワークアクセスが有効になっている必要があります。

ユースケース：クラウドネイティブインスタンスで Kibana のプライベートネットワークアクセスに使用するセキュリティグループ（ホワイトリスト制御）を変更する場合に、この API を使用します。

リクエストパラメーター：

パラメーター	型	場所	必須	説明
`InstanceId`	String	Path	Yes	インスタンス ID
`pvlId`	String	Query	Yes	Kibana プライベートリンク ID。形式：`{InstanceId}-kibana-internal-internal`
`endpointName`	String	Body	No	エンドポイント名
`securityGroups`	Array	Body	No	セキュリティグループ 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 の更新（Alibaba Cloud アカウント認証の有効化／無効化）

Kibana の Alibaba Cloud アカウント SSO 認証を有効または無効にします。有効にすると、Kibana を使用する前に Alibaba Cloud アカウントでログインする必要があります。

前提条件：この 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 を呼び出して変更を確認してください。

ベストプラクティス

クラウドネイティブ Kibana：プライベートネットワークには EnableKibanaPvlNetwork/DisableKibanaPvlNetwork を使用します。ホワイトリストの設定には UpdateKibanaPvlNetwork を使用します。SSO には UpdateKibanaSso を使用します（archType=public のみ）。
セキュリティ：0.0.0.0/0 の使用には注意してください。本番環境では HTTPS を有効にしてください。
信頼性：冪等性を確保するために clientToken を使用します。InstanceStatusNotSupportCurrentAction/ConcurrencyUpdateInstanceConflict が発生した場合は再試行してください（30〜60 秒待機）。変更前に現在の状態を確認し、希望する状態がすでに実現されている場合は処理を省略してください。

参考リンク

参考資料	説明
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	受け入れ基準

Markdown 対応

ログインしてコメント

基本情報

作者: aliyun
リポジトリ: aliyun/alibabacloud-aiops-skills
カテゴリ: クラウド・DevOps
インストール数: 125
GitHub スター: 281

問題を報告