文档中心

ListClusters

最近更新时间：2024.02.26 20:17:36

首次发布时间：2022.06.27 21:21:34

查询符合条件的集群详情列表。

请求参数

调用该 API 时的请求参数如下，除此之外还需传入公共请求参数。公共请求参数说明，请参见公共参数。

参数名称	类型	是否必选	示例值	描述
Action	String	是	ListClusters	公共参数，本接口值：ListClusters。
Version	String	是	2022-05-12	公共参数，本接口值：2022-05-12。
Filter	Object ClusterFilterRequest	否		待查询集群的筛选条件。
Tags	Array of Tag	否		基于标签查询集群列表。 Tags 中各个 Key 不可重复。 Tags 中的 Key、Value 不允许在最前或最后输入空格。单次最多支持 10 个标签。
PageNumber	Integer	否	1	分页查询时的起始页码，从 1 开始，默认为 1。
PageSize	Integer	否	10	分页查询时每页显示的记录数，取值：最小值：1 最大值：100 默认值：10

ClusterFilterRequest

参数	参数类型	是否必选	示例值	说明
Ids	Array of String	否	["cc9q8pbfqtofn8j******"]	集群 ID 列表。单次最多填写 100 个 ID。说明此参数为空数组时，筛选您本账号下公共参数中指定地域的所有集群。
Name	String	否	test	集群名称。
DeleteProtectionEnabled	Boolean	否	false	集群删除保护，取值： true：开启 false：关闭
PodsConfig.PodNetworkMode	String	否	Flannel	容器（Pod）网络模型（CNI），取值： Flannel：Flannel 网络模型，独立的 Underlay 容器网络方案，配合 VPC 的全局路由能力，实现集群高性能的网络体验。 VpcCniShared：VPC-CNI 网络模型，基于私有网络的弹性网卡 ENI 实现的 Underlay 容器网络方案，具有较高的网络通信性能。
Statuses	Array of Object ClusterStatusFilterRequest	否		需要筛选的集群状态数组。数组各个元素间是逻辑「或」关系。单次最多填写 15 个状态数组元素。
CreateClientToken	String	否	BB928624-11C0-4856-A233-84F9F9******	创建集群成功时的 ClientToken。 ClientToken 是保证请求幂等性的字符串。该字符串由调用方传入。
UpdateClientToken	String	否	BC028527-33B9-4990-A633-84E9F9******	最后一次更新集群成功时的 ClientToken。 ClientToken 是保证请求幂等性的字符串。该字符串由调用方传入。

ClusterStatusFilterRequest

注意

Phase 和 Conditions.Type 两者至少有一个参数必填，否则为无效数组元素。合法的 Phase 和 Conditions.Type 组合，请参见资源状态说明。

参数名	参数类型	是否必选	示例值	说明
Phase	String	否	Running	集群的状态，取值： Creating Running Updating Deleting Stopped Failed
Conditions.Type	String	否	Ok	集群当前主状态下的状态条件，即进入该主状态的原因，可以有多个原因，取值： Progressing Ok Balance CreateError ResourceCleanupFailed Unknown

参数名

参数类型

是否必选

示例值

说明

Phase

String

否

Running

集群的状态，取值：

Creating
Running
Updating
Deleting
Stopped
Failed

Conditions.Type

String

否

集群当前主状态下的状态条件，即进入该主状态的原因，可以有多个原因，取值：

Progressing
Ok
Balance
CreateError
ResourceCleanupFailed
Unknown

请求示例

POST /?Action=ListClusters&Version=2022-05-12 HTTP/1.1
Content-Type:application/json
{
    "PageNumber": 1,
    "PageSize": 10,
    "Filter": {
        "Name": "test",
        "Ids": ["cc9q8pbfqtofn8j******"],
        "DeleteProtectionEnabled": true,
        "Statuses": [{"Phase": "Running"}]
    },
    "Tags":[
        {
            "Key":"key",
            "Value":"value"
        }
    ]
}

