Criar um cluster de administrador usando o Terraform

Se você já gerencia seus recursos do Google Cloud e do VMware no local com o Terraform, use a mesma ferramenta para criar um cluster de administrador para o Google Distributed Cloud (somente software) para VMware. Você define o cluster em um arquivo de configuração do Terraform, e um cluster de inicialização temporário na estação de trabalho de administrador provisiona o cluster de administrador. Também é possível criar clusters de administrador usando gkectl ou o console doGoogle Cloud .

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 de 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 os componentes do Google Distributed Cloud. Para informações sobre como usar um registro particular do Docker, consulte privateRegistry. Nem o Terraform nem o console do Google Cloud são compatíveis com o 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 servidor proxy, 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

Antes de criar o cluster de administrador, você precisa executar o comando gkectl register bootstrap na estação de trabalho do administrador. Esse comando implanta um cluster do Kubernetes no Docker (tipo) na estação de trabalho do administrador. Esse cluster de inicialização hospeda os controladores do Kubernetes necessários para criar o cluster de administrador. Quando você cria o cluster de administrador, os controladores no cluster de inicialização provisionam os nós, executam verificações de simulação e registram o cluster de administrador na frota. O cluster de inicialização é excluído automaticamente após a criação do cluster de administrador.

Confira as etapas gerais para criar um cluster de administrador usando o Terraform:

  1. Preencher o arquivo de configuração. Use o recurso google_gkeonprem_vmware_admin_cluster e o exemplo a seguir para criar o arquivo de configuração main.tf.

  2. Crie um cluster do bootstrap. Execute o comando gkectl register bootstrap para criar o cluster de inicialização. Quando o comando terminar de criar o cluster de inicialização, a saída vai informar que você precisa concluir a configuração do cluster de administrador. O processo continua em execução até que o cluster de administrador seja criado.

  3. Criar um cluster de administrador. Em outra janela do terminal ou em outro computador que tenha acesso à API GKE On-Prem, execute comandos terraform para criar um novo cluster de administrador, conforme especificado no arquivo de configuração main.tf concluído.

Preencher o arquivo de configuração

O exemplo a seguir mostra como criar um cluster de administrador de alta disponibilidade (HA) com três nós de plano de controle com o MetalLB. Na versão 1.28 e mais recentes, os novos clusters de administrador precisam ser de alta disponibilidade. Por causa desse requisito, você precisa definir control_plane_node.replicas como 3.

Para mais informações e outros exemplos, consulte a documentação de referência de google_gkeonprem_vmware_admin_cluster. Para saber como usar um registro particular para imagens do sistema, consulte Configurar um registro de contêiner particular.

Preencha as variáveis de marcador de posição no exemplo a seguir e copie e cole em main.tf. Se você usou gkeadm para criar a estação de trabalho de administrador, abra o arquivo de configuração dela para copiar os valores da seção vCenter para as variáveis de marcador de posição correspondentes.

resource "google_gkeonprem_vmware_admin_cluster" "admin-cluster-metallb" {
  provider = google-beta
  name = "ADMIN_CLUSTER_NAME"
  project = "PROJECT_ID"
  location = "REGION"
  description = "DESCRIPTION"
  bootstrap_cluster_membership = "projects/PROJECT_ID/locations/REGION/memberships/bootstrap-ADMIN_CLUSTER_NAME"
  on_prem_version = "VERSION"
  image_type = "IMAGE_TYPE"
  vcenter {
    address = "VCENTER_ADDRESS"
    datacenter = "DATA_CENTER"
    cluster = "VCENTER_CLUSTER"
    resource_pool = "RESOURCE_POOL"
    datastore = "DATASTORE"
    ca_cert_data = "CA_CERT_DATA"
  }
  network_config {
    service_address_cidr_blocks = ["10.96.232.0/24"]
    pod_address_cidr_blocks = ["192.168.0.0/16"]
    vcenter_network = "NETWORK"
    dhcp_ip_config {
      enabled = true
    }
    host_config {
      dns_servers = ["DNS_SERVERS"]
      ntp_servers = ["NTP_SERVERS"]
    }
    ha_control_plane_config {
      control_plane_ip_block {
        gateway = "GATEWAY"
        netmask = "NETMASK"
        ips {
          hostname = "CONTROL_PLANE_HOST_1"
          ip       = "CONTROL_PLANE_NODE_IP_1"
        }
        ips {
          hostname = "CONTROL_PLANE_HOST_2"
          ip       = "CONTROL_PLANE_NODE_IP_2"
        }
        ips {
          hostname = "CONTROL_PLANE_HOST_3"
          ip       = "CONTROL_PLANE_NODE_IP_3"
        }
      }
    }
  }
  control_plane_node {
     cpus = NUM_CPUS
     memory = MEMORY
     replicas = 3
  }
  load_balancer {
    vip_config {
      control_plane_vip = "CONTROL_PLANE_VIP"
    }
    metal_lb_config {
      enabled = true
    }
  }
}

