如何添加节点到 TKE 集群

文档元信息

功能名称: 添加节点
API 版本: 2018-05-25
适用集群版本: 所有版本
文档更新时间: 2026-01-07
Agent 友好度: ⭐⭐⭐⭐⭐

功能概述

向现有 TKE 集群添加工作节点(Node),支持两种方式:

创建新节点: 自动购买 CVM 实例并加入集群
添加已有节点: 将现有 CVM 实例加入集群

任务目标: 扩展集群计算资源,增加可调度的工作节点

前置条件

集群状态为 Running
集群节点配额充足 (默认每集群 100 个节点)
目标可用区有足够的 CVM 库存 (创建新节点)
已有 CVM 实例满足加入条件 (添加已有节点)
账户余额充足 (创建新节点需付费)

方式一: 创建新节点

Step 1: 准备节点配置参数

参数名	必填	类型	说明	示例值
ClusterId	是	String	集群 ID	cls-xxxxxxxx
RunInstancePara	是	String	CVM 创建实例参数 JSON 字符串	见下方
InstanceAdvancedSettings	否	Object	节点高级配置	见下方

RunInstancePara 结构:

{
  "InstanceType": "SA2.MEDIUM4",           // 实例机型 (2核4G)
  "SystemDisk": {
    "DiskType": "CLOUD_PREMIUM",           // 高性能云硬盘
    "DiskSize": 50                         // 系统盘大小 GB
  },
  "DataDisks": [
    {
      "DiskType": "CLOUD_PREMIUM",
      "DiskSize": 100,                     // 数据盘大小 GB
      "DeleteWithInstance": true           // 随实例删除
    }
  ],
  "InternetAccessible": {
    "InternetMaxBandwidthOut": 5,          // 公网带宽 Mbps
    "PublicIpAssigned": true               // 分配公网 IP
  },
  "InstanceCount": 3,                      // 节点数量
  "Zone": "ap-guangzhou-3",                // 可用区
  "InstanceName": "tke-node",              // 实例名称
  "SecurityGroupIds": ["sg-xxxxxxxx"]      // 安全组
}

InstanceAdvancedSettings 结构:

{
  "Labels": [
    {
      "Name": "env",
      "Value": "production"
    }
  ],
  "Taints": [],                            // 污点配置
  "ExtraArgs": {
    "kubelet": [
      "max-pods=64"                        // 每节点最大 Pod 数
    ]
  },
  "UserScript": "",                        // 自定义脚本
  "DataDisks": [
    {
      "MountTarget": "/var/lib/docker",    // 挂载路径
      "DiskType": "CLOUD_PREMIUM",
      "DiskSize": 100
    }
  ]
}

Step 2: 调用 CreateClusterInstances API

使用 cURL (HTTP 直接调用):

curl -X POST "https://tke.tencentcloudapi.com/" \
  -H "Content-Type: application/json" \
  -H "X-TC-Action: CreateClusterInstances" \
  -H "X-TC-Version: 2018-05-25" \
  -H "X-TC-Region: ap-guangzhou" \
  -H "X-TC-Timestamp: $(date +%s)" \
  -H "Authorization: TC3-HMAC-SHA256 Credential=<SecretId>/..." \
  -d '{
    "ClusterId": "cls-xxxxxxxx",
    "RunInstancePara": "{\"InstanceType\":\"SA2.MEDIUM4\",\"SystemDisk\":{\"DiskType\":\"CLOUD_PREMIUM\",\"DiskSize\":50},\"DataDisks\":[{\"DiskType\":\"CLOUD_PREMIUM\",\"DiskSize\":100}],\"InternetAccessible\":{\"InternetMaxBandwidthOut\":5},\"InstanceCount\":3,\"Placement\":{\"Zone\":\"ap-guangzhou-3\"},\"SecurityGroupIds\":[\"sg-xxxxxxxx\"]}",
    "InstanceAdvancedSettings": {
      "Labels": [
        {
          "Name": "env",
          "Value": "production"
        }
      ]
    }
  }'

响应示例:

{
  "Response": {
    "InstanceIdSet": [
      "ins-xxxxxxx1",
      "ins-xxxxxxx2",
      "ins-xxxxxxx3"
    ],
    "RequestId": "12345678-1234-1234-1234-123456789012"
  }
}

使用腾讯云 CLI:

