调用CreateCluster创建一个Kubernetes托管版集群实例。如需创建Work节点,请参见创建节点池

调试

您可以在OpenAPI Explorer中直接运行该接口,免去您计算签名的困扰。运行成功后,OpenAPI Explorer可以自动生成SDK代码示例。

请求语法

POST /clusters HTTP/1.1 
Content-Type:application/json
{
  "name" : "String",
  "region_id" : "String",
  "cluster_type" : "String",
  "cluster_spec" : "String",
  "kubernetes_version" : "String",
  "resource_group_id" : "String",
  "vpcid" : "String",
  "vswitch_ids" : [ "String" ],
  "pod_vswitch_ids" : [ "String" ],
  "container_cidr" : "String",
  "service_cidr" : "String",
  "security_group_id" : "String",
  "is_enterprise_security_group" : Boolean,
  "node_cidr_mask" : "String",
  "snat_entry" : Boolean,
  "endpoint_public_access" : Boolean,
  "load_balancer_spec" :  "String",
  "timezone" : "String",
  "proxy_mode" : "String",
  "enable_rrsa" : Boolean,
  "tags" : [ {
    "key" : "String",
    "value" : "String"
  } ],
  "cluster_domain" : "String",
  "custom_san" : "String",
  "service_account_issuer" : "String",
  "api_audiences" : "String",
  "encryption_provider_key" : "String",
  "timeout_mins" : Long,
  "disable_rollback" : Boolean,
  "deletion_protection" : Boolean,
  "addons" : [ {
    "name" : "String",
    "config" : "String",
    "disabled" : Boolean
  } ],
  "controlplane_log_ttl" : "String",
  "controlplane_log_project" : "String",
  "controlplane_log_components" : [ "String" ]     
}

请求参数

表 1. 请求Body参数
分类 名称 类型 是否必选 示例值 描述
基本配置 name String cluster-demo

集群名称。

命名规则:由数字、汉字、英文字符、短划线(-)或下划线(_)组成,长度范围1~63个字符,且不能以下划线(_)开头。

region_id String cn-beijing

集群所在的地域ID。

cluster_type String ManagedKubernetes

集群类型。取值ManagedKubernetes创建标准托管版集群。

cluster_spec String ack.pro.small

托管版集群类型,面向托管集群。取值:

  • ack.pro.small:专业托管集群,即:”ACK Pro版集群“。
  • ack.standard:标准托管版集群。

默认值:ack.standard。取值可以为空,为空时则创建标准托管集群。

更多详情,请参见ACK Pro版集群概述

kubernetes_version String 1.22.3-aliyun.1

集群版本,与Kubernetes社区基线版本保持一致。建议选择最新版本,若不指定,默认使用最新版本。

目前您可以在ACK控制台创建两种最新版本的集群。您可以通过API创建其他Kubernetes版本集群。关于ACK支持的Kubernetes版本,请参见Kubernetes版本发布概览

resource_group_id String rg-acfm3mkrure****

集群所属资源组ID,实现不同资源的隔离。

charge_type String PostPaid
集群付费类型,如下资源的计费方式属于包年包月计费类型:
  • 节点池的节点(ECS)。
  • API Server的私网SLB实例。
取值:
  • PrePaid:包年包月。
  • PostPaid:按量付费。

默认值:PostPaid

period Long 1

购买时长。包年包月时长,当charge_type取值为PrePaid时才生效,且为必选值。

取值范围:{1, 2, 3, 6, 12, 24, 36, 48, 60}。

默认值:1。

period_unit String Month

付费周期,当付费类型为PrePaid的时候,需要指定周期。

取值:Month,当前仅支持以月为周期。

网络参数 vpcid String vpc-2zeik9h3ahvv2zz95****

集群使用的VPC实例ID。

vswitch_ids Array of String ["vsw-2ze48rkq464rsdts1****"]

交换机ID。List长度范围为[1,5]。

pod_vswitch_ids Array of String ["vsw-2ze97jwri7cei0mpw****"]

Terway网络类型的集群,需要指定Pod所在的虚拟交换,因为Pod独占一个机器IP。

container_cidr String 172.20.0.0/16

Pod网络地址段,不能和VPC网段冲突。当选择系统自动创建VPC时,默认使用172.16.0.0/16网段。

