Configurar o Config Controller

Esta página mostra como configurar o Config Controller.

O Config Controller fornece um plano de controle gerenciado, baseado no Kubernetes. Além disso, as instâncias do Config Controller são pré-instaladas com o Policy Controller, o Config Sync e o Config Connector. Ao usar esses componentes, é possível aproveitar as ferramentas e os fluxos de trabalho do Kubernetes para gerenciar recursos do Google Cloud e alcançar consistência usando um fluxo de trabalho do GitOps. Para saber mais, consulte a Visão geral do Config Controller.

Se você estiver criando uma instância do Config Controller pela primeira vez, consulte Guia de início rápido: gerenciar recursos com o Config Controller.

Limitações

• Como as instâncias do Config Controller são totalmente gerenciadas, não é possível registrá-las com uma frota.

Antes de começar

Antes de configurar o Config Controller, siga estas etapas:

1. Instale e inicialize a Google Cloud CLI, que fornece a Google Cloud CLI usada nestas instruções. Se você usa o Cloud Shell, a Google Cloud CLI já está instalada.

2. Como o kubectl não é instalado por padrão pela Google Cloud CLI, instale-o:

   gcloud components install kubectl
   

3. Defina o projeto do Google Cloud em que você quer hospedar o Config Controller:

   gcloud config set project PROJECT_ID
   

   Substitua PROJECT_ID pelo projeto do Google Cloud que hospedará o Config Controller.

4. Ative as APIs necessárias:

   gcloud services enable krmapihosting.googleapis.com \
       anthos.googleapis.com  \
       cloudresourcemanager.googleapis.com \
       serviceusage.googleapis.com
   

Criar uma instância do Config Controller

É possível criar uma instância do Config Controller com o cluster padrão ou um cluster do Autopilot. Os dois tipos de clusters são privados.

Selecione um cluster padrão se quiser mais opções de personalização. Selecione um cluster do Autopilot se quiser uma instalação mais rápida, escalonamento automático horizontal e vertical de pods e recursos de segurança aprimorados como Container-Optimized OS, Nós protegidos do GKE, Identidade da carga de trabalho e Inicialização segura.

1. Crie uma instância do Config Controller:

   Standard

   Crie uma instância do Config Controller com o suporte de um cluster particular do GKE:

   gcloud anthos config controller create CONFIG_CONTROLLER_NAME \
       --location=LOCATION
   

   Substitua:

   • CONFIG_CONTROLLER_NAME: o nome que você quer dar à instância do Config Controller.

   • LOCATION: adicione uma das seguintes regiões:

     • us-central1
     • us-east1
     • us-east4
     • us-east5
     • us-west2
     • northamerica-northeast1
     • northamerica-northeast2
     • europe-north1
     • europe-west1
     • europe-west3
     • europe-west6
     • australia-southeast1
     • australia-southeast2
     • asia-northeast1
     • asia-northeast2
     • asia-southeast1

     Essa é a região em que sua instância do Config Controller foi criada. Nenhuma outra região é compatível.

   É possível definir vários parâmetros opcionais ao criar uma instância padrão do Config Controller. Para ver a lista completa de opções, consulte a documentação do gcloud anthos config controller create.

   Autopilot

   Para criar uma instância do Config Controller com suporte de um cluster particular do GKE do Autopilot, execute o seguinte comando:

   gcloud anthos config controller create CONFIG_CONTROLLER_NAME \
       --location=LOCATION \
       --full-management
   

   Substitua:

   • CONFIG_CONTROLLER_NAME: o nome que você quer dar ao controlador.

   • LOCATION: adicione uma das seguintes regiões:

     • us-central1
     • us-east1
     • us-east4
     • us-east5
     • us-west2
     • northamerica-northeast1
     • northamerica-northeast2
     • europe-north1
     • europe-west1
     • europe-west3
     • europe-west6
     • australia-southeast1
     • australia-southeast2
     • asia-northeast1
     • asia-northeast2
     • asia-southeast1

     Nenhuma outra região é compatível.

   Essa operação pode levar até 15 minutos para ser concluída. Se você quiser observar o que está acontecendo durante a criação, visualize o Explorador de registros no console do Google Cloud.

   Acesse o Explorador de registros

   Se você encontrar erros durante a criação, consulte Resolver problemas do Config Controller para ver orientações sobre como resolver problemas comuns.

