Como gerenciar clusters do GKE com o Config Controller

Prévia

Este produto é coberto pelos Termos de ofertas pré-disponibilidade geral dos Termos de Serviço do Google Cloud Platform. Os produtos pré-disponibilidade geral podem ter suporte limitado, e as mudanças realizadas podem não ser compatíveis com outras versões pré-GA. Para mais informações, consulte as descrições das fases de lançamento.

Neste tutorial, mostramos como usar o blueprint do cluster do GKE para provisionar um cluster do Google Kubernetes Engine (GKE) com o Config Controller. Siga em frente se você for um operador de cluster do GKE e quiser gerenciar de maneira declarativa a configuração do cluster.

O Config Controller é um serviço hospedado para provisionar e orquestrar os recursos do Anthos e do Google Cloud. Ele oferece um endpoint de API que pode provisionar, atuar e orquestrar recursos do Google Cloud como parte do Anthos Config Management.

Os blueprints de KRM são uma maneira de empacotar recursos que são comumente usados juntos ao codificar práticas recomendadas que podem ser implantadas em toda a organização.

O blueprint do cluster do GKE é um blueprint do KRM que inclui todos os recursos necessários para gerenciar um cluster de GKE em uma rede do Google Cloud existente. É possível instanciar o blueprint várias vezes para configurar vários clusters.

Objetivos

• Configurar um cluster do GKE de maneira declarativa.
• Aplicar a configuração usando o Config Controller.

Custos

Neste tutorial, usamos o seguinte componente faturável do Google Cloud:

• Compute Engine
• Google Kubernetes Engine

Para ver uma lista completa de recursos incluídos no blueprint do cluster do GKE, consulte a seção Recursos do pacote do GKE e os respectivos subpacotes.

Para gerar uma estimativa de custo baseada na projeção de uso deste tutorial, use a calculadora de preços.

Observação: o blueprint do cluster do GKE é configurado com padrões destinados a se alinhar às práticas recomendadas de segurança e prontidão para a produção. Por esse motivo, a configuração padrão pode custar mais do que os clusters padrão criados com outros métodos. Revise a configuração com atenção antes de aplicá-la.

Ao concluir este tutorial, exclua os recursos criados para evitar o faturamento contínuo. Para mais informações, consulte Como fazer a limpeza.

Requisitos

• É necessário ter uma assinatura do Google Workspace ou do Cloud Identity.

  Saber como configurar o Cloud Identity.

  Saber como configurar o Google Workspace.

• Sua organização precisa ter um domínio verificado.

  Saber como verificar seu domínio com o Cloud Identity.

  Saber como verificar seu domínio com o Google Workspace.

• Você precisa ter um grupo chamado gke-security-groups na sua organização.

  Para mais informações sobre esse grupo de segurança, consulte Grupos para GKE.

  Maneiras de criar um grupo:

  • Console do Administrador do Google Workspace
  • Aplicativo Grupos (requer Grupos para empresas)
  • Grupos no Console do Cloud (requer Grupos para empresas)

  Saiba como ativar ou desativar o Grupos para empresas.

• Você precisa ter uma instância do Config Controller.

  Saber como configurar o Config Controller.

  Observação: neste tutorial, o KPT é usado para aplicar recursos. O GitOps não é obrigatório.

• Você precisa ter um projeto do Google Cloud. Esse é o projeto em que seu cluster do GKE será criado. Use o projeto em que o cluster do Config Controller está ou outro diferente.

  Saber como criar e gerenciar projetos

• O faturamento precisa estar ativado no seu projeto do Google Cloud.

  Saiba como confirmar se o faturamento está ativado para o projeto.

• Você precisa ter um namespace do Config Controller configurado para gerenciar recursos no projeto.

  Por padrão, o Config Controller vem com o namespace config-control pré-configurado para uso com o Config Connector. As instruções para configurar o Config Controller explicam como autorizar o Config Connector para gerenciar o projeto.

  No entanto, também é possível usar outro namespace configurado de maneira semelhante. Por convenção, esses namespaces geralmente recebem o nome depois do ID do projeto gerenciado.

  Saber como configurar o Config Connector para monitorar seu namespace.

