Instalar o Config Sync

Com o Config Sync, é possível gerenciar recursos do Kubernetes com arquivos de configuração armazenados em uma fonte de verdade. O Config Sync é compatível com repositórios Git , imagens OCI e gráficos Helm como fontes de verdade. Nesta página, mostramos como ativar e configurar o Config Sync para que ele seja sincronizado com seu repositório raiz. O Config Sync está disponível com a edição Enterprise do Google Kubernetes Engine (GKE).

Quando você instala o Config Sync usando o Console do Google Cloud ou a CLI do Google Cloud, as APIs RootSync e RepoSync são ativadas por padrão. Com esse operador, você tem recursos adicionais como a sincronização de vários repositórios e a sincronização das configurações do Kustomize e do Helm.

Antes de começar

Antes de instalar o Config Sync, prepare o ambiente, verifique se você atende aos requisitos do cluster e conceda as funções de usuário corretas.

Preparar o ambiente local

Prepare o ambiente local concluindo as tarefas a seguir:

  1. Crie ou verifique se você tem acesso a uma fonte de informações. Esse é o lugar em que você adiciona as configurações que o Config Sync sincroniza. Para saber mais sobre como definir as configurações e a fonte de verdade, consulte um dos guias a seguir:
  2. Instale e inicialize a CLI do Google Cloud, que fornece os comandos gcloud e nomos. Se você usa o Cloud Shell, a CLI do Google Cloud já vem pré-instalada. Se você já instalou a CLI do Google Cloud, instale a versão mais recente executando gcloud components update.

  3. Ative a API GKE Enterprise.

    Ativar a API GKE Enterprise

Requisitos de cluster

Para usar o Config Sync, seu cluster precisa atender aos seguintes requisitos:

  • Precisa ser uma plataforma e versão compatíveis do Google Kubernetes Engine (GKE) Enterprise.

  • (Opcional) Se você usa clusters do GKE, verifique se a Federação de Identidade da Carga de Trabalho para GKE está ativada. Os clusters do Autopilot têm a Federação de Identidade da Carga de Trabalho para GKE ativada por padrão.

  • Tem as permissões corretas de gravação de métricas para que o Config Sync possa enviar métricas ao Cloud Monitoring.

  • Se quiser fazer o upgrade automático da versão do Config Sync, verifique se o cluster do GKE está inscrito em um canal de lançamento. O Config Sync trata um cluster que não usa um canal de lançamento do GKE como se estivesse usando o canal de lançamento Stable.

  • Se quiser usar um cluster particular do GKE, configure o Cloud NAT para permitir a saída de nós particulares do GKE. Para detalhes, consulte Exemplo de configuração do GKE. Se preferir, ative o Acesso privado do Google para se conectar ao conjunto de endereços IP externos usados pelas APIs e serviços do Google.

  • Se quiser usar uma conta de serviço do IAM ao conceder acesso ao Config Sync à sua fonte de verdade, inclua o escopo somente leitura nos escopos de acesso dos nós no cluster do Cloud Source Repositories.

    É possível adicionar o escopo somente leitura incluindo cloud-source-repos-ro na lista --scopes especificada no momento da criação do cluster ou usando o escopo cloud-platform no momento da criação do cluster. Por exemplo:

    gcloud container clusters create CLUSTER_NAME --scopes=cloud-platform

    Não é possível modificar os escopos de acesso depois de criar um pool de nós. No entanto, é possível criar um novo pool de nós com o escopo de acesso apropriado e usar o mesmo cluster. O escopo gke-default padrão não inclui cloud-source-repos-ro.

  • Se você tiver requisitos rígidos de firewall da VPC que bloqueiem qualquer tráfego desnecessário, será necessário Criar regras de firewall para permitir o tráfego que segue em clusters públicos do GKE:

    • TCP: permite a entrada e a saída nas portas 53 e 443

    • UDP: permitir a saída na porta 53

    Se você não incluir essas regras, o Config Sync não será sincronizado corretamente, com nomos status informando o seguinte erro:

    Error: KNV2004: unable to sync repo Error in the git-sync container

    Pule essas etapas se estiver usando um cluster particular do GKE.

  • O Config Sync precisa ser executado em um pool de nós amd64. As imagens de contêiner do componente de back-end do Config Sync são criadas, distribuídas e testadas apenas para a arquitetura de máquina amd64. Se um componente do Config Sync for programado em um nó Arm, ele vai apresentar o erro exec format e falhar.

    Se você tiver nós Arm no cluster, adicione um ou mais nós amd64 a ele. Se você não estiver usando um cluster do GKE, adicione um taint aos nós arm64 para evitar a programação de pods sem tolerância específica. Os nós arm do GKE já têm um taint padrão. Portanto, não é necessário adicionar um.

Se o cluster for do Autopilot, saiba que ele ajusta os requisitos de recursos do contêiner para atender às seguintes regras:

Devido a essas regras, para clusters do Autopilot, o Config Sync:

Preparar o cluster

Depois de criar um cluster adequado, siga estas etapas:

  1. Conceda os papéis do IAM ao usuário que registra o cluster.

  2. Se você planeja usar a Google Cloud CLI para configurar o Config Sync ou usar clusters fora do Google Cloud, verifique se os clusters do GKE ou clusters fora do Google Cloud estão registradas em uma frota agora. Se você planeja usar o console do Google Cloud, é possível registrar clusters do GKE ao configurar o Config Sync.

Instalar o Config Sync

Nas seções a seguir, você concede acesso ao Config Sync a uma das seguintes fontes de verdade:

Depois de conceder acesso, você pode configurar o Config Sync.

Permitir acesso ao Git

O Config Sync precisa de acesso somente leitura ao seu repositório Git para ler os configs confirmados no repositório e aplicá-los aos clusters.

Se o repositório não exigir autenticação para acesso somente leitura, será possível continuar a configurar o Config Sync e usar none como o tipo de autenticação. Por exemplo, se for possível navegar no repositório usando uma interface da Web sem fazer login ou usar git clone para criar um clone do repositório localmente sem fornecer credenciais ou usar credenciais salvas, não será necessário fazer a autenticação. Nesse caso, você não precisa criar um secret.

No entanto, a maioria dos usuários precisa criar credenciais porque o acesso de leitura ao repositório é restrito. Se as credenciais forem necessárias, elas serão armazenadas no secret git-creds em cada cluster registrado (a menos que você esteja usando uma conta de serviço do Google). O secret precisa ser nomeado como git-creds porque esse é um valor fixo.

O Config Sync é compatível com os seguintes mecanismos de autenticação:

  • Par de chaves SSH (ssh)
  • Cookiefile (cookiefile)
  • Token (token)
  • Conta de serviço do Google.(gcpserviceaccount)
  • Conta de serviço padrão do Compute Engine (gcenode)

O mecanismo que você escolhe depende do suporte que seu repositório oferece. Geralmente, recomendamos o uso de um par de chaves SSH. O GitHub e o Bitbucket são compatíveis com o uso de um par de chaves SSH. No entanto, se você estiver usando um repositório no Cloud Source Repositories, recomendamos que utilize uma conta de serviço do Google, já que o processo é mais simples. Caso sua organização hospede o repositório e você não saiba quais métodos de autenticação são compatíveis, entre em contato com o administrador.

Para usar um repositório no Cloud Source Repositories como seu repositório do Config Sync, conclua as etapas a seguir para recuperar o URL do Cloud Source Repositories:

  1. Liste todos os repositórios:

    gcloud source repos list

  2. No resultado, copie o URL do repositório que quer usar. Por exemplo:

    REPO_NAME  PROJECT_ID  URL
my-repo    my-project  https://source.developers.google.com/p/my-project/r/my-repo-csr

    Você precisa usar esse URL ao configurar o Config Sync na seção a seguir. Se você configurar o Config Sync usando o Console do Google Cloud, adicione o URL no campo URL. Se você configurar o Config Sync usando a Google Cloud CLI, adicione o URL ao campo syncRepo do arquivo de configuração.

Par de chaves SSH

Um par de chaves SSH consiste em dois arquivos, uma chave pública e uma chave privada. A chave pública normalmente tem uma extensão .pub.

