Criar um cluster de administrador para uso em domínios de topologia

Esta página mostra como criar um cluster de administrador para uso em domínios de topologia do Google Distributed Cloud. O cluster de administrador gerencia clusters de usuários que executam cargas de trabalho. A versão 1.31 ou mais recente do Google Distributed Cloud é necessária para usar domínios de topologia.

Para configurar um domínio de topologia, é necessário ativar o cluster avançado. Observe as seguintes limitações com a visualização avançada de clusters:

  • É possível ativar o cluster avançado no momento da criação apenas para novos clusters da versão 1.31.
  • Depois que o cluster avançado for ativado, não será possível fazer upgrade dele para a versão 1.32. Ative o cluster avançado apenas em um ambiente de teste.

Esta página é destinada a administradores, arquitetos e operadores que configuram, monitoram e gerenciam a infraestrutura de tecnologia. Para saber mais sobre papéis comuns e exemplos de tarefas referenciados no conteúdo do Google Cloud , consulte Funções e tarefas comuns do usuário do GKE Enterprise.

Para mais detalhes sobre o cluster de administrador, consulte a visão geral da instalação.

Visão geral do procedimento

Estas são as principais etapas para criar um cluster de administrador:

  1. Preencher o arquivo de configuração do administrador
    Especifique os detalhes do novo cluster de administrador preenchendo um arquivo de configuração do cluster de administrador.
  2. Preencher o arquivo de configuração da infraestrutura do vSphere
    Especifique os detalhes sobre seus domínios de topologia em um arquivo de configuração da infraestrutura do vSphere.
  3. Preencher o arquivo de bloqueio de IP
    Especifique os endereços IP para o gateway, a máscara de rede e os nós do plano de controle em um arquivo de bloco de IP.
  4. Instalar imagens do SO
    Faça o download do pacote normal do Google Distributed Cloud. Em seguida, execute gkectl prepare, que importa as imagens do SO para o vSphere e envia imagens de contêiner para o registro particular, se aplicável.
  5. Criar um cluster de administrador.
    Use gkectl para criar um novo cluster de administrador, conforme especificado nos arquivos de configuração concluídos. Quando o Google Distributed Cloud cria um cluster de administrador, ele implanta um cluster do Kubernetes no Docker (tipo) para hospedar temporariamente os controladores do Kubernetes necessários para criar o cluster de administrador. Esse cluster transitório é chamado de cluster de inicialização. Os clusters de usuário são criados e atualizados pelo administrador de gerenciamento sem o uso de um cluster de inicialização.
  6. Verifique se o cluster de administrador está em execução.
    Use o kubectl para ver os nós do cluster.

No final do procedimento, você terá um cluster de administrador em execução para criar e gerenciar clusters de usuários em domínios de topologia.

Antes de começar

Preencha o arquivo de configuração do cluster de administrador.

Se você usou gkeadm para criar a estação de trabalho do administrador, ela gerou um arquivo de configuração chamado admin-cluster.yaml.

Se você não usou gkeadm para criar a estação de trabalho do administrador, gere admin-cluster.yaml executando este comando na estação de trabalho do administrador:

gkectl create-config admin

Esse arquivo de configuração serve para criar seu cluster de administrador.

Para se familiarizar com o arquivo de configuração, leia o documento arquivo de configuração do cluster de administrador. É recomendável manter esse documento aberto em uma guia ou janela separada para fazer referência a ele ao concluir as etapas a seguir.

name

Se você quiser especificar um nome para o cluster de administrador, preencha o campo name.

bundlePath

O pacote é um arquivo compactado que contém componentes de cluster. Ele está incluído na estação de trabalho de administrador. Este campo já foi preenchido para você.

enableAdvancedCluster

Defina enableAdvancedCluster como true. Isso ativa clusters avançados, que são necessários para configurar domínios de topologia.

infraConfigFilePath

Adicione o caminho completo ao arquivo de configuração da infraestrutura do vSphere no campo infraConfigFilePath.

vCenter

Remova toda esta seção. Em vez disso, configure as informações do servidor vCenter no arquivo de configuração da infraestrutura do vSphere.

network

  • Remova o seguinte do arquivo de configuração:

    • Toda a seção network.hostConfig. Essas informações são configuradas no arquivo de configuração da infraestrutura do vSphere por domínio de topologia.
    • O campo network.vCenter.networkName. Esse campo é configurado no arquivo de configuração da infraestrutura do vSphere por domínio de topologia.
    • Toda a seção network.controlPlaneIPBlock. Os endereços IP do gateway, da máscara de rede e dos nós do plano de controle são configurados em um arquivo de bloco de IP.

  • Defina network.ipMode.ipBlockFilePath como o caminho para o arquivo de bloco de IP.

  • Defina network.ipMode.type como static.

  • O network.podCIDR e o network.serviceCIDR têm valores pré-preenchidos que não podem ser alterados, a menos que entrem em conflito com endereços que já estão em uso na sua rede. O Kubernetes usa esses intervalos para atribuir endereços IP a pods e serviços no cluster.