2. Para verificar se as instâncias do Config Controller foram criadas, veja a lista de instâncias do Config Controller:

   gcloud anthos config controller list --location=LOCATION
   

   Você verá um valor de RUNNING na coluna de status. Se o status for CREATING, significa que sua instância do Config Controller ainda está sendo criada e você deve aguardar. Se ERROR for exibido, isso significa que há um problema que você não pode resolver. Entre em contato com o suporte do Google Cloud para receber ajuda.

3. Para se comunicar com o endpoint do Config Controller, consulte as credenciais e as informações do endpoint apropriadas:

   gcloud anthos config controller get-credentials CONFIG_CONTROLLER_NAME \
       --location LOCATION
   

Usar a instância do Config Controller

Agora que você criou uma instância do Config Controller, pode começar a usar os componentes instalados e concluir as seguintes tarefas:

• Use o Config Connector para criar recursos do Google Cloud. Se você já tiver recursos do Google Cloud que queira usar com o Config Controller, saiba mais sobre Como adquirir um recurso existente.

• Use o Policy Controller para aplicar restrições que aplicam a conformidade regulatória e os padrões do Kubernetes.

• Depois de configurar o Config Sync, na seção a seguir, sincronize sua instância do Config Controller com configs (incluindo restrições do Policy Controller e recursos do Config Connector) armazenados em uma fonte de verdade.

Para um exemplo guiado que mostra como concluir essas tarefas com o Config Controller, consulte o Guia de início rápido: gerenciar recursos com o Config Controller.

Configurar a instância do Config Controller

As seções a seguir explicam como configurar os componentes da instância do Config Controller.

Aviso: não edite, atualize ou exclua o cluster do Google Kubernetes Engine que faz backup da instância do Config Controller porque isso pode danificar sua instância. Para mais informações, consulte Mudanças incompatíveis no Config Controller.

Configurar o Config Connector

Não é preciso gerenciar as configurações de instalação do Config Connector. No entanto, você precisa conceder permissões do Config Controller para gerenciar recursos do Google Cloud:

1. Defina uma variável de ambiente para o e-mail da sua conta de serviço:

   export SA_EMAIL="$(kubectl get ConfigConnectorContext -n config-control \
       -o jsonpath='{.items[0].spec.googleServiceAccount}' 2> /dev/null)"
   

2. Crie a vinculação de política:

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member "serviceAccount:${SA_EMAIL}" \
       --role "ROLE" \
       --project PROJECT_ID
   

   Substitua:

   • PROJECT_ID: ID do projeto;
   • ROLE: um conjunto de papéis predefinidos ou funções personalizadas que atendem às suas necessidades. Como alternativa, use roles/owner para ambientes que não sejam de produção. Para saber mais sobre as permissões de IAM do Config Controller, leia Permissões do IAM para o Config Controller.

   Se a operação anterior falhar, verifique se os controladores estão prontos:

   kubectl wait pod --all --all-namespaces --for=condition=Ready
   

Depois de conceder essas permissões, você poderá começar a criar recursos do Google Cloud.

Configurar o Policy Controller

A configuração do Policy Controller é opcional, mas você pode fazer alterações na instalação padrão, se necessário.

Para configurar o Policy Controller, edite os campos spec.policyController do objeto ConfigManagement chamado config-management. O Config Controller cria automaticamente esse objeto ConfigManagement durante a instalação. Ao editar o objeto ConfigManagement, não defina spec.policyController.enabled como false. O Config Controller substitui automaticamente essa alteração. Para o monitoramento, você também precisa permitir que o Policy Controller envie métricas.

Execute este comando para permitir que o Policy Controller envie métricas:

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:PROJECT_ID.svc.id.goog[gatekeeper-system/gatekeeper-admin]" \
  --role=roles/monitoring.metricWriter

Substitua PROJECT_ID pelo ID do projeto do Google Cloud do cluster.

Configurar o Config Sync

Se você quiser que sua instância do Config Controller seja sincronizada a partir das configurações armazenadas em uma fonte de verdade, será necessário configurar o Config Sync.

Se você quiser usar o Config Sync para criar recursos do Config Connector, verifique se também concedeu permissão ao Config Controller para gerenciar recursos.

Para configurar o Config Sync, crie e edite um objeto RootSync:

