Este documento foi traduzido usando tecnologia de tradução automática de máquina. Sempre trabalhamos para apresentar traduções precisas, mas não oferecemos nenhuma garantia em relação à integridade, precisão ou confiabilidade do conteúdo traduzido. Em caso de qualquer discrepância, a versão original em inglês prevalecerá e constituirá o texto official.

Registrando Clusters Existentes

O recurso de registro de cluster substituiu o recurso de importar clusters.

O controle que o Rancher tem para gerenciar um cluster registrado depende do tipo de cluster. Para mais detalhes, veja Capacidades de Gerenciamento para Clusters Registrados.

Pré-requisitos

Kubernetes Node Roles

Clusters Kubernetes RKE registrados devem ter todas as três funções de nó - etcd, controlplane e worker. Um cluster com apenas componentes de controlplane não pode ser registrado no Rancher.

Para mais informações sobre funções de nó RKE, veja as melhores práticas.

Permissões

Para registrar um cluster no Rancher, você deve ter cluster-admin privilégios dentro desse cluster. Se você não tiver, conceda esses privilégios ao seu usuário executando:

kubectl create clusterrolebinding cluster-admin-binding \
  --clusterrole cluster-admin \
  --user [USER_ACCOUNT]

Como, por padrão, o Google Kubernetes Engine (GKE) não concede a função cluster-admin, você deve executar esses comandos em clusters GKE antes de poder registrá-los. Para saber mais sobre controle de acesso com base em função para GKE, consulte a documentação oficial do Google.

Elastic Kubernetes Service (EKS), Azure Kubernetes Service (AKS) e Google Kubernetes Engine (GKE)

Para importar ou provisionar com sucesso clusters EKS, AKS e GKE a partir do Rancher, o cluster deve ter pelo menos um grupo de nós gerenciado.

Clusters AKS podem ser importados apenas se contas locais estiverem habilitadas. Se um cluster estiver configurado para usar o Microsoft Entra ID para autenticação, o Rancher não poderá importá-lo e relatará um erro.

Clusters EKS Anywhere podem ser importados/registrados no Rancher com um endereço de API e credenciais, assim como qualquer cluster downstream. Clusters EKS Anywhere são tratados como clusters importados e não têm suporte completo ao ciclo de vida pelo Rancher.

Clusters GKE Autopilot não são suportados. Veja Comparar GKE Autopilot e Standard para mais informações sobre as diferenças entre os modos do GKE.

Registrando um Cluster

  1. Clique em ☰ > Gerenciamento de Cluster.

  2. Na página Clusters, Importar Existente.

  3. Escolha o tipo de cluster.

  4. Use Funções de Membro para configurar a autorização de usuários para o cluster. Clique em Adicionar Membro para adicionar usuários que podem acessar o cluster. Use o menu suspenso Função para definir permissões para cada usuário.

  5. Se você estiver importando um cluster Kubernetes genérico no Rancher, execute os seguintes passos para a configuração:

    1. Clique em Variáveis de Ambiente do Agente em Opções do Cluster para definir variáveis de ambiente para agente do cluster Rancher. As variáveis de ambiente podem ser definidas usando pares de chave e valor. Se o agente do Rancher exigir o uso de proxy para se comunicar com o servidor Rancher, as variáveis de ambiente HTTP_PROXY, HTTPS_PROXY e NO_PROXY podem ser definidas usando as variáveis de ambiente do agente.

    2. Ative o Isolamento de Rede do Projeto para garantir que o cluster suporte recursos Kubernetes NetworkPolicy. Os usuários podem selecionar a opção Isolamento de Rede do Projeto no menu suspenso Opções Avançadas para fazer isso.

    3. Configure o recurso de gerenciamento de versão para clusters RKE2 e K3s importados.

  6. Clique em Criar.

  7. O pré-requisito para cluster-admin privilégios é mostrado (veja Pré-requisitos acima), incluindo um comando de exemplo para cumprir o pré-requisito.

  8. Copie o comando kubectl para sua área de transferência e execute-o em um nó onde o kubeconfig está configurado para apontar para o cluster que você deseja importar. Se você não tiver certeza de que está configurado corretamente, execute kubectl get nodes para verificar antes de executar o comando mostrado no Rancher.

  9. Se você estiver usando certificados autoassinados, receberá a mensagem certificate signed by unknown authority. Para contornar essa validação, copie o comando começando com curl exibido no Rancher para sua área de transferência. Em seguida, execute o comando em um nó onde o kubeconfig está configurado para apontar para o cluster que você deseja importar.

  10. Quando você terminar de executar o(s) comando(s) em seu nó, clique em Concluído.

