Criar um cluster de administrador usando `gketl`

Crie um cluster de administrador para o software do Google Distributed Cloud somente para VMware usando gkectl. Use gkectl se precisar gerenciar todo o ciclo de vida do cluster de administrador localmente no ambiente on-premise para atender a requisitos rigorosos de segurança, conformidade ou isolamento. Também é possível criar um cluster de administrador usando o Terraform ou Google Cloud o console.

Antes de começar

• Verifique se você configurou e pode fazer login na estação de trabalho do administrador, conforme descrito em Criar uma estação de trabalho de administrador.

• Verifique se os arquivos de chave JSON das contas de serviço estão na estação de trabalho do administrador.

• Consulte o documento de planejamento de endereços IP. Verifique se há endereços IP suficientes disponíveis para os três nós do plano de controle e um VIP do plano de controle. Se você planeja criar clusters de usuários do kubeception, é necessário ter endereços IP suficientes disponíveis para os nós do plano de controle desses clusters de usuários.

• Consulte a visão geral do balanceamento de carga e reveja sua decisão sobre o tipo de balanceador de carga que você quer usar. Para balanceadores de carga manuais, configure o balanceador de carga antes de criar o cluster de administrador.

• Se você estiver usando gkectl para criar o cluster de administrador, decida se quer usar um registro público ou particular para componentes do Google Distributed Cloud. Para informações sobre como usar um registro particular do Docker, consulte privateRegistry. O Terraform e o Google Cloud console não oferecem suporte ao uso de um registro particular do Docker para componentes do sistema.

• Decida que tipo de sistema operacional você quer executar nos nós de cluster de administrador.

• Se a organização exigir que o tráfego de saída passe por um proxy server, inclua as APIs necessárias e o endereço do Artifact Registry na lista de permissões.

• Na versão 1.29 e mais recentes, as verificações de simulação do lado do servidor são ativadas por padrão. Verificações de simulação do lado do servidor não exigem regras de firewall adicionais. Em Regras de firewall para clusters de administrador, pesquise "Verificações de simulação" e garantir que todas as regras de firewall necessárias sejam configurados. As verificações de simulação do lado do servidor são executadas no cluster de inicialização em vez de localmente na estação de trabalho do administrador.

Visão geral do procedimento

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

1. Preencher os arquivos de configuração. Especifique os detalhes do novo arquivo de configuração de credenciais de administrador e, possivelmente, um arquivo de bloco de IP.

2. Importe imagens do SO para o vSphere e envie imagens de contêiner para o registro particular, se aplicável. Execute gkectl prepare.

3. 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 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.

4. 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.

Se você usa o VPC Service Controls, talvez apareçam erros ao executar alguns comandos gkectl, como "Validation Category: GCP - [UNKNOWN] GCP service: [Stackdriver] could not get GCP services". Para evitar esses erros, adicione o parâmetro --skip-validation-gcp aos comandos.

Preencher o arquivo de configuração

• Verifique se a estação de trabalho do administrador tem a versão necessária do gkectl. Normalmente, você usa a mesma versão do gkectl que será usada ao criar o cluster. Especifique a versão do cluster no campo gkeOnPremVersion no arquivo de configuração do cluster. As regras de versão a seguir são aplicadas durante a criação do cluster:

  • A versão secundária do gkectl não pode ser inferior à versão secundária do cluster. Por exemplo, não é permitido criar um cluster 1.30 usando a versão 1.29 do gkectl. As versões de patch não importam. Por exemplo, é possível usar a versão 1.29.0-gke.1456 do gkectl para criar um cluster com uma versão de patch mais recente, como 1.29.1000-gke.94.

  • A versão secundária do gkectl não pode ser mais de duas versões secundárias mais recentes do que a versão do cluster. Por exemplo, se você estiver criando um cluster 1.28, a versão do gkectl poderá ser 1.29 ou 1.30. No entanto, não é possível usar a versão 1.31 do gkectl, porque ela é três versões secundárias mais recentes do que a versão do cluster.

  Se necessário, consulte Fazer o download gkectl para receber uma versão compatível do gkectl.

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ê.

vCenter

Os campos nesta seção já estão preenchidos com os valores que você inseriu quando criou sua estação de trabalho de administrador.

enableAdvancedCluster

Na versão 1.31, se você quiser ativar o recurso de cluster avançado, defina enableAdvancedCluster como true.

Confira as diferenças entre as versões:

• Na versão 1.31, o recurso de cluster avançado está em pré-lançamento:

  • É possível ativar o cluster avançado no momento da criação do cluster apenas para novos clusters 1.31.

  • Depois que o cluster avançado for ativado, não será possível fazer upgrade do cluster para a versão 1.32. Ative o cluster avançado apenas em um ambiente de teste.

