ListClusters--容器服务-火山引擎

文档中心

立即注册

导航

ListClusters

最近更新时间：2024.09.29 18:50:56首次发布时间：2022.06.27 21:21:34

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

请求说明

请求方式：POST
请求地址：https://open.volcengineapi.com/?Action=ListClusters&Version=2022-05-12

调试

API Explorer

您可以通过 API Explorer 在线发起调用，无需关注签名生成过程，快速获取调用结果。

去调试

请求参数

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

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

ListClustersFilter

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

ClusterStatusFilter

参数	类型	是否必选	示例值	描述
Phase	String	否	Creating	集群的状态，取值： Creating Running Updating Deleting Stopped Failed 注意 Phase 和 Conditions.Type 两者至少有一个参数必填，否则为无效数组元素。合法的 Phase 和 Conditions.Type 组合，请参见资源状态说明。
Conditions.Type	String	否	Ok	集群当前主状态下的状态条件，即进入该主状态的原因，可以有多个原因，取值： Progressing Ok Balance CreateError ResourceCleanupFailed Unknown 注意 Phase 和 Conditions.Type 两者至少有一个参数必填，否则为无效数组元素。合法的 Phase 和 Conditions.Type 组合，请参见资源状态说明。

参数

类型

是否必选

示例值

描述

Phase

String

否

Creating

集群的状态，取值：

Creating
Running
Updating
Deleting
Stopped
Failed

注意

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

Conditions.Type

String

否

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

Progressing
Ok
Balance
CreateError
ResourceCleanupFailed
Unknown

注意

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

ListTagFilter

参数类型是否必选示例值描述

参数	类型	是否必选	示例值	描述
Key	String	是	key	标签键。不能以任何大小写形式的`volc:`开头。只能包含语言字符、数字、空格和特殊符号`_.:/=+-@`。长度限制为 1～128 个字符。
Value	String	否	value	标签值，可以为空。只能包含语言字符、数字、空格和特殊符号`_.:/=+-@`。长度不超过 256 个字符。

Key

String

是

key

标签键。

不能以任何大小写形式的volc:开头。
只能包含语言字符、数字、空格和特殊符号_.:/=+-@。
长度限制为 1～128 个字符。

Value

String

否

value

标签值，可以为空。

只能包含语言字符、数字、空格和特殊符号_.:/=+-@。
长度不超过 256 个字符。

请求示例

POST https://open.volcengineapi.com/?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 ClusterResponse	-	集群的详细信息列表。
PageNumber	Integer	1	当前页码。
PageSize	Integer	10	每页显示的集群数。
TotalCount	Integer	100	符合条件的集群总数。

ClusterResponse

参数	类型	示例值	描述
Id	String	cc9q8pbfq********	集群 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	TestCluster	集群名称。
Description	String	A Kubernetes Cluster Managed by VKE	集群描述信息。
Status	Object of ClusterStatus	-	集群状态。
DeleteProtectionEnabled	Boolean	false	集群删除保护，参数值说明： true：已开启删除保护。 false：已关闭删除保护。
ClusterConfig	Object of ClusterConfigResponse	-	集群控制面及部分节点的网络配置。
PodsConfig	Object of PodsConfigResponse	-	Pod 的网络配置。
ServicesConfig	Object of ServicesConfigResponse	-	服务的网络配置。
NodeStatistics	Object of NodeStatistics	-	集群中各主状态下对应的节点数量统计。
Tags	Array of TagResponse	-	集群绑定的标签信息。
LoggingConfig	Object of ClusterLoggingConfigResponse	-	集群的日志配置信息。

ClusterStatus

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

参数

类型

示例值

描述

Phase

String

Creating

集群的状态。参数值有：

Creating
Running
Updating
Deleting
Stopped
Failed

说明

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

Conditions

Array of ClusterStatusCondition

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

ClusterStatusCondition

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

PublicAccessConfigResponse

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

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（多线）。

ClusterApiServerEndpointsResponse

参数	类型	示例值	描述
PublicIp	Object of Endpoint	-	集群 API Server 私网的 Endpoint 地址。
PrivateIp	Object of Endpoint	-	集群 API Server 公网的 Endpoint 地址。

Endpoint

参数	类型	示例值	描述
Ipv4	String	10.249.151......	Endpoint 的 IPv4 地址。

PodsConfigResponse

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

参数

类型

示例值

描述

PodNetworkMode

String

Flannel

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

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

FlannelConfig

Object of FlannelConfigResponse

Flannel 网络配置。

VpcCniConfig

Object of VpcCniConfigResponse

VPC-CNI 网络配置。

FlannelConfigResponse

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

VpcCniConfigResponse

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

ServicesConfigResponse

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

NodeStatistics

参数	类型	示例值	描述
TotalCount	Integer	8	节点总数量。
CreatingCount	Integer	1	`Phase=Creating`的节点总数量。
RunningCount	Integer	1	`Phase=Running`的节点总数量。
UpdatingCount	Integer	1	`Phase=Updating`的节点总数量。
DeletingCount	Integer	1	`Phase=Deleting`的节点总数量。
FailedCount	Integer	1	`Phase=Failed`的节点总数量。

TagResponse

参数	类型	示例值	描述
Key	String	key	标签键。
Value	String	value	标签值。
Type	String	Custom	标签类型，参数值说明： System：系统标签。 Custom：用户自定义标签。

参数

类型

示例值

描述

Key

String

key

标签键。

Value

String

value

标签值。

Type

String

Custom

标签类型，参数值说明：

System： 系统标签。
Custom：用户自定义标签。

ClusterLoggingConfigResponse

参数	类型	示例值	描述
LogSetups	Array of LogSetupResponse	-	集群的日志选项信息。
LogProjectId	String	d94b4eb4-4931-86e7-2660********	集群的日志项目（Log Project）ID。如果为空，表示集群的日志项目未被创建。

LogSetupResponse

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

返回示例

Flannel 集群返回示例

HTTP/1.1 200 OK
Content-Type:application/json
{                                     
    "ResponseMetadata": {
        "RequestId": "20220515********",
        "Action": "ListClusters",
        "Version": "2022-05-12",
        "Service": "vke",
        "Region": "cn-beijing"
    },
    "Result": {
        "TotalCount": 1,
        "PageNumber": 1,
        "PageSize": 10,
        "Items": [
            {
                "Id": "cc9q8pbfqt********",
                "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-2d73mgmzui********",
                    "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
                        }
                    ]
                }
            }
        ]
    }
}

VPC-CNI 集群返回示例

HTTP/1.1 200 OK
Content-Type:application/json
{ 
    "ResponseMetadata": {
        "RequestId": "20220515********",
        "Action": "ListClusters",
        "Version": "2022-05-12",
        "Service": "vke",
        "Region": "cn-beijing"
    },
    "Result": {
        "TotalCount": 1,
        "PageNumber": 1,
        "PageSize": 10,
        "Items": [
            {
                "Id": "ccegio57qt********",
                "KubernetesVersion": "v1.20.15-vke.2",
                "Name": "vpc-cni-test",
                "Description": "",
                "Status": {
                    "Phase": "Running",
                    "Conditions": [
                        {
                            "Type": "Ok"
                        }
                    ]
                },
                "DeleteProtectionEnabled": false,
                "ClusterConfig": {
                    "VpcId": "vpc-2bztfypmh1********",
                    "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
                        }
                    ]
                }
            }
        ]
    }
}

错误码

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