Observação: não é preciso ter um direito do Anthos para seguir este tutorial.

Antes de começar

1. No Console do Cloud, ative o Cloud Shell.

   Ativar o Cloud Shell

   Na parte inferior do Console do Cloud, uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente com o SDK do Cloud pré-instalado com a ferramenta de linha de comando gcloud e os valores já definidos para seu projeto atual. A inicialização da sessão pode levar alguns segundos.

Execute todos os comandos deste tutorial no Cloud Shell.

Configure o ambiente

No Cloud Shell, execute os seguintes comandos:

1. Instale kubectl, a principal interface de linha de comando do Kubernetes:

   gcloud components install kubectl
   

2. Instale kpt, a principal interface de linha de comando para blueprints do KRM:

   gcloud components install kpt
   

   Observação: este tutorial requer kpt v1+.

3. Configure kubectl e kpt para se conectar com o Config Controller:

   gcloud anthos config controller get-credentials CONFIG_CONTROLLER_NAME \
       --location COMPUTE_REGION \
       --project CONFIG_CONTROLLER_PROJECT_ID
   

   Substitua:

   • CONFIG_CONTROLLER_NAME: o nome do cluster do Config Controller.

   • COMPUTE_REGION: a região do cluster do Config Controller (por exemplo, us-central1).

   • CONFIG_CONTROLLER_PROJECT_ID: o ID do projeto do cluster do Config Controller.

   Observação: na prévia, o Config Controller só está disponível na região us-central1.

4. Ative a API Resource Manager:

   gcloud services enable cloudresourcemanager.googleapis.com \
       --project PROJECT_ID
   

   Substitua PROJECT_ID pelo ID do seu projeto.

   Observação: a API Resource Manager é usada pelo Config Connector para gerenciar a ativação de outras APIs de serviço.

5. Instale o CRD ResourceGroup, se ainda não estiver instalado:

   kpt live install-resource-group
   

6. Verifique se o Config Connector está configurado e íntegro no namespace do projeto:

   kubectl get ConfigConnectorContext -n PROJECT_NAMESPACE \
       -o "custom-columns=NAMESPACE:.metadata.namespace,NAME:.metadata.name,HEALTHY:.status.healthy"
   

   Substitua PROJECT_NAMESPACE pelo namespace que você quer usar para gerenciar recursos do projeto (por exemplo, config-control).

   Exemplo de saída:

   NAMESPACE        NAME                                                HEALTHY
   config-control   configconnectorcontext.core.cnrm.cloud.google.com   true
   

Configurar um cluster do GKE

Para configurar um cluster do GKE com o blueprint do cluster do GKE, execute os comandos a seguir.

1. Busque o blueprint do cluster do GKE com kpt, no diretório de trabalho desejado:

   kpt pkg get \
       https://github.com/GoogleCloudPlatform/blueprints.git/catalog/gke@v0.3.0 \
       CLUSTER_NAME
   

   Substitua CLUSTER_NAME pelo nome que você quer usar para o cluster do GKE (por exemplo, hello-cluster).

2. Entre no diretório do cluster:

   cd ./CLUSTER_NAME/
   

