Criar um cluster de usuário para uso com domínios de topologia

No Google Distributed Cloud, as cargas de trabalho são executadas em um ou mais clusters de usuário. Esta página mostra como criar um cluster de usuários para uso em domínios de topologia do Google Distributed Cloud. O Google Distributed Cloud versão 1.31 ou mais recente é necessário 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 Tarefas e funções de usuário comuns do GKE Enterprise.

Antes de começar

Visão geral do procedimento

As seguintes etapas principais estão envolvidas no uso de gkectl para criar um cluster de usuários:

  1. Preencha o arquivo de configuração do cluster do usuário
    Especifique os detalhes do novo cluster no arquivo de configuração do cluster de usuário.
  2. Preencher o arquivo de bloqueio de IP
    Especifique os endereços IP do gateway, da máscara de rede, dos nós do plano de controle e, opcionalmente, dos nós de trabalho em um arquivo de bloco de IP.
  3. Criar um cluster de usuário
    Execute gkectl create cluster para criar um cluster conforme especificado nos arquivos de configuração.
  4. Verificar se o cluster de usuário está em execução
    Use o kubectl para ver os nós do cluster.

No final deste procedimento, você terá um cluster de usuários em execução para implantar as cargas de trabalho.

Preencha o arquivo de configuração do cluster do usuário

Se você usou gkeadm para criar a estação de trabalho do administrador, gkeadm gerou um modelo para o arquivo de configuração do cluster de usuário chamado user-cluster.yaml. Além disso, gkeadm preencheu alguns campos para você.

Se você não usou gkeadm para criar a estação de trabalho do administrador, use gkectl para gerar um modelo para o arquivo de configuração do cluster de usuário.

Para gerar um modelo para o arquivo de configuração do cluster de usuário:

gkectl create-config cluster --config=OUTPUT_FILENAME --gke-on-prem-version=VERSION

Substitua:

OUTPUT_FILENAME: um caminho de sua escolha para o modelo gerado. Se você omitir essa sinalização, gkectl nomeará o arquivo user-cluster.yaml e o colocará no diretório atual.

VERSION: o número da versão pretendida. Por exemplo, gkectl create-config cluster --gke-on-prem-version=1.31.200-gke.58.

Para se familiarizar com o arquivo de configuração, leia o documento arquivo de configuração do cluster de usuário. É 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

Defina o campo name como um nome de sua escolha para o cluster de usuário.

gkeOnPremVersion

Este campo já foi preenchido para você. Ele especifica a versão do Google Distributed Cloud. Por exemplo, 1.31.200-gke.58

enableAdvancedCluster

Defina enableAdvancedCluster como true.

enableControlplaneV2

O Controlplane V2 é necessário para todos os clusters de usuário da versão 1.30 e mais recentes. Defina enableControlplaneV2 como true.

Quando o Controlplane V2 está ativado, o plano de controle do cluster de usuário é executado nos nós no próprio cluster de usuário.

enableDataplaneV2

Defina enableDataplaneV2 como true.

vCenter

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

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.

  • Decida como você quer que os nós de trabalho recebam os endereços IP deles. As opções são:

    • De um servidor DHCP configurado com antecedência. Defina network.ipMode.type como "dhcp".

    • De uma lista de endereços IP estáticos fornecidos no arquivo de bloco de IP. Defina network.ipMode.type como "static".

    Os nós do plano de controle do cluster de usuário precisam receber os endereços IP de uma lista de endereços estáticos fornecidos no arquivo de bloco de IP. mesmo se os nós de trabalho receberem os endereços de um servidor DHCP.

    Independentemente de você depender de um servidor DHCP ou especificar uma lista de endereços IP estáticos, é necessário ter endereços IP suficientes disponíveis para o cluster de usuário. Para uma explicação de quantos endereços IP você precisa, consulte Planejar seus endereços IP.

  • 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

advancedNetworking

Se você planeja criar um gateway NAT de saída, defina advancedNetworking como true.

multipleNetworkInterfaces

Defina multipleNetworkInterfaces como false. Várias interfaces de rede para pods não são compatíveis com domínios de topologia.

storage

Defina storage.vSphereCSIDisabled como true para desativar a implantação de componentes do CSI do vSphere.