Para usar um par de chaves SSH, conclua estas etapas:

  1. Crie um par de chaves SSH para permitir que o Config Sync faça a autenticação no seu repositório Git. Essa etapa é necessária se você precisar se autenticar no repositório para cloná-lo ou lê-lo. Pule esta etapa se um administrador de segurança fornecer um par de chaves a você. É possível usar um único par de chaves para todos os clusters ou um par de chaves por cluster, dependendo dos seus requisitos de segurança e conformidade.

    O comando a seguir cria uma chave RSA de 4.096 bits. Valores inferiores não são recomendados:

    ssh-keygen -t rsa -b 4096 \
-C "GIT_REPOSITORY_USERNAME" \
-N '' \
-f /path/to/KEYPAIR_FILENAME

    Substitua:

    • GIT_REPOSITORY_USERNAME: o nome de usuário que você quer que o Config Sync use para se autenticar no repositório
    • /path/to/KEYPAIR_FILENAME: um caminho para o par de chaves

    Se você estiver usando um host de repositório Git de terceiros, como o GitHub, ou quiser usar uma conta de serviço com o Cloud Source Repositories, recomendamos usar uma conta separada.

  2. Configure seu repositório para reconhecer a chave pública recém-criada. Consulte a documentação do seu provedor de hospedagem Git. Instruções para alguns provedores de hospedagem Git conhecidos estão incluídas por conveniência:

  3. Adicione a chave privada a um novo Secret no cluster:

    kubectl create ns config-management-system && \
kubectl create secret generic git-creds \
 --namespace=config-management-system \
 --from-file=ssh=/path/to/KEYPAIR_PRIVATE_KEY_FILENAME

    Substitua /path/to/KEYPAIR_PRIVATE_KEY_FILENAME pelo nome da chave privada (aquela sem o sufixo .pub).

  4. (Recomendado) Para configurar a verificação de hosts conhecidos usando a autenticação SSH, adicione a chave de hosts conhecida ao campo data.known_hosts no secret git_creds. Para desativar a verificação de known_hosts, remova o campo known_hosts do secret. Para adicionar a chave de hosts conhecida, execute:

    kubectl edit secret git-creds \
 --namespace=config-management-system

    Em seguida, em data, adicione a entrada de hosts conhecida:

    known_hosts: KNOWN_HOSTS_KEY

  5. Exclua a chave privada do disco local ou a proteja.

  6. Ao configurar o Config Sync e adicionar o URL do repositório Git, use o protocolo SSH. Se você estiver usando um repositório no Cloud Source Repositories, será preciso usar o seguinte formato ao inserir o URL:

    ssh://EMAIL@source.developers.google.com:2022/p/PROJECT_ID/r/REPO_NAME

    Substitua:

    • EMAIL: seu nome de usuário do Google Cloud;
    • PROJECT_ID: o ID do projeto do Google Cloud em que o repositório está localizado;
    • REPO_NAME: o nome do repositório.

Cookiefile

O processo para adquirir um cookiefile depende da configuração no repositório. Por exemplo, consulte Gerar credenciais estáticas na documentação do Cloud Source Repositories. As credenciais geralmente são armazenadas no arquivo .gitcookies no diretório principal ou podem ser fornecidas a você por um administrador de segurança.

Para criar um cookiefile, conclua as etapas a seguir:

  1. Depois de criar e conseguir o cookiefile, adicione-o a um novo Secret no cluster.

    Se você não usa um proxy HTTPS, crie o Secret com o seguinte comando:

    kubectl create ns config-management-system && \
kubectl create secret generic git-creds \
 --namespace=config-management-system \
 --from-file=cookie_file=/path/to/COOKIEFILE

    Se você precisar usar um proxy HTTPS, adicione-o ao secret junto de cookiefile executando o comando a seguir:

    kubectl create ns config-management-system && \
kubectl create secret generic git-creds \
 --namespace=config-management-system \
 --from-file=cookie_file=/path/to/COOKIEFILE \
 --from-literal=https_proxy=HTTPS_PROXY_URL

    Substitua:

    • /path/to/COOKIEFILE: o caminho e nome de arquivo adequados;
    • HTTPS_PROXY_URL: o URL do proxy HTTPS que você usa ao se comunicar com o repositório Git.

  2. Proteja o conteúdo do cookiefile se você ainda precisar dele localmente. Caso contrário, exclua-o.

Token

Se sua organização não permitir o uso de chaves SSH, talvez você prefira usar um token. Com o Config Sync, é possível usar os tokens de acesso pessoal (PATs, na sigla em inglês) do GitHub ou do GiLab, chaves de implantação ou a senha do app Bitbucket como token.

Para criar um secret usando seu token, execute as etapas a seguir.

  1. Crie um token usando o GitHub, o GitLab ou o Bitbucket.

  2. Depois de criar e receber o token, adicione-o a um novo secret no cluster.

    Se você não usa um proxy HTTPS, crie o Secret com o seguinte comando:

    kubectl create ns config-management-system && \
kubectl create secret generic git-creds \
  --namespace="config-management-system" \
  --from-literal=username=USERNAME \
  --from-literal=token=TOKEN

    Substitua:

    • USERNAME: o nome de usuário que você quer usar.
    • TOKEN: o token criado na etapa anterior.

    Se você precisar usar um proxy HTTPS, adicione-o ao secret junto de username e token executando o comando a seguir:

    kubectl create ns config-management-system && \
kubectl create secret generic git-creds \
 --namespace=config-management-system \
 --from-literal=username=USERNAME \
  --from-literal=token=TOKEN \
 --from-literal=https_proxy=HTTPS_PROXY_URL

    Substitua:

    • USERNAME: o nome de usuário que você quer usar.
    • TOKEN: o token criado na etapa anterior.
    • HTTPS_PROXY_URL: o URL do proxy HTTPS que você usa ao se comunicar com o repositório Git.

  3. Proteja o token se você ainda precisar dele localmente. Caso contrário, exclua-o.

Conta de serviço do Google

Se o repositório estiver no Cloud Source Repositories e o cluster usar a Federação de Identidade da Carga de Trabalho para GKE do GKE ou a Federação de Identidade da Carga de Trabalho para GKE da frota, é possível conceder acesso ao Config Sync a um repositório no mesmo projeto que o cluster gerenciado usando uma conta de serviço do Google.

  1. Se você não tiver uma conta de serviço, crie uma.

  2. Conceda o papel do IAM de Leitor do Cloud Source Repositories (roles/source.reader) à conta de serviço do Google. Para mais informações sobre os papéis e permissões do Cloud Source Repositories, consulte Conceder permissões para visualizar repositórios.

    • Conceda permissão a todo o projeto se as mesmas permissões se aplicarem a todos os repositórios no projeto.

      gcloud projects add-iam-policy-binding PROJECT_ID \
  --role=roles/source.reader \
  --member="serviceAccount:GSA_NAME@PROJECT_ID.iam.gserviceaccount.com"

    • Conceda permissão específica ao repositório quando quiser que as contas de serviço tenham diferentes níveis de acesso para cada repositório no projeto.

      gcloud source repos set-iam-policy REPOSITORY POLICY_FILE --project=PROJECT_ID

  3. Se você configurar o Config Sync usando o console do Google Cloud, selecione Federação de Identidade da Carga de Trabalho para GKE como o Tipo de autenticação e adicione o e-mail da sua conta de serviço.

    Se você configurar o Config Sync usando a CLI do Google Cloud, adicione gcpserviceaccount como secretType e adicione o e-mail da conta de serviço a gcpServiceAccountEmail.

  4. Depois de configurar o Config Sync, crie uma Vinculação de políticas do IAM entre a conta de serviço do Kubernetes e a conta de serviço do Google. A conta de serviço do Kubernetes não será criada até que você configure o Config Sync pela primeira vez.

    Se você estiver usando clusters registrados em uma frota, só precisará criar a vinculação de política uma vez por frota. Todos os clusters registrados em uma frota compartilham a mesma federação de identidade da carga de trabalho para o pool do GKE. Com o conceito de semelhança de frota, se você adicionar a política de IAM à conta de serviço do Kubernetes em um cluster, a conta de serviço do Kubernetes do mesmo namespace em outros clusters na mesma frota também recebem a mesma política de IAM.

    Essa vinculação permite que a conta de serviço do Kubernetes do Config Sync atue como a conta de serviço do Google:

    gcloud iam service-accounts add-iam-policy-binding \
    GSA_NAME@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/iam.workloadIdentityUser \
    --member="serviceAccount:FLEET_HOST_PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]" \
    --project=PROJECT_ID