loadBalancer

  • Defina loadBalancer.kind como "ManualLB" e remova a seção manualLB.

  • Separe um VIP para o servidor da API do Kubernetes do cluster de administrador. Informe seu VIP como o valor de loadBalancer.vips.controlPlaneVIP.

Para mais informações, consulte VIPs na sub-rede do cluster de administrador.

antiAffinityGroups

Defina antiAffinityGroups.enabled como false. As regras de antiafinidade do Distributed Resource Scheduler (DRS) não são compatíveis com domínios de topologia.

adminMaster

  • Se você quiser especificar a CPU e a memória para os nós do plano de controle do cluster de administrador, preencha os campos cpus e memoryMB no adminMaster.

  • Os clusters de administrador precisam ter três nós do plano de controle. Defina o campo replicas na seção adminMaster como 3.

  • Se você quiser especificar um domínio de topologia específico para os nós do plano de controle usarem, adicione o nome do domínio de topologia ao campo adminMaster.topologyDomains. Se você não especificar um nome aqui, será necessário definir um nome em vSphereInfraConfig.defaultTopologyDomain no arquivo de configuração da infraestrutura do vSphere.

proxy

Se a rede que terá os nós do cluster de administrador estiver atrás de um servidor proxy, preencha a seção proxy.

privateRegistry

Decida onde você quer manter as imagens de contêiner dos componentes do Google Distributed Cloud. As opções são:

  • Artifact Registry

  • Seu próprio registro particular do Docker.

    Se você quiser usar seu próprio registro particular, preencha a seção privateRegistry.

componentAccessServiceAccountKeyPath

O Google Distributed Cloud usa sua conta de serviço de acesso a componentes para fazer o download de componentes do cluster do Artifact Registry. Esse campo contém o caminho de um arquivo de chave JSON para sua conta de serviço de acesso a componentes.

Este campo já foi preenchido para você.

gkeConnect

Registre seu cluster de administrador em uma frota do Google Cloud preenchendo a seção gkeConnect. O ID em gkeConnect.projectID precisa ser igual ao ID definido em stackdriver.projectID e cloudAuditLogging.projectID. Se os IDs do projeto não forem iguais, a criação do cluster falhará.

Você pode especificar uma região em que os serviços de frota e Connect são executados em gkeConnect.location. Se você não incluir esse campo, o cluster vai usar as instâncias globais desses serviços.

Se você incluir gkeConnect.location, a região especificada precisará ser a mesma configurada em cloudAuditLogging.clusterLocation, stackdriver.clusterLocation e gkeOnPremAPI.location. Se as regiões não forem iguais, a criação do cluster falhará.

gkeOnPremAPI

Esta seção descreve como os clusters são inscritos na API GKE On-Prem.

A ferramenta de linha de comando gkectl é a única ferramenta de gerenciamento de ciclo de vida de cluster disponível para clusters que usam domínios de topologia. Embora o console do Google Cloud , a Google Cloud CLI e o Terraform não tenham suporte para clusters que usam domínios de topologia, é possível registrar o cluster na API GKE On-Prem quando ele é criado.

Se a API GKE On-Prem estiver ativada no seu Google Cloud projeto, todos os clusters no projeto serão registrados na API GKE On-Prem automaticamente na região configurada em stackdriver.clusterLocation. A região gkeOnPremAPI.location precisa ser a mesma especificada em cloudAuditLogging.clusterLocation, gkeConnect.location e stackdriver.clusterLocation. Se as regiões não forem iguais, a criação do cluster falhará.

  • Se você quiser registrar todos os clusters do projeto na API GKE On-Prem, siga as etapas em Antes de começar para ativar e usar a API GKE On-Prem no projeto.

  • Se você não quiser registrar o cluster na API GKE On-Prem, inclua esta seção e defina gkeOnPremAPI.enabled como false. Se você não quiser registrar clusters no projeto, desative gkeonprem.googleapis.com (o nome do serviço da API GKE On-Prem) no projeto. Para instruções, consulte Como desativar serviços.

stackdriver

Preencha a seção stackdriver para ativar o Cloud Logging e o Cloud Monitoring no cluster.

Observe os requisitos abaixo:

  • O ID em stackdriver.projectID precisa ser o mesmo que o ID em gkeConnect.projectID e cloudAuditLogging.projectID.

  • A região definida em stackdriver.clusterLocation precisa ser igual à região definida em cloudAuditLogging.clusterLocation e gkeConnect.location. Além disso, se gkeOnPremAPI.enabled for true, a mesma região precisará ser definida em gkeOnPremAPI.location.