3. Configure o pacote modificando o arquivo setters.yaml:

   cat > setters.yaml << EOF
   apiVersion: v1
   kind: ConfigMap
   metadata: # kpt-merge: /setters
     name: setters
   data:
     # The cluster name
     cluster-name: CLUSTER_NAME
     # The environment (set as a label on the cluster)
     environment: dev
     # The compute location (region or zone)
     location: us-central1
     # The project in which to manage cluster resources
     platform-project-id: PROJECT_ID
     # The namespace in which to manage cluster resources
     platform-namespace: PROJECT_NAMESPACE
     # The name of the VPC in which to create a dedicated subnet
     network-name: default
     # The project that the VPC is in
     network-project-id: PROJECT_ID
     # The namespace in which to manage network resources
     networking-namespace: PROJECT_NAMESPACE
     # The private IP range for masters to use when peering to the VPC
     master-ip-range: 192.168.0.0/28
     # The private IP range for nodes to use, allocated to the dedicated subnet
     node-ip-range: 10.4.0.0/22
     # The private IP range for pods to use, allocated to the dedicated subnet
     pod-ip-range: 10.5.0.0/16
     # The private IP range for services to use, allocated to the dedicated subnet
     service-ip-range: 10.6.0.0/16
     # The namespace in which to manage service enablement resources
     projects-namespace: PROJECT_NAMESPACE
     # The group in which to manage the list of groups that can be used for RBAC.
     # Must be named exactly 'gke-security-groups'.
     security-group: gke-security-groups@YOUR_DOMAIN
   EOF
   

   Substitua:

   • PROJECT_ID: ID do projeto.

     Para este tutorial, o cluster e a rede são implantados no mesmo projeto.

   • PROJECT_NAMESPACE: o namespace a ser usado para gerenciar os recursos do projeto (por exemplo, config-control).

     Para este tutorial, o cluster, a rede e a ativação de serviços são gerenciados no mesmo namespace.

   • YOUR_DOMAIN: o domínio usado pelos Grupos (por exemplo, example.com).

     Observação: o valor security-group precisa ser um e-mail do grupo, não uma conta de serviço ou e-mail do usuário. O grupo precisa ter o mesmo nome gke-security-groups.

   Todos os outros campos de dados podem ser reconfigurados conforme desejado.

   Os padrões fornecidos devem funcionar em um projeto vazio com a rede padrão.

4. Renderize os valores setter nos recursos com modelo:

   kpt fn render
   

   Exemplo de saída:

   Package "example/cluster":
   [RUNNING] "gcr.io/kpt-fn/apply-setters:v0.1"
   [PASS] "gcr.io/kpt-fn/apply-setters:v0.1"
     Results:
       [INFO] set field value to "example-us-west4" in file "cluster/cluster.yaml" in field "metadata.name"
       [INFO] set field value to "config-control" in file "cluster/cluster.yaml" in field "metadata.namespace"
       [INFO] set field value to "dev" in file "cluster/cluster.yaml" in field "metadata.labels.gke.io/environment"
       [INFO] set field value to "platform-project-id" in file "cluster/cluster.yaml" in field "metadata.annotations.cnrm.cloud.google.com/project-id"
       ...(10 line(s) truncated, use '--truncate-output=false' to disable)
   
   Package "example/nodepools/primary":
   [RUNNING] "gcr.io/kpt-fn/apply-setters:v0.1"
   [PASS] "gcr.io/kpt-fn/apply-setters:v0.1"
     Results:
       [INFO] set field value to "gke-example-us-east4-primary" in file "nodepools/primary/node-iam.yaml" in field "metadata.name"
       [INFO] set field value to "config-control" in file "nodepools/primary/node-iam.yaml" in field "metadata.namespace"
       [INFO] set field value to "platform-project-id" in file "nodepools/primary/node-iam.yaml" in field "metadata.annotations.cnrm.cloud.google.com/project-id"
       [INFO] set field value to "gke-example-us-east4-primary" in file "nodepools/primary/node-iam.yaml" in field "spec.displayName"
       ...(23 line(s) truncated, use '--truncate-output=false' to disable)
   
   Package "example/subnet":
   [RUNNING] "gcr.io/kpt-fn/apply-setters:v0.1"
   [PASS] "gcr.io/kpt-fn/apply-setters:v0.1"
     Results:
       [INFO] set field value to "platform-project-id-example-us-west4" in file "subnet/subnet.yaml" in field "metadata.name"
       [INFO] set field value to "networking" in file "subnet/subnet.yaml" in field "metadata.namespace"
       [INFO] set field value to "network-project-id" in file "subnet/subnet.yaml" in field "metadata.annotations.cnrm.cloud.google.com/project-id"
       [INFO] set field value to "platform-project-id-example-us-west4" in file "subnet/subnet.yaml" in field "spec.description"
       ...(5 line(s) truncated, use '--truncate-output=false' to disable)
   
   Package "example":
   [RUNNING] "gcr.io/kpt-fn/apply-setters:v0.1"
   [PASS] "gcr.io/kpt-fn/apply-setters:v0.1"
     Results:
       [INFO] set field value to "example" in file "cluster/cluster.yaml" in field "metadata.name"
       [INFO] set field value to "config-control" in file "cluster/cluster.yaml" in field "metadata.namespace"
       [INFO] set field value to "dev" in file "cluster/cluster.yaml" in field "metadata.labels.gke.io/environment"
       [INFO] set field value to "example-project-1234" in file "cluster/cluster.yaml" in field "metadata.annotations.cnrm.cloud.google.com/project-id"
       ...(44 line(s) truncated, use '--truncate-output=false' to disable)
   
   Successfully executed 4 function(s) in 4 package(s).
   