返回参数

本接口返回参数如下表所示，公共返回参数请参见返回结果。

参数名称	类型	示例值	描述
Items	Array of Object ClusterResponse		集群的详细信息列表。
PageNumber	Integer	1	当前页码。
PageSize	Integer	10	每页显示的集群数。
TotalCount	Integer	100	返回数据列表的总量。

ClusterResponse

参数名	参数类型	示例值	说明
Id	String	cc5silumrsfeq****	集群 ID。
CreateClientToken	String	BC028527-33B9-4990-A633-84E9F9******	创建成功时的 ClientToken。 ClientToken 是保证请求幂等性的字符串。该字符串由调用方传入。
UpdateClientToken	String	BC028527-33B9-4990-A633-84E9F9******	最后一次更新成功时 ClientToken。 ClientToken 是保证请求幂等性的字符串。该字符串由调用方传入。
CreateTime	String	2022-05-06T02:49:19Z	集群创建时间。标准 RFC3339 格式的 UTC+0 时间。
UpdateTime	String	2022-05-15T03:13:20Z	集群最近一次更新的时间。标准 RFC3339 格式的 UTC+0 时间。
KubernetesVersion	String	v1.20.10-vke.2	集群对应的 Kubernetes 版本信息。
Name	String	test-cluster	集群名称。
Description	String	this is test cluster	集群描述信息。
Status	Object ClusterStatusRespons		集群状态。
DeleteProtectionEnabled	Boolean	false	集群删除保护，参数值说明： true：已开启删除保护。 false：已关闭删除保护。
ClusterConfig	Object ClusterConfigResponse		集群控制面及部分节点的网络配置。
PodsConfig	Object PodsConfigResponse		Pod 的网络配置。
ServicesConfig	Object ServicesConfigResponse		服务的网络配置。
NodeStatistics	Object NodeStatisticsResponse		集群中各主状态下对应的节点数量统计。
Tags	Array of TagResponse		集群绑定的标签信息。
LoggingConfig	Object ClusterLoggingConfigResponse		集群的日志配置信息。

ClusterStatusResponse

参数名	参数类型	示例值	说明
Phase	String	Running	集群的状态。参数值有： Creating Running Updating Deleting Stopped Failed 说明合法的 Phase 和 Conditions.Type 组合请参见资源状态说明。
Conditions	Array of Object ClusterStatusConditionResponse		集群当前主状态下的状态条件，即进入该主状态的原因。

参数名

参数类型

示例值

说明

Phase

String

Running

集群的状态。参数值有：

Creating
Running
Updating
Deleting
Stopped
Failed

说明

合法的 Phase 和 Conditions.Type 组合请参见资源状态说明。

Conditions

Array of Object ClusterStatusConditionResponse

集群当前主状态下的状态条件，即进入该主状态的原因。

ClusterStatusConditionResponse

参数名	参数类型	示例值	说明
Type	String	Ok	集群当前主状态下的状态条件，即进入该主状态的原因，可以有多个原因，参数值有： Progressing Ok Balance CreateError ResourceCleanupFailed Unknown 说明合法的 Phase 和 Conditions.Type 组合请参见资源状态说明。

参数名

参数类型

示例值

说明

Type

String

集群当前主状态下的状态条件，即进入该主状态的原因，可以有多个原因，参数值有：

Progressing
Ok
Balance
CreateError
ResourceCleanupFailed
Unknown

说明

合法的 Phase 和 Conditions.Type 组合请参见资源状态说明。

ClusterConfigResponse

