Todos os produtos
Search

Este produto

    Container Service for Kubernetes:Conectar-se a um cluster ACK usando kubectl

    Central de documentação

    Container Service for Kubernetes:Conectar-se a um cluster ACK usando kubectl

    Última atualização: Oct 14, 2026

    Além do console do Container Service for Kubernetes (ACK), você pode usar o kubectl, a ferramenta de linha de comando do Kubernetes, para gerenciar clusters e aplicações. Antes de se conectar a um cluster com o kubectl, obtenha o kubeconfig do cluster, que contém as informações de identidade do seu usuário atual.

    Etapa 1: Instalar e configurar o cliente kubectl

    Identifique a máquina cliente na qual deseja instalar o kubectl. Com base no seu ambiente operacional e na versão do cluster, instale o kubectl.

    Etapa 2: Obter e usar o kubeconfig

    1. Selecionar um tipo de kubeconfig

    O kubeconfig contém as informações de autenticação necessárias para acessar o cluster. Escolha o tipo de kubeconfig adequado aos seus requisitos de segurança e caso de uso.

    Importante

    Em Shared responsibility model, você é responsável por gerenciar e manter suas credenciais do kubeconfig. Mantenha-as apropriadas e válidas, faça a rotação regular do kubeconfig e siga o princípio do menor privilégio para evitar riscos de segurança decorrentes de vazamento.

    • Por período de validade do kubeconfig:

      • Kubeconfig temporário: Permite configurar uma validade entre 30 minutos e 3 dias. O arquivo expira automaticamente após o período definido, reduzindo o risco de segurança em caso de vazamento. É ideal para cenários que não exigem conexão permanente com o API server, como operações e manutenção diárias, solução de problemas e pipelines de CI/CD.

      • Kubeconfig de longo prazo: Possui validade padrão de 3 anos. Recomendado para sistemas automatizados ou serviços de monitoramento contínuo que não podem renovar o kubeconfig frequentemente.

    • Por método de acesso ao cluster:

      • Acesso interno: Obtenha um kubeconfig para acesso interno. A máquina cliente do kubectl deve estar na mesma Virtual Private Cloud (VPC) do cluster. As conexões pela rede interna da Alibaba Cloud oferecem menor latência e maior segurança.

      • Acesso público: Obtenha um kubeconfig para acesso público e utilize qualquer máquina na Internet como cliente para se conectar ao cluster. Este método depende de um Elastic IP Address (EIP) para conectar-se ao API Server e é adequado para desenvolvimento local ou operações e manutenção remotas.

        Após vincular o EIP, consulte Pay-as-you-go para obter informações sobre as taxas associadas.

    • Caso utilize um ACK dedicated cluster com acesso público habilitado, obtenha o kubeconfig diretamente do nó mestre via SSH e use o kubectl localmente para gerenciar o cluster. Para mais detalhes, consulte Connect to the master node of an ACK dedicated cluster over SSH.

    2. Obter o kubeconfig e conectar-se ao cluster

    Após obter o kubeconfig no console, o kubectl poderá usar esse arquivo para se conectar e gerenciar o cluster.

    Antes que um usuário do Resource Access Management (RAM) se conecte ao cluster, ele deve receber permissões de operação no cluster, além das permissões de sistema do Container Service. Para mais informações, consulte Authorization .

    1. Faça login no ACK console. No painel de navegação à esquerda, clique em Clusters.

    2. Na página Cluster List, clique no nome do cluster desejado ou clique em Details na coluna Actions.

    3. Na página Cluster Information, clique na aba Connection Information e selecione um kubeconfig temporário ou de longo prazo. Para o kubeconfig temporário, defina um período de validade apropriado.

    4. Selecione a aba Public Access ou Internal Access, clique em Copy, cole o conteúdo copiado no arquivo $HOME/.kube/config do cliente, salve e feche o arquivo.

      Se o arquivo $HOME/.kube/config não existir, execute mkdir -p $HOME/.kube e touch $HOME/.kube/config para criá-lo.

    5. Após concluir a configuração, execute um comando kubectl para verificar a conectividade com o cluster.

      O exemplo abaixo consulta namespaces.

      kubectl get namespaces

      Saída esperada:

      NAME              STATUS   AGE