Aplicar mudanças de configuração

As alterações locais nas etapas anteriores não afetam a nuvem até que sejam aplicadas.

Para aplicar as alterações de configuração, execute os comandos a seguir.

1. Inicialize o diretório de trabalho com o kpt, que cria um recurso para acompanhar as alterações:

   kpt live init --namespace PROJECT_NAMESPACE
   

   Substitua PROJECT_NAMESPACE pelo namespace usado para gerenciar recursos do projeto (por exemplo, config-control).

2. Visualize os recursos que serão criados:

   kpt live apply --dry-run
   

   Todos os recursos devem indicar "criado (simulação)".

   Exemplo de saída:

   service.serviceusage.cnrm.cloud.google.com/example-project-1234-example-container created (dry-run)
   computesubnetwork.compute.cnrm.cloud.google.com/example-project-1234-example created (dry-run)
   containercluster.container.cnrm.cloud.google.com/example created (dry-run)
   containernodepool.container.cnrm.cloud.google.com/example-primary created (dry-run)
   iampolicymember.iam.cnrm.cloud.google.com/artifactreader-gke-example-primary created (dry-run)
   iampolicymember.iam.cnrm.cloud.google.com/logwriter-gke-example-primary created (dry-run)
   iampolicymember.iam.cnrm.cloud.google.com/metricwriter-gke-example-primary created (dry-run)
   iamserviceaccount.iam.cnrm.cloud.google.com/gke-example-primary created (dry-run)
   8 resource(s) applied. 8 created, 0 unchanged, 0 configured, 0 failed (dry-run)
   0 resource(s) pruned, 0 skipped, 0 failed (dry-run)
   

3. Aplique os recursos com kpt:

   kpt live apply
   

   Todos os recursos devem indicar "criado".

   Exemplo de saída:

   service.serviceusage.cnrm.cloud.google.com/example-project-1234-example-container created
   computesubnetwork.compute.cnrm.cloud.google.com/example-project-1234-example created
   containercluster.container.cnrm.cloud.google.com/example created
   containernodepool.container.cnrm.cloud.google.com/example-primary created
   iampolicymember.iam.cnrm.cloud.google.com/artifactreader-gke-example-primary created
   iampolicymember.iam.cnrm.cloud.google.com/logwriter-gke-example-primary created
   iampolicymember.iam.cnrm.cloud.google.com/metricwriter-gke-example-primary created
   iamserviceaccount.iam.cnrm.cloud.google.com/gke-example-primary created
   8 resource(s) applied. 8 created, 0 unchanged, 0 configured, 0 failed
   0 resource(s) pruned, 0 skipped, 0 failed
   

