Back to Details

zeabur-cluster-scale

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Zeabur Cluster Scaling (LKE / EKS Node Pools)

Zeabur 集群扩容（LKE / EKS 节点池）

Node pool operations are not in the Zeabur CLI yet — call the Zeabur GraphQL API directly at 
https://api.zeabur.com/graphql
. The API maps 1:1 onto provider primitives: a node pool is an EKS managed node group or a Linode LKE node pool.
节点池操作目前尚未纳入Zeabur CLI——请直接调用Zeabur GraphQL API，地址为 
https://api.zeabur.com/graphql
。该API与云服务商的原生组件一一对应：节点池即EKS托管节点组或Linode LKE节点池。

⚠️ Scaling changes real billing — explicit confirmation is REQUIRED

⚠️ 扩容变更会影响实际账单——必须获得明确确认

Adding nodes or node pools increases the cluster's monthly subscription price; the price is recalculated automatically from the underlying provider resources after every change. You are the last line of defense: never run a mutation until the user has explicitly confirmed the exact change.
Before any mutation, present all of the following in one message:
  • Cluster (name + server ID)
  • Node pool (instance type + current node count)
  • The exact change (e.g. 
    3 → 5 nodes
    , or "add pool 
    g6-standard-4
    × 2")
  • Current monthly price (from 
    Server.price
    ) and that it will increase/decrease automatically after the change
Then ask a direct yes/no question, for example:
You are about to scale node pool 
g6-standard-4
on cluster 
my-cluster
from 3 to 5 nodes. Your current price is US$180/month and will increase roughly proportionally. Confirm?
Never infer consent from an ambiguous reply. A bare "ok" before seeing concrete numbers does NOT count. When in doubt, re-confirm instead of mutating.
添加节点或节点池会增加集群的月度订阅费用；每次变更后，费用会根据底层云服务商资源自动重新计算。你是最后一道防线：在用户明确确认具体变更内容前，绝不要执行任何变更操作。
执行任何变更操作前，请在一条消息中告知用户以下所有信息：
  • 集群（名称 + 服务器ID）
  • 节点池（实例类型 + 当前节点数量）
  • 具体变更内容（例如 
    3 → 5 nodes
    ，或“添加 
    g6-standard-4
    类型节点池×2”）
  • 当前月度费用（来自
    Server.price
    ），以及变更后费用会自动增加/减少
然后提出明确的是/否问题，例如：
你即将把集群
my-cluster
上的节点池
g6-standard-4
从3个节点扩容至5个节点。当前费用为180美元/月，变更后费用将大致按比例增加。是否确认？
绝不要从模糊回复中推断用户同意。在看到具体费用前仅回复“ok”不算确认。如有疑问，请再次确认，不要执行变更操作。

Authentication

认证

All requests need a Bearer token. Keep the token out of the process list — write it into a 
0600
curl config and pass that with 
-K
, instead of putting 
-H "Authorization: ..."
on the command line:
bash
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
  • Prefer the 
    ZEABUR_API_KEY
    environment variable if set
  • Otherwise reuse the CLI token from 
    ~/.config/zeabur/cli.yaml
    (present after 
    npx zeabur@latest auth login
    — use the 
    zeabur-auth
    skill if the user is not logged in)
  • Each tool/Bash invocation is a fresh shell — run this setup in the same shell block as the requests that use 
    $ZAPI_CFG
    , and 
    rm -f "$ZAPI_CFG"
    when done
All node pool mutations require manage access to the cluster (owner or admin). Collaborators with view-only access can list pools but not change them.
所有请求都需要Bearer令牌。请勿将令牌暴露在进程列表中——请将其写入权限为
0600
的curl配置文件，并通过
-K
参数传入，而不是在命令行中使用
-H "Authorization: ..."
：
bash
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调用都是独立的shell——请在与使用
    $ZAPI_CFG
    的请求相同的shell块中运行此设置，并在完成后执行
    rm -f "$ZAPI_CFG"
所有节点池变更操作都需要对集群拥有管理权限（所有者或管理员）。仅拥有查看权限的协作者可以列出节点池，但无法进行更改。

1. Find the cluster's server ID

1. 获取集群的服务器ID

bash
npx zeabur@latest server list -i=false
Only dedicated Kubernetes clusters (LKE / EKS) have node pools. If unsure whether a server is a cluster, check 
clusterType
in the query below — clusters return 
"dedicated_cluster"
and a non-empty 
nodePools
.
bash
npx zeabur@latest server list -i=false
只有专用Kubernetes集群（LKE / EKS）才有节点池。如果不确定某台服务器是否为集群，请通过以下查询查看
clusterType
字段——集群会返回
"dedicated_cluster"
，且
nodePools
不为空。

2. List node pools

2. 列出节点池

bash
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>"}}'
Field notes:
  • id
    — the provider-side identifier (EKS node group name, or LKE node pool ID). Pass it as 
    nodePoolID
    in the mutations below.
  • instanceType
    — provider machine type backing the pool (e.g. 
    t3.2xlarge
    for EKS, 
    g6-standard-4
    for LKE)
  • nodeCount
    vs 
    readyNodes
    — desired vs currently-in-service. They differ while a scale operation is in progress.
  • minNodes
    / 
    maxNodes
    — autoscaling floor/ceiling; both 
    0
    when autoscaling is not configured
  • price
    — the cluster's current monthly subscription price; quote it in the confirmation message
bash
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
    vs 
    readyNodes
    ——期望节点数 vs 当前已投入服务的节点数。扩容操作进行中时，两者数值会不同。
  • minNodes
    / 
    maxNodes
    ——自动扩缩容的下限/上限；未配置自动扩缩容时，两者均为
    0
  • price
    ——集群当前的月度订阅费用；需在确认消息中告知用户

3. Scale an existing node pool

3. 扩容现有节点池

The most common operation — changes the node count of a pool in place:
bash
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}}'
After mutating, poll the list query every ~30 seconds until 
readyNodes
equals the new 
nodeCount
and the pool 
status
is healthy (
ACTIVE
for EKS, 
ready
for LKE) — provisioning typically takes a few minutes. Bound the wait: if the pool reports a failed/degraded 
status
, stop immediately and relay it; if it has not converged after ~15 minutes, stop polling and report the current state instead of waiting forever. On success, report the updated pool and price to the user.
If a mutation request times out or fails at the transport layer, never blind-retry. The change may have been applied server-side — re-fetch the node pool list first, and only retry if the state shows the change did not happen. Blind-retrying 
addNodePool
can double-provision (and double-bill); blind-retrying 
removeNodePool
can hit a second pool if IDs were reused from a stale list.
Scaling down: warn the user that removed nodes are drained and their workloads reschedule onto the remaining nodes — make sure remaining capacity fits the current workload (check with the 
zeabur-service-metric
skill if needed). Never scale the cluster's only pool to 0.
这是最常见的操作——直接更改现有节点池的节点数量：
bash
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}}'
执行变更后，每隔约30秒调用一次列表查询，直到
readyNodes
等于新的
nodeCount
且节点池
status
显示健康（EKS为
ACTIVE
，LKE为
ready
）——资源配置通常需要几分钟。设置等待时限：如果节点池报告
status
为失败/异常，请立即停止等待并告知用户；如果超过约15分钟仍未完成配置，停止轮询并向用户报告当前状态，不要无限等待。操作成功后，向用户报告更新后的节点池信息和费用。
如果变更请求超时或传输层失败，绝不要盲目重试。变更可能已在服务端生效——请先重新获取节点池列表，只有当状态显示变更未生效时再重试。盲目重试
addNodePool
可能会导致重复配置（并重复计费）；盲目重试
removeNodePool
如果使用了过期列表中的ID，可能会误删其他节点池。
缩容操作：提醒用户，被移除的节点会被清空，其上的工作负载会调度到剩余节点上——请确保剩余节点容量足以承载当前工作负载（如有需要，使用
zeabur-service-metric
技能检查）。绝不要将集群的唯一节点池缩容至0个节点。