参数名	参数类型	示例值	说明
VpcId	String	vpc-2d73mgmzuivb458ozfd*****	集群控制面及部分节点的网络所在的私有网络（VPC）ID。
SubnetIds	Array of String	["subnet-2d73mhao7vj0g58ozfe53****"]	集群控制面在私有网络内通信的子网 ID。
SecurityGroupIds	Array of String	["sg-3re8ffwjclybk5zsk2hrp****"]	集群控制面及节点使用的的安全组。
ApiServerPublicAccessEnabled	Boolean	false	集群 API Server 公网访问配置，参数值说明： false：未开启 true：已开启
ApiServerPublicAccessConfig	Object PublicAccessConfigResponse		集群 API Server 公网访问配置信息。 `ApiServerPublicAccessEnable=true`时才返回的参数。
ResourcePublicAccessDefaultEnabled	Boolean	false	节点公网访问配置，参数值说明： false：未开启 true：已开启
ApiServerEndpoints	Object ClusterApiServerEndpointsResponse		集群 API Server 访问的 Endpoint 信息。

PublicAccessConfigResponse

参数名	参数类型	示例值	说明
PublicAccessNetworkConfig	Object EIPConfigResponse		公网访问网络配置。 `ApiServerPublicAccessEnable=true`时才返回的参数。
AccessSourceIpsv4	Array of String		IPv4 的公网访问白名单。空值代表放通所有网络段（`0.0.0.0/0`）。

PodsConfigResponse

参数名	参数类型	示例值	说明
PodNetworkMode	String	Flannel	容器（Pod）网络模型（CNI），参数值说明： Flannel：Flannel 网络模型，独立的 Underlay 容器网络模型。 VpcCniShared：VPC-CNI 网络模型，基于私有网络的弹性网卡 ENI 实现的 Underlay 容器网络模型。
FlannelConfig	Object FlannelConfigResponse		Flannel 网络配置。
VpcCniConfig	Object VpcCniConfigResponse		VPC-CNI 网络配置。

参数名

参数类型

示例值

说明

PodNetworkMode

String

Flannel

容器（Pod）网络模型（CNI），参数值说明：

Flannel：Flannel 网络模型，独立的 Underlay 容器网络模型。
VpcCniShared：VPC-CNI 网络模型，基于私有网络的弹性网卡 ENI 实现的 Underlay 容器网络模型。

FlannelConfig

Object FlannelConfigResponse

Flannel 网络配置。

VpcCniConfig

Object VpcCniConfigResponse

VPC-CNI 网络配置。

VpcCniConfigResponse

参数名	参数类型	示例值	说明
SubnetIds	Array of String	["subnet-3rfdvud78a7ls5zsk2ioe**","subnet-2byujbut86txc2dx0eeao**"]	VPC-CNI 容器网络模型对应的 Pod 子网 ID 列表。

FlannelConfigResponse

参数名	参数类型	示例值	说明
PodCidrs	Array of String	["172.18../20"]	Flannel 容器网络的 Pod CIDR。
MaxPodsPerNode	Integer	64	Flannel 容器网络的单节点 Pod 实例数量上限。

ClusterApiServerEndpointsResponse

参数名	参数类型	示例值	说明
PrivateIp	Object Endpoint		集群 API Server 私网的 Endpoint 地址。
PublicIp	Object Endpoint		集群 API Server 公网的 Endpoint 地址。

Endpoint

参数名	参数类型	示例值	说明
Ipv4	String	10.249..	Endpoint 的 IPv4 地址。

ServicesConfigResponse

参数名	参数类型	示例值	说明
ServiceCidrsv4	Array of String	["172.23../20"]	Kubernetes 服务（Service）暴露的 IPv4 私有网络地址。

EipConfigResponse

参数名	参数类型	示例值	说明
BillingType	Integer	3	公网 IP 的计费类型： 2：按量计费-按带宽上限 3：按量计费-按实际流量
Bandwidth	Integer	1	公网 IP 的带宽峰值，单位：Mbps。
Isp	String	BGP	公网 IP 的线路类型，参数值说明： BGP：BGP（多线）。

参数名

参数类型

示例值

说明

BillingType

Integer

公网 IP 的计费类型：

2：按量计费-按带宽上限
3：按量计费-按实际流量

Bandwidth

Integer

