功能介绍
该API用于获取指定项目下所有集群的详细信息。
调用方法
请参见如何调用API。
URI
GET /api/v3/projects/{project_id}/clusters
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
project_id |
是 |
String |
项目ID,获取方式请参见如何获取接口URI中参数。 |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
detail |
否 |
String |
查询集群详细信息。 若设置为true,获取集群下节点总数(totalNodesNumber)、正常节点数(activeNodesNumber)、CPU总量(totalNodesCPU)、内存总量(totalNodesMemory)、已安装插件列表(installedAddonInstances),已安装插件列表中包含名称(addonTemplateName)、版本号(version)、插件的状态信息(status),放入到annotation中。 |
status |
否 |
String |
集群状态,取值如下
|
type |
否 |
String |
集群类型:
|
version |
否 |
String |
集群版本过滤 |
请求参数
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
Content-Type |
是 |
String |
消息体的类型(格式) |
X-Auth-Token |
是 |
String |
调用接口的认证方式分为Token和AK/SK两种,如果您使用的Token方式,此参数为必填,请填写Token的值,获取方式请参见获取token。 |
响应参数
状态码: 200
参数 |
参数类型 |
描述 |
---|---|---|
kind |
String |
Api type |
apiVersion |
String |
API version |
items |
集群对象列表,包含了当前项目下所有集群的详细信息。您可通过items.metadata.name下的值来找到对应的集群。 |
参数 |
参数类型 |
描述 |
---|---|---|
kind |
String |
API类型,固定值“Cluster”或“cluster”,该值不可修改。 |
apiVersion |
String |
API版本,固定值“v3”,该值不可修改。 |
metadata |
集群的基本信息,为集合类的元素类型,包含一组由不同名称定义的属性。 |
|
spec |
spec是集合类的元素类型,您对需要管理的集群对象进行详细描述的主体部分都在spec中给出。CCE通过spec的描述来创建或更新对象。 |
|
status |
集合类的元素类型,用于记录对象在系统中的当前状态信息,包含了集群状态和本次创建集群作业的jobID |
参数 |
参数类型 |
描述 |
---|---|---|
name |
String |
集群名称。 命名规则:以小写字母开头,由小写字母、数字、中划线(-)组成,长度范围4-128位,且不能以中划线(-)结尾。 |
uid |
String |
集群ID,资源唯一标识,创建成功后自动生成,填写无效。 |
alias |
String |
集群显示名,用于在 CCE 界面显示,该名称创建后可修改。 命名规则:以小写字母开头,由小写字母、数字、中划线(-)组成,长度范围4-128位,且不能以中划线(-)结尾。 显示名和其他集群的名称、显示名不可以重复。 在创建集群、更新集群请求体中,集群显示名alias未指定或取值为空,表示与集群名称name一致。在查询集群等响应体中,集群显示名alias将必然返回,未配置时将返回集群名称name。 |
annotations |
Map<String,String> |
集群注解,由key/value组成: "annotations": {
"key1" : "value1",
"key2" : "value2"
}
说明:
|
labels |
Map<String,String> |
集群标签,key/value对格式。 说明:
该字段值由系统自动生成,用于升级时前端识别集群支持的特性开关,用户指定无效。 |
creationTimestamp |
String |
集群创建时间 |
updateTimestamp |
String |
集群更新时间 |
参数 |
参数类型 |
描述 |
---|---|---|
category |
String |
集群类别: |
type |
String |
集群Master节点架构:
|
flavor |
String |
字段默认值:创建CCE集群或鲲鹏集群时,如果是非专属云为cce.s1.small,专属云则为cce.dec.s1.small; 集群规格,集群创建完成后规格不可再变更,请按实际业务需求进行选择:
说明:
|
version |
String |
集群版本,与Kubernetes社区基线版本保持一致,建议选择最新版本。 在CCE控制台支持创建两种最新版本的集群。可登录CCE控制台创建集群,在“版本”处获取到集群版本。 其它集群版本,当前仍可通过api创建,但后续会逐渐下线,具体下线策略请关注CCE官方公告。 说明:
|
platformVersion |
String |
CCE集群平台版本号,表示集群版本(version)下的内部版本。用于跟踪某一集群版本内的迭代,集群版本内唯一,跨集群版本重新计数。不支持用户指定,集群创建时自动选择对应集群版本的最新平台版本。 platformVersion格式为:cce.X.Y
|
description |
String |
集群描述,对于集群使用目的的描述,可根据实际情况自定义,默认为空。集群创建成功后可通过接口更新指定的集群来做出修改,也可在CCE控制台中对应集群的“集群详情”下的“描述”处进行修改。仅支持utf-8编码。 |
customSan |
Array of strings |
集群的API Server服务端证书中的自定义SAN(Subject Alternative Name)字段,遵从SSL标准X509定义的格式规范。
示例: SAN 1: DNS Name=example.com
SAN 2: DNS Name=www.example.com
SAN 3: DNS Name=example.net
SAN 4: IP Address=93.184.216.34
|
ipv6enable |
Boolean |
集群是否使用IPv6模式,1.15版本及以上支持。 |
hostNetwork |
节点网络参数,包含了 虚拟私有云VPC 和子网的ID信息,而VPC是集群内节点之间的通信依赖,所以是必选的参数集。 |
|
containerNetwork |
容器网络参数,包含了容器网络类型和容器网段的信息。 |
|
eniNetwork |
云原生网络2.0网络配置,创建CCE Turbo集群时指定。 |
|
serviceNetwork |
服务网段参数,包含IPv4 CIDR。 |
|
authentication |
集群认证方式相关配置。 |
|
billingMode |
Integer |
集群的计费方式。
默认为“按需计费”。 |
masters |
控制节点的高级配置 |
|
kubernetesSvcIpRange |
String |
服务网段参数,kubernetes clusterIP取值范围,1.11.7版本及以上支持。创建集群时如若未传参,默认为"10.247.0.0/16"。该参数废弃中,推荐使用新字段serviceNetwork,包含IPv4服务网段。 |
clusterTags |
集群资源标签 |
|
kubeProxyMode |
String |
服务转发模式,支持以下两种实现:
|
az |
String |
可用区(仅查询返回字段)。 |
extendParam |
集群扩展字段,可配置多可用区集群、专属CCE集群,以及将集群创建在特定的企业项目下等。 |
|
supportIstio |
Boolean |
支持Istio |
configurationsOverride |
覆盖集群默认组件配置 若指定了不支持的组件或组件不支持的参数,该配置项将被忽略。 当前支持的可配置组件及其参数详见 配置管理 |
参数 |
参数类型 |
描述 |
---|---|---|
vpc |
String |
用于创建控制节点的VPC的ID。 获取方法如下: 说明:
当前vpc-router容器网络模型不支持对接含拓展网段的VPC。 |
subnet |
String |
用于创建控制节点的subnet的网络ID。获取方法如下:
|
SecurityGroup |
String |
集群默认的Node节点安全组ID,不指定该字段系统将自动为用户创建默认Node节点安全组,指定该字段时集群将绑定指定的安全组。Node节点安全组需要放通部分端口来保证正常通信。详细设置请参考集群安全组规则配置。 |
参数 |
参数类型 |
描述 |
---|---|---|
mode |
String |
容器网络类型(只可选择其一)
|
cidr |
String |
容器网络网段,建议使用网段10.0.0.0/12~19,172.16.0.0/16~19,192.168.0.0/16~19,如存在网段冲突,将会报错。 此参数在集群创建后不可更改,请谨慎选择。(已废弃,如填写cidrs将忽略该cidr) |
cidrs |
容器网络网段列表。1.21及新版本集群使用cidrs字段,当集群网络类型为vpc-router类型时,支持多个容器网段;1.21之前版本若使用cidrs字段,则取值cidrs数组中的第一个cidr元素作为容器网络网段地址。 此参数在集群创建后不可更改,请谨慎选择。 |
参数 |
参数类型 |
描述 |
---|---|---|
cidr |
String |
容器网络网段,建议使用网段10.0.0.0/12~19,172.16.0.0/16~19,192.168.0.0/16~19。 |
参数 |
参数类型 |
描述 |
---|---|---|
eniSubnetId |
String |
ENI所在子网的IPv4子网ID(暂不支持IPv6,废弃中)。获取方法如下:
|
eniSubnetCIDR |
String |
ENI子网CIDR(废弃中) |
subnets |
IPv4子网ID列表 |
参数 |
参数类型 |
描述 |
---|---|---|
subnetID |
String |
用于创建控制节点的subnet的IPv4子网ID(暂不支持IPv6)。获取方法如下:
|
参数 |
参数类型 |
描述 |
---|---|---|
IPv4CIDR |
String |
kubernetes clusterIP IPv4 CIDR取值范围。创建集群时若未传参,默认为"10.247.0.0/16"。 |
参数 |
参数类型 |
描述 |
---|---|---|
mode |
String |
集群认证模式。
|
authenticatingProxy |
authenticatingProxy模式相关配置。认证模式为authenticating_proxy时必选。 |
参数 |
参数类型 |
描述 |
---|---|---|
ca |
String |
authenticating_proxy模式配置的x509格式CA证书(base64编码)。当集群认证模式为authenticating_proxy时,此项必须填写。 最大长度:1M |
cert |
String |
authenticating_proxy模式配置的x509格式CA证书签发的客户端证书,用于kube-apiserver到扩展apiserver的认证。(base64编码)。当集群认证模式为authenticating_proxy时,此项必须填写。 |
privateKey |
String |
authenticating_proxy模式配置的x509格式CA证书签发的客户端证书时对应的私钥,用于kube-apiserver到扩展apiserver的认证。Kubernetes集群使用的私钥尚不支持密码加密,请使用未加密的私钥。(base64编码)。当集群认证模式为authenticating_proxy时,此项必须填写。 |
参数 |
参数类型 |
描述 |
---|---|---|
key |
String |
Key值。
|
value |
String |
Value值。
|
参数 |
参数类型 |
描述 |
---|---|---|
clusterAZ |
String |
集群控制节点可用区配置。 CCE支持的可用区请参考地区和终端节点
|
dssMasterVolumes |
String |
用于指定控制节点的系统盘和数据盘使用 专属分布式存储 ,未指定或者值为空时,默认使用EVS 云硬盘 。 如果配置专属CCE集群,该字段为必选,请按照如下格式设置: <rootVol.dssPoolID>.<rootVol.volType>;<dataVol.dssPoolID>.<dataVol.volType>
字段说明:
样例:c950ee97-587c-4f24-8a74-3367e3da570f.sas;6edbc2f4-1507-44f8-ac0d-eed1d2608d38.ssd 说明:
非专属CCE集群不支持配置该字段。 |
ent erp riseProjectId |
String |
集群所属的企业项目ID。 说明:
|
kubeProxyMode |
String |
服务转发模式,支持以下两种实现:
说明:
此参数已废弃,若同时指定此参数和ClusterSpec下的kubeProxyMode,以ClusterSpec下的为准。 |
clusterExternalIP |
String |
master 弹性公网IP |
alpha.cce/fixPoolMask |
String |
容器网络固定IP池掩码位数,仅vpc-router网络支持。 该参数决定节点可分配容器IP数量,与创建节点时设置的maxPods参数共同决定节点最多可以创建多少个Pod, 具体请参见节点最多可以创建多少Pod。 整数字符传取值范围: 24 ~ 28 |
decMasterFlavor |
String |
专属CCE集群指定可控制节点的规格。 |
docker UmaskMode |
String |
集群默认Docker的UmaskMode配置,可取值为secure或normal,不指定时默认为normal。 |
kubernetes.io/cpuManagerPolicy |
String |
集群CPU管理策略。取值为none(或空值)或static,默认为none(或空值)。
|
orderID |
String |
订单ID,集群付费类型为自动付费包周期类型时,响应中会返回此字段(仅创建场景涉及)。 |
periodType |
String |
说明:
作为请求参数,billingMode为1(包周期)时生效,且为必选。 作为响应参数,仅在创建包周期集群时返回。 |
periodNum |
Integer |
订购周期数,取值范围:
说明:
作为请求参数,billingMode为1时生效,且为必选。 作为响应参数,仅在创建包周期集群时返回。 |
isAutoRenew |
String |
是否自动续订
说明:
billingMode为1时生效,不填写此参数时默认不会自动续费。 |
isAutoPay |
String |
是否自动扣款
说明:
billingMode为1时生效,不填写此参数时默认不会自动扣款。 |
upgradefrom |
String |
记录集群通过何种升级方式升级到当前版本。 |
参数 |
参数类型 |
描述 |
---|---|---|
phase |
String |
集群状态,取值如下
|
jobID |
String |
任务ID,集群当前状态关联的任务ID。当前支持:
说明:
任务信息具有一定时效性,仅用于短期跟踪任务进度,请勿用于集群状态判断等额外场景。 |
reason |
String |
集群变为当前状态的原因,在集群在非“Available”状态下时,会返回此参数。 |
message |
String |
集群变为当前状态的原因的详细信息,在集群在非“Available”状态下时,会返回此参数。 |
endpoints |
集群中 kube-apiserver 的访问地址。 |
|
isLocked |
Boolean |
CBC资源锁定 |
lockScene |
String |
CBC资源锁定场景 |
lockSource |
String |
锁定资源 |
lockSourceId |
String |
锁定的资源ID |
deleteOption |
Object |
删除配置状态(仅删除请求响应包含) |
deleteStatus |
Object |
删除状态信息(仅删除请求响应包含) |
请求示例
无
响应示例
状态码: 200
表示获取集群列表成功。
{
"kind" : "Cluster",
"apiVersion" : "v3",
"items" : [ {
"kind" : "Cluster",
"apiVersion" : "v3",
"metadata" : {
"alias" : "mycluster",
"name" : "mycluster",
"uid" : "4d1ecb2c-229a-11e8-9c75-0255ac100ceb",
"creationTimestamp" : "2018-08-02 03:48:58.968214406 +0000 UTC",
"updateTimestamp" : "2018-08-02 04:05:29.386391813 +0000 UTC"
},
"spec" : {
"type" : "VirtualMachine",
"flavor" : "cce.s1.small",
"version" : "v1.7.3-r13",
"description" : "awesome cluster",
"customSan" : [ "192.168.1.0", "example.com" ],
"hostNetwork" : {
"vpc" : "f0c12911-4fdb-4284-9230-7ffb0860826a",
"subnet" : "ac274229-fd2e-4695-9f01-a0c1372b8006"
},
"containerNetwork" : {
"mode" : "overlay_l2",
"cidr" : "172.16.0.0/16"
},
"authentication" : {
"mode" : "x509",
"authenticatingProxy" : { }
},
"billingMode" : 0
},
"status" : {
"phase" : "Available",
"endpoints" : [ {
"url" : "https://192.168.0.11:5443",
"type" : "Internal"
} ]
}
} ]
}
SDK代码示例
SDK代码示例如下。
package com.huaweicloud.sdk.test;
import com.huaweicloud.sdk.core.auth.ICredential;
import com.huaweicloud.sdk.core.auth.BasicCredentials;
import com.huaweicloud.sdk.core.exception.ConnectionException;
import com.huaweicloud.sdk.core.exception.RequestTimeoutException;
import com.huaweicloud.sdk.core.exception.ServiceResponseException;
import com.huaweicloud.sdk.cce.v3.region.CceRegion;
import com.huaweicloud.sdk.cce.v3.*;
import com.huaweicloud.sdk.cce.v3.model.*;
public class ListClustersSolution {
public static void main(String[] args) {
String ak = "<YOUR AK>";
String sk = "<YOUR SK>";
String projectId = "<project_id>";
ICredential auth = new BasicCredentials()
.withProjectId(projectId)
.withAk(ak)
.withSk(sk);
CceClient client = CceClient.newBuilder()
.withCredential(auth)
.withRegion(CceRegion.valueOf("cn-north-4"))
.build();
ListClustersRequest request = new ListClustersRequest();
try {
ListClustersResponse response = client.listClusters(request);
System.out.println(response.toString());
} catch (ConnectionException e) {
e.printStackTrace();
} catch (RequestTimeoutException e) {
e.printStackTrace();
} catch (ServiceResponseException e) {
e.printStackTrace();
System.out.println(e.getHttpStatusCode());
System.out.println(e.getRequestId());
System.out.println(e.getErrorCode());
System.out.println(e.getErrorMsg());
}
}
}
# coding: utf-8
from huaweicloudsdkcore.auth.credentials import BasicCredentials
from huaweicloudsdkcce.v3.region.cce_region import CceRegion
from huaweicloudsdkcore.exceptions import exceptions
from huaweicloudsdkcce.v3 import *
if __name__ == "__main__":
ak = "<YOUR AK>"
sk = "<YOUR SK>"
projectId = "<project_id>"
credentials = BasicCredentials(ak, sk, projectId) \
client = CceClient.new_builder() \
.with_credentials(credentials) \
.with_region(CceRegion.value_of("cn-north-4")) \
.build()
try:
request = ListClustersRequest()
response = client.list_clusters(request)
print(response)
except exceptions.ClientRequestException as e:
print(e.status_code)
print(e.request_id)
print(e.error_code)
print(e.error_msg)
package main
import (
"fmt"
"github.com/huaweicloud/huaweicloud-sdk-go-v3/core/auth/basic"
cce "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/cce/v3"
"github.com/huaweicloud/huaweicloud-sdk-go-v3/services/cce/v3/model"
region "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/cce/v3/region"
)
func main() {
ak := "<YOUR AK>"
sk := "<YOUR SK>"
projectId := "<project_id>"
auth := basic.NewCredentialsBuilder().
WithAk(ak).
WithSk(sk).
WithProjectId(projectId).
Build()
client := cce.NewCceClient(
cce.CceClientBuilder().
WithRegion(region.ValueOf("cn-north-4")).
WithCredential(auth).
Build())
request := &model.ListClustersRequest{}
response, err := client.ListClusters(request)
if err == nil {
fmt.Printf("%+v\n", response)
} else {
fmt.Println(err)
}
}
更多编程语言的SDK代码示例,请参见API Explorer的代码示例页签,可生成自动对应的SDK代码示例。
状态码
状态码 |
描述 |
---|---|
200 |
表示获取集群列表成功。 |
错误码
请参见错误码。