全部产品
Search
文档中心

容器服务 Kubernetes 版 ACK:通过OpenAPI创建ACK托管集群

更新时间:Oct 15, 2024

调用CreateCluster创建一个ACK托管集群。您可以在创建集群的过程中,同时创建单个或多个节点池。

调试

您可以在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" ],
  "nodepools" : [ {
    "auto_scaling" : {
      "enable" : Boolean,
      "max_instances" : Long,
      "min_instances" : Long,
      "type" : "String",
      "is_bond_eip" : Boolean,
      "eip_internet_charge_type" : "String",
      "eip_bandwidth" : Long
    },
    "kubernetes_config" : {
      "cms_enabled" : Boolean,
      "cpu_policy" : "String",
      "labels" : [ {
        "key" : "String",
        "value" : "String"
      } ],
      "runtime" : "String",
      "runtime_version" : "String",
      "taints" : [ {
        "key" : "String",
        "value" : "String",
        "effect" : "String"
      } ],
      "user_data" : "String"
    },
    "nodepool_info" : {
      "name" : "String",
      "resource_group_id" : "String"
    },
    "scaling_group" : {
      "auto_renew" : Boolean,
      "auto_renew_period" : Long,
      "data_disks" : [ {
        "category" : "String",
        "size" : Long,
        "encrypted" : "String",
        "auto_snapshot_policy_id" : "String"
      } ],
      "image_id" : "String",
      "instance_charge_type" : "String",
      "instance_types" : [ "String" ],
      "key_pair" : "String",
      "login_password" : "String",
      "period" : Long,
      "period_unit" : "String",
      "platform" : "String",
      "rds_instances" : [ "String" ],
      "spot_strategy" : "String",
      "spot_price_limit" : [ {
        "instance_type" : "String",
        "price_limit" : "String"
      } ],
      "scaling_policy" : "String",
      "security_group_id" : "String",
      "security_group_ids" : [ "String" ],
      "system_disk_category" : "String",
      "system_disk_size" : Long,
      "tags" : [ {
        "key" : "String",
        "value" : "String"
      } ],
      "vswitch_ids" : [ "String" ],
      "multi_az_policy" : "String",
      "on_demand_base_capacity" : Long,
      "on_demand_percentage_above_base_capacity" : Long,
      "spot_instance_pools" : Long,
      "spot_instance_remedy" : Boolean,
      "compensate_with_on_demand" : Boolean,
      "internet_charge_type" : "String",
      "internet_max_bandwidth_out" : Long
    },
    "tee_config" : {
      "tee_enable" : Boolean
    },
    "management" : {
      "enable" : Boolean,
      "auto_repair" : Boolean,
      "upgrade_config" : {
        "auto_upgrade" : Boolean,
        "surge" : Long,
        "surge_percentage" : Long,
        "max_unavailable" : Long
      }
    },
    "count" : Long
  } ]
}

请求参数

表 1. 请求Body参数

分类

名称

类型

是否必选

示例值

描述

基本配置

name

String

cluster-demo

集群名称。

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

region_id

String

cn-beijing

集群所在的地域ID。

cluster_type

String

ManagedKubernetes

集群类型为ManagedKubernetes。取值:

  • ManagedKubernetes:创建ACK托管集群(Pro版和基础版)、ACK Serverless集群(Pro版和基础版)、ACK Edge集群(Pro版和基础版)。

  • KubernetesACK专有集群

  • ExternalKubernetes:注册集群。

cluster_spec

String

ack.pro.small

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

  • ack.pro.smallACK集群Pro版

  • ack.standardACK集群基础版

默认值:ack.standard。取值可以为空,为空时则创建ACK集群基础版

更多信息,请参见ACK集群Pro版概述

kubernetes_version

String

1.28.9-aliyun.1

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

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

runtime

Array of runtime

{"name": "containerd", "version": "1.6.20"}

容器运行时名称,ACK支持以下三种容器运行时。

  • containerd:推荐使用,支持所有集群版本。

  • Sandboxed-Container.runv:安全沙箱容器,提供更高的隔离性,支持1.24版本及以下集群。

  • docker:支持1.22版本及以下集群。

默认值:containerd

resource_group_id

String

rg-acfm3mkrure****

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

charge_type

String

PostPaid

集群付费类型,如下资源的计费方式属于包年包月计费类型:

API Server的私网SLB实例。

说明

该字段于2024年10月15日存在变更,更多信息,请参见【产品公告】关于集群创建接口CreateCluster参数行为变更的公告

取值:

  • PrePaid:包年包月。

  • PostPaid:按量付费。

默认值:PostPaid

period

Long

1

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

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

默认值:1。

说明

该字段于2024年10月15日存在变更,更多信息,请参见【产品公告】关于集群创建接口CreateCluster参数行为变更的公告

period_unit

String

Month

付费周期,当charge_type取值为PrePaid时,需要指定周期。

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

说明

该字段于2024年10月15日存在变更,更多信息,请参见【产品公告】关于集群创建接口CreateCluster参数行为变更的公告

auto_renew

boolean

true

是否开启自动续费,当charge_type取值为PrePaid时才生效。取值:

  • true:自动续费。

  • false:不自动续费。

默认值:false

说明