公网 IP 的带宽峰值，单位：Mbps。

Isp

String

BGP

公网 IP 的线路类型，参数值说明：
BGP：BGP（多线）。

ClusterLoggingConfigResponse

参数名	参数类型	示例值	说明
LogSetups	Array of	LogSetupResponse	集群的日志选项信息。
LogProjectId	String	b68324a0-2680-48c7-a42e-8d78********	集群的日志项目（Log Project）ID。如果为空，表示集群的日志项目未被创建。

LogSetupResponse

参数名	参数类型	示例值	说明
LogType	String	Audit	当前开启的日志类型，参数值说明： Audit：集群审计日志 KubeApiServer：kube-apiserver 组件日志 KubeScheduler：kube-scheduler 组件日志 KubeControllerManager：kube-controller-manager 组件日志
LogTtl	Integer	30	日志在日志服务中的保存时间，单位为天。 3650 天表示永久存储。
LogTopicId	String	d94b4eb4-1108-4931-86e7-2660********	采集目标的TLS日志主题ID。如果为空，表示对应日志的主题未被创建。
Enabled	Boolean	false	是否开启该日志选项，参数值说明： true：已开启 false：未开启

返回示例

Flannel 集群返回示例

HTTP/1.1 200 OK
Content-Type:application/json
{                                     
    "ResponseMetadata": {
        "RequestId": "2022051511134201****",
        "Action": "ListClusters",
        "Version": "2022-05-12",
        "Service": "vke",
        "Region": "cn-beijing"
    },
    "Result": {
        "TotalCount": 1,
        "PageNumber": 1,
        "PageSize": 10,
        "Items": [
            {
                "Id": "cc9q8pbfqtofn8jck****",
                "ClientToken": "",
                "CreateTime": "2022-05-06T02:49:19Z",
                "UpdateTime": "2022-05-15T03:13:20Z",
                "KubernetesVersion": "v1.20.15-vke.2",
                "Name": "test",
                "Description": "",
                "Status": {
                    "Phase": "Running",
                    "Conditions": [
                        {
                            "Type": "Ok"
                        }
                    ]
                },
                "DeleteProtectionEnabled": true,
                "ClusterConfig": {
                    "VpcId": "vpc-2d73mgmzuivb458ozfd*****",
                    "SubnetIds": [
                        "subnet-2d73mhao7vj0g58ozfe53****"
                    ],
                    "SecurityGroupIds": [
                        "sg-3re8ffwjclybk5zsk2hrp****"
                    ],
                    "ApiServerPublicAccessEnabled": true,
                    "ApiServerPublicAccessConfig": {
                        "PublicAccessNetworkConfig": {
                            "BillingType": 2,
                            "Bandwidth": 1,
                            "Isp": "BGP"
                        }
                    },
                    "ResourcePublicAccessDefaultEnabled": false,
                    "ApiServerEndpoints": {
                        "PrivateIp": {
                            "Ipv4": "192.168.**.**"
                        },
                        "PublicIp": {
                            "Ipv4": "10.249.**.**"
                        }
                    }
                },
                "PodsConfig": {
                    "PodNetworkMode": "Flannel",
                    "FlannelConfig": {
                        "PodCidrs": [
                            "172.18.**.**/20"
                        ],
                        "MaxPodsPerNode": 64
                    }
                },
                "ServicesConfig": {
                    "ServiceCidrsv4": [
                        "172.23.**.**/21"
                    ]
                },
                "NodeStatistics": {
                    "TotalCount": 3,
                    "CreatingCount": 0,
                    "RunningCount": 3,
                    "UpdatingCount": 0,
                    "DeletingCount": 0,
                    "FailedCount": 0
                },
                "ChargeType": "PostPaid",
                "Tags":[
                    {
                        "Key":"key",
                        "Value":"value",
                        "Type":"Custom"
                    }
                ],
                "LoggingConfig": {
                    "LogProjectId": "b68324a0-2680-48c7-a42e-8d78********",
                    "LogSetups": [
                        {
                            "LogType": "Audit",
                            "LogTopicId": "d94b4eb4-1108-4931-86e7-2660********",
                            "LogTtl": 30,
                            "Enabled": true
                        }
                    ]
                }
            }
        ]
    }
}