masterNode

  • Se você quiser especificar a CPU e a memória para os nós do plano de controle do cluster de usuário, preencha os campos cpus e memoryMB na seção masterNode.

  • Somente clusters de alta disponibilidade (HA) são compatíveis. Defina o campo replicas como 3 para especificar que o cluster terá três nós do plano de controle.

  • Para ativar o redimensionamento automático dos nós do plano de controle, defina autoResize.enabled como true.

  • Remova toda a seção masterNode.vsphere.

  • Preencha o campo masterNode.topologyDomains com o nome do domínio de topologia em que os nós do plano de controle vão estar.

nodePools

Um pool de nós é um grupo de nós de trabalho em um cluster, que têm a mesma configuração. Por exemplo, talvez você queira configurar um domínio de topologia separado para cada pool de nós. Preencha a seção nodePools para especificar pelo menos um pool de nós.

Para cada pool de nós especificado:

  • Preencha o campo nodePools[i].topologyDomains com o nome do domínio de topologia em que você quer que o pool de nós esteja.

  • Remova todos os campos da seção nodePools[i].vsphere, exceto nodePools[i].vsphere.tags. Especifique essas informações no arquivo de configuração da infraestrutura do vSphere por domínio de topologia.

# advanced-cluster-change #

Defina nodePools[i].osImageType como ubuntu_cgroupv2 ou ubuntu_containerd.

Para informações mais gerais sobre pools de nós, consulte Pools de nós e Como criar e gerenciar pools de nós.

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.

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 Google Cloud 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.

gkeConnect

Seu cluster de usuário precisa estar registrado em uma frota Google Cloud .

Preencha a seção gkeConnect para especificar um projeto host de frota e uma conta de serviço associada. 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á.

É 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 no arquivo de configuração, 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 do cluster disponível para clusters que usam domínios de topologia. Embora o console do Google Cloud, a CLI do Google Cloud 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 projeto do Google Cloud, 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 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.

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:

# advanced-cluster-change #

Defina cloudAuditLogging.serviceAccountKeyPath como o mesmo caminho que stackdriver.serviceAccountKeyPath.

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

  • A região em cloudAuditLogging.clusterLocation precisa ser a mesma definida em gkeConnect.location (se o campo estiver incluído no arquivo de configuração) e stackdriver.clusterLocation. 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.

preparedSecrets

Remova o campo preparedSecrets. Credenciais preparadas não são compatíveis quando os domínios de topologia estão ativados.

Exemplo de arquivos de configuração preenchidos

Confira um exemplo de um arquivo de bloco de IP e um arquivo de configuração de cluster de usuário:

usuario-ipblock.yaml

blocks:
  - netmask: 255.255.255.0
    gateway: 172.16.21.1
    ips:
    - ip: 172.16.21.2
      hostname: worker-vm-1
    - ip: 172.16.21.3
      hostname: worker-vm-2
    - ip: 172.16.21.4
      hostname: worker-vm-3
    - ip: 172.16.21.5
      hostname: worker-vm-4
  - netmask: 255.255.255.0
    gateway: 100.115.223.254
    ips:
    - ip: 100.115.222.205
      hostname: cp-1
      isControlPlane: true
    - ip: 100.115.222.206
      hostname: cp-2
      isControlPlane: true
    - ip: 100.115.222.207
      hostname: cp-3
      isControlPlane: true

user-cluster.yaml

cat user-cluster.yaml
apiVersion: v1
kind: UserCluster
name: "my-user-cluster"
gkeOnPremVersion: 1.31.200-gke.58
enableAdvancedCluster: true
enableControlplaneV2: true
enableDataplaneV2: true
network:
  ipMode:
    type: "static"
    ipBlockFilePath: "user-ipblock.yaml"
  serviceCIDR: 10.96.0.0/20
  podCIDR: 192.168.0.0/16
loadBalancer:
  vips:
    controlPlaneVIP: "100.115.222.200"
    ingressVIP: "172.16.21.30"
  kind: "ManualLB"
  manualLB:
    ingressHTTPNodePort: 32527
    ingressHTTPSNodePort: 30139
    controlPlaneNodePort: 30968