Se os IDs do projeto e as regiões não forem iguais, a criação do cluster vai falhar.

cloudAuditLogging

Se você quiser integrar os registros de auditoria do servidor da API Kubernetes do cluster com os registros de auditoria do Cloud, preencha a seção cloudAuditLogging.

Observe os seguintes requisitos para novos clusters:

  • Como enableAdvancedCluster está definido como true, é necessário especificar o mesmo caminho em cloudAuditLogging.serviceAccountKeyPath e stackdriver.serviceAccountKeyPath.

  • O ID em cloudAuditLogging.projectID precisa ser o mesmo que o ID em gkeConnect.projectID e stackdriver.projectID.

  • A região definida em cloudAuditLogging.clusterLocation precisa ser igual à região definida em stackdriver.clusterLocation e gkeConnect.location (se o campo estiver incluído no arquivo de configuração). Além disso, se gkeOnPremAPI.enabled for true, a mesma região precisará ser definida em gkeOnPremAPI.location.

Se os IDs do projeto e as regiões não forem iguais, a criação do cluster vai falhar.

clusterBackup

Remova esta seção. Não é possível fazer backup do cluster de administrador em um repositório de dados do vSphere.

autoRepair

Se você quiser ativar o reparo automático de nós no cluster de administrador, defina autoRepair.enabled como true.

secretsEncryption

Como enableAdvancedCluster está definido como true, remova esta seção.

osImageType

Defina o osImageType. para ubuntu_cgroupv2 e ubuntu_containerd.

preparedSecrets

Remova o campo preparedSecrets. Não é possível usar credenciais preparadas quando os domínios de topologia estão ativados.

Exemplo de arquivos de configuração preenchidos

Veja um exemplo de um arquivo de configuração de cluster de administrador preenchido. A configuração ativa alguns, mas não todos, os recursos disponíveis.

vc-01-admin-cluster.yaml

apiVersion: v1
kind: AdminCluster
name: "gke-admin-01"
bundlePath: "/var/lib/gke/bundles/gke-onprem-vsphere-1.31.0-gke.1-full.tgz"
enableAdvancedCluster: true
infraConfigFilePath: "/my-config-folder/vsphere-infrastructure-config.yaml"
network:
  serviceCIDR: "10.96.232.0/24"
  podCIDR: "192.168.0.0/16"
  ipMode:
    type: "static"
    ipBlockFilePath: "/my-config-folder/admin-cluster-ipblock.yaml"
loadBalancer:
  vips:
    controlPlaneVIP: "172.16.20.59"
  kind: "ManualLB"
antiAffinityGroups:
  enabled: false
adminMaster:
  cpus: 4
  memoryMB: 16384
  replicas: 3
  topologyDomains: "admin-cluster-domain"
componentAccessServiceAccountKeyPath: "sa-key.json"
gkeConnect:
  projectID: "my-project-123"
  registerServiceAccountKeyPath: "connect-register-sa-2203040617.json"
stackdriver:
  projectID: "my-project-123"
  clusterLocation: "us-central1"
  enableVPC: false
  serviceAccountKeyPath: "log-mon-sa-2203040617.json"
  disableVsphereResourceMetrics: false
autoRepair:
  enabled: true
osImageType: "ubuntu_containerd"

Preencher o arquivo de configuração da infraestrutura do vSphere

Copie o modelo do arquivo de configuração da infraestrutura do vSphere para o arquivo no diretório especificado no campo infraConfigFilePath no arquivo de configuração do cluster de administrador. Há apenas um arquivo de configuração da infraestrutura do vSphere para o cluster de administrador e todos os clusters de usuário gerenciados.

Secret

Preencha a seção Secret no arquivo de configuração da infraestrutura do vSphere. Esta seção descreve o segredo de credenciais do vSphere, que armazena as credenciais de cada vCenter Server.

VSphereInfraConfig.name

Preencha o campo VSphereInfraConfig,name.

VSphereInfraConfig.credentials.vCenters

Para cada Secret, adicione uma seção VSphereInfraConfig.credentials.vCenters correspondente.

VSphereInfraConfig,topologyDomains

Preencha a seção VSphereInfraConfig.topologyDomains para definir os domínios de topologia.

Preencher o arquivo de bloqueio de IP

Copie o modelo do arquivo de bloco de IP para o arquivo no diretório especificado no campo network.ipMode.ipBlockFilePath no arquivo de configuração do cluster de administrador. Adicione os endereços IP do gateway, da máscara de rede e dos três nós do plano de controle. Para cada endereço IP do nó do plano de controle, adicione isControlPlane: true, conforme mostrado no exemplo para domínios de topologia.