VpcCni 集群返回示例

HTTP/1.1 200 OK
Content-Type:application/json
{ 
    "ResponseMetadata": {
        "RequestId": "2022051511134201****",
        "Action": "ListClusters",
        "Version": "2022-05-12",
        "Service": "vke",
        "Region": "cn-beijing"
    },
    "Result": {
        "TotalCount": 1,
        "PageNumber": 1,
        "PageSize": 10,
        "Items": [
            {
                "Id": "ccegio57qtofqgq******",
                "KubernetesVersion": "v1.20.15-vke.2",
                "Name": "vpc-cni-test",
                "Description": "",
                "Status": {
                    "Phase": "Running",
                    "Conditions": [
                        {
                            "Type": "Ok"
                        }
                    ]
                },
                "DeleteProtectionEnabled": false,
                "ClusterConfig": {
                    "VpcId": "vpc-2bztfypmh1r0g2dx0ee******",
                    "SubnetIds": [
                        "subnet-2d74kxplgqcxs58ozfe******"
                    ],
                    "SecurityGroupIds": [
                        "sg-3re9w9akla48w5zsk2i******"
                    ],
                    "ApiServerPublicAccessEnabled": true,
                    "ApiServerPublicAccessConfig": {
                        "PublicAccessNetworkConfig": {
                            "BillingType": 3,
                            "Bandwidth": 10,
                            "Isp": "ChinaMobile"
                        }
                    },
                    "ResourcePublicAccessDefaultEnabled": false,
                    "ApiServerEndpoints": {
                        "PrivateIp": {
                            "Ipv4": "192.168.**.**"
                        },
                        "PublicIp": {
                            "Ipv4": "10.249.**.**"
                        }
                    }
                },
                "PodsConfig": {
                    "PodNetworkMode": "VpcCniShared",
                    "VpcCniConfig": {
                        "SubnetIds": [
                            "subnet-2d74kxplgqcxs58ozfe******"
                        ]
                    }
                },
                "ServicesConfig": {
                    "ServiceCidrsv4": [
                        "172.26.**.**/21"
                    ]
                },
                "NodeStatistics": {
                    "TotalCount": 2,
                    "CreatingCount": 0,
                    "RunningCount": 0,
                    "UpdatingCount": 0,
                    "DeletingCount": 0,
                    "FailedCount": 2
                },
                "ChargeType": "PostPaid",
                "CreateTime": "2022-12-20T03:29:24Z",
                "UpdateTime": "2022-12-20T03:37:43Z",
                "CreateClientToken": "1852d931f34-460249325618****",
                "UpdateClientToken": "",
                "Tags": [],
                "LoggingConfig": {
                    "LogProjectId": "b68324a0-2680-48c7-a42e-8d78********",
                    "LogSetups": [
                        {
                            "LogType": "Audit",
                            "LogTopicId": "d94b4eb4-1108-4931-86e7-2660********",
                            "LogTtl": 30,
                            "Enabled": true
                        }
                    ]
                }
            }
        ]
    }
}

错误码

本接口无专有错误码，公共错误码请参见公共错误码。

容器服务

ListClusters

请求参数

ClusterFilterRequest

ClusterStatusFilterRequest

请求示例

返回参数

ClusterResponse

ClusterStatusResponse

ClusterStatusConditionResponse

ClusterConfigResponse

PublicAccessConfigResponse

PodsConfigResponse

VpcCniConfigResponse

FlannelConfigResponse

ClusterApiServerEndpointsResponse

Endpoint

ServicesConfigResponse

EipConfigResponse

ClusterLoggingConfigResponse

LogSetupResponse

返回示例

错误码