重要
  • 当创建Flannel网络类型的集群时,该字段为必填。
  • 当创建Terway网络类型的集群时,该字段不需要填。
service_cidr String 172.21.0.0/20

Service网络地址段,不能和VPC网段及Pod网络网段冲突。当选择系统自动创建VPC时,默认使用172.19.0.0/20网段。

security_group_id String sg-bp1bdue0qc1g7k****

使用已有安全组创建集群时需要指定安全组ID,和is_enterprise_security_group二选一,集群节点自动加入到此安全组。

is_enterprise_security_group Boolean true

自动创建企业级安全组,当security_group_id为空的时生效。

说明 使用普通安全组时,集群内节点与Terway Pod数量之和不能超过2000。所以创建Terway网络类型集群时,建议使用企业安全组。
  • true:创建并使用企业级安全组。
  • false:不使用企业级安全组。

默认值:true

node_cidr_mask String 25

节点IP数量,通过指定网络的CIDR来确定IP的数量,只对于Flannel网络类型集群生效。

默认值:25

snat_entry Boolean true

是否为网络配置SNAT。

  • 当已有VPC能访问公网环境时,设置为false
  • 当已有VPC不能访问公网环境时:
    • 设置为true,表示配置SNAT,此时可以访问公网环境。
    • 设置为false,表示不配置SNAT,此时不能访问公网环境。

如果您需要访问公网,建议配置为true。

默认值:false。

说明 如果创建集群时未开启,后续业务需要访问公网,可为已有集群开启SNAT公网访问能力
endpoint_public_access Boolean true

是否开启公网访问。通过EIP暴露API Server,实现集群公网访问。

  • true:开启公网访问。
  • false:不开启公网访问。选择不开放时,则无法通过外网访问集群API Server。

默认值:true

load_balancer_spec String slb.s2.small

API Server负载均衡规格,取值:

  • slb.s1.small
  • slb.s2.small
  • slb.s2.medium
  • slb.s3.small
  • slb.s3.medium
  • slb.s3.large

默认值:slb.s2.small

高级选项 timezone String Asia/Shanghai

集群使用的时区。更多信息,请参见支持时区

proxy_mode String ipvs

kube-proxy代理模式:

  • iptables: 成熟稳定的kube-proxy代理模式,Kubernetes Service的服务发现和负载均衡使用iptables规则配置,但是性能一般,受规模影响较大,适用于集群存在少量的service。
  • ipvs:高性能的kube-proxy代理模式,Kubernetes Service的服务发现和负载均衡使用Linux IPVS模块进行配置,适用于集群存在大量的Service,对负载均衡有高性能要求的场景。

默认值:ipvs

enable_rrsa Boolean true 是否启用RRSA功能。
tags Array of tag [{"key": "env", "value": "prod"}]

给集群打tag标签。包含以下信息:

  • key:标签名称。
  • value:标签值。
cluster_domain String cluster.local

集群本地域名。

命名规则:域名由小数点(.)分隔的一个或多个部分构成,每个部分最长为63个字符,可以使用小写字母、数字和短划线(-),且首尾必须为小写字母或数字。

custom_san String cs.aliyun.com

自定义证书SAN,多个IP或域名以英文逗号(,)分隔。

service_account_issuer String kubernetes.default.svc

ServiceAccount是Pod和集群apiserver通讯的访问凭证。而service-account-issuerserviceaccount token中的签发身份,即token payload中的iss字段。

关于ServiceAccount更多详情,请参见部署服务账户令牌卷投影

api_audiences String kubernetes.default.svc

ServiceAccount是Pod和集群apiserver通讯的访问凭证,而api-audiences是合法的请求token身份,用于apiserver服务端认证请求token是否合法。支持配置多个audience,通过英文逗号(,)分割。

关于ServiceAccount更多详情,请参见部署服务账户令牌卷投影

encryption_provider_key String 0fe64791-55eb-4fc7-84c5-c6c7cdca****
KMS密钥ID,使用该密钥对Secret数据进行加密。更多详情,请参见什么是密钥管理服务
说明 该功能只在专业托管版集群(ACK Pro版集群)中生效。
timeout_mins Long 60

集群创建超时时间,单位分钟。