• Na versão 1.32, o recurso de cluster avançado está em disponibilidade geral.

  • Por padrão, os clusters de administrador são criados como clusters avançados. É necessário definir enableAdvancedCluster como false explicitamente se você quiser criar um cluster não avançado.

  • Para clusters que têm o recurso de clusters avançados ativado, os upgrades de cluster são compatíveis.

• Na versão 1.33 e mais recentes, todos os clusters são criados como clusters avançados. Se você definir enableAdvancedCluster como false, a criação do cluster falhará.

network

Preencha a network.controlPlaneIPBlock seção e a network.hostConfig seção. Defina também adminMaster.replicas como 3.

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.

Preencha o restante dos campos na seção de rede do arquivo de configuração conforme necessário.

loadBalancer

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.

Decida qual tipo de balanceamento de carga você quer usar. As opções são:

• Balanceamento de carga em pacote MetalLB. Defina loadBalancer.kind como "MetalLB".

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

Para mais informações, consulte Visão geral do balanceamento de carga.

antiAffinityGroups

Defina antiAffinityGroups.enabled como true ou false de acordo com sua preferência.

Use esse campo para especificar se você quer que o Google Distributed Cloud crie regras de antiafinidade Programador de recursos distribuído (DRS) do VMware para os nós do cluster de administrador, fazendo com que eles sejam distribuídos por pelo menos três hosts físicos no data center.

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 de plano de controle. Defina o campo replicas na seção adminMaster como 3.

proxy

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

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 privateRegistry seção.

Para mais informações sobre como usar um registro particular, incluindo diferenças entre clusters normais e avançados, consulte Configurar um registro de contêiner particular.

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 Google Cloud frota preenchendo a gkeConnect seção. Se você incluir as seções stackdriver e cloudAuditLogging no arquivo de configuração, o ID em gkeConnect.projectID precisará ser o mesmo definido em stackdriver.projectID e cloudAuditLogging.projectID. Se os IDs do projeto não forem iguais, a criação do cluster falhará.

Na versão 1.28 e mais recentes, é possível 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

Se a API GKE On-Prem estiver ativada no seu Google Cloud projeto, todos os clusters do 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

Se você quiser ativar o Cloud Logging e o Cloud Monitoring para o cluster, preencha a seção stackdriver.

Esta seção é obrigatória por padrão. Ou seja, se você não preencher essa seção, inclua a sinalização --skip-validation-stackdriver ao executar gkectl create admin.

Observe os requisitos abaixo:

• Se você ativar o cluster avançado, especifique o mesmo caminho em cloudAuditLogging.serviceAccountKeyPath e stackdriver.serviceAccountKeyPath.

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

• A Google Cloud região definida em stackdriver.clusterLocation precisa ser a mesma 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 requisitos abaixo:

• Se você ativar o cluster avançado, especifique 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 Google Cloud região definida em cloudAuditLogging.clusterLocation precisa ser a mesma 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

Se você quiser ativar o backup do cluster de administrador, defina clusterBackup.datastore como o armazenamento de dados do vSphere em que você quer salvar os backups de cluster.

Se você ativar o cluster avançado, remova esta seção. Não é possível fazer backup do cluster de administrador em um armazenamento 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

Se você quiser ativar a criptografia de Secrets sempre ativada, preencha a secretsEncryption seção.

Se você ativar o cluster avançado, defina secretsEncryption.enabled como false. A criptografia de Secrets sempre ativada não é compatível.

osImageType

Decida o tipo de imagem do SO que você quer usar para os nós do cluster de administrador e preencha a osImageType seção conforme necessário.

Se você ativar o cluster avançado, defina osImageType como ubuntu_cgroupv2 ou ubuntu_containerd.

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.28.0-gke.1-full.tgz"
vCenter:
  address: "vc01.example"
  datacenter: "vc-01"
  cluster: "vc01-workloads-1"
  resourcePool: "vc-01-pool-1"
  datastore: "vc01-datastore-1"
  caCertPath: "/usr/local/google/home/me/certs/vc01-cert.pem""
  credentials:
    fileRef:
      path: "credential.yaml"
      entry: "vCenter"
network:
  hostConfig:
    dnsServers:
    - "203.0.113.1"
    - "198.51.100.1"
    ntpServers:
    - "216.239.35.4"
  serviceCIDR: "10.96.232.0/24"
  podCIDR: "192.168.0.0/16"
  vCenter:
    networkName: "vc01-net-1"
  controlPlaneIPBlock:
    netmask: "255.255.248.0"
    gateway: "21.0.143.254"
    ips:
    - ip: "21.0.140.226"
      hostname: "admin-cp-vm-1"
    - ip: "21.0.141.48"
      hostname: "admin-cp-vm-2"
    - ip: "21.0.141.65"
      hostname: "admin-cp-vm-3"
loadBalancer:
  vips:
    controlPlaneVIP: "172.16.20.59"
  kind: "MetalLB"