Verificar o sucesso

Para verificar se as alterações foram aplicadas e os recursos especificados por eles foram provisionados, execute os comandos a seguir.

1. Aguarde até que os recursos estejam prontos:

   kpt live status --output table --poll-until current
   

   Esse comando pesquisará até que todos os recursos tenham o status Current e uma condição de Ready.

   Use ctrl-c para interromper, se necessário.

   Exemplo de saída:

   NAMESPACE   RESOURCE                                  STATUS      CONDITIONS      AGE     MESSAGE
   config-con  ComputeSubnetwork/example-project-1234-e  Current     Ready           41m     Resource is Ready
   config-con  ContainerCluster/example                  Current     Ready           41m     Resource is Ready
   config-con  ContainerNodePool/example-primary         Current     Ready           41m     Resource is Ready
   config-con  IAMPolicyMember/artifactreader-gke-examp  Current     Ready           41m     Resource is Ready
   config-con  IAMPolicyMember/logwriter-gke-example-pr  Current     Ready           41m     Resource is Ready
   config-con  IAMPolicyMember/metricwriter-gke-example  Current     Ready           41m     Resource is Ready
   config-con  IAMServiceAccount/gke-example-primary     Current     Ready           41m     Resource is Ready
   config-con  Service/example-project-1234-example-con  Current     Ready           41m     Resource is Ready
   

   Observação: os recursos deste blueprint podem levar mais de 40 minutos para serem provisionados.

2. Em caso de erro, use a saída de evento padrão para ver mensagens de erro completas:

   kpt live status
   

Perguntas frequentes

Como alterar um campo imutável?

Primeiro, exclua o recurso com kubectl e aplique novamente com kubectl ou kpt live apply.

Por que kpt live status diz que a condição do meu recurso é <NONE>?

Isso geralmente indica que o Config Connector não foi configurado para o namespace do projeto.

Saber como configurar o Config Connector para monitorar seu namespace.

Modifiquei setters.yaml e apliquei novamente. Por que a saída diz que meus recursos não foram unchanged?

Isso pode acontecer se você tentar aplicar as alterações sem renderizar primeiro.

A renderização executa o pipeline de funções especificadas no(s) Kptfile(s). Uma dessas funções é apply-setters, que usa setters.yaml como entrada.

Execute kpt fn render para executar o pipeline da função.

O cluster está pronto. Por que o pool de nós ainda não foi criado?

O Config Connector usa loops de repetição com espera exponencial ao aplicar alterações aos recursos do Google Cloud. Se não for possível atualizar o recurso por tempo suficiente, a espera máxima de 15 minutos poderá ser alcançada. Isso pode atrasar a aplicação de alterações em outros recursos quando há uma cadeia de dependências.

Como o provisionamento de cluster pode levar mais de 15 minutos e depende do provisionamento de sub-rede, no momento em que o cluster estiver pronto, o pool de nós poderá aguardar até 15 minutos para tentar novamente.

O pool de nós precisa ser provisionado eventualmente, mas se você quiser forçar uma nova tentativa manualmente, exclua e reaplique o recurso afetado.

Limpeza

Se você decidir parar de usar o Config Controller, primeiro limpe todos os recursos criados com o Config Controller e depois exclua o Config Controller.

1. Exclua os recursos com kpt, a partir do diretório de trabalho:

   kpt live destroy
   

2. Aguarde até que todos os recursos sejam excluídos:

   until [ -z "$(kubectl get -R -f . --ignore-not-found | tee /dev/fd/2)" ]; \
   do sleep 1; done
   

   Esse comando pesquisará até que todos os recursos tenham o status Deleted.

   Use ctrl-c para interromper, se necessário.

   Observação: os recursos neste blueprint podem levar mais de cinco minutos para serem excluídos.

A seguir

• Saiba mais sobre blueprints.
• Procure o catálogo de blueprints do KRM.
• Navegue pelo catálogo de blueprints do Terraform.