4. Add a node pool

4. 添加节点池

Use when the user needs a different machine type (e.g. adding bigger or GPU nodes) rather than more of the same:
bash
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
is passed through to the provider verbatim — you are expected to look up a valid type first:
  • LKE (Linode): 
    curl -s https://api.linode.com/v4/linode/types
    — public, no auth. Use the type 
    id
    (e.g. 
    g6-standard-4
    , 
    g6-dedicated-8
    ).
  • EKS (AWS): any EC2 instance type available in the cluster's region (e.g. 
    t3.2xlarge
    , 
    m6i.xlarge
    ). When unsure, ask the user or match the instance type of an existing pool.
An invalid or out-of-region instance type fails at the provider — the error message is passed through in the GraphQL 
errors
array.
当用户需要不同类型的机器（例如添加更大规格或带GPU的节点）而非同类型节点扩容时使用此操作：
bash
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. Remove a node pool

5. 删除节点池

Destructive. All nodes in the pool are drained and deleted; workloads reschedule onto the remaining pools. Never remove the last node pool of a cluster. Requires the same explicit confirmation as above, plus naming the pool being removed.
bash
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>"}}'
Completion check for removal: poll the list query (same bounds as above) until the pool no longer appears in 
nodePools
, then report the updated price.
此操作具有破坏性。节点池中的所有节点都会被清空并删除；工作负载会调度到剩余节点池。绝不要删除集群的最后一个节点池。需要与上述相同的明确确认，同时告知用户要删除的节点池名称。
bash
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
列表中，然后向用户报告更新后的费用。