Substitua:

  • PROJECT_ID: ID do projeto da organização.
  • FLEET_HOST_PROJECT_ID: se você estiver usando a Federação de Identidade da Carga de Trabalho para GKE do GKE, será igual a PROJECT_ID. Se você estiver usando a Federação de Identidade da Carga de Trabalho para GKE da frota, esse será o ID do projeto da frota em que o cluster está registrado.
  • GSA_NAME: a conta de Serviço do Google personalizada que você quer usar para se conectar ao Artifact Registry. Essa conta de serviço precisa ter o papel do IAM "Leitor do Artifact Registry" (roles/artifactregistry.reader).
  • KSA_NAME: a conta de serviço do Kubernetes do reconciliador.
    • Para repositórios raiz, se o nome RootSync for root-sync, use root-reconciler. Do contrário, use root-reconciler-ROOT_SYNC_NAME. Se você instalar o Config Sync usando o console do Google Cloud ou o Google Cloud CLI, o Config Sync criará automaticamente um objeto RootSync chamado root-sync.
  • REPOSITORY: o nome do repositório.
  • POLICY_FILE é o arquivo JSON ou YAML com a política de gerenciamento de identidade e acesso.

Conta de serviço padrão do Compute Engine

Se o repositório estiver no Cloud Source Repositories e o cluster for do GKE com a Federação de Identidade da Carga de Trabalho para GKE desativada, será possível usar gcenode como o tipo de autenticação.

Se você configurar o Config Sync usando o console do Google Cloud, selecione o Cloud Repository do Google como o Tipo de autenticação.

Se você configurar o Config Sync usando a Google Cloud CLI, adicione gcenode como secretType.

Ao selecionar Google Cloud Repository ou gcenode, é possível usar a conta de serviço padrão do Compute Engine. Conceda o papel do IAM de Leitor do Cloud Source Repositories (roles/source.reader) à conta de serviço padrão do Compute Engine. Para mais informações sobre os papéis e permissões do Cloud Source Repositories, consulte Conceder permissões para visualizar repositórios.

gcloud projects add-iam-policy-binding PROJECT_ID \
  --role=roles/source.reader \
  --member="serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com"

Substitua PROJECT_ID pelo ID do projeto da organização e PROJECT_NUMBER pelo número do projeto da organização.

Conceder acesso somente leitura do Config Sync ao OCI

O Config Sync precisa de acesso somente leitura à imagem OCI armazenada no Artifact Registry para ler as configurações incluídas na imagem e aplicá-las aos clusters.

Se o repositório não exigir autenticação para acesso somente leitura, será possível continuar a configurar o Config Sync e usar none como o tipo de autenticação. Por exemplo, se a imagem for pública e puder ser acessada por qualquer pessoa na Internet, você não precisará fazer a autenticação.

No entanto, a maioria dos usuários precisa criar credenciais para acessar imagens restritas. O Config Sync é compatível com os seguintes mecanismos de autenticação:

  • Conta de serviço do Kubernetes (k8sserviceaccount)
  • Conta de serviço do Google.(gcpserviceaccount)

  • Conta de serviço padrão do Compute Engine (gcenode)

Conta de serviço do Kubernetes

Se você armazenar sua imagem OCI no Artifact Registry e o cluster usar Federação de Identidade da Carga de Trabalho para GKE do GKE ou Federação de Identidade da Carga de Trabalho para GKE da frota, é possível usar k8sserviceaccount como o tipo de autenticação na versão 1.17.2 e mais recentes. Essa opção é recomendada em vez de gcpserviceaccount devido ao processo de configuração simplificado.

  1. Conceda o papel do IAM de leitor do Artifact Registry (roles/artifactregistry.reader) à conta de serviço do Kubernetes com o pool da Federação de Identidade da Carga de Trabalho para GKE. Para ver mais informações sobre os papéis e permissões do Artifact Registry, consulte Configurar papéis e permissões para o Artifact Registry.

    • Conceda permissão a todo o projeto se as mesmas permissões se aplicarem a todos os repositórios no projeto.

      gcloud projects add-iam-policy-binding PROJECT_ID \
      --role=roles/artifactregistry.reader \
      --member="serviceAccount:FLEET_HOST_PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]"

    • Conceda permissão específica ao repositório quando quiser que as contas de serviço tenham diferentes níveis de acesso para cada repositório no projeto.

      gcloud artifacts repositories add-iam-policy-binding REPOSITORY \
   --location=LOCATION \
   --role=roles/artifactregistry.reader \
   --member="serviceAccount:FLEET_HOST_PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]" \
   --project=PROJECT_ID

    Substitua:

    • PROJECT_ID: ID do projeto da organização.
    • FLEET_HOST_PROJECT_ID: se você estiver usando a Federação de Identidade da Carga de Trabalho para GKE do GKE, será igual a PROJECT_ID. Se você estiver usando a Federação de Identidade da Carga de Trabalho para GKE da frota, esse será o ID do projeto da frota em que o cluster está registrado.
    • KSA_NAME: a conta de serviço do Kubernetes do reconciliador.
      • Para repositórios raiz, se o nome RootSync for root-sync, use root-reconciler. Do contrário, use root-reconciler-ROOT_SYNC_NAME. Se você instalar o Config Sync usando o console do Google Cloud ou o Google Cloud CLI, o Config Sync criará automaticamente um objeto RootSync chamado root-sync.
    • REPOSITORY: o ID do repositório.
    • LOCATION é o local regional ou multirregional do repositório.

Conta de serviço do Google

Se você armazenar sua imagem OCI no Artifact Registry e o cluster usar a Federação de Identidade da Carga de Trabalho para GKE do GKE ou a Federação de Identidade da Carga de Trabalho para GKE da frota, é possível usar gcpserviceaccount como o tipo de autenticação. A partir da versão 1.17.2, é recomendável usar k8sserviceaccount. Essa opção elimina as etapas extras da criação de uma conta de serviço do Google e a vinculação de política do IAM associada.

  1. Se você não tiver uma conta de serviço, crie uma.

  2. Conceda o papel do IAM de leitor do Artifact Registry (roles/artifactregistry.reader) à conta de serviço do Google. Para ver mais informações sobre os papéis e permissões do Artifact Registry, consulte Configurar papéis e permissões para o Artifact Registry.

    • Conceda permissão a todo o projeto se as mesmas permissões se aplicarem a todos os repositórios no projeto.

      gcloud projects add-iam-policy-binding PROJECT_ID  \
   --role=roles/artifactregistry.reader \
   --member="serviceAccount:GSA_NAME@PROJECT_ID.iam.gserviceaccount.com"

    • Conceda permissão específica ao repositório quando quiser que as contas de serviço tenham diferentes níveis de acesso para cada repositório no projeto.

      gcloud artifacts repositories add-iam-policy-binding REPOSITORY \
   --location=LOCATION \
   --role=roles/artifactregistry.reader \
   --member="serviceAccount:GSA_NAME@PROJECT_ID.iam.gserviceaccount.com" \
   --project=PROJECT_ID

  3. Crie uma vinculação de política do IAM entre a conta de serviço do Kubernetes e a conta de serviço do Google executando o seguinte comando:

    gcloud iam service-accounts add-iam-policy-binding
  GSA_NAME@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/iam.workloadIdentityUser \
    --member="serviceAccount:FLEET_HOST_PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]" \
    --project=PROJECT_ID

