如何创建 TKE 集群

文档元信息

功能名称: 创建 TKE 集群
API 版本: 2018-05-25
适用集群版本: 所有版本
文档更新时间: 2026-06-17
Agent 友好度: ⭐⭐⭐⭐⭐

功能概述

创建一个新的腾讯云容器服务（TKE）集群,支持托管集群(MANAGED_CLUSTER)和独立集群(INDEPENDENT_CLUSTER)两种类型。本文档提供面向 Agent 的完整操作指南,包含 API 调用、CLI 命令和验证步骤。

任务目标: 通过 API 或 CLI 创建一个可用的 TKE 集群

前置条件

在执行创建集群操作前,必须满足以下条件:

已开通腾讯云账号并完成实名认证
已创建腾讯云 API 密钥 (SecretId 和 SecretKey)
账号具有 TKE 服务的创建权限 (QcloudTKEFullAccess 或 AdministratorAccess)
目标地域已创建 VPC 网络和子网
目标地域集群配额充足 (默认每地域 5 个集群)
已安装并配置 tccli 工具 (腾讯云 CLI) 或准备好 API 调用环境

操作步骤

方式一: 使用腾讯云 API

Step 1: 准备请求参数

创建集群的核心参数:

参数名	必填	类型	说明	示例值
ClusterType	是	String	集群类型: MANAGED_CLUSTER(托管) 或 INDEPENDENT_CLUSTER(独立)	MANAGED_CLUSTER
ClusterCIDRSettings	是	Object	容器网络配置	见下方
ClusterBasicSettings	否	Object	集群基础信息	见下方
RunInstancesForNode	否	Array	节点创建参数	见下方
Region	是	String	地域	ap-guangzhou

ClusterBasicSettings 常用参数:

参数名	必填	类型	说明	示例值
ClusterName	否	String	集群名称,建议不超过 50 个字符	my-tke-cluster
ClusterVersion	否	String	Kubernetes 版本	1.28.3
ClusterDescription	否	String	集群描述	生产集群
VpcId	否	String	VPC ID	vpc-xxxxxxxx
ProjectId	否	Integer	项目 ID,默认 0	0
TagSpecification	否	Array	集群资源标签配置	见下方
ClusterLevel	否	String	集群规模: L5/L20/L50/L100/L200/L500	L5
AutoUpgradeClusterLevel	否	Object	集群规格自动升配配置	`{"IsAutoUpgrade": true}`

ClusterCIDRSettings 结构:

{
  "ClusterCIDR": "172.16.0.0/16",        // 集群容器网络 CIDR
  "MaxNodePodNum": 64,                    // 每个节点最大 Pod 数
  "MaxClusterServiceNum": 256,            // 集群最大 Service 数
  "ServiceCIDR": "10.96.0.0/24"          // Service CIDR
}

ClusterBasicSettings 结构:

{
  "ClusterName": "my-tke-cluster",        // 集群名称 (不超过50字符)
  "ClusterVersion": "1.28.3",             // Kubernetes 版本
  "ClusterDescription": "测试集群",       // 集群描述
  "VpcId": "vpc-xxxxxxxx",                // VPC ID
  "ProjectId": 0,                         // 项目ID (默认0)
  "TagSpecification": [                   // 集群资源标签
    {
      "ResourceType": "cluster",
      "Tags": [
        {"Key": "env", "Value": "production"},
        {"Key": "owner", "Value": "platform-team"}
      ]
    }
  ],
  "ClusterLevel": "L5",                   // 集群规模: L5/L20/L50/L100/L200/L500
  "AutoUpgradeClusterLevel": {            // 集群规格自动升配配置
    "IsAutoUpgrade": true                 // 是否自动升配
  }
}

TagSpecification 结构:

[
  {
    "ResourceType": "cluster",            // 标签绑定的资源类型,创建集群时固定为 cluster
    "Tags": [
      {
        "Key": "env",                     // 标签键
        "Value": "production"             // 标签值
      },
      {
        "Key": "owner",
        "Value": "platform-team"
      }
    ]
  }
]

常用标签建议:

标签键	示例值	用途
env	production / staging / test	区分环境
owner	platform-team	标识责任团队
cost-center	cc-1001	成本分摊
project	payment	关联业务项目

Step 2: 调用 CreateCluster API

使用 cURL (HTTP 直接调用):

# 准备签名和请求头（需要腾讯云 API 签名算法）
# 示例使用 tccli 生成签名后的完整请求

