调用CreateCluster创建一个标准Kubernetes专有版集群。如需创建Worker节点,请参见创建节点池

调试

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

请求语法

POST /clusters HTTP/1.1 
Content-Type:application/json
{
  "name" : "String",
  "region_id" : "String",
  "cluster_type" : "String",
  "kubernetes_version" : "String",
  "runtime" : {
    "name" : "String",
    "version" : "String",
   },
  "resource_group_id" : "String",
  "vpcid" : "String",
  "pod_vswitch_ids" : [ "String" ],
  "container_cidr" : "String",
  "service_cidr" : "String",
  "node_cidr_mask" : "String",
  "security_group_id" : "String",
  "is_enterprise_security_group" : Boolean,
  "snat_entry" : Boolean,
  "endpoint_public_access" : Boolean,
  "load_balancer_spec" : "String",
  "ssh_flags" : Boolean,
  "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",
  "disable_rollback" : Boolean,
  "timeout_mins" : Long,
  "deletion_protection" : Boolean,  
  "node_name_mode" : "String",
  "keep_instance_name" : Boolean,
  "rds_instances" : [ "String" ],
  "master_count" : Long,
  "image_type" : "String",
  "image_id" : "String",
  "os_type" : "String",
  "master_vswitch_ids" : [ "String" ],
  "master_instance_types" : [ "String" ],
  "master_system_disk_category" : "String",
  "master_system_disk_size" : Long,
  "master_system_disk_performance_level" : "String",
  "master_system_disk_snapshot_policy_id" : "String", 
  "master_instance_charge_type" : "String",
  "master_period_unit" : "String",
  "master_period" : Long,
  "master_auto_renew" : Boolean,
  "master_auto_renew_period" : Long,
  "key_pair" : "String",
  "login_password" : "String",
  "addons" : [ {
    "name" : "String",
    "config" : "String",
    "disabled" : Boolean
  } ],
  "cloud_monitor_flags" : Boolean
}

请求参数

基本配置请求Body参数

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

集群名称。

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

region_idStringcn-beijing

集群所在的地域ID。

cluster_typeStringKubernetes

集群类型。取值:

  • Kubernetes:专有版集群。
  • ManagedKubernetes:标准托管版集群、边缘托管版集群。
  • Ask:标准Serverless集群。
  • ExternalKubernetes:注册至ACK的外部集群。
kubernetes_versionString1.16.9-aliyun.1

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

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

runtimeruntime{"name": "docker", "version": "19.03.5"}容器运行时,支持containerddockerSandboxed-Container.runv三种运行时,默认为docker。runtime包括以下2个信息:
  • name:容器运行时名称。
  • version:容器运行时版本。

有关容器运行时的选择,请参见如何选择Docker运行时、Containerd运行时、或者安全沙箱运行时?

resource_group_idStringrg-acfm3mkrure****

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

网络参数vpcidStringvpc-2zeik9h3ahvv2zz95****

集群使用的专有网络,创建集群时必须为集群提供。

pod_vswitch_idsArray of String["vsw-2ze97jwri7cei0mpw****"]

Pod虚拟交换机列表,您需要为每一个节点虚拟交换机指定至少一个相同可用区的Pod虚拟交换机并且不能跟节点vswitch重复,建议选择网段掩码不大于19的虚拟交换机。

重要 当集群采用Terway网络类型时,必须为集群指定pod_vswitch_ids
container_cidrString172.20.0.0/16

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

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

Service网络地址段,可选范围:10.0.0.0/16-24,172.16-31.0.0/16-24,192.168.0.0/16-24

不能与VPC网段10.1.0.0/21及VPC内已有Kubernetes集群使用的网段重复,创建成功后不能修改。

默认使用172.19.0.0/20网段。

node_cidr_maskString25

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

默认值:26

security_group_idStringsg-bp1bdue0qc1g7k****

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

is_enterprise_security_groupBooleantrue

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

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

默认值:true

snat_entryBooleantrue

为专有网络配置SNAT。取值:

  • true:将为您创建NAT网关并自动配置SNAT规则,若您集群内的节点、应用等需要访问公网需要设置为true
  • false:不为您创建NAT网关及SNAT规则。这种模式下,集群内节点及应用将不能访问公网。
说明 如果创建集群时未开启,后续业务需要访问公网,可为已有集群开启公网访问能力

默认值:true。

endpoint_public_accessBooleantrue

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

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

默认值:true

load_balancer_specStringslb.s2.small

负载均衡规格,取值:

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

默认值:slb.s2.small