Instalar imagens do SO

  1. Faça o download do pacote normal do Google Distributed Cloud para a estação de trabalho de administrador:

    gcloud storage cp gs://gke-on-prem-release/gke-onprem-bundle/VERSION/gke-onprem-vsphere-VERSION.tgz /var/lib/gke/bundles/gke-onprem-vsphere-VERSION.tgz

    Substitua VERSION pela versão do Google Distributed Cloud que você quer instalar.

    Esse comando faz o download do pacote normal. Não faça o download do pacote completo, porque ele não é compatível com clusters avançados.

  2. Execute gkectl prepare para inicializar o ambiente do vSphere:

    gkectl prepare --config ADMIN_CLUSTER_CONFIG

    Substitua ADMIN_CLUSTER_CONFIG pelo caminho da configuração do cluster de administrador.

    O comando gkectl prepare executa as seguintes tarefas preparatórias:

    • Importa as imagens do SO para o vSphere e as marca como modelos de VM.

    • Se você estiver usando um registro particular do Docker, as imagens do contêiner serão enviadas para seu registro.

    • Como alternativa, valide os atestados de build das imagens do contêiner, verificando se as imagens foram criadas e assinadas pelo Google e estão prontas para implantação.

Crie o cluster de administrador

Crie o cluster de administrador:

gkectl create admin --config ADMIN_CLUSTER_CONFIG

Retomar a criação do cluster de administrador após uma falha

Se a criação do cluster de administrador falhar ou for cancelada, será possível executar o comando create novamente:

gkectl create admin --config ADMIN_CLUSTER_CONFIG

Localizar o arquivo kubeconfig do cluster de administrador

O comando gkectl create admin cria um arquivo kubeconfig chamado kubeconfig no diretório atual. Você precisará desse arquivo kubeconfig mais tarde para interagir com o cluster de administrador.

O arquivo kubeconfig contém o nome do cluster de administrador. Para acessar o nome do cluster, execute o seguinte:

kubectl config get-clusters --kubeconfig ADMIN_CLUSTER_KUBECONFIG

A saída mostra o nome do cluster. Por exemplo:

NAME
gke-admin-tqk8x

Se preferir, é possível alterar o nome e o local do arquivo kubeconfig.

Verifique se o cluster de administrador está em execução

Verifique se o cluster de administrador está em execução:

kubectl get nodes --kubeconfig ADMIN_CLUSTER_KUBECONFIG

Substitua ADMIN_CLUSTER_KUBECONFIG pelo caminho do arquivo kubeconfig do cluster de administrador.

A saída mostra os nós do cluster de administrador. Exemplo:

admin-cp-vm-1   Ready    control-plane,master   ...
admin-cp-vm-2   Ready    control-plane,master   ...
admin-cp-vm-3   Ready    control-plane,master   ...

Configurar o PodTemplate

O rótulo da topologia é preenchido com rótulos de nós no domínio da topologia. A menos que a configuração do domínio de topologia tenha usado a restrição padrão, "topology.kubernetes.io/zone" como a chave de topologia, você precisa configurar a chave de topologia no modelo de pod da implantação, StatefulSet ou ReplicaSet, conforme aplicável.

Por exemplo, suponha que você tenha definido a chave no rótulo da topologia como "topology.examplepetstore.com/zone". No PodTemplate, você especifica a chave como o valor do campo topologySpreadConstraints.topologyKey. Isso permite que o programador do Kubernetes distribua pods pelo domínio de topologia para garantir alta disponibilidade e evitar a concentração excessiva em qualquer área em caso de falha.

Para mais informações sobre como configurar topologySpreadConstraints, consulte Restrições de propagação de topologia de pod na documentação do Kubernetes.

Fazer backup de arquivos

Recomendamos que você faça backup do arquivo kubeconfig do cluster de administrador. Ou seja, copie o arquivo kubeconfig da estação de trabalho do administrador para outro local. Se você perder o acesso à estação de trabalho do administrador ou se o arquivo kubeconfig na estação de trabalho de administrador for excluído acidentalmente, você ainda terá acesso ao cluster de administrador.

Também recomendamos que você faça backup da chave SSH privada do cluster de administrador. Em seguida, se você perder o acesso ao cluster de administrador, ainda vai poder usar o SSH para se conectar aos nós desse cluster. Isso permite resolver e investigar problemas de conectividade com o cluster de administrador.

Extraia a chave SSH do cluster de administrador para um arquivo chamado admin-cluster-ssh-key:

kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG get secrets -n kube-system sshkeys \
    -o jsonpath='{.data.vsphere_tmp}' | base64 -d > admin-cluster-ssh-key

Agora já é possível fazer backup do admin-cluster-ssh-key em outro local que quiser.

Solução de problemas

Consulte Solução de problemas na criação e no upgrade de clusters.

A seguir

Criar um cluster de usuários para uso no domínio de topologia