默认值:60

disable_rollback Boolean true

集群创建失败是否回滚。取值:

  • true:当集群创建失败时,进行回滚操作。
  • false:当集群创建失败时,不进行回滚操作。

默认值:true

deletion_protection Boolean true

集群删除保护,防止通过控制台或API误删除集群。取值:

  • true:启用集群删除保护,将不能通过控制台或API删除集群。
  • false:不启用集群删除保护,则能通过控制台或API删除集群。

默认值:false

组件配置 addons Array of addon [{"name": "terway-eniip","config": ""}, {"name": "logtail-ds","config": "{\"IngressDashboardEnabled\":\"true\",\"sls_project_name\":\"your_sls_project_name\"}"}, {"name":"nginx-ingress-controller","config":"{\"IngressSlbNetworkType\":\"internet\"}"}]

Kubernetes集群安装的组件列表,创建集群时通过addons指定想要安装的集群组件。

  • name:必填,组件名称。
  • config:可选,取值为空时表示无需配置。
  • disabled:可选,是否禁止默认安装。

网络组件:必选,包含Flannel和Terway两种网络类型,创建集群时二选一:

  • Flannel网络:[{"name":"flannel","config":""}]。
  • Terway网络:[{"name": "terway-eniip","config": ""}] 。

存储组件:必选,支持csiflexvolume两种类型:

  • csi:[{"name":"csi-plugin","config": ""},{"name": "csi-provisioner","config": ""}]。
  • flexvolume:[{"name": "flexvolume","config": ""}] 。

日志组件:可选。推荐开启,如果不开启日志服务时,将无法使用集群审计功能。

  • 使用已有SLS Project:[{"name": "logtail-ds","config": "{\"IngressDashboardEnabled\":\"true\",\"sls_project_name\":\"your_sls_project_name\"}"}] 。
  • 创建新的SLS Project:[{"name": "logtail-ds","config": "{\"IngressDashboardEnabled\":\"true\"}"}] 。

Ingress组件:可选,ACK专有版集群默认安装Ingress组件nginx-ingress-controller

  • 安装Ingress并且开启公网:[{"name":"nginx-ingress-controller","config":"{\"IngressSlbNetworkType\":\"internet\"}"}] 。
  • 禁止默认安装Ingress:[{"name": "nginx-ingress-controller","config": "","disabled": true}] 。

事件中心:可选,默认开启。

事件中心提供对Kubernetes事件的存储、查询、告警等能力。Kubernetes事件中心关联的Logstore在90天内免费。关于免费策略的更多信息,请参见创建并使用K8s事件中心

开启事件中心:[{"name":"ack-node-problem-detector","config":"{\"sls_project_name\":\"your_sls_project_name\"}"}]。

controlplane_log_ttl String 30

控制平面组件日志收集周期,单位:天。

默认值:7

controlplane_log_project String k8s-log-xxx

控制平面组件日志服务Project,可以使用已有Project用于日志存储,也可以使用系统自动创建Project用户日志存储。如果选择自动创建日志服务Project将会自动创建一个名称为k8s-log-{ClusterID}的日志服务Project。

controlplane_log_components Array of String ["apiserver","kcm","scheduler","ccm"]

组件名称列表,指定哪些控制平面的组件日志需要被收集。

默认采集API Server、KCM、Scheduler、CCM组件的日志。

响应体语法

HTTP/1.1 200
Content-Type:application/json
{
  "cluster_id" : "String",
  "request_id" : "String",
  "task_id" : "String"
}

响应参数

表 2. 响应Body参数
名称 类型 示例值 描述
cluster_id String cb95aa626a47740afbf6aa099b650****

集群ID。

request_id String 687C5BAA-D103-4993-884B-C35E4314A1E1

请求ID。

task_id String T-5a54309c80282e39ea00002f

任务ID。

创建ACK标准托管版集群示例

请求示例