masterNode:
  cpus: 4
  memoryMB: 8192
  replicas: 3
nodePools:
- name: "worker-node-pool1"
  cpus: 4
  memoryMB: 8192
  replicas: 3
  topologyDomains:
  - "domain1"
antiAffinityGroups:
  enabled: false
gkeConnect:
  projectID: "my-project-123"
  location: "us-central1"
  registerServiceAccountKeyPath: "connect-register-sa-2203040617.json"
stackdriver:
  projectID: "my-project-123"
  clusterLocation: "us-central1"
  enableVPC: false
  serviceAccountKeyPath: "log-mon-sa-2203040617.json"
autoRepair:
  enabled: true

Estes são os pontos importantes que você precisa entender no exemplo anterior:

  • O campo nodePools.replicas está definido como 3, o que significa que há três nós de trabalhador em "worker-node-pool". Todos os nós de trabalho usam endereços IP estáticos porque network.ipMode.type está definido como "static".

  • Os endereços IP dos nós do plano de controle e dos nós de trabalho são especificados em um arquivo de bloco de IP. O arquivo de bloco de IP tem quatro endereços para nós de trabalho, mesmo que haja apenas três deles. O endereço IP extra do nó worker é necessário durante o upgrade, a atualização e o reparo automático do cluster. Os endereços IP dos nós do plano de controle têm a flag isControlPlane: true.

  • Clusters avançados, Controlplane V2 e Dataplane V2 estão ativados.

  • O campo masterNode.replicas está definido como 3, então o cluster terá um plano de controle de alta disponibilidade.

  • O VIP do plano de controle está na mesma VLAN que os nós do plano de controle, e o VIP de entrada está na mesma VLAN que os nós de trabalho.

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 usuário. Crie arquivos de bloco de IP separados para o cluster de administrador e para cada cluster de usuário.

Adicione os endereços IP do gateway, da máscara de rede e dos nós do plano de controle ao arquivo de bloco de IP. Para cada endereço IP do nó do plano de controle, adicione isControlPlane: true, conforme mostrado no exemplo anterior. Se você quiser um cluster de usuário de alta disponibilidade (HA, na sigla em inglês), especifique três endereços IP. Caso contrário, especifique um endereço IP. O número de endereços IP especificados para os nós do plano de controle precisa corresponder ao número no campo masterNode.replicas do arquivo de configuração do cluster de usuário.

Se network.ipMode.type estiver definido como "static", adicione os endereços IP dos nós de trabalho ao arquivo de bloco de IP. Especifique um endereço IP extra para usar durante o upgrade, a atualização e o reparo automático do cluster.

Cada endereço de gateway no arquivo de bloco de IPs precisa corresponder ao endereço especificado em um campo topologyDomains[i].network.gateway no arquivo de configuração da infraestrutura do vSphere. Para mais informações, consulte o exemplo de domínios de topologia.

Criar um cluster de usuário

Execute o comando a seguir para criar um cluster de usuário:

gkectl create cluster --kubeconfig ADMIN_CLUSTER_KUBECONFIG --config USER_CLUSTER_CONFIG

Localizar o arquivo kubeconfig do cluster de usuário

O comando gkectl create cluster cria um arquivo kubeconfig chamado USER_CLUSTER_NAME-kubeconfig no diretório atual. Você precisará desse arquivo kubeconfig mais tarde para interagir com seu cluster de usuários.

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

kubectl config get-clusters --kubeconfig USER_CLUSTER_KUBECONFIG

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

NAME
my-user-cluster

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

Verificar se o cluster de usuário está em execução

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

kubectl get nodes --kubeconfig USER_CLUSTER_KUBECONFIG

Substitua USER_CLUSTER_KUBECONFIG pelo caminho do arquivo kubeconfig do cluster de usuário.

A saída mostra os nós do cluster de usuário. Exemplo:

cp-vm-1       Ready    control-plane,master   18m
cp-vm-2       Ready    control-plane,master   18m
cp-vm-3       Ready    control-plane,master   18m
worker-vm-1   Ready                           6m7s
worker-vm-2   Ready                           6m6s
worker-vm-3   Ready                           6m14s

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.

Solução de problemas

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

A seguir