Substitua:

  • ADMIN_CLUSTER_NAME: o nome do cluster de administrador. O nome pode ter até 20 caracteres.

  • PROJECT_ID: o ID do projeto do Google Cloud .

  • REGION: a região do Google Cloud em que a API GKE On-Prem (gkeonprem.googleapis.com), o serviço de frota (gkehub.googleapis.com) e o serviço do Connect (gkeconnect.googleapis.com) são executados. Especifique us-west1 ou outra região com disponibilidade.

    O campo location corresponde à flag --location no comando gkectl register bootstrap.

  • DESCRIPTION: uma descrição do cluster de administrador.

  • VERSION: a versão do Google Distributed Cloud para o cluster. A criação de um cluster usando o Terraform só é compatível com as versões 1.28 e mais recentes. A versão especificada aqui precisa corresponder à versão do pacote especificada na flag --bundle-path no comando gkectl register bootstrap. Para uma lista de versões, consulte Versões do Google Distributed Cloud somente software para VMware.

  • IMAGE_TYPE: o tipo de imagem do SO a ser executada nos nós do cluster de administrador. Especifique uma das seguintes opções: "ubuntu_containerd", "cos", "ubuntu_cgv2" ou "cos_cgv2".

  • VCENTER_ADDRESS: o endereço do vCenter Server.

    • Arquivo de configuração da estação de trabalho de administrador: use o valor do campo vCenter.credentials.address.

    • O campo vcenter.address corresponde à sinalização --vcenter-address no comando gkectl register bootstrap.

  • DATA_CENTER: o nome do data center do vCenter.

    • Arquivo de configuração da estação de trabalho de administrador: use o valor do campo vCenter.datacenter.

    • O campo vcenter.datacenter corresponde à flag --vcenter-datacenter no comando gkectl register bootstrap.

  • VCENTER_CLUSTER: o nome do cluster do vCenter.

    • Arquivo de configuração da estação de trabalho de administrador: use o valor do campo vCenter.cluster.

    • O campo vcenter.cluster corresponde à sinalização --vcenter-cluster no comando gkectl register bootstrap.

  • RESOURCE_POOL: o nome ou caminho do pool de recursos do vCenter.

    • Arquivo de configuração da estação de trabalho de administrador: use o valor do campo vCenter.resourcePool.

    • O campo vcenter.resource_pool corresponde à flag --vcenter-resource-pool no comando gkectl register bootstrap.

  • DATASTORE: o nome do armazenamento de dados do vCenter. O valor especificado precisa ser um nome, e não um caminho. Se você precisar inserir um caminho, adicione o seguinte campo: folder = "FOLDER"

    • Arquivo de configuração da estação de trabalho de administrador: use o valor do campo vCenter.datastore.

    • O campo vcenter.datastore corresponde à flag --vcenter-datastore no comando gkectl register bootstrap.

    Se você quiser usar uma política de armazenamento de VM para os nós do cluster, remova o campo vcenter.datastore e adicione vcenter.storage_policy_name. Além disso, adicione a flag --vcenter-storage-policy ao comando gkectl register bootstrap. É necessário especificar um valor para vcenter.datastore ou vcenter.storage_policy_name, mas não ambos.

  • FOLDER: o nome da pasta do vCenter em que as VMs do cluster estão localizadas. Se você não estiver usando uma pasta, não adicione o campo folder.

    • Arquivo de configuração da estação de trabalho de administrador: use o valor do campo vCenter.folder.

    • O campo vcenter.folder corresponde à flag --vcenter-folder no comando gkectl register bootstrap.

  • CA_CERT_DATA: o certificado de CA do vCenter no formato PEM, mas com todas as novas linhas substituídas pela string \n.

    1. Execute o comando a seguir para substituir as novas linhas por \n:

      awk 'ORS="\\n" {print}' CA_CERT_PATH_LOCAL
      

      Substitua CA_CERT_PATH_LOCAL pelo caminho para o certificado de CA raiz do seu vCenter Server. Se você usou gkeadm para criar a estação de trabalho do administrador, use o valor do campo caCertPath no arquivo de configuração da estação de trabalho do administrador, que é o caminho no computador local. gkeadm copiou o arquivo de certificado de CA para a estação de trabalho do administrador. Especifique o caminho da estação de trabalho do administrador na flag --vcenter-ca-cert-path no comando gkectl register bootstrap.

    2. Copie a saída do comando anterior e cole-a na variável de marcador de posição CA_CERT_DATA.

  • NETWORK: o nome da sua rede do vCenter.

    • Arquivo de configuração da estação de trabalho de administrador: use o valor do campo vCenter.network.

    • O campo network_config.vcenter_network corresponde à flag --vcenter-network no comando gkectl register bootstrap.

  • GATEWAY: o endereço IP do gateway padrão da sub-rede que tem os nós do cluster do plano de controle.

  • NETMASK: a máscara de rede da sub-rede que tem os nós do cluster do plano de controle.

  • DNS_SERVERS: o endereço IP do servidor DNS.

  • NTP_SERVERS: o endereço IP do servidor de horário (NTP).

  • CONTROL_PLANE_NODE_IP_1, CONTROL_PLANE_NODE_IP_2 e CONTROL_PLANE_NODE_IP_3: os endereços IP dos três nós do plano de controle na seção control_plane_ip_block.ips.

  • CONTROL_PLANE_HOST_1, CONTROL_PLANE_HOST_2 e CONTROL_PLANE_HOST_3: opcionalmente, os nomes de host dos três nós do plano de controle. Se você não inserir um nome do host, remova os campos hostname da configuração.

  • NUM_CPUS: o número de vCPUs de cada nó do plano de controle no cluster de administrador. Precisa ser no mínimo 4.

  • MEMORY: o número de mebibytes de memória para cada nó do plano de controle no cluster de administrador. Precisa ser no mínimo 8.192, mas recomendamos 16.384.

  • CONTROL_PLANE_VIP: o endereço IP que você decidiu configurar no balanceador de carga para o servidor de API Kubernetes do cluster de administrador.

