zeabur-cluster-scale

Zeabur クラスターのスケーリング（LKE / EKS ノードプール）

ノードプールの操作は、まだ Zeabur CLI では利用できません。Zeabur GraphQL API（https://api.zeabur.com/graphql）を直接呼び出してください。API はプロバイダーのプリミティブに 1 対 1 で対応しています。ノードプールは、EKS のマネージドノードグループまたは Linode LKE のノードプールです。

⚠️ スケーリングの変更は実際の請求額に影響します — 明示的な確認が必須です

ノードまたはノードプールを追加すると、クラスターの月額サブスクリプション料金が上がります。変更のたびに、基盤となるプロバイダーのリソースに基づいて料金が自動的に再計算されます。最後の防波堤はあなたです。ユーザーが変更内容を明示的に確認するまで、ミューテーションを絶対に実行しないでください。

ミューテーションの実行前に、以下のすべてを 1 つのメッセージで提示してください。

• クラスター（名前 + サーバー ID）
• ノードプール（インスタンスタイプ + 現在のノード数）
• 変更内容の詳細（例：3 → 5 nodes、または「プール g6-standard-4 を 2 台追加」）
• 現在の月額料金（Server.price の値）と、変更後に料金が自動的に増減すること

次に、次のように「はい」か「いいえ」で答えられる質問をしてください。

クラスター my-cluster のノードプール g6-standard-4 を 3 台から 5 台にスケールしようとしています。現在の料金は US$180/month で、変更後はおおむね比例して増加します。確認しますか？

曖昧な返答から同意を推測してはいけません。具体的な数値を提示する前の単なる「ok」は、同意とはみなしません。迷った場合は、ミューテーションを実行するのではなく、再確認してください。

認証

すべてのリクエストには Bearer トークンが必要です。トークンをプロセス一覧に表示しないよう、0600 の curl 設定ファイルに書き込み、コマンドラインで -H "Authorization: ..." を指定する代わりに、-K で渡してください。

TOKEN="${ZEABUR_API_KEY:-$(grep '^token:' ~/.config/zeabur/cli.yaml | awk '{print $2}')}"
ZAPI_CFG=$(mktemp)
chmod 600 "$ZAPI_CFG"
printf 'header = "Authorization: Bearer %s"\n' "$TOKEN" > "$ZAPI_CFG"
unset TOKEN

• ZEABUR_API_KEY 環境変数が設定されている場合は、そちらを優先してください。
• それ以外の場合は、~/.config/zeabur/cli.yaml の CLI トークンを再利用してください（npx zeabur@latest auth login の実行後に存在します。ユーザーがログインしていない場合は、zeabur-auth スキルを使用してください）。
• ツールまたは Bash を呼び出すたびに、新しいシェルが起動します。$ZAPI_CFG を使用するリクエストと同じシェルブロック内でこの設定を行い、完了後に rm -f "$ZAPI_CFG" を実行してください。

すべてのノードプールの変更には、クラスターへの管理アクセス権（オーナーまたは管理者）が必要です。閲覧のみの権限を持つコラボレーターは、プールを一覧表示できますが、変更はできません。

1. クラスターのサーバー ID を確認する

npx zeabur@latest server list -i=false

専用 Kubernetes クラスター（LKE / EKS）のみがノードプールを持ちます。サーバーがクラスターかどうかわからない場合は、次のクエリで clusterType を確認してください。クラスターの場合は "dedicated_cluster" が返され、nodePools は空ではありません。

2. ノードプールを一覧表示する

curl -sS --max-time 30 -K "$ZAPI_CFG" https://api.zeabur.com/graphql \
  -H "Content-Type: application/json" \
  -d '{"query":"query($id: ObjectID!) { server(_id: $id) { name clusterType price nodePools { id instanceType nodeCount minNodes maxNodes readyNodes status } } }","variables":{"id":"<server-id>"}}'

フィールドの説明：

• id — プロバイダー側の識別子です（EKS のノードグループ名、または LKE のノードプール ID）。以下のミューテーションでは nodePoolID として渡します。
• instanceType — プールを構成するプロバイダーのマシンタイプです（例：EKS の t3.2xlarge、LKE の g6-standard-4）。
• nodeCount と readyNodes — それぞれ希望するノード数と、現在サービス提供中のノード数です。スケール操作中は異なる場合があります。
• minNodes / maxNodes — オートスケーリングの下限と上限です。オートスケーリングが設定されていない場合は、どちらも 0 です。
• price — クラスターの現在の月額サブスクリプション料金です。確認メッセージに記載してください。

3. 既存のノードプールをスケールする

最も一般的な操作です。プールのノード数をその場で変更します。

curl -sS --max-time 30 -K "$ZAPI_CFG" https://api.zeabur.com/graphql \
  -H "Content-Type: application/json" \
  -d '{"query":"mutation($sid: ObjectID!, $pid: String!, $n: Int!) { scaleNodePool(serverID: $sid, nodePoolID: $pid, nodeCount: $n) }","variables":{"sid":"<server-id>","pid":"<node-pool-id>","n":5}}'