Substitua:

  • PROJECT_ID: ID do projeto da organização.
  • FLEET_HOST_PROJECT_ID: se você estiver usando a Federação de Identidade da Carga de Trabalho para GKE do GKE, será igual a PROJECT_ID. Se você estiver usando a Federação de Identidade da Carga de Trabalho para GKE da frota, esse será o ID do projeto da frota em que o cluster está registrado.
  • GSA_NAME: a conta de Serviço do Google personalizada que você quer usar para se conectar ao Artifact Registry. Essa conta de serviço precisa ter o papel do IAM "Leitor do Artifact Registry" (roles/artifactregistry.reader).
  • KSA_NAME: a conta de serviço do Kubernetes do reconciliador.
    • Para repositórios raiz, se o nome RootSync for root-sync, use root-reconciler. Do contrário, use root-reconciler-ROOT_SYNC_NAME. Se você instalar o Config Sync usando o console do Google Cloud ou o Google Cloud CLI, o Config Sync criará automaticamente um objeto RootSync chamado root-sync.
  • REPOSITORY: o ID do repositório.
  • LOCATION é o local regional ou multirregional do repositório.

Conta de serviço padrão do Compute Engine

Se você armazenar o gráfico Helm no Artifact Registry e o cluster for do GKE com a Federação de Identidade da Carga de Trabalho para GKE desativada, será possível usar gcenode como tipo de autenticação. O Config Sync usa a conta de serviço padrão do Compute Engine. Conceda ao leitor de conta de serviço padrão do Compute Engine o acesso ao Artifact Registry.

  1. Conceda à conta de serviço do Compute Engine permissão de leitura para o Artifact Registry executando o seguinte comando:

    gcloud projects add-iam-policy-binding PROJECT_ID \
   --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
   --role=roles/artifactregistry.reader

    Substitua PROJECT_ID pelo ID do projeto da organização e PROJECT_NUMBER pelo número do projeto da organização.

Conceder acesso somente leitura do Config Sync ao Helm

O Config Sync precisa de acesso somente leitura ao seu repositório do Helm para ler os gráficos do Helm no repositório e instalá-los nos clusters.

Se o repositório não exigir autenticação para acesso somente leitura, será possível continuar a configurar o Config Sync e usar none como o tipo de autenticação. Por exemplo, se o repositório do Helm for público e puder ser acessado por qualquer pessoa na Internet, não será necessário autenticar.

No entanto, a maioria dos usuários precisa criar credenciais para acessar repositórios particulares do Helm. O Config Sync é compatível com os seguintes mecanismos de autenticação:

  • Token (token)
  • Conta de serviço do Kubernetes (k8sserviceaccount)
  • Conta de serviço do Google.(gcpserviceaccount)
  • Conta de serviço padrão do Compute Engine (gcenode)

Token

Crie um Secret com um nome de usuário e uma senha do repositório Helm:

kubectl create secret generic SECRET_NAME \
    --namespace=config-management-system \
    --from-literal=username=USERNAME \
    --from-literal=password=PASSWORD

Substitua:

  • SECRET_NAME: o nome que você quer dar ao Secret.
  • USERNAME: o nome de usuário do repositório do Helm.
  • PASSWORD: a senha do repositório do Helm.

Ao configurar o ConfigManagement Operator, você usará o nome do secret escolhido para spec.helm.secretRef.name.

Conta de serviço do Kubernetes

Se você armazenar o gráfico Helm no Artifact Registry e o cluster usar a Federação de Identidade da Carga de Trabalho para GKE do GKE ou a Federação de Identidade da Carga de Trabalho para GKE da frota, é possível usar k8sserviceaccount como o tipo de autenticação na versão 1.17.2 e mais recentes. Essa opção é recomendada em vez de gcpserviceaccount devido ao processo de configuração simplificado.

  1. Conceda o papel do IAM de leitor do Artifact Registry (roles/artifactregistry.reader) à conta de serviço do Kubernetes com o pool da Federação de Identidade da Carga de Trabalho para GKE. Para ver mais informações sobre os papéis e permissões do Artifact Registry, consulte Configurar papéis e permissões para o Artifact Registry.

    • Conceda permissão a todo o projeto se as mesmas permissões se aplicarem a todos os repositórios no projeto.

      gcloud projects add-iam-policy-binding PROJECT_ID \
   --role=roles/artifactregistry.reader \
   --member="serviceAccount:FLEET_HOST_PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]"

    • Conceda permissão específica ao repositório quando quiser que as contas de serviço tenham diferentes níveis de acesso para cada repositório no projeto.

      gcloud artifacts repositories add-iam-policy-binding REPOSITORY \
   --location=LOCATION \
   --role=roles/artifactregistry.reader \
   --member="serviceAccount:FLEET_HOST_PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]" \
   --project=PROJECT_ID

    Substitua:

    • PROJECT_ID: ID do projeto da organização.
    • FLEET_HOST_PROJECT_ID: se você estiver usando a Federação de Identidade da Carga de Trabalho para GKE do GKE, será igual a PROJECT_ID. Se você estiver usando a Federação de Identidade da Carga de Trabalho para GKE da frota, esse será o ID do projeto da frota em que o cluster está registrado.
    • KSA_NAME: a conta de serviço do Kubernetes do reconciliador.
      • Para repositórios raiz, se o nome RootSync for root-sync, use root-reconciler. Do contrário, use root-reconciler-ROOT_SYNC_NAME.
    • REPOSITORY: o ID do repositório.
    • LOCATION é o local regional ou multirregional do repositório.

Conta de serviço do Google

Se você armazenar o gráfico Helm no Artifact Registry e o cluster usar a Federação de Identidade da Carga de Trabalho para GKE do GKE ou a Federação de Identidade da Carga de Trabalho para GKE da frota, é possível usar gcpserviceaccount como o tipo de autenticação. A partir da versão 1.17.2, é recomendável usar k8sserviceaccount. Essa opção elimina as etapas extras da criação de uma conta de serviço do Google e a vinculação de política do IAM associada.

  1. Se você não tiver uma conta de serviço, crie uma.

  2. Conceda o papel do IAM de leitor do Artifact Registry (roles/artifactregistry.reader) à conta de serviço do Google. Para ver mais informações sobre os papéis e permissões do Artifact Registry, consulte Configurar papéis e permissões para o Artifact Registry.

    • Conceda permissão a todo o projeto se as mesmas permissões se aplicarem a todos os repositórios no projeto.

      gcloud projects add-iam-policy-binding PROJECT_ID  \
      --role=roles/artifactregistry.reader \
      --member="serviceAccount:GSA_NAME@PROJECT_ID.iam.gserviceaccount.com"

    • Conceda permissão específica ao repositório quando quiser que as contas de serviço tenham diferentes níveis de acesso para cada repositório no projeto.

      gcloud artifacts repositories add-iam-policy-binding REPOSITORY \
   --location=LOCATION \
   --role=roles/artifactregistry.reader \
   --member="serviceAccount:GSA_NAME@PROJECT_ID.iam.gserviceaccount.com" \
   --project=PROJECT_ID

  3. Crie uma vinculação de política do IAM entre a conta de serviço do Kubernetes e a conta de serviço do Google executando o seguinte comando:

    gcloud iam service-accounts add-iam-policy-binding
  GSA_NAME@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/iam.workloadIdentityUser \
    --member="serviceAccount:FLEET_HOST_PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]"
    --project=PROJECT_ID

Substitua:

  • PROJECT_ID: ID do projeto da organização.
  • FLEET_HOST_PROJECT_ID: se você estiver usando a Federação de Identidade da Carga de Trabalho para GKE do GKE, será igual a PROJECT_ID. Se você estiver usando a Federação de Identidade da Carga de Trabalho para GKE da frota, esse será o ID do projeto da frota em que o cluster está registrado.
  • GSA_NAME: a conta de Serviço do Google personalizada que você quer usar para se conectar ao Artifact Registry. Essa conta de serviço precisa ter o papel do IAM "Leitor do Artifact Registry" (roles/artifactregistry.reader).
  • KSA_NAME: a conta de serviço do Kubernetes do reconciliador.
    • Para repositórios raiz, se o nome RootSync for root-sync, use root-reconciler. Do contrário, use root-reconciler-ROOT_SYNC_NAME.
  • REPOSITORY: o ID do repositório.
  • LOCATION é o local regional ou multirregional do repositório.

Conta de serviço padrão do Compute Engine