1. Para sincronizar a partir de um repositório externo (por exemplo, GitHub), configure o Cloud NAT com o GKE. Isso é necessário porque os nós do cluster particular não têm acesso de saída à Internet.

2. Salve um dos seguintes manifestos como root-sync.yaml. Use a versão do manifesto que corresponde ao tipo de origem das suas configurações.

   Git

   # root-sync.yaml
   apiVersion: configsync.gke.io/v1beta1
   kind: RootSync
   metadata:
     name: ROOT_SYNC_NAME
     namespace: config-management-system
   spec:
     sourceType: git
     sourceFormat: ROOT_FORMAT
     git:
       repo: ROOT_REPOSITORY
       revision: ROOT_REVISION
       branch: ROOT_BRANCH
       dir: ROOT_DIRECTORY
       auth: ROOT_AUTH_TYPE
       gcpServiceAccountEmail: ROOT_EMAIL
       secretRef:
         name: ROOT_SECRET_NAME
       noSSLVerify: ROOT_NO_SSL_VERIFY
       caCertSecretRef:
         name: ROOT_CA_CERT_SECRET_NAME
   

   Substitua:

   • ROOT_SYNC_NAME: adicione o nome do objeto RootSync.
   • ROOT_FORMAT: adicione unstructured para usar um repositório não estruturado ou hierarchy para usar um repositório hierárquico. Esses valores diferenciam maiúsculas de minúsculas. Este campo é opcional e o valor padrão é hierarchy. Recomendamos que você adicione unstructured como esse formato para organizar suas configurações da maneira mais conveniente para você.
   • ROOT_REPOSITORY: adicione o URL do repositório Git para usar como repositório raiz. É possível inserir URLs usando o protocolo HTTPS ou SSH. Por exemplo, https://github.com/GoogleCloudPlatform/anthos-config-management-samples usa o protocolo HTTPS. Este campo é obrigatório.
   • ROOT_REVISION: adiciona a revisão Git (tag ou hash) de sincronização. Esse campo é opcional, e o valor padrão é HEAD. A partir da versão 1.17.0 do Config Sync, também é possível especificar um nome de ramificação no campo revision. Ao usar um hash na versão 1.17.0 ou mais recente, ele precisa ser um hash completo, não um formato abreviado.
   • ROOT_BRANCH: adicione a ramificação do repositório para sincronizar. Esse campo é opcional, e o valor padrão é master. A partir da versão 1.17.0 do Config Sync, é recomendável usar o campo revision para especificar um nome de ramificação para simplificar. Se os campos revision e branch forem especificados, revision terá precedência sobre branch.
   • ROOT_DIRECTORY: adicione o caminho no repositório Git ao diretório raiz que contém a configuração com a qual você quer sincronizar. Esse campo é opcional, e o padrão é o diretório raiz (/) do repositório.

   • ROOT_AUTH_TYPE: adicione um dos seguintes tipos de autenticação:

     • none: não usa autenticação
     • ssh: use um par de chaves SSH
     • cookiefile: use um cookiefile
     • token: usar um token
     • gcpserviceaccount: use uma conta de serviço do Google para acessar um Cloud Source Repositories.
     • gcenode: use uma conta de serviço do Google para acessar um Cloud Source Repositories. Selecione esta opção somente se a identidade da carga de trabalho não estiver ativada em seu cluster.

     Para mais informações sobre esses tipos de autenticação, consulte Como conceder acesso somente leitura do Config Sync ao Git.

     Este campo é obrigatório.

   • ROOT_EMAIL: se você adicionou gcpserviceaccount como ROOT_AUTH_TYPE, adicione o endereço de e-mail da sua conta de serviço do Google. Por exemplo, acm@PROJECT_ID.iam.gserviceaccount.com.

   • ROOT_SECRET_NAME: adicione o nome do secret; Se este campo for definido, será necessário adicionar a chave pública do Secret ao provedor do Git. Este campo é opcional.

   • ROOT_NO_SSL_VERIFY: para desativar a verificação do certificado SSL, defina esse campo como true. O valor padrão é false.

   • ROOT_CA_CERT_SECRET_NAME: adicione o nome do secret; Se esse campo estiver definido, seu provedor Git precisará usar um certificado emitido por essa autoridade certificadora (CA, na sigla em inglês). O secret precisa conter o certificado de CA em uma chave chamada cert. Este campo é opcional.

     Para saber mais sobre como configurar o objeto do secret para o certificado de CA, consulte Configurar operador de uma autoridade de certificação.

   Para uma explicação sobre os campos e uma lista completa de campos que você pode adicionar ao campo spec, consulte Campos RootSync.

   Esse manifesto cria um objeto RootSync que usa o Git como origem.

   OCI

   # root-sync.yaml
   apiVersion: configsync.gke.io/v1beta1
   kind: RootSync
   metadata:
     name: ROOT_SYNC_NAME
     namespace: config-management-system
   spec:
     sourceType: oci
     sourceFormat: ROOT_FORMAT
     oci:
       image: ROOT_IMAGE
       dir: ROOT_DIRECTORY
       auth: ROOT_AUTH_TYPE
       gcpServiceAccountEmail: ROOT_EMAIL
   

   Substitua:

   • ROOT_SYNC_NAME: adicione o nome do objeto RootSync.
   • ROOT_FORMAT: adicione unstructured para usar um repositório não estruturado ou hierarchy para usar um repositório hierárquico. Esses valores diferenciam maiúsculas de minúsculas. Este campo é opcional e o valor padrão é hierarchy. Recomendamos que você adicione unstructured como esse formato para organizar suas configurações da maneira mais conveniente para você.
   • ROOT_IMAGE: o URL da imagem OCI para usar como repositório raiz, por exemplo, LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/PACKAGE_NAME. Por padrão, a imagem é extraída da tag latest, mas é possível extrair imagens por TAG ou DIGEST. Especifique TAG ou DIGEST no PACKAGE_NAME:
     • Para extrair por TAG: LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/PACKAGE_NAME:TAG
     • Para extrair por DIGEST: LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/PACKAGE_NAME@sha256:DIGEST

   Cuidado: O Config Sync exige que a camada OCI seja compactada em tar ou tar+gzip Outros formatos (por exemplo, tar+bz2) não serão reconhecidos pelo Config Sync. A mudança de um REPO válido para uma imagem OCI com um formato incompatível fará com que os recursos gerenciados sejam removidos sem um erro.

   • ROOT_DIRECTORY: adicione o caminho no repositório Git ao diretório raiz que contém a configuração com a qual você quer sincronizar. Esse campo é opcional, e o padrão é o diretório raiz (/) do repositório.

   • ROOT_AUTH_TYPE: adicione um dos seguintes tipos de autenticação:

     • none: não usa autenticação
     • gcenode: use a conta de serviço padrão do Compute Engine para acessar uma imagem no Artifact Registry. Selecione esta opção somente se a identidade da carga de trabalho não estiver ativada em seu cluster.
     • gcpserviceaccount: use uma conta de serviço do Google para acessar uma imagem.

     Este campo é obrigatório.

   • ROOT_EMAIL: se você adicionou gcpserviceaccount como ROOT_AUTH_TYPE, adicione o endereço de e-mail da sua conta de serviço do Google. Por exemplo, acm@PROJECT_ID.iam.gserviceaccount.com.

   Para uma explicação sobre os campos e uma lista completa de campos que você pode adicionar ao campo spec, consulte Campos RootSync.

   Esse manifesto cria um objeto RootSync que usa uma imagem OCI como origem.

   Helm

   # root-sync.yaml
   apiVersion: configsync.gke.io/v1beta1
   kind: RootSync
   metadata:
     name: ROOT_SYNC_NAME
     namespace: config-management-system
   spec:
     sourceType: helm
     sourceFormat: ROOT_FORMAT
     helm:
       repo: ROOT_HELM_REPOSITORY
       chart: HELM_CHART_NAME
       version: HELM_CHART_VERSION
       releaseName: HELM_RELEASE_NAME
       namespace: HELM_RELEASE_NAMESPACE
       values:
         foo:
           bar: VALUE_1
         baz:
         - qux: VALUE_2
           xyz: VALUE_3
       includeCRDs: HELM_INCLUDE_CRDS
       auth: ROOT_AUTH_TYPE
         gcpServiceAccountEmail: ROOT_EMAIL
         secretRef:
           name: ROOT_SECRET_NAME
   

   Substitua:

   • ROOT_SYNC_NAME: adicione o nome do objeto RootSync.
   • ROOT_FORMAT: adicione unstructured para usar um repositório não estruturado ou hierarchy para usar um repositório hierárquico. Esses valores diferenciam maiúsculas de minúsculas. Este campo é opcional e o valor padrão é hierarchy. Recomendamos que você adicione unstructured como esse formato para organizar suas configurações da maneira mais conveniente para você.
   • ROOT_HELM_REPOSITORY: o URL do repositório do Helm a ser usado como o repositório raiz. É possível inserir URLs usando o protocolo HTTPS ou SSH. Por exemplo, https://github.com/GoogleCloudPlatform/anthos-config-management-samples usa o protocolo HTTPS. Este campo é obrigatório.
   • HELM_CHART_NAME: adicione o nome do seu gráfico do Helm. Este campo é obrigatório.
   • HELM_CHART_VERSION: a versão do gráfico. Este campo é opcional. Se nenhum valor for especificado, a versão mais recente será usada.
   • HELM_RELEASE_NAME: o nome da versão do Helm. Este campo é opcional.
   • HELM_RELEASE_NAMESPACE: o namespace de destino de uma versão. Ele define apenas um namespace para os recursos que contêm namespace: {{ .Release.Namespace }} nos modelos. Este campo é opcional. Se nenhum valor for especificado, o namespace padrão config-management-system será usado.
   • HELM_INCLUDE_CRDS: defina como true se você quiser que o modelo do Helm também gere uma CustomResourceDefinition. Este campo é opcional. Se nenhum valor for especificado, o padrão será false e um CRD não será gerado.
   • VALUE: valores a serem usados em vez de valores padrão que acompanham o gráfico Helm. Formate esse campo da mesma forma que o arquivo values.yaml do gráfico do helm. Este campo é opcional.

   • ROOT_AUTH_TYPE: adicione um dos seguintes tipos de autenticação:

     • none: não usa autenticação
     • token: use um nome de usuário e uma senha para acessar um repositório particular do Helm.
     • gcenode: use a conta de serviço padrão do Compute Engine para acessar uma imagem no Artifact Registry. Selecione esta opção somente se a identidade da carga de trabalho não estiver ativada em seu cluster.
     • gcpserviceaccount: use uma conta de serviço do Google para acessar uma imagem.

     Este campo é obrigatório.

   • ROOT_EMAIL: se você adicionou gcpserviceaccount como ROOT_AUTH_TYPE, adicione o endereço de e-mail da sua conta de serviço do Google. Por exemplo, acm@PROJECT_ID.iam.gserviceaccount.com.

   • ROOT_SECRET_NAME: adicione o nome do secret se token for o ROOT_AUTH_TYPE. Este campo é opcional.

   Para uma explicação sobre os campos e uma lista completa de campos que você pode adicionar ao campo spec, consulte Campos RootSync.

   Esse manifesto cria um objeto RootSync que usa o Git como origem.