Opcional: configurar um registro particular

Por padrão, durante a criação ou o upgrade do cluster, o software do Google Distributed Cloud somente para VMware extrai imagens do sistema de gcr.io/gke-on-prem-release usando a conta de serviço de acesso a componentes. Se quiser, forneça seu próprio servidor de registro de contêiner para que as imagens do sistema sejam extraídas do seu servidor de registro particular.

Para configurar um registro particular, faça o seguinte:

  1. Adicione o seguinte ao arquivo de configuração do cluster de administrador:

    private_registry_config {
      address = "ADDRESS"
      ca_cert = "CA_CERT"
    }
    

    Substitua:

    • ADDRESS: o endereço IP ou FQDN (nome de domínio totalmente qualificado) da máquina que executa o registro particular.

    • CA_CERT: os dados do certificado de CA da chave pública, mas com todas as novas linhas substituídas pela string \n.

    1. Execute o comando a seguir para substituir as novas linhas por \n:

      awk 'ORS="\\n" {print}' PUBLIC_KEY_PATH
      

      Substitua PUBLIC_KEY_PATH pelo caminho para a chave pública.

    2. Copie a saída do comando anterior e cole-a na variável de marcador de posição CA_CERT.

  2. Se a rede estiver protegida por um servidor proxy, adicione o seguinte:

    proxy {
      url: "PROXY_SERVER_ADDRESS"
      no_proxy: "BYPASS_LIST"
    }
    

    Substitua:

    • PROXY_SERVER_ADDRESS: o endereço HTTP do servidor proxy. Inclua o número da porta mesmo que ele seja igual à porta padrão do esquema.

    • BYPASS_LIST: uma lista separada por vírgulas de endereços IP, intervalos de endereços IP, nomes de host e nomes de domínio que não podem passar pelo servidor proxy.

    Exemplo:

    url: "http://my-proxy.example.local:80"
    no_proxy: "192.0.2.0/24,my-host.example.local,198.51.100.0"
    

    Quando o Google Distributed Cloud envia uma solicitação para um desses endereços, hosts ou domínios, a solicitação ignora o servidor proxy e é enviada diretamente ao destino.

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