Se você armazenar o gráfico Helm no Artifact Registry e o cluster for do GKE com a Federação de Identidade da Carga de Trabalho para GKE desativada, será possível usar gcenode como tipo de autenticação. O Config Sync usa a conta de serviço padrão do Compute Engine. Conceda ao leitor de conta de serviço padrão do Compute Engine o acesso ao Artifact Registry. Talvez seja necessário conceder acesso ao escopo storage-ro para conceder permissão somente leitura para extrair imagens.

  1. Conceda à conta de serviço do Compute Engine a permissão de leitura para o Artifact Registry:

    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/artifactregistry.reader

    Substitua PROJECT_ID pelo ID do projeto da organização e PROJECT_NUMBER pelo número do projeto da organização.

Configurar o Config Sync

Nesta seção, você definirá as configurações do seu repositório raiz. Se você estiver fazendo a sincronização com um repositório do Git, use o console do Google Cloud para orientações durante o processo de instalação e para automatizar algumas etapas.

Quando você instala o Config Sync usando o console do Google Cloud ou a Google Cloud CLI, o Config Sync cria automaticamente um objeto RootSync chamado root-sync. É possível usar comandos kubectl para modificar root-sync e adicionar outras configurações do Config Sync. Para saber mais, consulte Configurar o Config Sync com comandos kubectl.

Console

Instalar o Config Sync

Para instalar o Config Sync, todos os clusters precisam estar registrados em uma frota. Ao instalar o Config Sync no console do Google Cloud, a seleção de clusters individuais os registra automaticamente na frota.

  1. No console do Google Cloud, acesse a página Configuração na seção Recursos.

    Acessar a configuração

  2. Clique em Instalar o Config Sync.
  3. Selecione Upgrades automáticos (Visualização) para ativar o Config Sync para fazer upgrade das versões automaticamente ou selecione Upgrades manuais para gerenciar a versão do Config Sync. Para mais informações sobre como os upgrades automáticos funcionam, consulte Fazer upgrade do Config Sync.
  4. Em Opções de instalação, selecione uma das seguintes opções:
    • Instalar o Config Sync em toda a frota (recomendado): o Config Sync será instalado em todos os clusters da frota.
    • Instalar o Config Sync em clusters individuais: todos os clusters selecionados serão registrados automaticamente em uma frota. O Config Sync será instalado em todos os clusters da frota.
  5. Se você estiver instalando o Config Sync em clusters individuais, selecione aqueles em que você quer instalar o Config Sync na tabela Clusters disponíveis.
  6. Clique em Instalar o Config Sync. Na guia Configurações, após alguns minutos, a mensagem Ativado vai aparecer na coluna Status dos clusters na sua frota.

Implantar um pacote

Depois de registrar os clusters em uma frota e instalar o Config Sync, é possível configurar o Config Sync para implantar um pacote em um cluster de uma fonte de verdade. É possível implantar o mesmo pacote em vários clusters ou implantar pacotes diferentes em clusters diferentes. É possível editar um pacote após a implantação, exceto algumas configurações, como o nome do pacote e o tipo de sincronização. Para mais informações, consulte Gerenciar pacotes.

Para implantar um pacote, siga estas etapas:

  1. No console do Google Cloud, acesse o painel do Config Sync.

    Acessar o painel do Config Sync

  2. Clique em Implantar pacote.

  3. Na tabela Selecionar clusters para implantação do pacote, selecione o cluster em que quer implantar um pacote e clique em Continuar.

  4. Selecione Pacote hospedado no Git ou Pacote hospedado na OCI como tipo de origem e clique em Continuar.

  5. Na seção Package details, insira um Package name, que identifica o objeto RootSync ou RepoSync.

  6. No campo Sync type, escolha Cluster scoped sync ou Namespace scoped sync como o tipo de sincronização.

    A sincronização com escopo de Cluster cria um objeto RootSync, e a sincronização com escopo de Namespace cria um objeto RepoSync. Para mais informações sobre esses objetos, consulte Arquitetura do Config Sync.

  7. Na seção Origem, faça o seguinte:

    • Para fontes hospedadas em um repositório Git, insira os seguintes campos:

      1. Digite o URL do repositório Git que você está usando como fonte de verdade como o URL do repositório.
      2. Opcional: atualize o campo Revisão para verificar se você não está usando o HEAD padrão.
      3. Opcional: atualize o campo Path se você não quiser sincronizar a partir do repositório raiz.
      4. Opcional: atualize o campo Ramificação se você não estiver usando a ramificação main padrão.

    • Para fontes hospedadas em uma imagem OCI, insira os seguintes campos:

      1. Insira o URL da imagem OCI que você está usando como fonte de verdade como a Imagem.
      2. Insira o caminho do diretório de onde sincronizar, relativo ao diretório raiz, como o Diretório.

  8. (Opcional): expanda a seção Configurações avançadas para concluir o seguinte:

    1. Selecione um Tipo de autenticação. O Config Sync precisa de acesso somente leitura à sua fonte de verdade para ler os arquivos de configuração na origem e aplicá-los aos clusters. A menos que a origem não exija autenticação, como um repositório público, conceda acesso somente leitura ao Config Sync ao repositório Git, imagem OCI ou gráfico Helm (somente na gcloud CLI). Escolha o mesmo tipo de autenticação que você configurou ao instalar o Config Sync:

      • Nenhum: não usar autenticação.
      • SSH: faça a autenticação usando um par de chaves SSH.
      • Cookiefile: faça a autenticação usando um cookiefile.
      • Token: faça a autenticação usando um token de acesso ou uma senha.
      • Google Cloud Repository: use uma conta de serviço do Google para acessar um repositório do Cloud Source Repositories. Selecione esta opção somente se a Federação de Identidade da Carga de Trabalho para GKE não estiver ativada no cluster.
      • Identidade da carga de trabalho: use uma conta de serviço do Google para acessar um repositório do Cloud Source Repositories.

    2. Insira um número em segundos para definir o Tempo de espera da sincronização, que determina quanto tempo o Config Sync espera entre as tentativas de extração da fonte de verdade.

    3. Insira um URL de proxy Git para o proxy HTTPS a ser usado ao se comunicar com a fonte da verdade.

    4. Escolha Hierarquia para mudar o Formato de origem.

      O valor padrão Não estruturado é recomendado na maioria dos casos, porque permite organizar a fonte de verdade como você quiser.

  9. Clique em Implantar pacote.

    Você será redirecionado para a página Pacotes do Config Sync. Após alguns minutos, a mensagem Sincronizado vai aparecer na coluna Status da sincronização do cluster configurado.

gcloud

Antes de continuar, registre seus clusters em uma frota.

  1. Ative o recurso de frota ConfigManagement:

    gcloud beta container fleet config-management enable

  2. Prepare a configuração criando um novo manifesto apply-spec.yaml ou usando um existente. Se você escolher a última opção, é possível configurar um cluster com as mesmas configurações usadas por outro.

    Criar novo manifesto

    Para definir o Config Sync com novas configurações para o cluster, crie um arquivo chamado apply-spec.yaml e copie o arquivo YAML a seguir nele.

    É possível definir todos os campos spec.configSyncopcionais que são necessários ao criar o manifesto e depois usar comandos kubectl para a configuração. Também é possível definir apenas o campo spec.configSync.enabled como true e omitir os campos opcionais. Posteriormente, é possível usar comandos kubectl para criar outros objetos RootSync ou RepoSyncs que poderão ser gerenciados totalmente mais tarde por meio de comandos kubectl.

    # apply-spec.yaml