POST /clusters 
<公共请求头>
{
    "name":"ACK托管版",                      // 集群名称 #required
    "region_id":"cn-zhangjiakou",           // 地域ID, #required。
    "cluster_type":"ManagedKubernetes",     // 集群类型 #required
    "cluster_spec":"ack.pro.small",        // 托管版集群类型。ack.pro.small:ACK Pro版集群;ack.standard:标准托管版集群。
    "kubernetes_version":"1.18.8-aliyun.1",  // 集群版本,只维护最新的2个版本。
    "resource_group_id":"rg-acfm3mkrure****",
    "vpcid":"vpc-8vbh3b9a2f38urhls****",          // 集群专有网络ID。 #required
    "vswitch_ids":[                               // 集群虚拟交换机ID。 #required
        "vsw-8vbmoffowsztjaawj****"
    ],
    "pod_vswitch_ids":[                                // Terway网络类型的集群,需要指定POD所在的虚拟交换,因为POD独占一个机器IP。                     
        "vsw-8vbo5fwyqiw0bbtlq****"
    ],
    "container_cidr":"172.20.0.0/16",             // 集群POD网段#required, 网络模式是terway插件的情况下不必须。
    "service_cidr":"172.21.0.0/20",               // 集群Service网段。 #required
    "security_group_id":"sg-8vb7grbyvlb10j0i****",     // 使用已有安全组。和is_enterprise_security_group二选一。
    "is_enterprise_security_group":true,               // 自动创建企业安全组,和security_group_id二选一。
    "node_cidr_mask":"25",                // 节点IP数量,通过指定节点网段的掩码来决定。  
    "snat_entry":true,                 // 为专有网络配置SNAT规则,以开启集群公网访问。
    "endpoint_public_access":true,      // 开启公网访问。
    "load_balancer_spec":slb.s2.small,   
    "timezone":"Asia/Shanghai",   // 时区
    "proxy_mode":"ipvs",           // kube-proxy代理模式,取值:iptables或者ipvs。
    "enable_rrsa":true,
    "tags":[                       // 集群标签。标签将同时作用于 ACK集群、ECS实例和Kuberntes节点。
        {
            "key":"tag-k",
            "value":"tag-v"
        }
    ],
    "cluster_domain":"cluster.local",    // 集群本地域名,默认:cluster.local。
    "custom_san":"cs.aliyuncs.com",      // 集群自定义证书SAN。
    "service_account_issuer":"kubernetes.default.svc", // 服务账户令牌卷投影。serviceaccount token中的签发身份,即token payload中的iss字段。
    "api_audiences":"kubernetes.default.svc",          // 服务账户令牌卷投影。合法的请求token身份,用于apiserver服务端认证请求token是否合法。
    "encryption_provider_key":"8734596c-c0d6-4a63-a76e-fe72c7b0****", // Secret落盘加密的密钥ID。
    "timeout_mins":60,                      // 集群创建超时时间。
    "disable_rollback":true,                // 失败是否回滚。
    "deletion_protection":true,    // 集群删除保护。
    "addons":[                    // 组件配置
        {
            "name":"flannel"      // 当集群网络类型是Terway时,设置为{"name":"terway-eni"}。
        },
        {
            "name":"csi-plugin"
        },
        {
            "name":"csi-provisioner"
        },
        {
            "name":"logtail-ds",
            "config":"{\"IngressDashboardEnabled\":\"true\"}"
        },
        {
            "name":"ack-node-problem-detector",
            "config":"{\"sls_project_name\":\"\"}"
        },
        {
            "name":"nginx-ingress-controller",                      // 组件名称
            "config":"{\"IngressSlbNetworkType\":\"internet\"}",    // 组件配置
            "disabled": true                                        // 是否禁止默认安装。
        },
        {
            "name":"arms-prometheus"
        }
    ],
    "controlplane_log_ttl" : "30",
    "controlplane_log_project" : "k8s-log-xxx",
    "controlplane_log_components" : ["apiserver","kcm","scheduler"]
 }

返回示例

XML格式
<cluster_id>cb95aa626a47740afbf6aa099b65****</cluster_id>
<task_id>687C5BAA-D103-4993-884B-C35E4314A1E1</task_id>
<request_id>T-5a54309c80282e39ea00002f</request_id>

JSON格式

{
    "cluster_id": "cb95aa626a47740afbf6aa099b65****",
    "request_id": "687C5BAA-D103-4993-884B-C35E4314A1E1",
    "task_id": "T-5a54309c80282e39ea00002f"
}

错误码

访问错误中心查看更多错误码。