DescribeClustersV1 - Container Service for Kubernetes: Central de Documentação do Alibaba Cloud

Consulta uma lista de clusters ACK que atendem a condições especificadas, como tipo de cluster e especificação do cluster, na conta atual.

Experimente agora

Experimente esta API no OpenAPI Explorer, sem necessidade de assinatura manual. Chamadas bem-sucedidas geram automaticamente código SDK correspondente aos seus parâmetros. Faça o download com segurança de credenciais integrada para uso local.

Testar

Autorização RAM

A tabela abaixo descreve a autorização necessária para chamar esta API. Você pode defini-la em uma política do Resource Access Management (RAM). As colunas da tabela estão detalhadas abaixo:

Ação: As ações que podem ser usadas no elemento Action das instruções de política de permissão do RAM para conceder permissões para executar a operação.
API: A API que você pode chamar para executar a ação.
Nível de acesso: O nível de acesso predefinido concedido para cada API. Valores válidos: create, list, get, update e delete.
Tipo de recurso: O tipo de recurso que suporta autorização para executar a ação. Indica se a ação suporta permissão em nível de recurso. O recurso especificado deve ser compatível com a ação. Caso contrário, a política será ineficaz.
- Para APIs com permissões em nível de recurso, os tipos de recursos obrigatórios são marcados com um asterisco (*). Especifique o Nome de Recurso Alibaba Cloud (ARN) correspondente no elemento Resource da política.
- Para APIs sem permissões em nível de recurso, é exibido como Todos os Recursos. Use um asterisco (*) no elemento Resource da política.
Chave de condição: As chaves de condição definidas pelo serviço. A chave permite controle granular, aplicando-se somente a ações ou a ações associadas a recursos específicos. Além das chaves de condição específicas do serviço, o Alibaba Cloud fornece um conjunto de chaves de condição comuns aplicáveis a todos os serviços compatíveis com RAM.
Ação dependente: As ações dependentes necessárias para executar a ação. Para concluir a ação, o usuário RAM ou a função RAM deve ter permissões para executar todas as ações dependentes.

Ação

Nível de acesso

Tipo de recurso

Chave de condição

Ação dependente

cs:GetClusters

get

*Cluster