Verificar o arquivo de configuração e o plano

No diretório em que main.tf está localizado, execute os seguintes comandos:

  1. Inicialize o Terraform:

    terraform init
    

    O Terraform instala todas as bibliotecas necessárias, como o provedor do Google Cloud . Corrija os erros em main.tf, se necessário.

  2. Crie o plano do Terraform:

    terraform plan -out tfplan
    

    Revise a configuração e faça alterações, se necessário.

Antes de aplicar o plano, crie o cluster de inicialização, conforme descrito na próxima seção.

Criar o cluster de inicialização

Quando você executa o comando gkectl register bootstrap, ele solicita o nome de usuário e a senha da conta do vCenter. Verifique se você tem as credenciais disponíveis. Se você usou gkeadm para criar a estação de trabalho de administrador, o nome de usuário e a senha estão no arquivo credential.yaml.

  1. Faça login na estação de trabalho de administrador usando SSH.

  2. Faça a autenticação com a CLI do Google Cloud:

    gcloud auth login
    
  3. Execute o seguinte comando para criar o cluster de inicialização. Muitos dos valores de flag são iguais aos dos campos main.tf. No entanto, o comando usa outros valores que você precisa especificar nas variáveis de marcador de posição fornecidas.

    gkectl register bootstrap \
        --target-cluster-name=ADMIN_CLUSTER_NAME \
        --project-id=PROJECT_ID \
        --location=REGION \
        --vcenter-address=VCENTER_ADDRESS \
        --vcenter-datacenter=DATA_CENTER \
        --vcenter-cluster=VCENTER_CLUSTER \
        --vcenter-resource-pool=RESOURCE_POOL \
        --vcenter-datastore=DATASTORE \
        --vcenter-network=NETWORK \
        --vcenter-ca-cert-path=CA_CERT_PATH \
        --bundle-path=BUNDLE_PATH \
        --component-access-service-account-key-path=COMPONENT_ACCESS_SA_PATH \
        --register-service-account-key-path=CONNECT_REGISTER_SA_PATH \
        --stackdriver-service-account-key-path=LOG_MON_SA_PATH \
        --cloud-audit-logging-service-account-key-path=CLOUD_AUDIT_SA_PATH \
        --admin-kubeconfig-out=KUBECONFIG_NAME
    

    Substitua o seguinte pelos caminhos da estação de trabalho de administrador:

    • CA_CERT_PATH: o caminho para o certificado de CA raiz do servidor vCenter.
    • BUNDLE_PATH: o caminho para o arquivo do pacote. Se você usou gkeadm para criar a estação de trabalho de administrador, o arquivo de pacote está localizado em /var/lib/gke/bundles/. O nome do arquivo depende da versão do software do Google Distributed Cloud somente para VMware, por exemplo, gke-onprem-vsphere-1.31.0-gke.889-full.tgz.
    • COMPONENT_ACCESS_SA_PATH: o caminho para o arquivo de chave da conta de serviço de acesso a componentes.
    • CONNECT_REGISTER_SA_PATH: o caminho para o arquivo de chave da conta de serviço connect-register.
    • LOG_MON_SA_PATH: o caminho para o arquivo de chave da conta de serviço de geração de registros e monitoramento.
    • CLOUD_AUDIT_SA_PATH: o caminho para o arquivo de chave da conta de serviço de geração de registros de auditoria. Se você não criou uma conta de serviço de geração de registros de auditoria, especifique o caminho para o arquivo de chave da conta de serviço de monitoramento de registros.
    • KUBECONFIG_NAME: o nome do arquivo kubeconfig que o comando gkectl register bootstrap cria. Se você não especificar essa flag, o comando vai criar o arquivo com o nome kubeconfig no diretório de trabalho atual. Se houver um arquivo chamado kubeconfig, o comando o substituirá.

    Modifique o comando conforme necessário para as seguintes flags:

    • Se você especificou uma pasta em main.tf, adicione a seguinte flag: --vcenter-folder=FOLDER
    • Se você especificou uma política de armazenamento de VM em main.tf, remova --vcenter-datastore e adicione a seguinte flag: --vcenter-storage-policy-name=STORAGE_POLICY_NAME
    • Se a estação de trabalho do administrador estiver em uma rede protegida por um servidor proxy, adicione as seguintes flags:

      • --proxy-url=PROXY_URL
      • --no-proxy=NO_PROXY

      Substitua:

      • PROXY_URL: o URL do servidor proxy.
      • NO_PROXY: o valor dos domínios e endereços IP excluídos do proxy, separados por vírgulas.

    Se você adicionar uma flag, adicione o caractere de barra invertida de continuação da linha de comando (\).

  4. Quando solicitado, digite (ou copie e cole) o nome de usuário do vCenter. O nome de usuário não é repetido na tela.

  5. Quando solicitado, digite (ou copie e cole) a senha do vCenter. A senha não é exibida na tela.