applySpecVersion: 1
spec:
  # upgrades: UPGRADE_SETTING
  configSync:
    # Set to true to install and enable Config Sync
    enabled: true
    # If you don't have a source of truth yet, omit the
    # following fields. You can configure them later.
    sourceType: SOURCE_TYPE
    sourceFormat: FORMAT
    syncRepo: REPO
    syncRev: REVISION
    syncBranch: BRANCH
    secretType: SECRET_TYPE
    gcpServiceAccountEmail: EMAIL
    metricsGcpServiceAccountEmail: METRICS_EMAIL
    policyDir: DIRECTORY
    preventDrift: PREVENT_DRIFT

    Substitua:

    • (Visualização) UPGRADE_SETTING: desmarque o campo e defina como auto para configurar o Config Sync para upgrade automático. Defina como manual para fazer upgrade manual do Config Sync. O valor padrão é manual. Essa flag só é compatível com GKE em clusters do Google Cloud. Para usar esse campo, talvez seja necessário atualizar a gcloud CLI executando gcloud components update.

    • SOURCE_TYPE: adicione git para sincronizar a partir de um repositório Git, oci para sincronizar a partir de uma imagem OCI ou helm para sincronizar a partir de um gráfico Helm. Se nenhum valor for especificado, o padrão será git.

    • 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 melhor maneira para você.

    • REPO: adicione o URL da fonte da verdade. Os URLs de repositórios Git e Helm usam o protocolo HTTPS ou SSH. Por exemplo, https://github.com/GoogleCloudPlatform/anthos-config-management-samples. Se você planeja usar o SSH como o secretType, digite o URL com o protocolo SSH. Esse campo é obrigatório e, caso você não insira um protocolo, o URL será tratado como HTTPS URL.

      Os URLs da OCI usam o seguinte formato: 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

    • REVISION: adicione a revisão Git (tag ou hash) com que sincronizar. Este 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 syncRev. Ao usar um hash na versão 1.17.0 ou mais recente, ele precisa ser um hash completo, e não uma forma abreviada.

    • BRANCH: a ramificação do repositório com que sincronizar. Este campo é opcional e o padrão é master. A partir da versão 1.17.0 do Config Sync, recomenda-se usar o campo syncRev especificar um nome de ramificação para simplificação. Se o campo syncRev e o campo syncBranch forem especificados, syncRev terá precedência sobre syncBranch.

    • SECRET_TYPE: uma das seguintes opções secretTypes:

      git

      • none: não usa autenticação.
      • ssh: usa 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. Se você selecionar esse tipo de autenticação, precisará criar uma vinculação de política do IAM depois de concluir a configuração do Config Sync. Para mais detalhes, consulte a guia "Conta de serviço do Google" da seção Conceder acesso somente de leitura do Config Sync ao Git.
      • gcenode: use uma conta de serviço do Google para acessar um Cloud Source Repositories. Selecione esta opção somente se a Federação de Identidade da Carga de Trabalho para GKE não estiver ativada no cluster.

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

      oci

      • none: nenhuma autenticação é usada
      • 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 Federação de Identidade da Carga de Trabalho para GKE não estiver ativada no cluster.
      • gcpserviceaccount: use uma conta de serviço do Google para acessar uma imagem.

      helm

      • token: usar um token.
      • 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 Federação de Identidade da Carga de Trabalho para GKE não estiver ativada no cluster.
      • gcpserviceaccount: use uma conta de serviço do Google para acessar uma imagem.

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

    • METRICS_EMAIL: o e-mail da conta de serviço do Google Cloud (GSA) usada para exportar as métricas do Config Sync para o Cloud Monitoring. A GSA precisa ter o papel do IAM de Gravador de métricas do Monitoring (roles/monitoring.metricWriter). A conta de serviço do Kubernetes default no namespace config-management-monitoring precisa ser vinculada ao GSA.

    • DIRECTORY: o caminho do diretório de onde sincronizar em relação à raiz do repositório Git. Todos os subdiretórios que você especificar serão incluídos e sincronizados com o cluster. O valor padrão é o diretório raiz do repositório.

    • PREVENT_DRIFT: se definido como true, ativa o webhook de admissão do Config Sync para evitar desvios, rejeitando alterações conflitantes de envio para clusters ativos. A configuração padrão é false. O Config Sync sempre corrige desvios, independentemente do valor desse campo.

    Para uma lista completa de campos que podem ser adicionados ao campo spec, consulte gcloud.

    Usar manifesto existente

    Para definir o cluster com as mesmas configurações usadas por outro cluster, recupere as configurações de um cluster registrado:

    gcloud alpha container fleet config-management fetch-for-apply \
    --membership=MEMBERSHIP_NAME \
    --project=PROJECT_ID \
    > CONFIG_YAML_PATH

    Substitua:

    • MEMBERSHIP_NAME: o nome da assinatura do cluster registrado que tem as configurações do Config Sync que você quer usar
    • PROJECT_ID: ID do projeto
    • CONFIG_YAML_PATH: o caminho para o arquivo apply-spec.yaml que contém as configurações encontradas no cluster

  3. Aplique o arquivo apply-spec.yaml. Se estiver usando um manifesto atual, aplique o arquivo ao cluster que quer configurar com as configurações encontradas no comando anterior:

    gcloud beta container fleet config-management apply \
    --membership=MEMBERSHIP_NAME \
    --config=CONFIG_YAML_PATH \
    --project=PROJECT_ID

    Substitua:

    • MEMBERSHIP_NAME: o nome da assinatura da frota escolhida ao registrar o cluster. É possível encontrar o nome com gcloud container fleet memberships list.
    • CONFIG_YAML_PATH: o caminho para o arquivo apply-spec.yaml.
    • PROJECT_ID: o ID do projeto.

Terraform

Para cada cluster em que você quer configurar o Config Sync, aplique um bloco de recursos google_gkehub_feature_membership que contenha um bloco configmanagement e config_sync:

git

resource "google_container_cluster" "cluster" {
 name = "EXISTING_CLUSTER_NAME"
 location = "EXISTING_CLUSTER_LOCATION"
}

resource "google_gke_hub_membership" "membership" {
 membership_id = "MEMBERSHIP_ID"
 endpoint {
   gke_cluster {
     resource_link = "//container.googleapis.com/${google_container_cluster.cluster.id}"
   }
 }
}

resource "google_gke_hub_feature" "feature" {
 name = "configmanagement"
 location = "global"
}

resource "google_gke_hub_feature_membership" "feature_member" {
 location = "global"
 feature = google_gke_hub_feature.feature.name
 membership = google_gke_hub_membership.membership.membership_id
 configmanagement {
   version = "VERSION"
   config_sync {
     # The field `enabled` was introduced in Terraform version 5.41.0, and
     # needs to be set to `true` explicitly to install Config Sync.
     enabled = true
     git {
       sync_repo = "REPO"
       sync_branch = "BRANCH"
       policy_dir = "DIRECTORY"
       secret_type = "SECRET"
     }
   }
 }
}

Substitua:

  • EXISTING_CLUSTER_NAME: o nome do cluster atual.
  • EXISTING_CLUSTER_LOCATION: o local do cluster.
  • MEMBERSHIP_ID: o ID de vinculação da assinatura.
  • VERSION: (opcional) o número da versão do Config Sync. Precisa ser definido para a versão 1.17.0 ou mais recente. Se ficar em branco, o padrão será a versão mais recente.
  • REPO: o URL do repositório que contém os arquivos de configuração.
  • BRANCH: a ramificação do repositório, por exemplo, main.
  • DIRECTORY: o caminho no repositório Git que representa o nível superior do repositório para sincronizar.
  • SECRET: o tipo de autenticação secreta.

oci

resource "google_container_cluster" "cluster" {
 name = "EXISTING_CLUSTER_NAME"
 location = "EXISTING_CLUSTER_LOCATION"
}

resource "google_gke_hub_membership" "membership" {
 membership_id = "MEMBERSHIP_ID"
 endpoint {
   gke_cluster {
     resource_link = "//container.googleapis.com/${google_container_cluster.cluster.id}"
   }
 }
}

resource "google_gke_hub_feature" "feature" {
 name = "configmanagement"
 location = "global"
}

resource "google_gke_hub_feature_membership" "feature_member" {
 location = "global"
 feature = google_gke_hub_feature.feature.name
 membership = google_gke_hub_membership.membership.membership_id
 configmanagement {
   version = "VERSION"
   config_sync {
     # The field `enabled` was introduced in Terraform version 5.41.0, and
     # needs to be set to `true` explicitly to install Config Sync.
     enabled = true
     oci {
       sync_repo = "REPO"
       policy_dir = "DIRECTORY"
       secret_type = "SECRET"
     }
   }
 }
}