acs:cs:*:{#accountId}:cluster/*

Nenhuma

Sintaxe da solicitação

GET /api/v1/clusters HTTP/1.1

Parâmetros da solicitação

Parâmetro	Tipo	Obrigatório	Descrição	Exemplo
name	string	Não	O nome do cluster.	cluster-demo
cluster_type	string	Não	O tipo de cluster. Kubernetes: cluster dedicado do ACK. ManagedKubernetes: tipos de cluster gerenciado do ACK, incluindo clusters gerenciados do ACK (Pro e Basic), clusters ACK Serverless (Pro e Basic), clusters ACK Edge (Pro e Basic) e clusters ACK Lingjun (Pro). ExternalKubernetes: cluster registrado.	Kubernetes
page_size	integer	Não	O número de registros por página.	10
page_number	integer	Não	O número da página atual.	1
profile	string	Não	Quando você define cluster_type como ManagedKubernetes, pode especificar ainda o subtipo do cluster. Default: cluster gerenciado do ACK, incluindo cluster ACK Pro e cluster ACK Basic. Edge: cluster ACK Edge, incluindo cluster ACK Edge Pro e cluster ACK Edge Basic. Serverless: cluster ACK Serverless, incluindo cluster ACK Serverless Pro e cluster ACK Serverless Basic. Lingjun: cluster ACK Lingjun, disponível na versão Pro.	Default
cluster_spec	string	Não	A especificação do cluster quando cluster_type é definido como ManagedKubernetes e profile é configurado. Valores válidos: ack.standard: Basic ack.pro.small: Pro ack.pro.xlarge: Pro XL ack.pro.2xlarge: Pro 2XL ack.pro.4xlarge: Pro 4XL (entre em contato com o atendimento ao cliente para ser adicionado à lista de permissões) Pro XL, Pro 2XL e Pro 4XL são três níveis fornecidos pelo Plano de controle provisionado do ACK Pro. Ao pré-alocar e dedicar recursos do plano de controle, esses níveis garantem que a simultaneidade da API e os recursos de agendamento de pods permaneçam em um nível consistentemente alto. Eles são adequados para treinamento e inferência de IA, clusters de escala ultragrande e cargas de trabalho de missão crítica. Para obter informações sobre as taxas de gerenciamento de cluster para as edições Pro e plano de controle provisionado, consulte Taxa de gerenciamento de cluster.	ack.pro.small
region_id	string	Não	A região do cluster. Especifique este parâmetro para filtrar a lista de clusters por região.	cn-hangzhou
cluster_id	string	Não	O ID do cluster.	c3fb96524f9274b4495df0f12a6b5****

Elementos de resposta

Elemento	Tipo	Descrição	Exemplo
	object	O corpo da resposta.
clusters	array<object>	A lista de informações do cluster.
	array<object>	A instância do cluster.
cluster_domain	string	O nome de domínio local do cluster.	cluster.local
cluster_id	string	O ID do cluster.	c3fb96524f9274b4495df0f12a6b5****
cluster_spec	string	A especificação do cluster.	ack.standard
cluster_type	string	O tipo de cluster.	Kubernetes
container_cidr	string	O bloco CIDR dos pods. Esta é a configuração de rede Flannel.	172.20.xx.xx/16
created	string	A hora em que o cluster foi criado.	2025-04-07T09:57:26+08:00
current_version	string	A versão atual do cluster.	1.32.1-aliyun.1
deletion_protection	boolean	Indica se a proteção contra exclusão está ativada para o cluster. A proteção contra exclusão evita que o cluster seja excluído acidentalmente no console ou por meio de chamadas de operações de API. Valores válidos: true: A proteção contra exclusão está ativada. O cluster não pode ser excluído no console ou por meio de chamadas de operações de API. false: A proteção contra exclusão não está ativada. O cluster pode ser excluído no console ou por meio de chamadas de operações de API.	true
docker_version `deprecated`	string	A versão do Docker usada pelo cluster.	19.03.5
external_loadbalancer_id `deprecated`	string	A instância de SLB associada ao Ingress do cluster. Tipo de instância padrão: instância de desempenho garantido (slb.s1.small).	lb-2vcrbmlevo6kjpgch****
init_version	string	A versão inicial do cluster. Para obter mais informações sobre as versões do Kubernetes suportadas pelo ACK, consulte Visão geral do lançamento de versões do Kubernetes.	1.32.1-aliyun.1
ip_stack	string	A pilha de protocolos IP do cluster. Valores válidos: ipv4: cria um cluster que suporta apenas a pilha de protocolos IPv4. dual: cria um cluster que suporta a pilha dupla IPv4/IPv6.	ipv4
maintenance_window	maintenance_window	A janela de manutenção do cluster. Este recurso entra em vigor apenas para clusters gerenciados ACK e clusters ACK Serverless.
master_url	string	Os endereços de acesso do servidor de API do cluster, incluindo o endereço de acesso à rede interna e o endereço de acesso à rede pública.	{\"api_server_endpoint\":\"\",\"intranet_api_server_endpoint\":\"https://192.168.xx.xx:6443\"}
meta_data	string	Os metadados do cluster.	{\"Addons\":[{\"config\":***}}
name	string	O nome do cluster.	cluster-demo
network_mode `deprecated`	string	O modo de rede do cluster. Valores válidos: classic: rede clássica. vpc: nuvem privada virtual (VPC). overlay: rede overlay. calico: rede Calico.	vpc
next_version	string	A versão para a qual o cluster pode ser atualizado.	1.xx.x-aliyun.1
operation_policy	object	A política de O&M automático do cluster.
cluster_auto_upgrade	object	A configuração de atualização automática do cluster.
channel	string	A frequência de atualização automática do cluster. Para obter mais informações, consulte Frequência de atualização. Valores válidos: patch: a versão de patch mais recente. stable: a segunda versão secundária mais recente. rapid: a versão secundária mais recente.	patch
enabled	boolean	Indica se a atualização automática do cluster está ativada.	true
private_zone `deprecated`	boolean	A configuração do Private Zone do cluster. Valores válidos: true: O Private Zone está ativado. false: O Private Zone não está ativado.	false
profile	string	O subtipo do cluster.	Default
proxy_mode	string	O modo kube-proxy. Valores válidos: iptables: um modo kube-proxy maduro e estável. A descoberta de serviços e o balanceamento de carga para Serviços do Kubernetes são configurados usando regras do iptables. O desempenho é mediano e é afetado pela escala do cluster. Este modo é adequado para clusters que contêm um pequeno número de Serviços. ipvs: um modo kube-proxy de alto desempenho. A descoberta de serviços e o balanceamento de carga para Serviços do Kubernetes são configurados usando o módulo IPVS do Linux. Este modo é adequado para clusters que contêm um grande número de Serviços e requerem balanceamento de carga de alto desempenho.	ipvs
region_id	string	O ID da região onde o cluster está implantado.	cn-beijing
resource_group_id	string	O ID do grupo de recursos ao qual o cluster pertence.	rg-acfmyvw3wjm****
security_group_id	string	O ID do grupo de segurança associado ao cluster.	sg-2vcgwsrwgt5mp0yi****
service_cidr	string	O bloco CIDR dos serviços.	172.21.xx.xx/20
size	integer	O número atual de nós no cluster, incluindo nós mestres e nós de trabalho.	5
state	string	O status de execução do cluster. Valores válidos: `initial`: O cluster está sendo criado. `failed`: Falha ao criar o cluster. `running`: O cluster está em execução. `updating`: O cluster está sendo atualizado. `upgrading`: O cluster está passando por upgrade. `removing`: Os nós estão sendo removidos. `draining`: Os nós estão sendo drenados. `scaling`: O cluster está sendo dimensionado. `inactive`: O cluster está inativo. `unavailable`: O cluster está indisponível. `deleting`: O cluster está sendo excluído. `deleted`: O cluster foi excluído. `delete_failed`: Falha ao excluir o cluster. `waiting`: O cluster está no estado de espera, aguardando conexão. `disconnected`: O cluster está desconectado.	running
subnet_cidr `deprecated`	string	[Descontinuado] Use container_cidr para obter o bloco CIDR de pods.	null
tags	array	As tags de recurso do cluster.
	tag	As tags de recurso do cluster.
timezone	string	O fuso horário.	Asia/Shanghai
updated	string	A hora em que o cluster foi atualizado pela última vez.	2025-04-07T09:57:26+08:00
vpc_id	string	O ID da VPC associada ao cluster.	vpc-2vcg932hsxsxuqbgl****
vswitch_id `deprecated`	string	O ID do vSwitch do cluster.	vsw-2vc41xuumx5z2rdma**,vsw-2vc41xuumx5z2rdma**
vswitch_ids	array	Os vSwitches do plano de controle do cluster.
	string	Os vSwitches do plano de controle do cluster.	vsw-2vc41xuumx5z2rdma****
worker_ram_role_name `deprecated`	string	O nome da função RAM do worker que autoriza instâncias ECS a atuarem como nós worker do cluster.	KubernetesWorkerRole-ec87d15b-edca-4302-933f-c8a16bf0****
zone_id `deprecated`	string	O ID da zona do cluster.	cn-beijing-b
page_info	object	As informações de paginação.
page_number	integer	O número da página.	3
page_size	integer	O número de entradas por página.	20
total_count	integer	O número total de resultados.	50

Exemplos

Resposta de sucesso

JSON formato

{
  "clusters": [
    {
      "cluster_domain": "cluster.local",
      "cluster_id": "c3fb96524f9274b4495df0f12a6b5****",
      "cluster_spec": "ack.standard",
      "cluster_type": "Kubernetes",
      "container_cidr": "172.20.xx.xx/16",
      "created": "2025-04-07T09:57:26+08:00",
      "current_version": "1.32.1-aliyun.1",
      "deletion_protection": true,
      "docker_version": "19.03.5",
      "external_loadbalancer_id": "lb-2vcrbmlevo6kjpgch****",
      "init_version": "1.32.1-aliyun.1",
      "ip_stack": "ipv4",
      "maintenance_window": {
        "duration": "3h",
        "enable": false,
        "exclusions": [
          {
            "description": "Todas as alterações são proibidas durante o período de congelamento",
            "end_time": "2026-11-15T00:00:00+08:00",
            "scope": "NoOperations",
            "start_time": "2026-11-01T00:00:00+08:00"
          }
        ],
        "maintenance_time": "2020-10-15T12:31:00.000+08:00",
        "recurrence": "FREQ=WEEKLY;INTERVAL=4;BYDAY=MO,TU",
        "weekly_period": "Monday,Thursday"
      },
      "master_url": "{\\\"api_server_endpoint\\\":\\\"\\\",\\\"intranet_api_server_endpoint\\\":\\\"https://192.168.xx.xx:6443\\\"}",
      "meta_data": "{\\\"Addons\\\":[{\\\"config\\\":***}}",
      "name": "cluster-demo",
      "network_mode": "vpc",
      "next_version": "1.xx.x-aliyun.1",
      "operation_policy": {
        "cluster_auto_upgrade": {
          "channel": "patch",
          "enabled": true
        }
      },
      "private_zone": false,
      "profile": "Default",
      "proxy_mode": "ipvs",
      "region_id": "cn-beijing",
      "resource_group_id": "rg-acfmyvw3wjm****",
      "security_group_id": "sg-2vcgwsrwgt5mp0yi****",
      "service_cidr": "172.21.xx.xx/20",
      "size": 5,
      "state": "running",
      "subnet_cidr": "null",
      "tags": [
        {
          "key": "env",
          "value": "prod"
        }
      ],
      "timezone": "Asia/Shanghai",
      "updated": "2025-04-07T09:57:26+08:00",
      "vpc_id": "vpc-2vcg932hsxsxuqbgl****",
      "vswitch_id": "vsw-2vc41xuumx5z2rdma****,vsw-2vc41xuumx5z2rdma****",
      "vswitch_ids": [
        "vsw-2vc41xuumx5z2rdma****"
      ],
      "worker_ram_role_name": "KubernetesWorkerRole-ec87d15b-edca-4302-933f-c8a16bf0****",
      "zone_id": "cn-beijing-b"
    }
  ],
  "page_info": {
    "page_number": 3,
    "page_size": 20,
    "total_count": 50
  }
}

Códigos de erro

Consulte Códigos de Erro para uma lista completa.

Notas de versão

Consulte Notas de Versão para uma lista completa.