Recommended guidance flow

推荐指导流程

When the user asks to scale (or complains about capacity):
  1. Show current state first — list node pools with ready counts and the current monthly price
  2. Propose a concrete change — which pool, what count (or what new instance type), and the billing impact
  3. Get explicit confirmation — see the confirmation requirements at the top
  4. Mutate, then watch — poll with the bounds above until the operation-specific completion check passes (scale/add: 
    readyNodes
    matches and 
    status
    healthy; remove: pool gone from the list); report completion and the updated price
当用户请求扩容（或抱怨容量不足）时：
  1. 先展示当前状态——列出节点池的可用节点数和当前月度费用
  2. 提出具体变更方案——涉及哪个节点池、变更后的节点数（或新实例类型），以及对账单的影响
  3. 获取明确确认——参照顶部的确认要求
  4. 执行变更并监控——按照上述时限轮询，直到达到操作对应的完成标准（扩容/添加：
    readyNodes
    匹配新数值且
    status
    健康；删除：节点池从列表中消失）；向用户报告操作完成及更新后的费用

Errors

错误处理

  • 401
    / unauthenticated — token missing or expired: re-run 
    npx zeabur@latest auth login
    or check 
    ZEABUR_API_KEY
  • "requires manage access" — the user is not the cluster's owner/admin; they must ask the owner to perform the change
  • Empty 
    nodePools
    — the server is not a dedicated Kubernetes cluster (single-VM dedicated servers cannot be scaled this way; suggest 
    zeabur-server-rent
    for renting more capacity)
  • Provider-side errors (invalid instance type, capacity unavailable in region) are surfaced verbatim in the GraphQL 
    errors
    array — relay them to the user and suggest an alternative type/region
  • 401
    / 未认证——令牌缺失或过期：重新执行
    npx zeabur@latest auth login
    或检查
    ZEABUR_API_KEY
  • "requires manage access"——用户不是集群所有者/管理员；他们需要请所有者执行变更操作
  • nodePools
    为空——该服务器不是专用Kubernetes集群（单VM专用服务器无法通过此方式扩容；建议使用
    zeabur-server-rent
    技能租赁更多容量）
  • 云服务商侧错误（无效实例类型、区域容量不足）会直接在GraphQL的
    errors
    数组中显示——将错误信息告知用户，并建议替代的实例类型/区域