Substitua:

  • EXISTING_CLUSTER_NAME: o nome do cluster atual.
  • EXISTING_CLUSTER_LOCATION: o local do cluster.
  • MEMBERSHIP_ID: o ID de vinculação da assinatura.
  • VERSION: (opcional) o número da versão do Config Sync. Se ficar em branco, o padrão será a versão mais recente.
  • REPO: o URL do repositório de imagens OCI que contém os arquivos de configuração.
  • DIRECTORY: o caminho absoluto do diretório que contém os recursos para sincronizar. Deixe em branco para usar o diretório raiz.
  • SECRET: o tipo de autenticação secreta.

Repita esse processo para cada cluster que quiser sincronizar.

Depois de configurar o repositório raiz, é possível optar por configurar a sincronização de vários repositórios, incluindo outros repositórios raiz e repositórios de namespace. Os repositórios de namespace são úteis caso você queira um repositório que contenha configurações com escopo de namespace sincronizadas com um namespace específico nos clusters.

Configurar padrões no nível da frota

Se a edição Enterprise do Google Kubernetes Engine (GKE) estiver ativada, será possível ativar e configurar o Config Sync como um padrão no nível da frota para os clusters. Isso significa que cada novo cluster do GKE no Google Cloud criado na frota terá o Config Sync ativado no cluster com as configurações especificadas. Saiba mais sobre a configuração padrão da frota em Gerenciar recursos no nível da frota.

Usando apenas o console do Google Cloud, é possível ativar o Config Sync por padrão nos clusters e definir a versão do Config Sync para a frota. Usando a gcloud CLI ou o Terraform, é possível ativar o Config Sync por padrão nos clusters, definir a versão do Config Sync para a frota e configurar a conexão com o repositório Git ou o repositório de imagens OCI.

Para configurar os padrões no nível da frota para o Config Sync, siga estas etapas:

gcloud

Execute o comando enable para o recurso, transmitindo o arquivo de configuração apply-spec.yaml criado ao configurar o Config Sync em um cluster individual:

gcloud beta container fleet config-management enable \
    --fleet-default-member-config=apply-spec.yaml

Use esse comando para atualizar as configurações padrão da frota a qualquer momento. Se você atualizar as configurações padrão da frota, será necessário sincronizar novamente os clusters com as configurações padrão.

Console

  1. No console do Google Cloud, acesse a página Gerenciador de recursos.

    Acessar o gerenciador de recursos

  2. No painel Config Sync, clique em Configurar.

  3. Revisar as configurações no nível da frota Todos os novos clusters criados na frota vão herdar essas configurações.

  4. Opcional: para mudar as configurações padrão, clique em Personalizar configurações da frota. Na caixa de diálogo exibida, execute as ações a seguir:

  5. Selecione Upgrades automáticos (visualização) para que o Config Sync faça upgrade das versões automaticamente ou selecione Upgrades manuais para gerenciar a versão do Config Sync. Para mais informações sobre como os upgrades automáticos funcionam, consulte Fazer upgrade do Config Sync.

  6. Se você selecionou Upgrades manuais, na lista Versão, selecione a versão do Config Sync que quer usar.

  7. Clique em Salvar alterações.

  8. Clique em Configurar.

  9. Na caixa de diálogo de confirmação Configurar as configurações da frota, clique em Confirmar. Se ainda não tiver ativado o Config Sync, clique em Confirmar para ativar a API anthosconfigmanagement.googleapis.com.

Terraform

  1. Crie um diretório para os arquivos de configuração de frota padrão do Terraform. Nesse diretório, adicione um arquivo main.tf com o seguinte recurso que define as configurações do Config Sync:

    git

    terraform {
  required_providers {
    google = {
      source = "hashicorp/google"
      version = ">=5.16.0"
      }
    }
  }

provider "google" {
  project = "PROJECT_ID"
}

resource "google_gke_hub_feature" "feature" {
  name = "configmanagement"
  location = "global"
  provider = google
  fleet_default_member_config {
    configmanagement {
    version = "VERSION"
    config_sync {
    source_format = "unstructured"
      git {
        sync_repo = "REPO"
        sync_branch = "BRANCH"
        policy_dir = "DIRECTORY"
        secret_type = "SECRET"
      }
    }
    }
  }
}

    Substitua:

    • PROJECT_ID: o ID do projeto host da frota.
    • VERSION: (opcional) o número da versão do Config Sync. Se ficar em branco, o padrão será a versão mais recente.
    • REPO: o URL do repositório que contém os arquivos de configuração.
    • BRANCH: a ramificação do repositório, por exemplo, main.
    • DIRECTORY: o caminho no repositório Git que representa o nível superior do repositório para sincronizar.
    • SECRET: o tipo de autenticação secreta.

    Para ver uma lista completa de configurações compatíveis no bloco git do Config Sync, consulte a documentação de referência do Terraform para recursos do hub do GKE.

    OCI

    terraform {
  required_providers {
    google = {
      source = "hashicorp/google"
      version = ">=5.16.0"
      }
    }
  }

provider "google" {
  project = "PROJECT_ID"
}

resource "google_gke_hub_feature" "feature" {
  name = "configmanagement"
  location = "global"
  provider = google
  fleet_default_member_config {
    configmanagement {
    version = "VERSION"
    config_sync {
    source_format = "unstructured"
      oci {
        sync_repo = "REPO"
        policy_dir = "DIRECTORY"
        secret_type = "SECRET"
      }
    }
    }
  }
}

    Substitua:

    • PROJECT_ID: o ID do projeto host da frota.
    • VERSION: o número da versão do Config Sync. Precisa ser definido para a versão 1.17.0 ou mais recente. Se ficar em branco, o padrão será a versão mais recente.
    • REPO: o URL do repositório de imagens OCI que contém arquivos de configuração.
    • DIRECTORY: o caminho absoluto do diretório que contém os recursos para sincronizar. Deixe em branco para usar o diretório raiz.
    • SECRET: o tipo de autenticação secreta.

    Para ver uma lista completa de configurações compatíveis no bloco oci do Config Sync, consulte a documentação de referência do Terraform para recursos do hub do GKE.

  2. Inicialize o Terraform no diretório criado:

    terraform init

  3. Verifique se as alterações propostas pelo Terraform correspondem ao plano esperado:

    terraform plan

  4. Crie as configurações padrão dos membros da frota:

    terraform apply

Para atualizar clusters existentes para usar as configurações padrão do Config Sync, use o console do Google Cloud ou a gcloud CLI para sincronizar clusters de frota selecionados com os padrões da frota. Também é possível configurar manualmente cada cluster com as mesmas configurações usando o Terraform seguindo as instruções para configurar o Config Sync. Se você já usou o Terraform para especificar os padrões da frota, use o mesmo bloco configmanagement e config_sync usado na definição dos padrões para configurar os clusters escolhidos.

Para sincronizar as configurações padrão do Config Sync em toda a frota, siga estas etapas:

gcloud

  1. Sincronize uma assinatura existente com a configuração padrão da frota:

    gcloud beta container fleet config-management apply \
    --origin=FLEET \
    --membership=MEMBERSHIP_NAME

    Substitua MEMBERSHIP_NAME pelo nome da assinatura de frota do cluster que deve ser sincronizado com a configuração padrão da frota.

  2. Confirme se as configurações de assinatura estão sincronizadas com o padrão da frota:

    gcloud beta container fleet config-management status

    A saída desse comando vai aparecer como Yes para o status Synced_to_Fleet_Default da assinatura que você sincronizou.

console

  1. Acessar o Gerenciador de recursosger:

    Acessar o Gerenciador de recursos: Config Sync

  2. Na tabela de clusters, selecione os clusters que quer sincronizar com as configurações da frota.

  3. Clique em Sincronizar com as configurações da frota.

Para desativar as configurações padrão do Config Sync em toda a frota, siga estas etapas:

  1. Para desativar a configuração padrão da frota, execute o seguinte comando:

    gcloud beta container fleet config-management disable --fleet-default-member-config

  2. Confirme se a configuração padrão da frota está desativada:

    gcloud beta container fleet config-management status

As configurações padrão do Config Sync são aplicadas a todos os clusters selecionados. Embora o console do Google Cloud mostre apenas um subconjunto de configurações, como a versão do Config Sync, todas as configurações no nível da frota são sincronizadas com os clusters. Por exemplo, se você configurar o Config Sync para sincronizar com um repositório Git usando o Terraform ou a gcloud CLI, essa configuração será sincronizada com seus clusters, mas não será mostrada no console do Google Cloud.

