Todos os produtos
Search
Central de documentação

:Consultar uma lista de clusters do ACK

Última atualização: Jul 09, 2026

Chame a operação DescribeClustersV1 para consultar uma lista de clusters do Container Service for Kubernetes (ACK).

Depuração

O OpenAPI Explorer calcula automaticamente o valor da assinatura. Para sua conveniência, recomendamos que você chame esta operação no OpenAPI Explorer. O OpenAPI Explorer gera dinamicamente o código de exemplo da operação para diferentes SDKs.

Sintaxe da solicitação

GET /api/v1/clusters?name=String&cluster_type=String&page_size=Long&page_number=Long HTTP/1.1 
Content-Type:application/json

Parâmetros da solicitação

Parâmetros de consulta da solicitação

Parâmetro

Tipo

Obrigatório

Exemplo

Descrição

name String Não cluster-demo

Nome do cluster.

O nome deve ter de 1 a 63 caracteres e pode conter dígitos, letras e hifens (-). Não pode começar com um hífen (-).

cluster_type String Não Kubernetes

Tipo do cluster. Valores válidos:

  • Kubernetes: cluster dedicado do ACK.
  • ManagedKubernetes: cluster gerenciado do ACK. Inclui clusters ACK Pro, ACK Basic, ACK Serverless Pro, ACK Serverless Basic, ACK Edge Pro e ACK Edge Basic.
  • ExternalKubernetes: cluster externo registrado no ACK.
page_size Long Não 10

Número de entradas por página.

page_number Long Não 3

Número da página.

profile String Não Default

Identificador do cluster.

Valores válidos quando o parâmetro cluster_type está definido como ManagedKubernetes:

  • Default: cluster gerenciado do ACK.
  • Serverless: cluster ACK Serverless.
  • Edge: cluster ACK Edge.

Valores válidos quando o parâmetro cluster_type está definido como Ask:

ask.v2: cluster ACK Serverless.

Por padrão, este parâmetro fica vazio. Se deixado vazio, os clusters do ACK não serão filtrados por identificador.

cluster_spec String Não ack.pro.small

Edição do cluster. Disponível apenas quando o parâmetro cluster_type está definido como ManagedKubernetes. Valores válidos:

  • ack.pro.small: cluster ACK Pro.
  • ack.standard: cluster ACK Basic.

Por padrão, este parâmetro fica vazio. Se deixado vazio, os clusters do ACK não serão filtrados por edição.

region_id String Não cn-hangzhou

ID da região do cluster. Especifique este parâmetro para consultar todos os clusters do ACK em uma região.

Sintaxe da resposta

HTTP/1.1 200 OK
Content-Type:application/json

{
  "clusters" : [ {
    "cluster_id" : "String",
    "cluster_type" : "String",
    "created" : "String",
    "init_version" : "String",
    "current_version" : "String",
    "next_version" : "String",
    "deletion_protection" : Boolean,
    "docker_version" : "String",
    "external_loadbalancer_id" : "String",
    "master_url" : "String",
    "meta_data" : "String",
    "name" : "String",
    "network_mode" : "String",
    "private_zone" : Boolean,
    "profile" : "String",
    "region_id" : "String",
    "resource_group_id" : "String",
    "security_group_id" : "String",
    "size" : Long,
    "state" : "String",
    "subnet_cidr" : "String",
    "tags" : [ {
      "key" : "String",
      "value" : "String"
    } ],
    "updated" : "String",
    "vpc_id" : "String",
    "vswitch_id" : "String",
    "worker_ram_role_name" : "String",
    "zone_id" : "String",
    "cluster_spec" : "String",
    "maintenance_window" : {
      "enable" : Boolean,
      "maintenance_time" : "String",
      "duration" : "String",
      "weekly_period" : "String"
    }
  } ],
  "page_info" : {
    "page_number" : Integer,
    "page_size" : Integer,
    "total_count" : Integer
  }
}

Parâmetros da resposta

Parâmetros do corpo da resposta

Parâmetro

Tipo

Exemplo

Descrição

clusters Array

Detalhes dos clusters.

cluster_id String c3fb96524f9274b4495df0f12a6b5****

ID do cluster.

cluster_type String Kubernetes

Tipo do cluster. Valores válidos:

  • Kubernetes: cluster dedicado do ACK.
  • ManagedKubernetes: cluster gerenciado do ACK.
  • Ask: cluster ACK Serverless.
  • ExternalKubernetes: cluster registrado.
created String 2020-08-20T10:51:29+08:00

Horário de criação do cluster.

init_version String 1.16.9-aliyun.1

Versão do Kubernetes do cluster. As versões suportadas pelo ACK correspondem às do Kubernetes open source. Recomendamos especificar a versão mais recente. Caso não especifique este parâmetro, o sistema usará a versão mais recente do Kubernetes.

É possível criar clusters das duas versões mais recentes do Kubernetes no console do ACK. Para criar clusters de outras versões, chame a operação de API correspondente do ACK. Para obter mais informações sobre as versões suportadas, consulte Notas de lançamento das versões do Kubernetes.