変更後は、readyNodes が新しい nodeCount と一致し、プールの status が正常（EKS では ACTIVE、LKE では ready）になるまで、リストクエリを約30秒ごとにポーリングします。プロビジョニングには通常数分かかります。待機時間に上限を設けてください。プールの status が失敗または劣化を示した場合は、直ちに停止してその状態を伝えます。約15分経っても収束しない場合は、ポーリングを停止し、いつまでも待たずに現在の状態を報告します。成功したら、更新後のプールと料金をユーザーに報告します。

変更リクエストがタイムアウトした場合や、トランスポート層で失敗した場合は、状態を確認せずに再試行しないでください。 サーバー側では変更が適用されている可能性があります。まずノードプールのリストを再取得し、変更が行われていないことを状態から確認できた場合にのみ再試行してください。addNodePool を確認せずに再試行すると、二重にプロビジョニング（および二重請求）される可能性があります。removeNodePool を確認せずに再試行すると、古いリストの ID が再利用されていた場合に、別のプールに影響する可能性があります。

スケールダウン： 削除対象のノードはドレインされ、そこにあるワークロードは残りのノードに再スケジュールされることをユーザーに警告します。残りの容量で現在のワークロードを処理できることを確認してください（必要に応じて zeabur-service-metric スキルを確認します）。クラスター唯一のプールを0にスケールすることは絶対に避けてください。

4. ノードプールを追加する

同じ種類のマシンを増やすのではなく、別のマシンタイプ（より大きなノードや GPU ノードなど）が必要な場合に使用します。

curl -sS --max-time 30 -K "$ZAPI_CFG" https://api.zeabur.com/graphql \
  -H "Content-Type: application/json" \
  -d '{"query":"mutation($sid: ObjectID!, $t: String!, $n: Int!) { addNodePool(serverID: $sid, instanceType: $t, nodeCount: $n) { id instanceType nodeCount status } }","variables":{"sid":"<server-id>","t":"g6-standard-4","n":2}}'

instanceType はプロバイダーにそのまま渡されるため、最初に有効なタイプを調べる必要があります。

• LKE（Linode）：curl -s https://api.linode.com/v4/linode/types — 公開されており、認証は不要です。タイプの id（例：g6-standard-4、g6-dedicated-8）を使用します。
• EKS（AWS）：クラスターのリージョンで利用可能な EC2 インスタンスタイプを使用します（例：t3.2xlarge、m6i.xlarge）。判断できない場合はユーザーに尋ねるか、既存のプールのインスタンスタイプに合わせます。

無効なインスタンスタイプやリージョンで利用できないインスタンスタイプを指定すると、プロバイダー側で失敗します。エラーメッセージは GraphQL の errors 配列にそのまま渡されます。

5. ノードプールを削除する

破壊的な操作です。 プール内のすべてのノードがドレインされて削除され、ワークロードは残りのプールに再スケジュールされます。クラスターの最後のノードプールは削除しないでください。前述と同じ明示的な確認に加え、削除するプール名を指定する必要があります。

curl -sS --max-time 30 -K "$ZAPI_CFG" https://api.zeabur.com/graphql \
  -H "Content-Type: application/json" \
  -d '{"query":"mutation($sid: ObjectID!, $pid: String!) { removeNodePool(serverID: $sid, nodePoolID: $pid) }","variables":{"sid":"<server-id>","pid":"<node-pool-id>"}}'

削除完了の確認：上記と同じ上限時間を適用してリストクエリをポーリングし、プールが nodePools に表示されなくなるまで待ってから、更新後の料金を報告します。

推奨する案内の流れ

ユーザーからスケールの依頼（または容量に関する不満）があった場合：

1. まず現在の状態を示す — ノードプールと準備完了ノード数、現在の月額料金を表示します
2. 具体的な変更案を提示する — 対象のプール、変更後の数（または新しいインスタンスタイプ）、請求への影響を示します
3. 明示的な確認を得る — 冒頭の確認要件を参照します
4. 変更してから状況を確認する — 上記の上限時間を適用してポーリングし、操作ごとの完了条件を満たすまで待ちます（スケール／追加：readyNodes が一致し、status が正常。削除：プールがリストから消える）。完了と更新後の料金を報告します

エラー

• 401 / 認証されていない — トークンがないか、有効期限が切れています。npx zeabur@latest auth login を再実行するか、ZEABUR_API_KEY を確認します
• "requires manage access" — ユーザーはクラスターの所有者／管理者ではありません。変更は所有者に依頼する必要があります
• nodePools が空 — サーバーは専用 Kubernetes クラスターではありません（単一 VM の専用サーバーはこの方法ではスケールできません。容量を増やすには zeabur-server-rent を利用してレンタルするよう提案します）
• プロバイダー側のエラー（無効なインスタンスタイプ、リージョンで容量を利用できないなど）は GraphQL の errors 配列にそのまま表示されます。ユーザーに伝え、代替のタイプ／リージョンを提案します