Verifique a instalação

Depois de instalar e configurar o Config Sync, verifique se a instalação foi concluída com êxito.

Console

Siga estas etapas:

  1. No console do Google Cloud, acesse a página Configuração na seção Recursos.

    Acessar a configuração

  2. Na guia Pacotes, verifique a coluna Status da sincronização na tabela de clusters. Uma instalação bem-sucedida do Config Sync tem o status Instalado. Uma fonte de verdade configurada tem o status Sincronizado.

gcloud

Execute este comando:

gcloud beta container fleet config-management status \
    --project=PROJECT_ID

Substitua PROJECT_ID pelo ID do projeto.

Uma instalação bem-sucedida tem um status de SYNCED. A partir da versão 1.18.0 do Config Sync, a saída também mostra qual versão do Config Sync está instalada e a configuração de upgrade do Config Sync.

Se uma mensagem de erro aparecer depois de executar o comando anterior, verifique se você criou o Secret git-creds. Se você criou o Secret, tente executar novamente o comando a seguir:

gcloud beta container fleet config-management apply

Também é possível usar o comando nomos status para verificar se o Config Sync foi instalado com sucesso. Uma instalação válida sem problemas tem o status PENDING ou SYNCED. Uma instalação inválida ou incompleta tem o status de NOT INSTALLED ou NOT CONFIGURED. A saída também inclui todos os erros informados.

Permissões e controles de acesso baseados em funções (RBAC)

O Config Sync inclui cargas de trabalho altamente privilegiadas. A tabela a seguir lista as permissões para essas cargas de trabalho:

Componente Namespace Conta de serviço Permissões Descrição
ConfigManagement Operator config-management-system config-management-operator cluster-admin O ConfigManagement Operator instala os outros componentes nesta tabela. Alguns desses componentes exigem permissões de administrador de cluster e, portanto, o Config Management Operator também as exige.
Config Sync config-management-system Consulte as permissões necessárias do Config Sync.

Solicitações de recursos

A seção a seguir lista as solicitações de recursos para o Config Sync.

A tabela a seguir lista os requisitos de recursos do Kubernetes para componentes do Config Sync. Para mais informações, consulte Como gerenciar recursos para contêineres na documentação do Kubernetes.

Nem todos os componentes listados são criados. As condições a seguir fazem com que cada componente seja programado:

  • O config-management-operator é instalado quando o Config Sync é ativado.
  • O reconciler-manager é instalado quando o Config Sync é ativado.
  • O admission-webhook é instalado quando a prevenção de deslocamento é ativada.
  • um reconciler é instalado para cada RootSync e RepoSync.
  • O otel-collector é instalado quando o Config Sync é ativado.

Para saber mais sobre esses componentes, consulte Arquitetura do Config Sync.

1.18

Nome da implantação Solicitação de CPU (m) por réplica Solicitação de memória (Mi) por réplica
config-management-operator 100 200
resource-group-controller-manager 110 300
admission-webhook1 10 100
otel-collector 200 400
reconciler-manager 20 150
reconciler (um por RootSync e RepoSync) Consulte Implantação do reconciliador para ver mais detalhes.

1 O webhook de admissão tem duas réplicas. Portanto, ao calcular as solicitações de recursos totais, dobre o valor se estiver usando o webhook de admissão. O webhook de admissão é desativado por padrão.

1.17

Nome da implantação Solicitação de CPU (m) por réplica Solicitação de memória (Mi) por réplica
config-management-operator 100 200
resource-group-controller-manager 110 300
admission-webhook1 10 100
otel-collector 200 400
reconciler-manager 20 150
reconciler (um por RootSync e RepoSync) Consulte Implantação do reconciliador para ver mais detalhes.

1 O webhook de admissão tem duas réplicas. Portanto, ao calcular as solicitações de recursos totais, dobre o valor se estiver usando o webhook de admissão. O webhook de admissão é desativado por padrão.

1.16

Nome da implantação Solicitação de CPU (m) por réplica Solicitação de memória (Mi) por réplica
config-management-operator 100 200
resource-group-controller-manager 110 300
admission-webhook1 10 100
otel-collector 200 400
reconciler-manager 20 150
reconciler (um por RootSync e RepoSync) Consulte Implantação do reconciliador para ver mais detalhes.

1 O webhook de admissão tem duas réplicas. Portanto, ao calcular as solicitações de recursos totais, dobre o valor se estiver usando o webhook de admissão. O webhook de admissão é desativado por padrão.

Implantação do reconciliador

Para cada objeto RootSync e RepoSync, o Config Sync cria uma implantação de reconciliador independente para processar a sincronização. A implantação do reconciliador consiste em vários contêineres. Para saber mais sobre esses contêineres, consulte Contêineres do reconciliador.

Nas versões 1.17.0 e mais recentes do Config Sync, as solicitações de recursos padrão para reconciliadores são diferentes para clusters padrão e do Autopilot. Todos os outros tipos de cluster usam os padrões Standard.

Clusters Standard

1.18

Nome do contêiner Solicitação de CPU (m) Solicitação de memória (Mi)
reconciler 50 200
otel-agent 10 100
hydration-controller (Opcional) 10 100
git-sync 10 16
gcenode-askpass-sidecar (Opcional) 10 20
helm-sync 75 128
oci-sync 25 32

1.17

Nome do contêiner Solicitação de CPU (m) Solicitação de memória (Mi)
reconciler 50 200
otel-agent 10 100
hydration-controller (Opcional) 10 100
git-sync 10 16
gcenode-askpass-sidecar (Opcional) 10 20
helm-sync 75 128
oci-sync 25 32

1.16

Nome do contêiner Solicitação de CPU (m) Solicitação de memória (Mi)
reconciler 50 200
otel-agent 10 100
hydration-controller (Opcional) 10 100
git-sync 10 200
gcenode-askpass-sidecar (Opcional) 10 20
helm-sync 50 256
oci-sync 10 200

Clusters do Autopilot

1.18

Nome do contêiner Solicitação e limite de CPU (m) Solicitação e limite de memória (Mi)
reconciler 700 512
otel-agent 10 64
hydration-controller (Opcional) 200 256
git-sync 20 32
gcenode-askpass-sidecar (Opcional) 50 64
helm-sync 250 384
oci-sync 50 64

1.17

Nome do contêiner Solicitação e limite de CPU (m) Solicitação e limite de memória (Mi)
reconciler 700 512
otel-agent 10 64
hydration-controller (Opcional) 200 256
git-sync 20 32
gcenode-askpass-sidecar (Opcional) 50 64
helm-sync 150 256
oci-sync 50 64

1.16

Nas versões do Config Sync anteriores à 1.17.0, as solicitações de recursos são as mesmas para o Standard e o Autopilot.

Para saber como substituir os limites e as solicitações de recursos padrão, consulte Substituições de recursos.

Versões Helm e Kustomize agrupadas

O Config Sync aproveita os executáveis Helm e Kustomize para renderizar as configurações em segundo plano. A tabela a seguir fornece uma lista de versões do Config Sync compatíveis com o recurso de renderização, junto com as versões agrupadas do Helm e do Kustomize.

Versões do Config Sync Versão do Helm Versão do Kustomize
1.18.0 v3.14.3 v5.3.0
1.17.1 e 1.17.3 v3.13.3 v5.3.0
1.16.3 e 1.17.0 v3.13.1 v5.1.1
1.16.1 e 1.16.2 v3.12.3 v5.1.1
1.16.0 v3.12.2 v5.1.1
1.15.3 v3.12.2 v5.1.0
1.15.1 a 1.15.2 v3.11.3 v5.0.3
1.15.0 v3.11.3 v5.0.1
1.11.0 a 1.14.3 v3.6.3 v4.5.2

Para mais informações sobre como renderizar o Helm por meio do Kustomize, consulte Configurar o Kubernetes com o Kustomize. Para informações sobre como usar a API Helm, consulte Como sincronizar gráficos do Helm a partir do Artifact Registry.

A seguir