Como gerenciar clusters do GKE com o Config Controller e blueprints de KRM

Neste tutorial, mostramos como compor os blueprints de KRM com o Config Controller para provisionar um cluster do Google Kubernetes Engine (GKE) e a infraestrutura de rede necessária, como uma nuvem privada virtual (VPC) e uma sub-rede para hospedar o cluster do GKE e intervalos de IP nomeados para pods e serviços. Siga em frente se você for um operador de cluster do GKE e quiser gerenciar de maneira declarativa a configuração do cluster e a infraestrutura de rede.

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 de cluster do GKE é um blueprint de KRM que inclui todos os recursos necessários para gerenciar um cluster do GKE em uma sub-rede, intervalos de IP e VPC do Google Cloud. É possível instanciar o blueprint várias vezes para configurar vários clusters.

Os blueprints de rede são um conjunto de blueprints de KRM que ajudam a criar os componentes de rede, como VPC, sub-redes e intervalos de IP de alias, necessários para criar um cluster do GKE. É possível instanciar esses blueprints várias vezes para configurar várias sub-redes e intervalos de IP de alias conforme necessário para vários clusters.

Objetivos

  • Criar de maneira declarativa a infraestrutura de rede necessária para hospedar um cluster do GKE.
  • Configurar um cluster do GKE de maneira declarativa nessa infraestrutura de rede.
  • Aplicar a configuração usando o Config Controller.

Custos

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

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.

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

Requisitos

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 shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.

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

  4. Ative a API Resource Manager:

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

    Substitua PROJECT_ID pelo ID do seu projeto.

  5. 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 uma VPC, uma sub-rede e intervalos de IP do alias para o cluster

Configurar a VPC

Para definir e configurar a VPC com os blueprints de rede, execute os comandos a seguir.

  1. Busque os blueprints de rede com kpt, no diretório de trabalho desejado:

    kpt pkg get \
      https://github.com/GoogleCloudPlatform/blueprints.git/catalog/networking/network/vpc@networking-blueprint-v0.4.0 \
      VPC_NAME
    

    Substitua VPC_NAME pelo nome que você quer usar para a VPC (por exemplo, my-vpc).

  2. Acesse o diretório recém-criado:

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

    Atualize os seguintes campos no arquivo. Forneça seu próprio ID do projeto:

      namespace: PROJECT_NAMESPACE
      network-name: VPC_NAME
      project-id: PROJECT_ID
    

    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.

  4. Adicione um novo campo chamado prefixo no final do arquivo. Verifique se o recuo está correto:

      prefix: NAT-PREFIX
    

    Substitua NAT-PREFIX por um prefixo (por exemplo, nat).

    Isso é usado como prefixo do nome do NAT na configuração da VPC.

    O arquivo será semelhante a este:

    apiVersion: v1
    kind: ConfigMap
    metadata: # kpt-merge: /setters
      name: setters
    data:
      namespace: PROJECT_NAMESPACE
      network-name: VPC_NAME
      project-id: PROJECT_ID
      prefix: NAT-PREFIX
    
  5. Use a função kpt set-namespace para alterar o namespace no blueprint da seguinte maneira:

      kpt fn eval --image set-namespace:v0.1 -- namespace=PROJECT_NAMESPACE
    

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