curl -X POST "https://tke.tencentcloudapi.com/" \
  -H "Content-Type: application/json" \
  -H "X-TC-Action: CreateCluster" \
  -H "X-TC-Version: 2018-05-25" \
  -H "X-TC-Region: ap-guangzhou" \
  -H "X-TC-Timestamp: $(date +%s)" \
  -H "X-TC-Language: zh-CN" \
  -H "Authorization: TC3-HMAC-SHA256 Credential=<SecretId>/..." \
  -d '{
    "ClusterType": "MANAGED_CLUSTER",
    "ClusterBasicSettings": {
      "ClusterName": "my-tke-cluster",
      "ClusterVersion": "1.28.3",
      "VpcId": "vpc-xxxxxxxx",
      "ClusterLevel": "L5",
      "AutoUpgradeClusterLevel": {
        "IsAutoUpgrade": true
      },
      "TagSpecification": [
        {
          "ResourceType": "cluster",
          "Tags": [
            {"Key": "env", "Value": "production"},
            {"Key": "owner", "Value": "platform-team"}
          ]
        }
      ]
    },
    "ClusterCIDRSettings": {
      "ClusterCIDR": "172.16.0.0/16",
      "MaxNodePodNum": 64,
      "ServiceCIDR": "10.96.0.0/24"
    }
  }'

注意: 腾讯云 API 需要 TC3-HMAC-SHA256 签名算法,建议使用 SDK 或 tccli 工具简化调用。签名算法详见: https://cloud.tencent.com/document/api/457/31853

Live Verify 会在执行层为创建类请求注入 billing:virgilliang 治理标签；普通读者不需要在下方示例中手工照抄该标签。

使用腾讯云 CLI (tccli):

tccli tke CreateCluster \
  --Region ap-guangzhou \
  --ClusterType MANAGED_CLUSTER \
  --ClusterBasicSettings '{
    "ClusterName": "my-tke-cluster",
    "ClusterVersion": "1.28.3",
    "VpcId": "vpc-xxxxxxxx",
    "ClusterLevel": "L5",
    "AutoUpgradeClusterLevel": {
      "IsAutoUpgrade": true
    },
    "TagSpecification": [
      {
        "ResourceType": "cluster",
        "Tags": [
          {"Key": "env", "Value": "production"},
          {"Key": "owner", "Value": "platform-team"}
        ]
      }
    ]
  }' \
  --ClusterCIDRSettings '{
    "ClusterCIDR": "172.16.0.0/16",
    "MaxNodePodNum": 64,
    "ServiceCIDR": "10.96.0.0/24"
  }'

使用 Python SDK:

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.CreateClusterRequest()
req.ClusterType = "MANAGED_CLUSTER"

# 集群基础配置
req.ClusterBasicSettings = models.ClusterBasicSettings()
req.ClusterBasicSettings.ClusterName = "my-tke-cluster"
req.ClusterBasicSettings.ClusterVersion = "1.28.3"
req.ClusterBasicSettings.VpcId = "vpc-xxxxxxxx"
tag_spec = models.TagSpecification()
tag_spec.ResourceType = "cluster"
env_tag = models.Tag()
env_tag.Key = "env"
env_tag.Value = "production"
owner_tag = models.Tag()
owner_tag.Key = "owner"
owner_tag.Value = "platform-team"
tag_spec.Tags = [env_tag, owner_tag]
req.ClusterBasicSettings.TagSpecification = [tag_spec]
req.ClusterBasicSettings.ClusterLevel = "L5"
req.ClusterBasicSettings.AutoUpgradeClusterLevel = models.AutoUpgradeClusterLevel()
req.ClusterBasicSettings.AutoUpgradeClusterLevel.IsAutoUpgrade = True

# 网络配置
req.ClusterCIDRSettings = models.ClusterCIDRSettings()
req.ClusterCIDRSettings.ClusterCIDR = "172.16.0.0/16"
req.ClusterCIDRSettings.MaxNodePodNum = 64
req.ClusterCIDRSettings.ServiceCIDR = "10.96.0.0/24"

# 发起请求
resp = client.CreateCluster(req)
print(f"集群ID: {resp.ClusterId}")

使用 Go SDK:

package main

import (
  "fmt"
  "github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/common"
  "github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/common/profile"
  tke "github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/tke/v20180525"
)