A variável de ambiente NO_PROXY não é padronizada, e o formato aceito do valor pode diferir entre aplicações. Ao configurar a variável NO_PROXY para o Rancher, o valor deve seguir o formato esperado pelo Golang.

Especificamente, o valor deve ser uma string delimitada por vírgulas que contenha apenas endereços IP, notação CIDR, nomes de domínio ou rótulos DNS especiais (por exemplo, *). Para uma descrição completa do formato de valor esperado, consulte a documentação upstream Golang.

Resultado:

  • Seu cluster está registrado e atribuído a um estado de Pending. O Rancher está implantando recursos para gerenciar seu cluster.

  • Você pode acessar seu cluster após seu estado ser atualizado para Ativo.

  • Clusters Ativos são atribuídos a dois Projetos: Default (contendo o namespace default) e System (contendo os namespaces cattle-system, traefik, kube-public e kube-system, se presentes).

Você não pode re-registrar um cluster que está atualmente ativo em uma configuração do Rancher.

Configurando um Cluster EKS, AKS ou GKE Importado com Terraform

Você deve definir apenas os campos mínimos que o Rancher requer ao importar um cluster EKS, AKS ou GKE com Terraform. Isso é importante, pois o Rancher irá sobrescrever o que estava na configuração do cluster com qualquer configuração que o usuário tenha fornecido.

Mesmo uma pequena diferença entre o cluster atual e uma configuração fornecida pelo usuário pode ter resultados inesperados.

Os campos de configuração mínimos exigidos pelo Rancher para importar clusters EKS com Terraform usando eks_config_v2 são os seguintes:

  • cloud_credential_id

  • name

  • região

  • importado (este campo deve sempre ser definido como true para clusters importados)

Exemplo de configuração YAML para clusters EKS importados:

resource "rancher2_cluster" "my-eks-to-import" {
  name        = "my-eks-to-import"
  description = "Terraform EKS Cluster"
  eks_config_v2 {
    cloud_credential_id = rancher2_cloud_credential.aws.id
    name                = var.aws_eks_name
    region              = var.aws_region
    imported            = true
  }
}

Você pode encontrar exemplos adicionais para outros provedores de nuvem na documentação Rancher2 Terraform Provider.

Capacidades de Gerenciamento para Clusters Registrados

O controle que o Rancher tem para gerenciar um cluster registrado depende do tipo de cluster.

Recursos para Todos os Clusters Registrados

Após registrar um cluster, o proprietário do cluster pode:

Recursos Adicionais para Clusters Registrados SUSE® Rancher Prime: RKE2 e SUSE® Rancher Prime: K3s

K3s é uma distribuição Kubernetes leve e totalmente compatível para instalações em edge.

RKE2 é a distribuição Kubernetes de próxima geração do Rancher para instalações em datacenters e nuvens.

Quando um cluster RKE2 ou K3s é registrado no Rancher, o Rancher o reconhecerá. A interface do usuário do Rancher exporá recursos disponíveis para todos os clusters registrados, juntamente com as seguintes opções para editar e atualizar o cluster:

Recursos Adicionais para Clusters EKS, AKS e GKE Registrados

O Rancher trata clusters EKS, AKS ou GKE registrados de forma semelhante a clusters criados no Rancher. No entanto, o Rancher não destrói clusters registrados quando você os exclui pela interface do Rancher.

Quando você cria um cluster EKS, AKS ou GKE no Rancher e depois o exclui, o Rancher destrói o cluster. Quando você exclui um cluster registrado através do Rancher, o servidor Rancher desconecta do cluster. O cluster permanece ativo, embora não esteja mais no Rancher. Você ainda pode acessar o cluster desregistrado da mesma forma que fez antes de registrá-lo.

Veja Capacidades de Gerenciamento de Cluster por Tipo de Cluster para mais informações sobre quais recursos estão disponíveis para gerenciar clusters registrados.

Configurando o Gerenciamento de Versão para Clusters SUSE® Rancher Prime: RKE2 e SUSE® Rancher Prime: K3s

Quando o gerenciamento de versão está habilitado para um cluster importado, fazer upgrade nele fora do Rancher pode levar a consequências inesperadas.

O recurso de gerenciamento de versão para clusters RKE2 e K3s importados pode ser configurado usando uma das seguintes opções:

  • Padrão global (padrão): Herda o comportamento da configuração global gerenciamento-de-versão-de-cluster-importado.

  • Verdadeiro: Habilita o gerenciamento de versão, permitindo que os usuários controlem a versão do Kubernetes e a estratégia de atualização do cluster através do Rancher.

  • Falso: Desabilita o gerenciamento de versão, permitindo que os usuários gerenciem a versão do Kubernetes do cluster de forma independente, fora do Rancher.