高级选项ssh_flagsBooleantrue

是否开放公网SSH登录。用于登录专有版集群的Master节点,托管版集群中该参数不生效。

  • true:表示开放。
  • false:表示不开放。

默认值:false

timezoneStringAsia/Shanghai

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

proxy_modeStringipvs

kube-proxy代理模式:

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

默认值:ipvs

enable_rrsaBooleantrue是否启用RRSA功能。
tagsArray of tag
  • 标签由区分大小写的键值对组成,您最多可以设置20个标签。
  • 标签键不可以重复,最长为64个字符;标签值可以为空,最长为128个字符。标签键和标签值都不能以“aliyun”、“acs:”、“https://”或“http://”开头。详情请参见Labels and Selectors
cluster_domainStringcluster.local

集群本地域名。

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

custom_sanStringcs.aliyun.com

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

service_account_issuerStringkubernetes.default.svc

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

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

api_audiencesStringkubernetes.default.svc

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

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

disable_rollbackBooleantrue

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

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

默认值:true

timeout_minsLong60

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

默认值:60

deletion_protectionBooleantrue

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

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

默认值:false

node_name_modeStringaliyun.com192.168.0.55test

自定义节点名称。

节点名称由三部分组成:前缀+节点IP地址+后缀:

  • 总长度为2-64个字符。
  • 前缀和后缀允许使用大小写字母、数字、连字符(-)和点号(.)。必须以大小写字母开头,不能以连字符(-)或点号(.)开头或结尾。不能连续使用连字符(-)或点号(.)
  • 前缀必选(ECS限制),后缀可选。

例如,节点IP地址为:192.168.0.55,指定前缀为aliyun.com,后缀为test,则节点名称为aliyun.com192.168.0.55test。

keep_instance_nameBooleantrue

使用已有实例创建集群时,是否保留实例名称。

  • true:保留。
  • false:不保留,会用系统规则进行替换。

默认值:true

rds_instancesArray of String["rm-2zev748xi27xc****"]

RDS实例名称。

Master配置master_countLong3

Master节点数量,可选值35

默认值:3

image_typeStringCentOS

操作系统发行版类型,推荐使用该字段指定节点操作系统。取值:

  • CentOS
  • AliyunLinux
  • AliyunLinux Qboot
  • AliyunLinuxUEFI
  • AliyunLinux3
  • Windows
  • WindowsCore
  • AliyunLinux3Arm64
  • ContainerOS

默认值:CentOS

image_idStringm-bp16z7xko3vvv8gt****

节点自定义镜像,默认使用系统镜像。当选择自定义镜像时,将取代默认系统镜像。请参见使用自定义镜像创建ACK集群

os_typeStringLinux

操作系统平台类型。取值:

  • Windows
  • Linux

默认值:Linux

master_vswitch_idsArray of String["vsw-2ze3ds0mdip0hdz8i****"]

虚拟交换ID。

master_instance_typesArray of String["ecs.n4.xlarge"]

Master节点实例类型。关于ECS实例规格的具体介绍,请参见实例规格族

master_system_disk_categoryLongcloud_ssd

Master节点系统盘类型,取值:

  • cloud_efficiency:高效云盘。
  • cloud_ssd:SSD云盘。
  • cloud_essd:ESSD云盘。

默认值:cloud_ssd。不同可用区,默认值可能会有所差异。

master_system_disk_sizeLong120

Master节点系统盘类型,取值范围[40,500],单位:GiB。

默认值:120

master_system_disk_performance_levelStringPL1

集群Master节点系统盘磁盘性能等级, 仅对ESSD磁盘生效。磁盘性能等级和磁盘大小有关。更多信息,请参见ESSD云盘

master_system_disk_snapshot_policy_idStringsp-2zej1nogjvovnz4z****

Master节点系统盘采用的自动快照策略ID。

master_instance_charge_typeStringPrePaid

Master节点付费类型,取值:

  • PrePaid:包年包月。
  • PostPaid:按量付费。

默认值:PostPaid

master_period_unitStringMonth

Master节点付费周期,当付费类型为PrePaid的时候必须指定周期。

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

master_periodLong1

Master节点包年包月时长,当master_instance_charge_type取值为PrePaid时才生效且为必选值。

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

默认值:1。

master_auto_renewBooleantrue

否开启自动续费,当master_instance_charge_type取值为PrePaid时才生效,可选值为:

  • true:自动续费。
  • false:不自动续费。

默认值:true

master_auto_renew_periodLong1