该字段于2024年10月15日存在变更,更多信息,请参见【产品公告】关于集群创建接口CreateCluster参数行为变更的公告

auto_renew_period

long

1

自动续费周期,当选择预付费和自动续费时才生效。当PeriodUnit=Month时,取值范围:{1, 2, 3, 6, 12}。

默认值:1。

说明

该字段于2024年10月15日存在变更,更多信息,请参见【产品公告】关于集群创建接口CreateCluster参数行为变更的公告

网络参数

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分配IP的虚拟交换机。每个Pod虚拟交换机分别对应一个Worker节点的虚拟交换机,Pod虚拟交换机和Worker节点的虚拟交换机的可用区需保持一致。

重要

Pod虚拟交换机的网段掩码建议不超过19,最大不超过25,否则集群网络可分配的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。

说明

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

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更多详情,请参见使用ServiceAccount Token卷投影

api_audiences

String

kubernetes.default.svc

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

关于ServiceAccount更多详情,请参见使用ServiceAccount Token卷投影

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": ""}] 。

存储组件:可选,仅支持csi类型:

csi:[{"name":"csi-plugin","config": ""},{"name": "csi-provisioner","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

控制平面组件日志收集周期。取值范围:1~3000,单位:天。

默认值:30

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组件的日志。

节点池配置

nodepools

Array of nodepool

节点池的参数配置。

响应体语法

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:ACK基础版集群。
    "kubernetes_version":"1.28.9-aliyun.1",  // 集群版本,只维护最新的3个版本。
    "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实例和Kubernetes节点。
        {
            "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-eniip"}。
        },
        {
            "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"],
    "nodepools" : [ {
      "auto_scaling" : {
        "enable" : true,
        "max_instances" : 10,
        "min_instances" : 1,
        "type" : "cpu"
      },
      "kubernetes_config" : {
        "cms_enabled" : true,
        "cpu_policy" : "none",
        "labels" : [ {
          "key" : "env",
          "value" : "prod"
        } ],
        "runtime" : "containerd",
        "runtime_version" : "1.6.20",
        "taints" : [ {
          "key" : "key",
          "value" : "value",
          "effect" : "NoSchedule"
        } ],
        "user_data" : "dGhpcyBpcyBhIGV4YW1wbGU=",
        "node_name_mode" : "aliyun.com00055test"
      },
      "nodepool_info" : {
        "name" : "cluster-demo",
        "resource_group_id" : "rg-acfmyvw3wjmb****",
        "type" : "ess"
      },
      "scaling_group" : {
        "auto_renew" : true,
        "auto_renew_period" : 1,
        "data_disks" : [ {
          "category" : "cloud_ssd",
          "size" : 40,
          "encrypted" : "true",
          "auto_snapshot_policy_id" : "sp-2zej1nogjvovnz4z****",
          "performance_level" : "PL1"
        } ],
        "image_id" : "aliyun_2_1903_x64_20G_alibase_20200529.vhd",
        "instance_charge_type" : "PrePaid",
        "instance_types" : [ "ecs.d1ne.2xlarge" ],
        "key_pair" : "np-key-name",
        "login_password" : "Hello1234",
        "period" : 1,
        "period_unit" : "Month",
        "platform" : "AliyunLinux",
        "rds_instances" : [ "rds-****" ],
        "spot_strategy" : "NoSpot",
        "spot_price_limit" : [ {
          "instance_type" : "ecs.c6.large",
          "price_limit" : "0.39"
        } ],
        "scaling_policy" : "release",
        "security_group_id" : "sg-wz9a8g2mt6x5llu0****",
        "security_group_ids" : [ "sg-wz9a8g2mt6x5llu0****" ],
        "system_disk_category" : "cloud_efficiency",
        "system_disk_size" : 120,
        "system_disk_performance_level" : "PL1",
        "tags" : [ {
          "key" : "node-k-1",
          "value" : "node-v-1"
        } ],
        "vswitch_ids" : [ "vsw-wz9mfnhmssud6eicu****" ],
        "multi_az_policy" : "COST_OPTIMIZED",
        "on_demand_base_capacity" : 0,
        "on_demand_percentage_above_base_capacity" : 20,
        "spot_instance_pools" : 5,
        "spot_instance_remedy" : false,
        "compensate_with_on_demand" : true,
        "internet_charge_type" : "PayByTraffic",
        "internet_max_bandwidth_out" : 5,
        "image_type" : "AliyunLinux",
        "deploymentset_id" : "ds-bp1d19mmbsv3jf6xxxxx",
        "desired_size" : 0
      },
      "tee_config" : {
        "tee_enable" : true
      },
      "management" : {
        "enable" : false,
        "auto_repair" : false,
        "upgrade_config" : {
          "auto_upgrade" : false,
          "surge" : 0,
          "surge_percentage" : 0,
          "max_unavailable" : 1
        }
      },
      "count" : 1,
      "interconnect_mode" : "basic",
      "interconnect_config" : {
        "cen_id" : "cen-ey9k9nfhz0f*******",
        "ccn_id" : "ccn-qm5i0i0q9yi*******",
        "ccn_region_id" : "cn-shanghai",
        "bandwidth" : 10,
        "improved_period" : "1"
      },
      "max_nodes" : 10
  } ]
}

返回示例

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"
}

错误码

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