tccli tke CreateClusterInstances \
  --Region ap-guangzhou \
  --ClusterId cls-xxxxxxxx \
  --RunInstancePara '{
    "InstanceType": "SA2.MEDIUM4",
    "SystemDisk": {
      "DiskType": "CLOUD_PREMIUM",
      "DiskSize": 50
    },
    "DataDisks": [
      {
        "DiskType": "CLOUD_PREMIUM",
        "DiskSize": 100
      }
    ],
    "InternetAccessible": {
      "InternetMaxBandwidthOut": 5
    },
    "InstanceCount": 3,
    "Placement": {
      "Zone": "ap-guangzhou-3"
    },
    "SecurityGroupIds": ["sg-xxxxxxxx"]
  }' \
  --InstanceAdvancedSettings '{
    "Labels": [
      {
        "Name": "env",
        "Value": "production"
      }
    ]
  }'

使用 Python SDK:

import json

from tencentcloud.common import credential
from tencentcloud.tke.v20180525 import tke_client, models

cred = credential.Credential("SecretId", "SecretKey")
client = tke_client.TkeClient(cred, "ap-guangzhou")

req = models.CreateClusterInstancesRequest()
req.ClusterId = "cls-xxxxxxxx"

# CVM 创建参数,通过 RunInstancePara 透传
req.RunInstancePara = json.dumps({
    "InstanceType": "SA2.MEDIUM4",
    "SystemDisk": {
        "DiskType": "CLOUD_PREMIUM",
        "DiskSize": 50,
    },
    "InstanceCount": 3,
    "Placement": {
        "Zone": "ap-guangzhou-3",
    },
    "SecurityGroupIds": ["sg-xxxxxxxx"],
})

# 高级配置
advanced = models.InstanceAdvancedSettings()
label = models.Label()
label.Name = "env"
label.Value = "production"
advanced.Labels = [label]

req.InstanceAdvancedSettings = advanced

resp = client.CreateClusterInstances(req)
print(f"节点ID列表: {resp.InstanceIdSet}")

Step 3: 获取响应

成功响应:

{
  "Response": {
    "InstanceIdSet": [
      "ins-xxxxxxx1",
      "ins-xxxxxxx2",
      "ins-xxxxxxx3"
    ],
    "RequestId": "12345678-1234-1234-1234-123456789012"
  }
}

方式二: 添加已有节点

Step 1: 检查已有节点是否满足条件

节点必须满足:

操作系统为 CentOS 7.x / Ubuntu 18.04+ / TencentOS Server
与集群在同一 VPC 内
未安装 Docker/Containerd (或愿意重装)
未加入其他 TKE 集群

Step 2: 调用 AddExistedInstances API

使用腾讯云 CLI:

tccli tke AddExistedInstances \
  --Region ap-guangzhou \
  --ClusterId cls-xxxxxxxx \
  --InstanceIds '["ins-existed01", "ins-existed02"]' \
  --InstanceAdvancedSettings '{
    "Labels": [
      {
        "Name": "node-role",
        "Value": "worker"
      }
    ]
  }'

使用 Python SDK:

req = models.AddExistedInstancesRequest()
req.ClusterId = "cls-xxxxxxxx"
req.InstanceIds = ["ins-existed01", "ins-existed02"]

advanced = models.InstanceAdvancedSettings()
label = models.Label()
label.Name = "node-role"
label.Value = "worker"
advanced.Labels = [label]

req.InstanceAdvancedSettings = advanced

resp = client.AddExistedInstances(req)
print(f"加入成功: {resp.SuccessInstanceIds}")
print(f"加入失败: {resp.FailedInstanceIds}")

验证步骤

Step 1: 查询节点状态

tccli tke DescribeClusterInstances \
  --Region ap-guangzhou \
  --ClusterId cls-xxxxxxxx \
  --InstanceIds '["ins-xxxxxxxx"]'

Step 2: 使用 kubectl 验证

# 查看节点列表
kubectl get nodes

# 查看节点详情
kubectl describe node <node-name>

# 检查节点状态
kubectl get nodes -o wide

期望结果:

NAME            STATUS   ROLES    AGE   VERSION
tke-node-xxx1   Ready    <none>   2m    v1.28.3
tke-node-xxx2   Ready    <none>   2m    v1.28.3
tke-node-xxx3   Ready    <none>   2m    v1.28.3

Step 3: 检查节点组件

# 检查 kubelet 状态
kubectl get --raw "/api/v1/nodes/<node-name>/proxy/healthz"

# 查看节点资源使用情况
kubectl top node <node-name>