antiAffinityGroups:
  enabled: true
adminMaster:
  cpus: 4
  memoryMB: 16384
  replicas: 3
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
clusterBackup:
  datastore: "vc-01-datastore-bu"
autoRepair:
  enabled: true
osImageType: "ubuntu_containerd"

Validar o arquivo de configuração

Depois de preencher o arquivo de configuração do cluster de administrador, execute gkectl check-config para verificar se o arquivo é válido:

gkectl check-config --config ADMIN_CLUSTER_CONFIG

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

Se o comando retornar mensagens, corrija os problemas e valide o arquivo novamente.

Se quiser pular as validações mais demoradas, transmita a sinalização --fast. Para pular validações individuais, use as flags --skip-validation-yyy. Para saber mais sobre o comando check-config, consulte Como executar verificações de simulação.

Instalar imagens do SO

Execute gkectl prepare para inicializar o ambiente do vSphere:

gkectl prepare --config ADMIN_CLUSTER_CONFIG

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.

Se você configurou seu bundlePath para usar um pacote completo, gkectl prepare usa as imagens de SO e contêiner incluídas no pacote, evitando a necessidade de fazer o download delas de redes externas redes. Isso é recomendado para ambientes atrás de um proxy lento ou com acesso limitado à Internet. Para mais informações, consulte Sobre os pacotes do Google Distributed Cloud.

Observação: se você estiver usando nomes DNS internos ou se a estação de trabalho não puder acessar endereços DNS públicos do Google (8.8.8.8 ou 8.8.4.4), será preciso especificar o servidor de nomes interno em /etc/resolv.conf.

Crie o cluster de administrador

Crie o cluster de administrador:

gkectl create admin --config ADMIN_CLUSTER_CONFIG

Se você usa o VPC Service Controls, talvez apareçam erros ao executar alguns comandos gkectl, como "Validation Category: GCP - [UNKNOWN] GCP service: [Stackdriver] could not get GCP services". Para evitar esses erros, adicione o parâmetro --skip-validation-gcp aos comandos.

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.

Gerenciar o arquivo checkpoint.yaml

Esta seção se aplica apenas a clusters de administrador não HA. O arquivo checkpoint.yaml não é usado na criação de clusters de administrador de alta disponibilidade.

Quando você executou o comando gkectl create admin para criar o cluster de administrador, ele criou um arquivo de ponto de controle na mesma pasta do armazenamento de dados do disco de dados do cluster de administrador. Por padrão, esse arquivo tem o nome DATA_DISK_NAME‑checkpoint.yaml. Se o comprimento de DATA_DISK_NAME for maior ou igual a 245 caracteres, devido ao limite de vSphere no tamanho do nome de arquivo, o nome será DATA_DISK_NAME.yaml.

Esse arquivo contém o estado e as credenciais do cluster de administrador e é usado para upgrades futuros. Não exclua esse arquivo, a menos que você esteja seguindo o processo de exclusão de um cluster de administrador.

Se você tiver ativado a criptografia de VM na instância do vCenter Server, precisará ter o privilégio Operações criptográficas.Acesso direto antes de criar ou fazer upgrade do cluster de administrador. Caso contrário, o checkpoint não será enviado. Se você não conseguir esse privilégio, desative o upload do arquivo de checkpoint usando a sinalização oculta --disable-checkpoint ao executar um comando relevante.

O arquivo checkpoint.yaml é atualizado automaticamente quando você executa o comando gkectl upgrade admin ou um comando gkectl update que afeta o cluster de administrador.

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. Por 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   ...

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.

Políticas de RBAC

Quando você preenche a gkeConnect seção no arquivo de configuração do cluster de administrador, o cluster é registrado na sua frota durante a criação ou atualização. Para ativar a funcionalidade de gerenciamento de frota,implanta o agente do Connect e cria uma conta de serviço do Google que representa o projeto em que o cluster está registrado. Google Cloud O agente do Connect estabelece uma conexão com a conta de serviço para processar solicitações para o servidor da API Kubernetes do cluster. Isso permite o acesso aos recursos de gerenciamento de clusters e cargas de trabalho no Google Cloud, incluindo o acesso ao Google Cloud console, que permite interagir com o cluster.

O servidor da API Kubernetes do cluster de administrador precisa autorizar solicitações do agente do Connect. Para garantir isso, as seguintes políticas de controle de acesso baseado em papéis (RBAC) são configuradas na conta de serviço:

• Uma política de falsificação de identidade que autoriza o agente do Connect a enviar solicitações ao servidor da API Kubernetes em nome de uma conta de serviço.

• Uma política de permissões que especifica as operações permitidas em outros recursos do Kubernetes.

A conta de serviço e as políticas do RBAC são necessárias para gerenciar o ciclo de vida dos clusters de usuário no Google Cloud console.