您可以通过OpenAPI创建ACK集群,包含ACK托管集群、ACK专有集群、ACK Serverless集群,ACK Edge集群以及注册集群。创建集群时,您将完成集群信息、集群组件以及ACK相关云资源的配置。
接口说明
本文仅提供创建 ACK 集群的全量参数配置,关于如何通过 OpenAPI 创建不同类型 ACK 集群的具体操作,请参见如下文档操作:
调试
您可以在OpenAPI Explorer中直接运行该接口,免去您计算签名的困扰。运行成功后,OpenAPI Explorer可以自动生成SDK代码示例。
授权信息
下表是API对应的授权信息,可以在RAM权限策略语句的Action
元素中使用,用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下:
- 操作:是指具体的权限点。
- 访问级别:是指每个操作的访问级别,取值为写入(Write)、读取(Read)或列出(List)。
- 资源类型:是指操作中支持授权的资源类型。具体说明如下:
- 对于必选的资源类型,用背景高亮的方式表示。
- 对于不支持资源级授权的操作,用
全部资源
表示。
- 条件关键字:是指云产品自身定义的条件关键字。
- 关联操作:是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限,操作才能成功。
操作 | 访问级别 | 资源类型 | 条件关键字 | 关联操作 |
---|---|---|---|---|
cs:CreateCluster | create | *Cluster acs:cs:{#regionId}:{#accountId}:cluster/* |
| 无 |
请求语法
POST /clusters HTTP/1.1
请求参数
名称 | 类型 | 必填 | 描述 | 示例值 |
---|---|---|---|---|
body | object | 否 | 请求体参数。 | |
name | string | 是 | 集群名称。 命名规则:由数字、汉字、英文字符或短划线(-)组成,长度范围 1~63 个字符,且不能以短划线(-)开头。 | cluster-demo |
region_id | string | 是 | 集群所在的地域 ID。 | cn-beijing |
cluster_type | string | 是 |
| Kubernetes |
cluster_spec | string | 否 | 当您选择
| ack.pro.small |
kubernetes_version | string | 否 | 集群版本,与 Kubernetes 社区基线版本保持一致。建议选择最新版本,若不指定,默认使用最新版本。 目前您可以在 ACK 控制台创建两种最新版本的集群。您可以通过 API 创建其他 Kubernetes 版本集群。关于 ACK 支持的 Kubernetes 版本,请参见 Kubernetes 版本发布概览。 | 1.30.1-aliyun.1 |
runtime | runtime | 否 | 集群内容器运行时,默认采用 Docker 运行时,同时还支持 Containerd 和安全沙箱容器运行时。 更多有关容器引擎的选择,请参见如何选择 Docker 运行时与安全沙箱运行时。 | |
vpcid | string | 否 | 集群使用的专有网络,创建集群时必须为集群提供。 | vpc-2zeik9h3ahvv2zz95**** |
pod_vswitch_ids | array | 否 | 网络插件选择 Terway 时,您需要为 Pod 分配 IP 的虚拟交换机。每个 Pod 虚拟交换机分别对应一个 Worker 节点的虚拟交换机,Pod 虚拟交换机和 Worker 节点的虚拟交换机的可用区需保持一致。 说明
Pod 虚拟交换机的网段掩码建议不超过 19,最大不超过 25,否则集群网络可分配的 Pod IP 地址非常有限,会影响集群的正常使用。
| |
string | 否 | 网络插件选择 Terway 时,您需要为 Pod 分配 IP 的虚拟交换机。每个 Pod 虚拟交换机分别对应一个 Worker 节点的虚拟交换机,Pod 虚拟交换机和 Worker 节点的虚拟交换机的可用区需保持一致。 说明
Pod 虚拟交换机的网段掩码建议不超过 19,最大不超过 25,否则集群网络可分配的 Pod IP 地址非常有限,会影响集群的正常使用。
| vsw-2ze97jwri7cei0mpw**** | |
container_cidr | string | 否 | Pod 网络地址段,必须是有效的私有网段,即以下网段及其子网:10.0.0.0/8、172.16-31.0.0/12-16、192.168.0.0/16。不能与 VPC 及 VPC 内已有 Kubernetes 集群使用的网段重复,创建成功后不能修改。 有关集群网络规划,请参见VPC 下 Kubernetes 的网络地址段规划。 说明
当创建 Flannel 网络类型的集群时,该字段为必填。
| 172.20.0.0/16 |
service_cidr | string | 是 | 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 网段。 | 172.21.0.0/20 |
security_group_id | string | 否 | 使用已有安全组创建集群时需要指定安全组 ID,和 | sg-bp1bdue0qc1g7k**** |
is_enterprise_security_group | boolean | 否 | 自动创建企业级安全组,当 说明
使用普通安全组时,集群内节点与 Terway Pod 数量之和不能超过 2000。所以创建 Terway 网络类型集群时,建议使用企业安全组。
默认值: | true |
snat_entry | boolean | 否 | 为专有网络配置 SNAT。取值:
说明
如果创建集群时未开启,后续业务需要访问公网,可手动开启。更多信息,请参见手动开启。
默认值: | true |
endpoint_public_access | boolean | 否 | 是否开启公网访问。通过 EIP 暴露 API Server,实现集群公网访问。
默认值: | true |
ssh_flags | boolean | 否 | 是否开放公网 SSH 登录。用登录"专有版集群"的 Master 节点,托管版集群中该参数不生效。
默认值: | true |
timezone | string | 否 | 集群使用的时区。 | Asia/Shanghai |
node_cidr_mask | string | 否 | 节点 IP 数量,通过指定网络的 CIDR 来确定 IP 的数量,只对于 Flannel 网络类型集群生效。 默认值: | 25 |
user_ca | string | 否 | 自定义集群 CA。 | -----BEGIN CERTIFICATE-----**** |
user_data | string | 否 | 自定义节点数据。 | IyEvdXNyL2Jpbi9iYXNoCmVjaG8gIkhlbGxvIEFD**** |
cluster_domain | string | 否 | 集群本地域名。 命名规则:域名由小数点(.)分隔的一个或多个部分构成,每个部分最长为 63 个字符,可以使用小写字母、数字和短划线(-),且首尾必须为小写字母或数字。 | cluster.local |
node_name_modedeprecated | string | 否 | 自定义节点名称。 节点名称由三部分组成:前缀+节点 IP 地址子串+后缀:
例如,节点 IP 地址为:192.168.0.55,指定前缀为 aliyun.com,IP 地址段长度为 5,后缀为 test,则节点名称为 aliyun.com00055test。 | aliyun.com00055test |
custom_san | string | 否 | 自定义证书 SAN,多个 IP 或域名以英文逗号(,)分隔。 | cs.aliyun.com |
encryption_provider_key | string | 否 | KMS 密钥 ID,使用该密钥对数据盘进行加密。更多详情,请参见密钥管理服务。 说明
该功能只在专业托管版集群(ACK Pro 版集群)中生效。
| 0fe64791-55eb-4fc7-84c5-c6c7cdca**** |
service_account_issuer | string | 否 | ServiceAccount 是 Pod 和集群 关于 | kubernetes.default.svc |
api_audiences | string | 否 | ServiceAccount 是 Pod 和集群 关于 | kubernetes.default.svc |
image_iddeprecated | string | 否 | 节点自定义镜像,默认使用系统镜像。当选择自定义镜像时,将取代默认系统镜像。请参见自定义镜像。 | m-bp16z7xko3vvv8gt**** |
rds_instancesdeprecated | array | 否 | RDS 实例列表,选择您想想要添加白名单的 RDS 实例。 建议前往 RDS 加入容器 Pod 网段与 Node 网段,设置 RDS 实例会由于实例非运行的状态导致无法弹出。 | |
string | 否 | RDS 实例列表,选择您想想要添加白名单的 RDS 实例。 建议前往 RDS 加入容器 Pod 网段与 Node 网段,设置 RDS 实例会由于实例非运行的状态导致无法弹出。 | rm-2zev748xi27xc**** | |
tags | array | 否 | 节点标签。标签定义规则:
| |
tag | 否 | 节点标签。标签定义规则:
| ||
addons | array | 否 | 集群组件列表,创建集群时通过 网络组件:必选,包含 Flannel 和 Terway 两种网络类型,创建集群时二选一:
存储组件:可选,仅支持
日志组件:可选。推荐开启,如果不开启日志服务时,将无法使用集群审计功能。
Ingress 组件:可选,ACK 专有版集群默认安装 Ingress 组件
事件中心:可选,默认开启。 事件中心提供对 Kubernetes 事件的存储、查询、告警等能力。Kubernetes 事件中心关联的 Logstore 在 90 天内免费。关于免费策略的更多信息,请参见创建并使用 Kubernetes 事件中心。 开启事件中心示例:[{"name":"ack-node-problem-detector","config":"{"sls_project_name":"your_sls_project_name"}"}]。 | |
addon | 否 | 集群组件列表,创建集群时通过 | ||
taintsdeprecated | array | 否 | 节点污点信息。污点和容忍度(Toleration)相互配合,可以用来避免 Pod 被分配到不合适的节点上。更多信息,请参见taint-and-toleration。 | |
taint | 否 | 节点污点信息。污点和容忍度(Toleration)相互配合,可以用来避免 Pod 被分配到不合适的节点上。更多信息,请参见taint-and-toleration。 | ||
cloud_monitor_flagsdeprecated | boolean | 否 | 集群是否安装云监控插件。取值:
默认值: | true |
platformdeprecated | string | 否 | 操作系统发行版。取值:
默认值: | CentOS |
os_typedeprecated | string | 否 | 操作系统平台类型。取值:
默认值: | Linux |
soc_enableddeprecated | boolean | 否 | false | |
security_hardening_osdeprecated | boolean | 否 | 阿里云 OS 安全加固。取值:
默认值: | false |
cis_enableddeprecated | boolean | 否 | 【已废弃】请使用参数 security_hardening_os 替代。 | false |
cpu_policydeprecated | string | 否 | 节点 CPU 管理策略。当集群版本在 1.12.6 及以上时支持以下两种策略:
默认值: | none |
proxy_mode | string | 否 | kube-proxy 代理模式
默认值: | ipvs |
node_port_range | string | 否 | 节点服务端口,可选端口范围:[30000,65535]。 默认值: | 30000~32767 |
master_vswitch_idsdeprecated | array | 否 | Master 节点交换机 ID 列表,交换机个数取值范围为[1,3]。为确保集群的高可用性,推荐您选择 3 个交换机,且分布在不同的可用区。 指定的实例规格数量需要和 | |
string | 否 | Master 节点交换机 ID 列表,交换机个数取值范围为[1,3]。为确保集群的高可用性,推荐您选择 3 个交换机,且分布在不同的可用区。 指定的实例规格数量需要和 | vsw-2ze3ds0mdip0hdz8i**** | |
key_pairdeprecated | string | 否 | 密钥对名称,和 | secrity-key |
login_passworddeprecated | string | 否 | SSH 登录密码,和 | Hello@1234 |
master_countdeprecated | long | 否 | Master 节点数量,可选值 默认值: | 3 |
master_instance_typesdeprecated | array | 否 | Master 节点实例类型。更多信息,请参见实例规格族。 | |
string | 否 | Master 节点实例类型。指定的实例规格数量需要和 | ecs.n4.xlarge | |
master_system_disk_categorydeprecated | string | 否 | Master 节点系统盘类型,取值:
默认值: | cloud_ssd |
master_system_disk_sizedeprecated | long | 否 | Master 节点系统盘类型,取值范围[40,500],单位:GiB。 默认值: | 120 |
master_system_disk_performance_leveldeprecated | string | 否 | 集群 Master 节点系统盘磁盘性能等级, 仅对 ESSD 磁盘生效。磁盘性能等级和磁盘大小有关,更多信息,请参见 ESSD 云盘。 | PL1 |
master_system_disk_snapshot_policy_iddeprecated | string | 否 | Master 节点系统盘采用的自动快照策略 ID。 | sp-2zej1nogjvovnz4z**** |
master_instance_charge_typedeprecated | string | 否 | Master 节点付费类型,取值:
默认值: | PrePaid |
master_period_unitdeprecated | string | 否 | Master 节点付费周期,当付费类型为 取值: | Month |
master_perioddeprecated | long | 否 | Master 节点包年包月时长,当 取值范围:{1, 2, 3, 6, 12, 24, 36, 48, 60}。 默认值:1。 | 1 |
master_auto_renewdeprecated | boolean | 否 | Master 节点是否开启自动续费,当
默认值: | true |
master_auto_renew_perioddeprecated | long | 否 | Master 节点自动续费周期,当选择包年包月付费类型时才生效,且为必选值。 取值范围:{1, 2, 3, 6, 12}。 默认值:1。 | 1 |
num_of_nodesdeprecated | long | 否 | Worker 节点数。范围是[0,100]。 | 3 |
vswitch_ids | array | 否 | 集群节点所在虚拟交换机,当创建零节点的托管版集群时,该字段必填。 | |
string | 否 | 集群节点所在虚拟交换机,当创建零节点的托管版集群时,该字段必填。 | vsw-2ze3ds0mdip0hdz8i**** | |
worker_vswitch_idsdeprecated | array | 否 | 集群节点使用的虚拟交换机列表,一个节点对应一个值。 当创建零节点的托管版集群时,字段 | |
string | 否 | Worker 节点虚拟交换机列表,取值范围:[1,20]。为保证高可用性,建议选择不同可用区的虚拟交换机。 当创建零节点的托管版集群时,字段 | vsw-2ze3ds0mdip0hdz8i**** | |
worker_instance_typesdeprecated | array | 否 | Worker 节点实例配置。 | |
string | 否 | Worker 节点实例规格,至少要指定一个实例规格。更多信息,请参见实例规格族。 说明
实例规格优先级随着在数据中的位置增大依次降低。当无法根据优先级较高的实例规格创建出实例时,会自动选择下一优先级的实例规格来创建实例。
| ecs.n4.large | |
worker_system_disk_categorydeprecated | string | 否 | cloud_efficiency | |
worker_system_disk_sizedeprecated | long | 否 | Worker 节点系统盘大小,单位为 GiB。 取值范围:[40,500]。 该参数的取值必须大于或者等于 max{40, ImageSize}。 默认值: | 120 |
worker_system_disk_snapshot_policy_iddeprecated | string | 否 | Worker 节点系统盘采用的自动快照策略 ID。 | sp-2zej1nogjvovnz4z**** |
worker_system_disk_performance_leveldeprecated | string | 否 | PL1 | |
worker_data_disksdeprecated | array<object> | 否 | Worker 节点数据盘类型、大小等配置的组合。 | |
object | 否 | 数据盘配置集合。 | ||
category | string | 是 | 数据盘类型。 | cloud_essd |
encrypted | string | 否 | 是否对数据盘加密。取值:
默认值: | true |
size | string | 是 | 数据盘大小,取值范围:40~32767。单位:GiB。 | 120 |
performance_level | string | 否 | 节点数据盘磁盘性能等级,仅对 ESSD 磁盘生效。磁盘性能等级和磁盘大小有关。更多信息,请参见 ESSD 云盘。 | PL1 |
worker_instance_charge_typedeprecated | string | 否 | Worker 节点付费类型,取值:
默认值:按量付费。 | PrePaid |
worker_period_unitdeprecated | string | 否 | Wroker 节点付费周期,当付费类型为 取值: | Month |
worker_perioddeprecated | long | 否 | Worker 节点包年包月时长,当 取值范围:{1, 2, 3, 6, 12, 24, 36, 48, 60}。 默认值:1。 | 1 |
worker_auto_renewdeprecated | boolean | 否 | Worker 节点是否开启自动续费,当
默认值: | true |
worker_auto_renew_perioddeprecated | long | 否 | Worker 节点自动续费周期,当选择包年包月付费类型时才生效,且为必选值。 取值范围:{1, 2, 3, 6, 12}。 | 1 |
instancesdeprecated | array | 否 | 使用已经节点创建集群时,需要指定 ECS 实例列表,该实例会作为 Worker 节点加入集群。 说明
使用已有实例创建集群时,该字段必填。
| |
string | 否 | 使用已经节点创建集群时,需要指定 ECS 实例列表,该实例会作为 Worker 节点加入集群。 说明
使用已有实例创建集群时,该字段必填。
| i-2ze4zxnm36vq00xn**** | |
format_diskdeprecated | boolean | 否 | 使用已有实例创建集群时,是否对实例进行数据盘挂载,取值:
默认值: 数据盘挂载规则:
| false |
keep_instance_namedeprecated | boolean | 否 | 使用已有实例创建集群时,是否保留实例名称。
默认值: | true |
service_discovery_types | array | 否 | 集群内服务发现类型,用于在
默认值:不开启。 | |
string | 否 | 集群内服务发现类型,用于在
默认值:不开启。 | PrivateZone | |
nat_gateway | boolean | 否 | 【已废弃】请使用参数 | true |
zone_iddeprecated | string | 否 | 【已废弃】请使用 集群所属地域的可用区 ID。此参数为 ACK 托管类的集群特有参数。 当创建 ACK 托管类的集群时,如果未指定 | cn-beiji**** |
profile | string | 否 | 当您选择
| Default |
logging_type | string | 否 | 集群开启日志服务,只针对 ACK Serverless 集群生效,且取值必须是 | SLS |
controlplane_log_ttl | string | 否 | 控制平面组件日志保存天数。 | 30 |
controlplane_log_project | string | 否 | 控制平面组件日志服务 Project,可以使用已有 Project 用于日志存储,也可以使用系统自动创建 Project 用户日志存储。如果选择自动创建日志服务 Project 将会自动创建一个名称为 | k8s-log-xxx |
controlplane_log_components | array | 否 | 组件名称列表,指定那些控制平面的组件日志需要被收集。 默认采集 apiserver、kcm、scheduler 组件的日志。 | |
string | 否 | 组件名称列表,指定那些控制平面的组件日志需要被收集。 默认采集 apiserver、kcm、scheduler 组件的日志。 | ["apiserver","kcm","scheduler"] | |
deletion_protection | boolean | 否 | 集群删除保护,防止通过控制台或 API 误删除集群。取值:
默认值: | true |
disable_rollbackdeprecated | boolean | 否 | 集群创建失败是否回滚。取值:
默认值: | true |
timeout_minsdeprecated | long | 否 | 集群创建超时时间,单位分钟。 默认值: | 60 |
image_typedeprecated | string | 否 | 操作系统发行版类型,推荐使用该字段指定节点操作系统。取值:
默认值: | AliyunLinux |
load_balancer_specdeprecated | string | 否 | 负载均衡规格,取值:
默认值: | slb.s2.small |
enable_rrsa | boolean | 否 | 是否启用 RRSA 功能。 | true |
resource_group_id | string | 否 | 集群所属资源组 ID,实现不同资源的隔离。 | rg-acfm3mkrure**** |
charge_typedeprecated | string | 否 | 资源付费类型,如下资源的计费方式属于包年包月计费类型: API Server 的私网 SLB 实例。 取值: PrePaid:包年包月。 PostPaid:按量付费。 默认值:PostPaid。 该字段于 2024 年 10 月 15 日存在变更,更多信息,请参见关于集群创建接口 CreateCluster 参数行为变更的公告。 | PostPaid |
period_unitdeprecated | string | 否 | 付费周期,当付费类型为 PrePaid 的时候,需要指定周期。 取值:Month,当前仅支持以月为周期。 该字段于 2024 年 10 月 15 日存在变更,更多信息,请参见关于集群创建接口 CreateCluster 参数行为变更的公告。 | Month |
perioddeprecated | long | 否 | 购买时长。包年包月时长,当 charge_type 取值为 PrePaid 时才生效,且为必选值。 取值范围:{1, 2, 3, 6, 12, 24, 36, 48, 60}。 默认值:1。 该字段于 2024 年 10 月 15 日存在变更,更多信息,请参见关于集群创建接口 CreateCluster 参数行为变更的公告。 | 1 |
auto_renewdeprecated | boolean | 否 | 是否开启自动续费,当
默认值: 该字段于 2024 年 10 月 15 日存在变更,更多信息,请参见关于集群创建接口 CreateCluster 参数行为变更的公告。 | true |
auto_renew_perioddeprecated | long | 否 | 自动续费周期,当选择预付费和自动续费时才生效。当 默认值:1。 该字段于 2024 年 10 月 15 日存在变更,更多信息,请参见关于集群创建接口 CreateCluster 参数行为变更的公告。 | 1 |
ip_stack | string | 否 | 集群 ip_stack。 | 可选值: ipv4(单栈) dual(双栈),默认值为ipv4。 |
access_control_list | array | 否 | 注册集群 API Server SLB 访问控制列表。 | |
string | 否 | 注册集群 API Server SLB 访问控制列表。 | 192.168.1.0/24 | |
nodepools | array | 否 | 节点池列表。 | |
nodepool | 否 | 节点池配置。 | ||
zone_ids | array | 否 | 集群所属地域的多个可用区 ID。此参数为 ACK 托管类的集群特有参数。 当创建 ACK 托管类的集群时,如果未指定 | |
string | 否 | 集群所属地域的可用区 ID,将在该可用区自动创建虚拟交换机。 | cn-beijing-h | |
load_balancer_id | string | 否 | 指定用于 APIServer 访问的 CLB 实例 ID。指定该参数时,将不再自动创建 APIServer CLB。 | lb-wz9t256gqa3vbouk**** |
maintenance_window | maintenance_window | 否 | 集群维护窗口。 | |
operation_policy | object | 否 | 集群自动运维策略。 | |
cluster_auto_upgrade | object | 否 | 集群自动升级。 | |
enabled | boolean | 否 | 是否开启集群自动升级。 | true |
channel | string | 否 | 集群自动升级频次。可取值:
| patch |
返回参数
示例
正常返回示例
JSON
格式
{
"cluster_id": "cb95aa626a47740afbf6aa099b650****",
"request_id": "687C5BAA-D103-4993-884B-C35E4314A1E1",
"task_id": "T-5a54309c80282e39ea****"
}
示例
正常返回示例
JSON
格式
{
"cluster_id": "cb95aa626a47740afbf6aa099b650****",
"task_id": "T-5a54309c80282e39ea00002f",
"request_id": "687C5BAA-D103-4993-884B-C35E4314A1E1"
}
XML
格式
<cluster_id>cb95aa626a47740afbf6aa099b650****</cluster_id>
<task_id>T-5a54309c80282e39ea00002f</task_id>
<request_id>687C5BAA-D103-4993-884B-C35E4314A1E1</request_id>
错误码
访问错误中心查看更多错误码。
变更历史
变更时间 | 变更内容概要 | 操作 |
---|---|---|
2024-11-19 | API 内部配置变更,不影响调用 | 查看变更详情 |
2024-10-15 | API 内部配置变更,不影响调用 | 查看变更详情 |
2024-09-13 | API 内部配置变更,不影响调用 | 查看变更详情 |
2024-09-11 | API 内部配置变更,不影响调用 | 查看变更详情 |
2024-09-04 | API 内部配置变更,不影响调用 | 查看变更详情 |
2024-04-22 | API 内部配置变更,不影响调用 | 查看变更详情 |
2024-04-19 | API 内部配置变更,不影响调用 | 查看变更详情 |
2023-08-21 | API 内部配置变更,不影响调用 | 查看变更详情 |
2023-08-08 | API 内部配置变更,不影响调用 | 查看变更详情 |
2022-09-23 | API 内部配置变更,不影响调用 | 查看变更详情 |
2022-08-02 | API 内部配置变更,不影响调用 | 查看变更详情 |
2021-11-24 | API 内部配置变更,不影响调用 | 查看变更详情 |