default           Active   4h39m
kube-node-lease   Active   4h39m
kube-public       Active   4h39m
kube-system       Active   4h39m

    Uso em produção

    • Garanta a validade do kubeconfig: Para evitar interrupções no acesso ao cluster quando o kubeconfig expirar, renove-o prontamente.

      Um kubeconfig de longo prazo tem validade de 3 anos. Como melhor prática, obtenha um novo kubeconfig dentro dos 180 dias anteriores à expiração através do ACK console ou chamando a DescribeClusterUserKubeconfig.

      O novo kubeconfig também terá validade de 3 anos. O kubeconfig antigo permanecerá válido até que seu certificado expire.

    • Revogue rapidamente um kubeconfig: Se suspeitar que um kubeconfig foi vazado, Revoke a cluster's kubeconfig file imediatamente. Após a revogação, o sistema gera um novo kubeconfig e vínculo de autorização, invalidando todas as conexões baseadas no kubeconfig antigo.

    • Limpeza de permissões: Quando os usuários não precisarem mais de permissões de acesso, como após o término de um projeto ou desligamento de um funcionário, use o recurso Clean Up para revogar permissões de kubeconfig em massa. O sistema não gera um novo kubeconfig após a limpeza. Para instruções, consulte Delete kubeconfig files e Clean up user permissions with ack-ram-tool.

      Para evitar exclusão acidental de permissões, você pode Use the kubeconfig recycle bin para restaurar as permissões específicas de kubeconfig que foram removidas.

    Perguntas frequentes

    Como obter as informações de identidade associadas ao certificado usado em um kubeconfig?

    Execute o seguinte comando para obter as informações de identidade.

    grep client-certificate-data kubeconfig |awk '{print $2}' |base64 -d | openssl x509 -noout -text |grep Subject:
    Substitua o caminho do kubeconfig pelo seu caminho real. Por padrão, o kubectl usa $HOME/.kube/config para se conectar ao cluster. Você também pode definir a variável de ambiente KUBECONFIG ou o parâmetro --kubeconfig para especificar outro arquivo kubeconfig.

    A saída esperada é semelhante à seguinte:

            Subject: O=system:users, OU=, CN=1***-1673419473

    Onde:

    • O: Informações do grupo de usuários do Kubernetes. Neste exemplo, o nome do grupo é system:users.

    • CN: Informações do usuário associado. Neste exemplo, o usuário é 1***-1673419473, onde 1*** está associado a um ID de usuário da Alibaba Cloud sob a conta.

    Como obter o horário de expiração do certificado usado por um kubeconfig?

    Execute o seguinte comando para obter o horário de expiração associado ao certificado usado pelo arquivo kubeconfig.

    grep client-certificate-data kubeconfig |awk '{print $2}' |base64 -d | openssl x509 -noout -enddate
    Substitua o caminho do kubeconfig pelo seu caminho real. Por padrão, o kubectl usa $HOME/.kube/config para se conectar ao cluster. Você também pode definir a variável de ambiente KUBECONFIG ou o parâmetro --kubeconfig para especificar outro arquivo kubeconfig.

    A saída esperada é semelhante à seguinte:

    notAfter=Jan 10 06:44:34 2026 GMT

    Neste exemplo, Jan 10 06:44:34 2026 GMT é o horário de expiração do certificado.

    Dentro dos 180 dias anteriores à expiração do certificado ou após sua expiração, você pode obter um kubeconfig que utiliza um certificado com nova data de expiração através do console ou via OpenAPI.

    Como obter o certificado de cliente, chave privada do cliente e informações do API Server?

    Use os seguintes comandos para extrair o certificado de cliente, a chave privada do cliente e as informações do API Server do arquivo kubeconfig.

    cat  ./kubeconfig |grep client-certificate-data | awk -F ' ' '{print $2}' |base64 -d > ./client-cert.pem
cat  ./kubeconfig |grep client-key-data | awk -F ' ' '{print $2}' |base64 -d > ./client-key.pem
APISERVER=`cat  ./kubeconfig |grep server | awk -F ' ' '{print $2}'`
    Substitua o caminho do kubeconfig pelo seu caminho real. Por padrão, o kubectl usa $HOME/.kube/config para se conectar ao cluster. Você também pode definir a variável de ambiente KUBECONFIG ou o parâmetro --kubeconfig para especificar outro arquivo kubeconfig.

    Como resolver o erro certificate is valid for ao me conectar a um cluster usando kubectl?

    Após vincular um novo endereço IP à instância do Server Load Balancer (SLB) do API Server do cluster, a execução de comandos kubectl para acessar o novo IP pode falhar com o erro Error while proxying request: x509: certificate is valid for xxx ou Unable to connect to the server: x509: certificate is valid for xxx.

    • ACK managed cluster: Adicione o novo endereço IP ao SAN do certificado do API Server. Para mais informações, consulte Customize ACK API server certificate SANs.

    • ACK dedicated cluster: Configure o kubectl para ignorar este erro usando a configuração insecure-skip-tls-verify.

      Importante

      Este método impede que o cliente verifique o certificado do API Server e não é recomendado para ambientes de produção. Em vez disso, Hot migrate an ACK dedicated cluster to an ACK Pro cluster e adicione o novo endereço IP ao SAN do certificado do API Server para resolver essa questão.

      • Método 1: Especifique o parâmetro --insecure-skip-tls-verify ao executar um comando kubectl.

        kubectl -s https://<IP>:6443 --insecure-skip-tls-verify get ns

      • Método 2: Modifique o arquivo kubeconfig, adicione a configuração insecure-skip-tls-verify: true e remova a configuração certificate-authority-data.

        apiVersion: v1
clusters:
- cluster:
    server: https://<IP>:6443
    insecure-skip-tls-verify: true
  name: kubernetes
contexts:
...

    ACK managed cluster Posso obter a chave do certificado raiz do cluster para gerar meu próprio certificado kubeconfig?

    O ACK managed cluster não fornece a chave do certificado raiz do cluster externamente. Obtenha o kubeconfig do cluster através do console ou da OpenAPI.

    Referências