current_version String 1.16.9-aliyun.1

Versão atual do Kubernetes do cluster.

next_version String 1.18.8-aliyun.1

Versão do Kubernetes para a qual o cluster pode ser atualizado.

deletion_protection Boolean true

Indica se a proteção contra exclusão está ativada para o cluster. Com a proteção ativada, não é possível excluir o cluster pelo console do ACK ou por chamadas de API. Valores válidos:

  • true: proteção contra exclusão ativada. O cluster não pode ser excluído pelo console do ACK ou por chamadas de API.
  • false: proteção contra exclusão desativada. O cluster pode ser excluído pelo console do ACK ou por chamadas de API.
docker_version String 19.03.5

Versão do docker utilizada pelo cluster.

external_loadbalancer_id String lb-2vcrbmlevo6kjpgch****

ID da instância do Server Load Balancer (SLB) utilizada pelo Ingress do cluster.

A especificação padrão do SLB é slb.s1.small, pertencente ao tipo de instância de alto desempenho.

master_url String {\"api_server_endpoint\":\"\",\"intranet_api_server_endpoint\":\"https://192.168.0.251:6443\"}

Endereço do servidor de api do cluster. Inclui um endpoint interno e um endpoint público.

meta_data String {\"Addons\":[{\"config\":***}

Metadados do cluster.

name String cluster-demo

Nome do cluster.

O nome deve ter de 1 a 63 caracteres e pode conter dígitos, letras e hifens (-). Não pode começar com um hífen (-).

network_mode String vpc

Modo de rede do cluster. Valores válidos:

  • classic: rede clássica.
  • vpc: Virtual Private Cloud (vpc).
  • overlay: rede overlay.
  • calico: rede fornecida pelo Calico.
private_zone Boolean false

Indica se o Alibaba Cloud DNS PrivateZone está ativado. Valores válidos:

  • true: Alibaba Cloud DNS PrivateZone ativado.
  • false: Alibaba Cloud DNS PrivateZone desativado.
profile String Default

Identificador do cluster. Valores válidos:

  • Edge: cluster ACK Edge.
  • Default: cluster não ACK Edge.
region_id String cn-beijing

ID da região do cluster.

resource_group_id String rg-acfmyvw3wjm****

ID do grupo de recursos ao qual o cluster pertence.

security_group_id String sg-2vcgwsrwgt5mp0yi****

ID do grupo de segurança ao qual as instâncias do cluster pertencem.

size Long 5

Número de nós no cluster. Inclui nós mestre e de trabalho.

state String running

Status do cluster. Valores válidos:

  • initial: criação em andamento.
  • failed: falha na criação.
  • running: em execução.
  • updating: atualização em andamento.
  • updating_failed: falha na atualização.
  • scaling: dimensionamento em andamento.
  • stopped: parado.
  • deleting: exclusão em andamento.
  • deleted: excluído.
  • delete_failed: falha na exclusão.
subnet_cidr String 172.21.0.0/16

Bloco CIDR dos pods. Deve ser um bloco CIDR privado e válido, correspondente a um dos seguintes blocos ou suas sub-redes:

  • 10.0.0.0/8
  • 172.16-31.0.0/12-16
  • 192.168.0.0/16

O bloco CIDR dos pods não pode se sobrepor ao bloco CIDR da vpc onde o cluster está implantado nem aos blocos CIDR de clusters existentes nessa vpc. Não é possível modificar o bloco CIDR dos pods após a criação do cluster.

Para obter mais informações, consulte Planejar blocos CIDR para um cluster do ACK.

tags Array de tag

Tags de recurso do cluster.

updated String 2020-09-16T11:09:55+08:00

Horário da última atualização do cluster.

vpc_id String vpc-2vcg932hsxsxuqbgl****

ID da vpc onde o cluster está implantado. Parâmetro obrigatório na criação do cluster.

vswitch_id String vsw-2vc41xuumx5z2rdma****,vsw-2vc41xuumx5z2rdma****

IDs dos vSwitches. Selecione de um a três vSwitches ao criar um cluster. Recomendamos selecionar vSwitches em zonas diferentes para garantir alta disponibilidade.

worker_ram_role_name String KubernetesWorkerRole-ec87d15b-edca-4302-933f-c8a16bf0****

Nome da função do Resource Access Management (RAM) de trabalho. Atribuída aos nós de trabalho criados em instâncias do Elastic Compute Service (ECS).

zone_id String cn-beijing-b

ID da zona do cluster.

cluster_spec String ack.standard

Edição do cluster. Disponível apenas para clusters gerenciados do ACK. Valores válidos:

  • ack.pro.small: cluster ACK Pro.
  • ack.standard: cluster ACK Basic.
maintenance_window maintenance_window

Janela de manutenção do cluster. Recurso disponível apenas em clusters ACK Pro.

page_info Object

Informações de paginação.

page_number Integer 3

Número da página.

page_size Integer 20

Número de entradas por página.

total_count Integer 50

Número total de entradas retornadas.

Exemplos

Exemplos de solicitações

GET /api/v1/clusters?name=cluster-demo&cluster_type=Kubernetes&page_size=10&page_number=3&profile=Default&cluster_spec=ack.pro.small&region_id=cn-hangzhou HTTP/1.1
Host:cs.aliyuncs.com
Content-Type:application/json

Exemplos de respostas de sucesso

Formato XML

HTTP/1.1 200 OK
Content-Type:application/xml

<DescribeClustersV1Response>
    <clusters>
        <cluster_id>c3fb96524f9274b4495df0f12a6b5****</cluster_id>
        <cluster_type>Kubernetes</cluster_type>
        <created>2020-08-20T10:51:29+08:00</created>
        <init_version>1.16.9-aliyun.1</init_version>
        <current_version>1.16.9-aliyun.1</current_version>
        <next_version>1.18.8-aliyun.1</next_version>
        <deletion_protection>true</deletion_protection>
        <docker_version>19.03.5</docker_version>
        <external_loadbalancer_id>lb-2vcrbmlevo6kjpgch****</external_loadbalancer_id>
        <master_url>{\"api_server_endpoint\":\"\",\"intranet_api_server_endpoint\":\"https://192.168.0.251:6443\"}</master_url>
        <meta_data>{\"Addons\":[{\"config\":***}</meta_data>
        <name>cluster-demo</name>
        <network_mode>vpc</network_mode>
        <private_zone>false</private_zone>
        <profile>Default</profile>
        <region_id>cn-beijing</region_id>
        <resource_group_id>rg-acfmyvw3wjm****</resource_group_id>
        <security_group_id>sg-2vcgwsrwgt5mp0yi****</security_group_id>
        <size>5</size>
        <state>running</state>
        <subnet_cidr>172.21.0.0/16</subnet_cidr>
        <tags>
            <key>env</key>
            <value>prod</value>
        </tags>
        <updated>2020-09-16T11:09:55+08:00</updated>
        <vpc_id>vpc-2vcg932hsxsxuqbgl****</vpc_id>
        <vswitch_id>vsw-2vc41xuumx5z2rdma****,vsw-2vc41xuumx5z2rdma****</vswitch_id>
        <worker_ram_role_name>KubernetesWorkerRole-ec87d15b-edca-4302-933f-c8a16bf0****</worker_ram_role_name>
        <zone_id>cn-beijing-b</zone_id>
        <cluster_spec>ack.standard</cluster_spec>
        <maintenance_window>
            <enable>false</enable>
            <maintenance_time>03:00:00Z</maintenance_time>
            <duration>3h</duration>
            <weekly_period>Monday,Thursday</weekly_period>
        </maintenance_window>
    </clusters>
    <page_info>
        <page_number>3</page_number>
        <page_size>20</page_size>
        <total_count>50</total_count>
    </page_info>
</DescribeClustersV1Response>

Formato JSON

HTTP/1.1 200 OK
Content-Type:application/json

{
  "clusters" : [ {
    "cluster_id" : "c3fb96524f9274b4495df0f12a6b5****",
    "cluster_type" : "Kubernetes",
    "created" : "2020-08-20T10:51:29+08:00",
    "init_version" : "1.16.9-aliyun.1",
    "current_version" : "1.16.9-aliyun.1",
    "next_version" : "1.18.8-aliyun.1",
    "deletion_protection" : true,
    "docker_version" : "19.03.5",
    "external_loadbalancer_id" : "lb-2vcrbmlevo6kjpgch****",
    "master_url" : "{\\\"api_server_endpoint\\\":\\\"\\\",\\\"intranet_api_server_endpoint\\\":\\\"https://192.168.0.251:6443\\\"}",
    "meta_data" : "{\\\"Addons\\\":[{\\\"config\\\":***}",
    "name" : "cluster-demo",
    "network_mode" : "vpc",
    "private_zone" : false,
    "profile" : "Default",
    "region_id" : "cn-beijing",
    "resource_group_id" : "rg-acfmyvw3wjm****",
    "security_group_id" : "sg-2vcgwsrwgt5mp0yi****",
    "size" : 5,
    "state" : "running",
    "subnet_cidr" : "172.21.0.0/16",
    "tags" : [ {
      "key" : "env",
      "value" : "prod"
    } ],
    "updated" : "2020-09-16T11:09:55+08:00",
    "vpc_id" : "vpc-2vcg932hsxsxuqbgl****",
    "vswitch_id" : "vsw-2vc41xuumx5z2rdma****,vsw-2vc41xuumx5z2rdma****",
    "worker_ram_role_name" : "KubernetesWorkerRole-ec87d15b-edca-4302-933f-c8a16bf0****",
    "zone_id" : "cn-beijing-b",
    "cluster_spec" : "ack.standard",
    "maintenance_window" : {
      "enable" : false,
      "maintenance_time" : "03:00:00Z",
      "duration" : "3h",
      "weekly_period" : "Monday,Thursday"
    }
  } ],
  "page_info" : {
    "page_number" : 3,
    "page_size" : 20,
    "total_count" : 50
  }
}

Códigos de erro

Para obter uma lista de códigos de erro, consulte Códigos de erro do serviço.