Você pode definir o comportamento padrão para clusters recém-criados ou existentes configurados como "Padrão global" modificando a configuração gerenciamento-de-versão-de-cluster-importado.

Mudanças na configuração global gerenciamento-de-versão-de-cluster-importado entram em vigor durante o próximo ciclo de reconciliação do cluster.

Se o gerenciamento de versão estiver habilitado para um cluster, o Rancher implantará o app system-upgrade-controller, juntamente com os Planos associados e outros recursos Kubernetes necessários, no cluster. Se o gerenciamento de versão estiver desabilitado, o Rancher removerá esses componentes do cluster.

Configurando o upgrade dos clusters SUSE® Rancher Prime: RKE2 e SUSE® Rancher Prime: K3s

É uma boa prática do Kubernetes fazer backup do cluster antes de fazer upgrade. Ao fazer upgrade de um cluster K3s de alta disponibilidade com um banco de dados externo, faça backup do banco de dados da maneira recomendada pelo provedor do banco de dados relacional.

A concorrência é o número máximo de nós que podem estar indisponíveis durante uma atualização. Se o número de nós indisponíveis for maior que a concorrência, a atualização falhará. Se uma atualização falhar, pode ser necessário reparar ou remover nós com falha antes que a atualização possa ser bem-sucedida.

  • Concorrência do plano de controle: O número máximo de nós de servidor a serem atualizados de uma só vez; também o número máximo de nós de servidor indisponíveis

  • Concorrência de Trabalhadores: O número máximo de nós worker a serem submetidos a upgrade ao mesmo tempo; também o número máximo de nós worker indisponíveis

Na documentação do RKE2 e K3s, os nós do plano de controle são chamados de nós de servidor. Esses nós executam o mestre do Kubernetes, que mantém o estado desejado do cluster. Por padrão, esses nós do plano de controle têm a capacidade de ter cargas de trabalho agendadas para eles por padrão.

Também na documentação do RKE2 e K3s, os nós com o papel de worker são chamados de nós agentes. Quaisquer cargas de trabalho ou pods que são implantados no cluster podem ser agendados para esses nós por padrão.

Registro de Depuração e Solução de Problemas para Clusters Registrados SUSE® Rancher Prime: RKE2 e SUSE® Rancher Prime: K3s

Os nós são atualizados pelo controlador de atualização do sistema que está em execução no cluster downstream. Com base na configuração do cluster, o Rancher implanta dois planos para fazer upgrade nos nós: um para nós do plano de controle e outro para nós worker. O controlador de atualização do sistema segue os planos e faz upgrade nos nós.

Para habilitar o registro de depuração na implantação do controlador de atualização do sistema, edite o configmap para definir a variável de ambiente de depuração como verdadeira. Em seguida, reinicie o pod system-upgrade-controller.

Os logs criados pelo system-upgrade-controller podem ser visualizados executando este comando:

kubectl logs -n cattle-system system-upgrade-controller

O status atual dos planos pode ser visualizado com este comando:

kubectl get plans -A -o yaml

Se o cluster ficar preso no upgrade, reinicie o system-upgrade-controller.

Para evitar problemas durante o upgrade, as melhores práticas para fazer upgrade do Kubernetes devem ser seguidas.

Suporte a Ponto de Extremidade de Cluster Autorizado para Clusters SUSE® Rancher Prime: RKE2 e SUSE® Rancher Prime: K3s

O Rancher suporta Pontos de Extremidade de Cluster Autorizados (ACE) para clusters RKE2 e K3s registrados. Esse suporte inclui etapas manuais que você realizará no cluster downstream para habilitar o ACE. Para mais informações sobre o ponto de extremidade de cluster autorizado, clique aqui.

Notas:

  • Essas etapas precisam ser realizadas apenas nos nós do plano de controle do cluster downstream. Você deve configurar cada nó do plano de controle individualmente.

  • As seguintes etapas funcionarão tanto em clusters RKE2 quanto K3s registrados na versão v2.6.x, bem como aqueles registrados (ou importados) de uma versão anterior do Rancher com uma atualização para v2.6.x.

  • Essas etapas alterarão a configuração dos clusters RKE2 e K3s downstream e implantarão o kube-api-authn-webhook. Se uma futura implementação do ACE exigir uma atualização para o kube-api-authn-webhook, isso também terá que ser feito manualmente. Para mais informações sobre este webhook, clique here.