func main() {
  credential := common.NewCredential("SecretId", "SecretKey")
  cpf := profile.NewClientProfile()
  client, _ := tke.NewClient(credential, "ap-guangzhou", cpf)

  request := tke.NewCreateClusterRequest()
  request.ClusterType = common.StringPtr("MANAGED_CLUSTER")

  request.ClusterBasicSettings = &tke.ClusterBasicSettings{
    ClusterName:    common.StringPtr("my-tke-cluster"),
    ClusterVersion: common.StringPtr("1.28.3"),
    VpcId:          common.StringPtr("vpc-xxxxxxxx"),
    TagSpecification: []*tke.TagSpecification{
      {
        ResourceType: common.StringPtr("cluster"),
        Tags: []*tke.Tag{
          {Key: common.StringPtr("env"), Value: common.StringPtr("production")},
          {Key: common.StringPtr("owner"), Value: common.StringPtr("platform-team")},
        },
      },
    },
    ClusterLevel:   common.StringPtr("L5"),
    AutoUpgradeClusterLevel: &tke.AutoUpgradeClusterLevel{
      IsAutoUpgrade: common.BoolPtr(true),
    },
  }

  request.ClusterCIDRSettings = &tke.ClusterCIDRSettings{
    ClusterCIDR:           common.StringPtr("172.16.0.0/16"),
    MaxNodePodNum:         common.Uint64Ptr(64),
    ServiceCIDR:           common.StringPtr("10.96.0.0/24"),
  }

  response, err := client.CreateCluster(request)
  if err != nil {
    panic(err)
  }
  fmt.Printf("集群ID: %s\n", *response.Response.ClusterId)
}

Step 3: 获取响应

成功响应示例:

{
  "Response": {
    "ClusterId": "cls-xxxxxxxx",
    "RequestId": "12345678-1234-1234-1234-123456789012"
  }
}

响应参数说明:

参数名	类型	说明
ClusterId	String	集群唯一 ID,用于后续操作
RequestId	String	请求唯一标识,用于问题排查

方式二: 使用 kubectl 配合 TKE CLI

TKE 不支持通过 kubectl 直接创建集群,必须使用 API 或控制台。但可以在创建后使用 kubectl 管理集群。

验证步骤

创建集群后,需要验证集群状态:

Step 1: 查询集群状态

tccli tke DescribeClusters \
  --Region ap-guangzhou \
  --ClusterIds '["cls-xxxxxxxx"]'

期望结果:

{
  "Response": {
    "TotalCount": 1,
    "Clusters": [
      {
        "ClusterId": "cls-xxxxxxxx",
        "ClusterName": "my-tke-cluster",
        "ClusterStatus": "Running",
        "ClusterVersion": "1.28.3"
      }
    ]
  }
}

集群状态说明:

状态	说明	下一步操作
Creating	创建中	等待状态变为 Running
Running	运行中	可以添加节点和部署应用
Abnormal	异常	检查集群事件和错误日志
Deleting	删除中	等待删除完成

Step 2: 获取集群访问凭证

tccli tke DescribeClusterKubeconfig \
  --Region ap-guangzhou \
  --ClusterId cls-xxxxxxxx

Step 3: 配置 kubectl 访问

# 将返回的 Kubeconfig 内容保存到文件
echo "<kubeconfig_content>" > ~/.kube/config-tke

# 设置 KUBECONFIG 环境变量
export KUBECONFIG=~/.kube/config-tke

# 验证连接
kubectl cluster-info
kubectl get nodes

期望结果:

Kubernetes control plane is running at https://cls-xxxxxxxx.ccs.tencent-cloud.com
CoreDNS is running at https://cls-xxxxxxxx.ccs.tencent-cloud.com/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy

异常处理

常见错误及解决方案

错误码	错误信息	原因	解决方案
InvalidParameter.ClusterCIDRConflict	集群 CIDR 冲突	指定的 ClusterCIDR 与 VPC CIDR 冲突	修改 ClusterCIDR 为不冲突的网段
InvalidParameter.VpcNotFound	VPC 不存在	指定的 VpcId 不存在或无权限	检查 VpcId 是否正确
LimitExceeded.ClusterLimit	集群数量超限	当前地域集群数量已达上限	删除不用的集群或申请配额
InsufficientBalance	余额不足	账户余额不足以支付集群费用	充值后重试
FailedOperation.ComponentClientHTTP	组件请求失败	网络或组件异常	等待1-2分钟后重试
InvalidParameter.ClusterVersionInvalid	集群版本无效	指定的 Kubernetes 版本不支持	使用 DescribeAvailableClusterVersion 查询可用版本

排查步骤

检查请求参数: 确认所有必填参数已正确填写
查看 RequestId: 记录 RequestId 用于提交工单
查询集群状态: 使用 DescribeClusters 查看集群状态和错误信息
查看集群事件: 登录控制台查看集群事件详情

高级配置

创建集群时同时添加节点

在 RunInstancesForNode 参数中指定节点配置:

{
  "RunInstancesForNode": [
    {
      "InstanceType": "SA2.MEDIUM4",
      "SystemDisk": {
        "DiskType": "CLOUD_PREMIUM",
        "DiskSize": 50
      },
      "DataDisks": [
        {
          "DiskType": "CLOUD_PREMIUM",
          "DiskSize": 100
        }
      ],
      "InternetAccessible": {
        "InternetMaxBandwidthOut": 5
      },
      "InstanceCount": 3,
      "Zone": "ap-guangzhou-3"
    }
  ]
}