Configurar a sub-rede

  1. Busque o blueprint de sub-rede com kpt no diretório VPC_NAME:

    kpt pkg get \
      https://github.com/GoogleCloudPlatform/blueprints.git/catalog/networking/network/subnet@networking-blueprint-v0.4.0 \
      SUBNET_NAME
    

    Substitua SUBNET_NAME pelo namespace usado para gerenciar recursos do projeto (por exemplo, gke-subnet).

  2. Mova-o para o diretório da sub-rede:

    cd SUBNET_NAME
    
  3. Edite o arquivo subnet.yaml e adicione o seguinte snippet no final do arquivo, na seção spec. Isso define os dois intervalos nomeados que serão usados para alocar os endereços IP dos pods e serviços do cluster do GKE:

      secondaryIpRange:
      - ipCidrRange: 172.17.0.0/16
        rangeName: pods
      - ipCidrRange: 172.18.0.0/16
        rangeName: services
    

    O arquivo subnet.yaml será parecido com o seguinte:

    apiVersion: compute.cnrm.cloud.google.com/v1beta1
    kind: ComputeSubnetwork
    metadata: # kpt-merge: networking/network-name-subnetwork
      name: network-name-subnetwork # kpt-set: ${prefix}${network-name}-subnetwork
      namespace: networking # kpt-set: ${namespace}
      annotations:
        cnrm.cloud.google.com/project-id: project-id # kpt-set: ${project-id}
        cnrm.cloud.google.com/blueprint: cnrm/landing-zone:networking/v0.4.0
    spec:
      description: Subnetwork
      ipCidrRange: 10.2.0.0/16 # kpt-set: ${ip-cidr-range}
      logConfig:
        metadata: INCLUDE_ALL_METADATA
        aggregationInterval: INTERVAL_10_MIN
        flowSampling: 0.5
      networkRef:
        name: network-name # kpt-set: ${network-name}
      privateIpGoogleAccess: false
      region: us-central1 # kpt-set: ${region}
      secondaryIpRange:
      - ipCidrRange: 172.17.0.0/16
        rangeName: pods
      - ipCidrRange: 172.18.0.0/16
        rangeName: services
    

Renderizar o blueprint

Antes de aplicar o modelo, ele precisa ser renderizado. Essa etapa executa o pipeline de funções, conforme definido no Kptfile, nos recursos do blueprint. Um exemplo típico de uma função que pode ser executada é apply-setters, que aplica os setters que você editou antes.

  1. Agora, volte para o diretório VPC_NAME e use kpt para renderizar os valores setter nos recursos com modelo:

    cd ..
    kpt fn render
    

    A saída será semelhante a:

    [RUNNING] "gcr.io/kpt-fn/apply-setters:v0.1"
    [PASS] "gcr.io/kpt-fn/apply-setters:v0.1" in 5.4s
      Results:
        [INFO] set field value to "ALL_SUBNETWORKS_ALL_IP_RANGES" in file "nat.yaml" in field "spec.sourceSubnetworkIpRangesToNat"
        [INFO] set field value to "10.2.0.0/16" in file "subnet.yaml" in field "spec.ipCidrRange"
    
    Package "my-vpc":
    [RUNNING] "gcr.io/kpt-fn/apply-setters:v0.1"
    [PASS] "gcr.io/kpt-fn/apply-setters:v0.1" in 2.3s
      Results:
        [INFO] set field value to "00-my-vpc-router-nat" in file "nat.yaml" in field "metadata.name"
        [INFO] set field value to "config-control" in file "nat.yaml" in field "metadata.namespace"
        [INFO] set field value to "krm-playground-00" in file "nat.yaml" in field "metadata.annotations.cnrm.cloud.google.com/project-id"
        [INFO] set field value to "00-my-vpc-router" in file "nat.yaml" in field "spec.routerRef.name"
        ...(13 line(s) truncated, use '--truncate-output=false' to disable)
    
    Successfully executed 2 function(s) in 2 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).

    initializing Kptfile inventory info (namespace: config-control)...success
    
  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:

    computerouter.compute.cnrm.cloud.google.com/my-vpc-router created (dry-run)
    computerouternat.compute.cnrm.cloud.google.com/my-vpc-router-nat created (dry-run)
    computesubnetwork.compute.cnrm.cloud.google.com/my-vpc-subnetwork created (dry-run)
    service.serviceusage.cnrm.cloud.google.com/proj-id-00-compute created (dry-run)
    computenetwork.compute.cnrm.cloud.google.com/my-vpc created (dry-run)
    5 resource(s) applied. 5 created, 0 unchanged, 0 configured, 0 failed (dry-run)
    
  3. Aplique os recursos com kpt:

    kpt live apply
    

    Todos os recursos devem indicar "reconciliado".

    Exemplo de saída:

    computenetwork.compute.cnrm.cloud.google.com/my-vpc created
    computerouter.compute.cnrm.cloud.google.com/my-vpc-router created
    computerouternat.compute.cnrm.cloud.google.com/my-vpc-router-nat created
    computesubnetwork.compute.cnrm.cloud.google.com/my-vpc-subnetwork created
    service.serviceusage.cnrm.cloud.google.com/proj-id-00-compute created
    5 resource(s) applied. 5 created, 0 unchanged, 0 configured, 0 failed
    