3. Para criar o Config Sync, crie um objeto RootSync aplicando o manifesto:

   kubectl apply -f root-sync.yaml
   

4. Para verificar se as alterações foram aplicadas, veja o objeto RootSync:

   kubectl describe rootsync ROOT_SYNC_NAME -n config-management-system
   

Fazer upgrade do Config Controller

Como o Config Controller é um serviço gerenciado, ele é atualizado automaticamente pelo Google. Para detalhes sobre novos recursos e saber quais versões do Config Sync, Policy Controller e Config Connector o Config Controller usa, consulte as Notas da versão do Config Controller.

Excluir a instância do Config Controller

Se você decidir parar de usar uma instância do Config Controller, limpe todos os recursos do Config Connector criados antes de excluir o cluster do Config Controller.

Excluir o controlador de configuração sem primeiro excluir os recursos provisionados deixa os recursos em um estado abandonado. Os recursos ainda existem no Google Cloud (e geram cobranças de faturamento), mas não são gerenciados pela configuração declarativa.

Depois que todos os recursos forem excluídos, exclua o cluster do Config Controller:

gcloud anthos config controller delete \
    --location=LOCATION CONFIG_CONTROLLER_NAME

Considerações de produção

Na produção, confira as considerações de alta disponibilidade para o Config Controller.

A seguir

• Conheça as práticas recomendadas para escalonabilidade do Config Controller
• Resolva problemas do Config Controller.
• Receba suporte.
• Saiba mais sobre como sincronizar as configurações e políticas com o Config Sync.
• Saiba mais sobre como aplicar políticas com o Policy Controller.
• Saiba mais sobre os recursos do Config Connector.