配置集群自动升级

{
  "ClusterBasicSettings": {
    "AutoUpgradeClusterLevel": {
      "IsAutoUpgrade": true
    }
  }
}

AutoUpgradeClusterLevel 是对象类型,不是布尔值；当前 CreateCluster API 示例使用 {"IsAutoUpgrade": true}。

配置集群标签

创建集群时可以通过 ClusterBasicSettings.TagSpecification 同步绑定标签到集群实例:

{
  "ClusterBasicSettings": {
    "ClusterName": "prod-payment-gz",
    "TagSpecification": [
      {
        "ResourceType": "cluster",
        "Tags": [
          {"Key": "env", "Value": "production"},
          {"Key": "project", "Value": "payment"},
          {"Key": "cost-center", "Value": "cc-1001"}
        ]
      }
    ]
  }
}

!!! note “标签说明” ResourceType 创建集群时使用 cluster。标签用于资源检索、权限治理和成本分摊,建议在创建时一次性写入基础标签,避免后续补录遗漏。

配置集群删除保护

创建后通过 API 启用:

tccli tke EnableClusterDeletionProtection \
  --Region ap-guangzhou \
  --ClusterId cls-xxxxxxxx

Agent Prompt 模板

基础创建 Prompt

请帮我创建一个 TKE 集群:
- 地域: {{region}}
- 集群名称: {{cluster_name}}
- Kubernetes 版本: {{k8s_version}}
- VPC ID: {{vpc_id}}
- 集群类型: 托管集群
- 容器网络 CIDR: 172.16.0.0/16
- Service CIDR: 10.96.0.0/24
- 集群规模: L5
- 集群标签: env=production, owner=platform-team, cost-center=cc-1001

带节点创建 Prompt

请帮我创建一个带3个节点的 TKE 集群:
- 地域: ap-guangzhou
- 集群名称: production-cluster
- Kubernetes 版本: 1.28.3
- VPC ID: vpc-xxxxxxxx
- 节点机型: SA2.MEDIUM4 (2核4G)
- 节点数量: 3
- 系统盘: 高性能云硬盘 50GB
- 数据盘: 高性能云硬盘 100GB

最佳实践

集群命名规范: 使用 {env}-{project}-{region} 格式,如 prod-api-gz
网络规划:
- ClusterCIDR 建议使用 /16 网段,支持更多 Pod
- ServiceCIDR 掩码需使用 TKE API 接受的 /17 到 /27 范围；示例采用 /24,并需避免与 VPC CIDR、ClusterCIDR 及同 VPC 内其他集群 CIDR 冲突
集群规模选择:
- L5: ≤5 节点,适合测试环境
- L20: 6-20 节点,适合小型生产
- L50: 21-50 节点,适合中型生产
启用删除保护: 生产集群建议启用删除保护
标签策略:
- 创建时添加 env、owner、project、cost-center 等基础标签
- 标签键和值保持稳定,避免同一含义出现 team、owner、department 等多套命名
- 结合 CAM、账单和资源检索需求提前约定标签规范
版本选择: 选择稳定版本,避免使用最新版本

API 文档链接

API 文档: https://cloud.tencent.com/document/product/457/34527
SDK 文档: https://cloud.tencent.com/document/sdk
API Explorer: https://console.cloud.tencent.com/api/explorer?Product=tke&Version=2018-05-25&Action=CreateCluster

Cookbook 示例

完整可执行代码示例: TKE 集群创建 Cookbook；源码见 cookbook/cluster/create_cluster.py。

执行真实创建前,可先运行 dry-run 校验 SDK 请求结构:

python3 cookbook/cluster/create_cluster.py \
  --cluster-name my-tke-cluster \
  --region ap-guangzhou \
  --vpc-id vpc-xxxxxxxx \
  --dry-run

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

如何创建 TKE 集群

如何创建 TKE 集群

文档元信息

功能概述

前置条件

操作步骤

方式一: 使用腾讯云 API

Step 1: 准备请求参数

Step 2: 调用 CreateCluster API

Step 3: 获取响应

方式二: 使用 kubectl 配合 TKE CLI

验证步骤

Step 1: 查询集群状态

Step 2: 获取集群访问凭证

Step 3: 配置 kubectl 访问

异常处理

常见错误及解决方案

排查步骤

高级配置

创建集群时同时添加节点

配置集群自动升级

配置集群标签

配置集群删除保护

Agent Prompt 模板

基础创建 Prompt

带节点创建 Prompt

最佳实践

相关文档

API 文档链接

Cookbook 示例