O comando executa várias validações. Depois que gkectl criar o cluster de inicialização, será exibida uma saída como esta, que é truncada para facilitar a leitura:

Running workstation validations
- Validation Category: Workstation
    - [SUCCESS] Workstation OS
    - [SUCCESS] Workstation Hardware
    - [SUCCESS] Workstation Package
    - [SUCCESS] Workstation NTP
    - [SUCCESS] Workstation Docker
...
All validation results were SUCCESS.
Unpacking GKE on-prem bundle: /var/lib/gke/bundles/gke-onprem-vsphere-1.31.0-gke.889-full.tgz
...
Successfully created and registered the bootstrap cluster
...
Waiting for preflight checks to run or OnPremAdminCluster to be applied...... -

O processo continua em execução até que o cluster de administrador seja criado.

Se você sair do comando gkectl register bootstrap antes da criação do cluster de administrador, a criação do cluster de administrador vai falhar, e você vai precisar excluir o cluster de inicialização usando o seguinte comando:

gkectl delete bootstrap \
    --target-cluster-name=ADMIN_CLUSTER_NAME \
    --project-id=PROJECT_ID \
    --location=REGION \
     --register-service-account-key-path=CONNECT_REGISTER_SA_PATH

Crie o cluster de administrador

Aplique o plano do Terraform para criar o cluster de administrador:

terraform apply "tfplan"

Leva 15 minutos ou mais para criar o cluster de administrador. É possível visualizar o cluster no console do Google Cloud na página Clusters do GKE.

Conectar-se ao cluster de administrador

O comando gkectl register bootstrap cria um arquivo kubeconfig para o cluster de administrador na estação de trabalho do administrador. Se você não tiver especificado a flag --admin-kubeconfig-out ao executar gkectl register bootstrap, o comando vai criar um arquivo kubeconfig chamado kubeconfig no diretório em que você executou o comando.

É necessário restringir o acesso a esse kubeconfig, porque ele contém as credenciais de autenticação do cluster.

Além disso, é possível executar comandos kubectl somente leitura pelo gateway do Connect.

  1. Execute o comando a seguir em um computador que tenha a CLI gcloud para receber uma entrada kubeconfig que possa acessar o cluster pelo gateway de conexão.

    gcloud container fleet memberships get-credentials ADMIN_CLUSTER_NAME \
        --project=PROJECT_ID
    

    O resultado será o seguinte:

    Starting to build Gateway kubeconfig...
    Current project_id: PROJECT_ID
    A new kubeconfig entry "connectgateway_PROJECT_ID_global_ADMIN_CLUSTER_NAME" has been generated and set as the current context.
    
  2. Agora é possível executar comandos kubectl somente leitura pelo gateway do Connect, como:

    kubectl get pods -A
    

    Se você precisar de privilégios de administrador completos para o cluster de administrador, consulte Configurar o gateway de conexão.