Verificar se os recursos de rede foram criados

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  ComputeNetwork/my-vpc                   Current     Ready           2m      Resource is Ready
    config-con  ComputeRouter/my-vpc-router             Current     Ready           2m      Resource is Ready
    config-con  ComputeRouterNAT/my-vpc-router-nat      Current     Ready           2m      Resource is Ready
    config-con  ComputeSubnetwork/my-vpc-subnetwork     Current     Ready           2m      Resource is Ready
    config-con  Service/proj-id-00-compute              Current     Ready           2m      Resource is Ready
    
  2. Em caso de erro, use a saída de evento padrão para ver mensagens de erro completas:

    kpt live status
    

    Leva alguns minutos para que todos os recursos sejam criados e estejam prontos.

    Depois que os recursos de rede forem criados, mova um diretório para cima para começar a configurar o cluster do GKE.

    cd ..
    

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@gke-blueprint-v0.4.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 name of this cluster
      cluster-name: CLUSTER_NAME
      # The compute location (region for a regional cluster or zone for a zonal cluster)
      location: us-central1
      # The private IP range for masters to use when peering to the VPC
      master-ip-range: 10.254.0.0/28
      # The reference to the network
      network-ref: projects/PROJECT_ID/global/networks/VPC_NAME
      # The reference to the subnet
      subnet-ref: projects/PROJECT_ID/regions/us-central1/subnetworks/subnetwork
      # The namespace in which to manage cluster resources
      platform-namespace: PROJECT_NAMESPACE
      # The project in which to manage cluster resources
      project-id: PROJECT_ID
      # The namespace in which to manage service enablement resources
      projects-namespace: PROJECT_NAMESPACE
      # The private IP range name for Pods to use, this range must already exist
      pods-range-name: pods
      # The private IP range name for services to use, this range must already exist
      services-range-name: services
      # 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).

    • network-ref: a referência do selfLink à rede em que o cluster será criado.

      Ela está no formato: projects/{network-project-id}/global/networks/{vpc-name}

    • subnet-ref a referência do selfLink para a sub-rede em que o cluster deve ser criado.

      Ela está no formato: projects/{network-project-id}/regions/{region}/subnetworks/{subnet-name}

    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.

Como desativar o Grupos do Google para RBAC

Se você não quiser configurar o RBAC para usar os Grupos do Google para autorização, além de somente indivíduos, altere a configuração do cluster para desativar o recurso Grupos do Google para RBAC. Isso pode ser necessário, por exemplo, se você não criou o gke-security-groups e não tem as permissões para criá-lo. Saiba mais em Configuração de grupos

  1. Para desativar os Grupos do Google para RBAC, basta editar o arquivo cluster/cluster.yaml diretamente.

  2. Encontre a seção com o campo authenticatorGroupsConfig e remova as três linhas a seguir:

      # Enable Groups for GKE, to allow role binding to Google Groups.
      authenticatorGroupsConfig:
        securityGroup: gke-security-group@example.com # kpt-set: ${security-group}
    
  3. Salve o arquivo

    Isso desativa o recurso RBAC para Grupos do Google.

Renderizar o blueprint