Etapas manuais a serem realizadas no plano de controle de cada cluster downstream para habilitar o ACE:

  1. Crie um arquivo em /var/lib/rancher/{rke2,k3s}/kube-api-authn-webhook.yaml com o seguinte conteúdo:

     apiVersion: v1
 kind: Config
 clusters:
 ** name: Default
cluster:
  insecure-skip-tls-verify: true
  server: http://127.0.0.1:6440/v1/authenticate
 users:
 ** name: Default
user:
  insecure-skip-tls-verify: true
 current-context: webhook
 contexts:
 ** name: webhook
context:
  user: Default
  cluster: Default

  2. Adicione o seguinte ao arquivo de configuração (ou crie um se não existir); observe que o local padrão é /etc/rancher/{rke2,k3s}/config.yaml:

     kube-apiserver-arg:
     - authentication-token-webhook-config-file=/var/lib/rancher/{rke2,k3s}/kube-api-authn-webhook.yaml

  3. Execute os seguintes comandos:

    sudo systemctl stop {rke2,k3s}-server
sudo systemctl start {rke2,k3s}-server

  4. Finalmente, você deve voltar para a interface do Rancher e editar o cluster importado lá para completar a habilitação do ACE. Clique em ⋮ > Editar Config, em seguida, clique na guia Networking em Configuração do Cluster. Por fim, clique no botão Habilitado para Ponto de Extremidade Autorizado. Uma vez que o ACE esteja habilitado, você terá a opção de inserir um Nome de Domínio Completo e Qualificado (FQDN) e informações do certificado.

O campo FQDN é opcional, e se um for inserido, deve apontar para o cluster downstream. As informações do certificado são necessárias apenas se houver um balanceador de carga na frente do cluster downstream que esteja usando um certificado não confiável. Se você tiver um certificado válido, então nada precisa ser adicionado ao campo Certificados CA.

Anotando Clusters Registrados

Para todos os tipos de clusters Kubernetes registrados, exceto para clusters Kubernetes RKE2 e K3s, o Rancher não possui informações sobre como o cluster é provisionado ou configurado.

Portanto, quando o Rancher registra um cluster, ele assume que várias capacidades estão desativadas por padrão. O Rancher assume isso para evitar expor opções da interface do usuário ao usuário, mesmo quando as capacidades não estão habilitadas no cluster registrado.

No entanto, se o cluster tiver uma certa capacidade, um usuário desse cluster ainda pode querer selecionar a capacidade para o cluster na interface do Rancher. Para fazer isso, o usuário precisará indicar manualmente ao Rancher que certas capacidades estão habilitadas para o cluster.

Ao anotar um cluster registrado, é possível indicar ao Rancher que um cluster recebeu capacidades adicionais fora do Rancher.

A seguinte anotação indica capacidades de Ingress. Observe que os valores de objetos não primitivos precisam ser codificados em JSON, com aspas escapadas.

"capabilities.cattle.io/ingressCapabilities": "[
  {
    "customDefaultBackend":true,
    "ingressProvider":"asdf"
  }
]"

Essas capacidades podem ser anotadas para o cluster:

  • ingressCapabilities

  • loadBalancerCapabilities

  • nodePoolScalingSupported

  • nodePortRange

  • taintSupport

Todas as capacidades e suas definições de tipo podem ser visualizadas na visualização da API do Rancher, em [Rancher Server URL]/v3/schemas/capabilities.

Para anotar um cluster registrado,

  1. Clique em ☰ > Gerenciamento de Cluster.

  2. Na página Clusters, vá para o cluster personalizado que você deseja anotar e clique em ⋮ > Editar Config.

  3. Expanda a seção Rótulos e Anotações.

  4. Clique em Adicionar Anotação.

  5. Adicione uma anotação ao cluster com o formato capabilities/<capability>: <value>, onde value é a capacidade do cluster que será substituída pela anotação. Neste cenário, o Rancher não está ciente de nenhuma capacidade do cluster até que você adicione a anotação.

  6. Clique em Salvar.

Resultado: A anotação não confere capacidades ao cluster, mas indica ao Rancher que o cluster possui essas capacidades.

Solução de problemas

Esta seção lista alguns dos erros mais comuns que podem ocorrer ao importar um cluster e fornece etapas para solucioná-los.

AKS

O seguinte erro pode ocorrer se contas locais estiverem desativadas em seu cluster:

Error: Getting static credential is not allowed because this cluster is set to disable local accounts.

Para resolver esse problema, ative as contas locais antes de tentar importar o cluster novamente:

az aks update --resource-group <resource-group> --name <cluster-name> --enable-local-accounts