异常处理

常见错误及解决方案

错误码	错误信息	原因	解决方案
InvalidParameter.InstanceNotFound	实例不存在	InstanceId 不存在或无权限	检查实例 ID 是否正确
FailedOperation.InstanceInOtherCluster	实例已在其他集群	实例已加入其他 TKE 集群	先从原集群移除
FailedOperation.InstanceNotInVpc	实例不在 VPC 中	实例网络类型不是 VPC	使用 VPC 内的实例
LimitExceeded.NodeLimit	节点数量超限	集群节点数已达上限	升级集群规格或删除不用的节点
FailedOperation.InitNodeFailed	节点初始化失败	网络不通或脚本执行失败	检查网络和安全组配置
InsufficientBalance	余额不足	账户余额不足	充值后重试

节点加入超时处理

如果节点状态长时间为 Initializing:

# 1. 登录节点查看日志
ssh root@<node-ip>

# 2. 查看初始化日志
tail -f /var/log/tke-node-init.log

# 3. 检查 kubelet 状态
systemctl status kubelet

# 4. 查看容器运行时状态
systemctl status containerd

高级配置

配置节点标签和污点

{
  "Labels": [
    {
      "Name": "node.kubernetes.io/role",
      "Value": "compute"
    },
    {
      "Name": "gpu",
      "Value": "true"
    }
  ],
  "Taints": [
    {
      "Key": "dedicated",
      "Value": "gpu",
      "Effect": "NoSchedule"
    }
  ]
}

配置节点自定义脚本

{
  "UserScript": "#!/bin/bash\necho 'vm.max_map_count=262144' >> /etc/sysctl.conf\nsysctl -p"
}

配置数据盘挂载

{
  "DataDisks": [
    {
      "MountTarget": "/var/lib/containerd",
      "DiskType": "CLOUD_SSD",
      "DiskSize": 200,
      "FileSystem": "ext4",
      "AutoFormatAndMount": true
    }
  ]
}

Agent Prompt 模板

创建节点 Prompt

请向集群添加 3 个新节点:
- 集群ID: {{cluster_id}}
- 节点机型: SA2.MEDIUM4 (2核4G)
- 系统盘: 50GB 高性能云硬盘
- 数据盘: 100GB 高性能云硬盘
- 可用区: ap-guangzhou-3
- 标签: env=production

添加已有节点 Prompt

请将以下已有 CVM 实例加入集群:
- 集群ID: cls-xxxxxxxx
- 实例ID列表: ins-aaa, ins-bbb, ins-ccc
- 添加标签: role=worker

最佳实践

节点规格选择:
- 通用场景: SA2.MEDIUM4 (2核4G) 起步
- 计算密集: SA3.LARGE8 (4核8G) 或更高
- GPU 场景: GN7/GN10X 系列
数据盘配置:
- 建议挂载独立数据盘用于容器存储
- 生产环境使用 SSD 云硬盘
- 最小建议 100GB
安全组配置:
- 允许集群 CIDR 访问节点 10250 端口 (kubelet)
- 允许 NodePort 范围 30000-32768
标签管理:
- 使用标签标识节点用途: role=compute
- 使用标签标识环境: env=production
- 使用标签进行应用调度: app=nginx

API 文档链接

CreateClusterInstances: https://cloud.tencent.com/document/api/457
AddExistedInstances: https://cloud.tencent.com/document/api/457
API Explorer: https://console.cloud.tencent.com/api/explorer?Product=tke

Cookbook 示例

完整可执行代码示例: TKE 节点添加 Cookbook

文档版本: v1.0
最后更新: 2026-01-07
维护者: TKE Documentation Team

如何添加节点到 TKE 集群

如何添加节点到 TKE 集群

文档元信息

功能概述

前置条件

方式一: 创建新节点

Step 1: 准备节点配置参数

Step 2: 调用 CreateClusterInstances API

Step 3: 获取响应

方式二: 添加已有节点

Step 1: 检查已有节点是否满足条件

Step 2: 调用 AddExistedInstances API

验证步骤

Step 1: 查询节点状态

Step 2: 使用 kubectl 验证

Step 3: 检查节点组件

异常处理

常见错误及解决方案

节点加入超时处理

高级配置

配置节点标签和污点

配置节点自定义脚本

配置数据盘挂载

Agent Prompt 模板

创建节点 Prompt

添加已有节点 Prompt

最佳实践

相关文档

API 文档链接

Cookbook 示例