Essa etapa executa o pipeline de funções, conforme definido no Kptfile, nos recursos do blueprint. Normalmente, isso executa apply-setters, que aplica os setters que você editou antes.

  1. 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" in 3.3s
      Results:
        [INFO] set field value to "example-us-west4" in file "cluster.yaml" in field "metadata.name"
        [INFO] set field value to "config-control" in file "cluster.yaml" in field "metadata.namespace"
        [INFO] set field value to "project-id" in file "cluster.yaml" in field "metadata.annotations.cnrm.cloud.google.com/project-id"
        ...(9 line(s) truncated, use '--truncate-output=false' to disable)
    
    Package "test-00/nodepools/primary":
    [RUNNING] "gcr.io/kpt-fn/apply-setters:v0.1"
    [PASS] "gcr.io/kpt-fn/apply-setters:v0.1" in 2.2s
      Results:
        [INFO] set field value to "gke-example-us-east4-primary" in file "node-iam.yaml" in field "metadata.name"
        [INFO] set field value to "config-control" in file "node-iam.yaml" in field "metadata.namespace"
        [INFO] set field value to "project-id" in file "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 "node-iam.yaml" in field "spec.displayName"
        ...(23 line(s) truncated, use '--truncate-output=false' to disable)
    
    Package "test-00":
    [RUNNING] "gcr.io/kpt-fn/apply-setters:v0.1"
    [PASS] "gcr.io/kpt-fn/apply-setters:v0.1" in 2.3s
      Results:
        [INFO] set field value to "test-00" in file "cluster.yaml" in field "metadata.name"
        [INFO] set field value to "config-control" in file "cluster.yaml" in field "metadata.namespace"
        [INFO] set field value to "krm-playground-00" in file "cluster.yaml" in field "metadata.annotations.cnrm.cloud.google.com/project-id"
        ...(36 line(s) truncated, use '--truncate-output=false' to disable)
    
    Successfully executed 3 function(s) in 3 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/proj-id-00-test-00-container created (dry-run)
    containercluster.container.cnrm.cloud.google.com/test-00 created (dry-run)
    containernodepool.container.cnrm.cloud.google.com/test-00-primary created (dry-run)
    iampolicymember.iam.cnrm.cloud.google.com/artifactreader-gke-test-00-primary created (dry-run)
    iampolicymember.iam.cnrm.cloud.google.com/logwriter-gke-test-00-primary created (dry-run)
    iampolicymember.iam.cnrm.cloud.google.com/metricwriter-gke-test-00-primary created (dry-run)
    iamserviceaccount.iam.cnrm.cloud.google.com/gke-test-00-primary created (dry-run)
    7 resource(s) applied. 7 created, 0 unchanged, 0 configured, 0 failed (dry-run)
    
  3. Aplique os recursos com kpt:

    kpt live apply
    

    Todos os recursos devem indicar "criado".

    Exemplo de saída:

    iamserviceaccount.iam.cnrm.cloud.google.com/gke-test-00-primary created
    service.serviceusage.cnrm.cloud.google.com/proj-id-00-test-00-container created
    containercluster.container.cnrm.cloud.google.com/test-00 created
    containernodepool.container.cnrm.cloud.google.com/test-00-primary created
    iampolicymember.iam.cnrm.cloud.google.com/artifactreader-gke-test-00-primary created
    iampolicymember.iam.cnrm.cloud.google.com/logwriter-gke-test-00-primary created
    iampolicymember.iam.cnrm.cloud.google.com/metricwriter-gke-test-00-primary created
    7 resource(s) applied. 7 created, 0 unchanged, 0 configured, 0 failed
    

Verificar se os recursos do cluster do GKE foram criados

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  ContainerCluster/test-00                  Current     Ready           12m     Resource is Ready
    config-con  ContainerNodePool/test-00-primary         Current     Ready           12m     Resource is Ready
    config-con  IAMPolicyMember/artifactreader-gke-test-  Current     Ready           12m     Resource is Ready
    config-con  IAMPolicyMember/logwriter-gke-test-00-pr  Current     Ready           12m     Resource is Ready
    config-con  IAMPolicyMember/metricwriter-gke-test-00  Current     Ready           12m     Resource is Ready
    config-con  IAMServiceAccount/gke-test-00-primary     Current     Ready           12m     Resource is Ready
    config-con  Service/proj-id-00-test-00-contai         Current     Ready           12m     Resource is Ready
    
  2. Em caso de erro, use a saída de evento padrão para ver mensagens de erro completas:

    kpt live status
    

Perguntas frequentes

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 primeiro os recursos do cluster com kpt a partir do diretório de trabalho do blueprint do cluster do GKE:

    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.

  3. Exclua os recursos de rede se você os tiver criado como parte deste tutorial. Use kpt no diretório da VPC que você criou para o blueprint:

    kpt live destroy
    
  4. 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.

A seguir