Master节点自动续费周期,以月为单位,当选择包年包月付费类型时才生效,且为必选值。

取值范围:{1, 2, 3, 6, 12}。

默认值:1。

key_pairStringsecurity-key

Mater节点的密钥对名称,和login_password二选一。

login_passwordStringHello@1234

Master节点的SSH登录密码,和key_pair二选一。密码规则为8~30个字符,且至少同时包含三项(大小写字母、数字和特殊符号)。

组件配置addonsArray of addon

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

网络组件:必选,包含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\"}"}]。

cloud_monitor_flagsBooleantrue

集群是否安装云监控插件。取值:

  • true:安装云监控插件。
  • false:不安装云监控插件。

默认值:false

响应体语法

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

响应参数

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

集群ID。

request_idString687C5BAA-D103-4993-884B-C35E4314A1E1

请求ID。

task_idStringT-5a54309c80282e39ea00002f

任务ID。

创建ACK专有版集群示例

请求示例

POST /clusters
{
    "name":"ACK专有版",
    "region_id":"cn-zhangjiakou",
    "cluster_type":"Kubernetes",
    "kubernetes_version":"1.18.8-aliyun.1",
    "runtime":{
        "name":"docker",
        "version":"19.03.5"
    },
    "resource_group_id":"rg-acfm3mkrure****",
    "vpcid":"vpc-8vbh3b9a2f38urhls****",
    "pod_vswitch_ids":[                                 
        "vsw-8vbo5fwyqiw0bbtlq0mc9"
    ],
    "container_cidr":"172.20.0.0/16",
    "service_cidr":"172.21.0.0/20",
    "node_cidr_mask":"26",
    "security_group_id":"sg-8vb7grbyvlb10j0i****",
    "is_enterprise_security_group":true,
    "snat_entry":true,
    "endpoint_public_access":true,
    "load_balancer_spec":"slb.s2.small",
    "ssh_flags":true,               // 是否允许SSH访问Kubernetes集群,即登录集群的Master节点。
    "timezone":"Asia/Shanghai",
    "proxy_mode":"ipvs",   
    "enable_rrsa":true, 
    "tags":[
        {
            "key":"tag-k",
            "value":"tag-v"
        }
    ],
    "cluster_domain":"cluster.local",
    "custom_san":"cs.aliyuncs.com",
    "service_account_issuer":"kubernetes.default.svc",
    "api_audiences":"kubernetes.default.svc",
    "disable_rollback":true,
    "timeout_mins":60,
    "deletion_protection":true,
    "node_name_mode":"customized,aliyun,5,test",
    "keep_instance_name": true 
    "rds_instances": ["rm-xx","rm-xx"],      
    "master_count":3,                 // Master节点数量,支持:3、5
    "image_type":"CentOS",
    "image_id":"m-bp16z7xko3vvv8gt****", 
    "os_type":"Linux",
    "master_vswitch_ids":[            // Master节点虚拟交换机列表。
        "vsw-8vbmoffowsztjaawjtyzo",
        "vsw-8vbmoffowsztjaawjtyzo",
        "vsw-8vbmoffowsztjaawjtyzo"
    ],
    "master_instance_types":[         // Master节点的实例规格。
        "ecs.c6.large",
        "ecs.c6.large",
        "ecs.c6.large"
    ],
    "master_system_disk_category":"cloud_essd",   // Master节点系统盘类型。
    "master_system_disk_size":120,                // Master节点系统盘大小,取值范围:40~500。
    "master_system_disk_performance_level":"PL1",
    "master_system_disk_snapshot_policy_id":"sp-2zej1nogjvovnz4z****",
    "master_instance_charge_type":"PrePaid", // Master节点付费类型。
    "master_period_unit":"Month",            // Master节点付费周期。
    "master_period":1,                       // Master节点包年包月时长。
    "master_auto_renew":true,                // Master节点到期是否自动续费。
    "master_auto_renew_period":1,            // Master节点自动续费时长。
    "key_pair": "sin-name",
    "login_password":"Hello1234",
    "addons":[
        {
            "name":"flannel"
        },
        {
            "name":"arms-prometheus"
        },
        {
            "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\"}"
        }
    ],
    "cloud_monitor_flags":true
}

正常返回示例

XML 格式

<cluster_id>cb95aa626a47740afbf6aa099b650****</cluster_id>
<task_id>T-5a54309c80282e39ea00002f</task_id>
<request_id>687C5BAA-D103-4993-884B-C35E4314A1E1</request_id>

JSON 格式

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

错误码

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