Instalar manualmente o Config Sync com kubectl

Nesta página, mostramos como instalar o Config Sync usando comandos kubectl. O Config Management Operator é um controlador que gerencia o Config Sync em um cluster do Kubernetes. Siga estas etapas para instalar e configurar o Operator em cada cluster que você quer gerenciar usando o Config Sync.

Atenção: os métodos usados nesta página só devem ser usados se você for um usuário do Anthos que use clusters do Anthos no VMware. Se você instalar o Config Sync com esses comandos, sua instalação não será compatível com o Console do Google Cloud ou a Google Cloud CLI.

Antes de começar

Nesta seção, descrevemos os pré-requisitos que você precisa atender antes de instalar o Config Sync usando kubectl.

Preparar o ambiente local

Antes de instalar o Operator, confira se você preparou o ambiente local realizando as seguintes tarefas:

• Criar, ou ter acesso a, um repositório Git que contenha as configurações que o Config Sync sincroniza com, um repositório Helm que contém os gráficos que o Config Sync sincroniza com (Visualizar) ou uma imagem OCI armazenada no Artifact Registry ou no Container Registry.

• Instale e inicialize a Google Cloud CLI, que fornece os comandos gcloud, gsutil, kubectl e nomos usados nestas instruções. Se você usa o Cloud Shell, a Google Cloud CLI já vem pré-instalada.

• O kubectl não é instalado por padrão pela Google Cloud CLI. Para instalar o kubectl, use o seguinte comando:

  gcloud components install kubectl
  

• Autentique-se no Google Cloud usando o comando gcloud auth login para fazer o download de componentes do Config Sync.

Prepare seus clusters

Criar ou ter acesso a um cluster do GKE que atenda aos requisitos do Config Sync.

Preparar permissões

Usuários do Google Cloud que estão instalando o Config Sync precisam de permissões do IAM para criar novos papéis no cluster. Se necessário, conceda esses papéis com os seguintes comandos:

gcloud container clusters get-credentials CLUSTER_NAME

kubectl create clusterrolebinding cluster-admin-binding \
    --clusterrole cluster-admin --user USER_ACCOUNT

Substitua:

• CLUSTER_NAME: o nome do cluster
• USER_ACCOUNT: o endereço de e-mail da sua conta do Google Cloud

Dependendo de como você configurou a Google Cloud CLI no sistema local, talvez seja necessário adicionar os campos --project e --zone.

Se você precisarpermitir que o Operator tenha acesso ao OCI usando gcpserviceaccount como tipo de autenticação, para criar uma vinculação de política, é preciso ter a permissão iam.serviceAccounts.setIamPolicy. Para consegui-la, conceda o papel de administrador da conta de serviço do IAM (roles/iam.serviceAccountAdmin). Também é possível conseguir essa permissão com papéis personalizados ou outros papéis predefinidos.

Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.

Registrar um cluster

Para inscrever um cluster no Config Sync, siga estas etapas:

1. Implante o operador
2. Conceda ao operador acesso somente leitura a uma das seguintes opções:
   • Git
   • OCI
   • Helm (visualização)
3. Configure o operador

Implante o operador

Depois de garantir que você atende a todos os pré-requisitos, implante o Operator fazendo o download e aplicando um manifesto YAML.

1. Faça o download da versão mais recente dos manifestos do Operator usando o comando a seguir. Para fazer o download de uma versão específica, consulte Downloads.

   gsutil cp gs://config-management-release/released/latest/config-management-operator.yaml config-management-operator.yaml
   

2. Aplique os manifestos:

   kubectl apply -f config-management-operator.yaml

Se isso falhar, consulte a solução de problemas.

Permitir acesso de somente leitura ao Operator

Se você armazenar suas configurações no Git, precisará conceder ao Operator acesso somente leitura ao Git. Se você armazenar as configurações como imagens OCI, será necessário conceder ao Operator acesso somente leitura a OCI. Se você armazenar suas configurações no Helm, será necessário conceder acesso somente leitura ao operador para o Helm.

Conceder ao operador acesso somente leitura 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 você puder navegar no repositório usando uma interface da Web sem fazer login ou se você puder 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
• cookiefile
• Token
• Conta de serviço do Google (somente Google Source Repositories)

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.

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.

Aviso: proteja os arquivos criados por este comando. Eles permitem ler seu repositório.

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.

   Observação: crie a chave SSH sem uma senha longa. O Config Sync não é compatível com senhas longas de chave SSH.

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:

   • Cloud Source Repositories
   • Bitbucket
   • GitHub. Recomendamos que você crie chaves de implantação separadas para fornecer acesso somente leitura a um único repositório do GitHub.
   • GitLab

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. Exclua a chave privada do disco local ou a proteja.

5. 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://[e-mail]: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

Observação: o uso de credenciais cookiefile só é compatível com o Cloud Source Repositories. Se você quiser usar o GitHub com autenticação cookiefile, use o Cloud Source Repositories para espelhar seu repositório do GitHub.

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.
   Observação: por questões de segurança, o proxy HTTP não é suportado.

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.

   • GitHub: crie um PAT. Conceda ao token o escopo repo para que ele possa ler os repositórios particulares. Como você vincula um PAT a uma conta do GitHub, também recomendamos criar um usuário de máquina e vincular seu PAT a ele.
   • GitLab: crie um PAT ou um token de implantação
   • Bitbucket: crie uma senha de app.

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 que você criou 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 que você criou na etapa anterior
   • HTTPS_PROXY_URL: o URL do proxy HTTPS que você usa ao se comunicar com o repositório Git.
   Observação: por questões de segurança, o proxy HTTP não é suportado.

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, será possível conceder ao Config Sync acesso a um repositório no mesmo projeto do cluster gerenciado usando uma conta de serviço do Google.

Para usar um repositório no Cloud Source Repositories como seu repositório do Config Sync, siga estas etapas:

1. Recupere seu 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 você quer usar. 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.

2. Ao configurar o Config Sync, selecione o tipo de autenticação apropriado. O tipo de autenticação que você precisa escolher depende do tipo de cluster que você tem e de como ativou a Identidade da carga de trabalho.

   • Identidade da carga de trabalho ativada: use esse método se a Identidade da carga de trabalho do GKE estiver ativada ou se você estiver usando a Identidade da carga de trabalho da frota. Se você estiver usando a Identidade da carga de trabalho da frota, poderá usar esse método de autenticação para clusters do GKE e de outros clusters.

     O Config Sync usará a Identidade da carga de trabalho da frota por padrão se o cluster estiver registrado em uma frota. Verifique se a Identidade da carga de trabalho da frota está ativada nos clusters registrados. Para mais informações, consulte Registrar um cluster. Se o cluster estiver em um projeto diferente do projeto host da frota, será necessário vincular a conta de serviço do Google à conta de serviço do Kubernetes no projeto host da frota.

   • Identidade da carga de trabalho não ativada: só é possível usar o método para clusters do GKE.

   Identidade da carga de trabalho ativada

   1. Se necessário, crie uma conta de serviço. Conceda à conta de serviço acesso de leitura ao Cloud Source Repositories concedendo a ela o papel source.reader.

   2. Se você configurar o Config Sync usando o Console do Google Cloud, selecione Identidade da carga de trabalho 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 Google Cloud CLI, adicione gcpserviceaccount como secretType e adicione o e-mail da conta de serviço a gcpServiceAccountEmail.

   3. 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 o mesmo Pool de Identidades de cargas de trabalho. Com o conceito de integridade 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 do 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 \
         --role roles/iam.workloadIdentityUser \
         --member "serviceAccount:PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]" \
         GSA_NAME@PROJECT_ID.iam.gserviceaccount.com
      

      Substitua:

      • PROJECT_ID: se você estiver usando a Identidade da carga de trabalho do GKE, adicione a ID do projeto da sua organização.

        Se você usa a Identidade da carga de trabalho da frota, é possível utilizar duas IDs de projetos diferentes. Em serviceAccount:PROJECT_ID, adicione a ID do projeto da frota em que o cluster está registrado. Em GSA_NAME@PROJECT_ID, adicione um ID para qualquer projeto que tenha acesso de leitura ao repositório no Cloud Source Repositories.

      • KSA_NAME: a conta de serviço do Kubernetes do reconciliador. Para repositórios raiz, se o nome RootSync for root-sync, KSA_NAME será root-reconciler. Caso contrário, será root-reconciler-ROOT_SYNC_NAME.

        Para repositórios de namespace, se o nome do RepoSync for repo-sync, KSA_NAME será ns-reconciler-NAMESPACE. Caso contrário, será ns-reconciler-NAMESPACE-REPO_SYNC_NAME.

      • GSA_NAME: a conta de serviço personalizada do Google que você quer usar para se conectar ao Cloud Source Repositories. Verifique se a conta de serviço do Google selecionada tem o papel source.reader.

      Observação: a criação dessa vinculação de política requer a permissão iam.serviceAccounts.setIamPolicy.

   Identidade da carga de trabalho não ativada

   Se você configurar o Config Sync usando o Console do Google Cloud, selecione Google Cloud Repository 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. Por padrão, a conta de serviço padrão do Compute Engine, [e-mail], tem acesso de source.reader ao repositório para o mesmo projeto. No entanto, se o Cloud Source Repositories estiver localizado em um projeto diferente do projeto do cluster, você precisará conceder a conta de serviço padrão do Compute Engine do projeto do cluster, o source.reader no projeto do Cloud Source Repositories.

   É possível adicionar o papel source.reader com o seguinte comando:

   gcloud projects add-iam-policy-binding PROJECT_ID \
     --member serviceAccount:[e-mail] \
     --role roles/source.reader
   

   Substitua:

   • PROJECT_ID: ID do projeto da organização
   • PROJECT_NUMBER: número do projeto da organização

   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.

Conceder ao Operator acesso somente leitura a OCI

O Config Sync precisa de acesso somente leitura à imagem OCI armazenada no Artifact Registry ou no Container 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. Para imagens com acesso de leitura restrito, use uma conta de serviço do Google para autenticação com gcenode ou gcpserviceaccount como o tipo de autenticação.

gcenode

Se o cluster for um cluster do GKE e a Identidade da carga de trabalho não estiver ativada, use gcenode como o tipo de autenticação. O Config Sync usa a conta de serviço padrão do Compute Engine. Conceda à conta de serviço padrão do Compute Engine acesso de leitura ao Artifact Registry ou ao Container Registry.

1. Salve o número do projeto em uma variável de ambiente executando o seguinte comando:

   export PROJECT_NUMBER=$(gcloud projects describe PROJECT_ID \
       --format=json | jq -r .projectNumber)
   

   Substitua PROJECT_ID pelo ID do projeto.

2. Conceda à conta de serviço do Compute Engine permissão de leitura para o Artifact Registry ou o Container Registry:

   Artifact Registry

   Para conceder acesso ao Artifact Registry, execute o seguinte comando:

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member=serviceAccount:[e-mail] \
       --role=roles/artifactregistry.reader
   

   Container Registry

   Para conceder acesso ao Container Registry, execute o seguinte comando:

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member=serviceAccount:[e-mail] \
       --role=roles/containerregistry.ServiceAgent
   

gcpserviceaccount

Se o cluster usar a Identidade da carga de trabalho do GKE ou a Identidade da carga de trabalho da frota, será possível usar gcpserviceaccount como o tipo de autenticação.

1. Se você ainda não tiver uma conta de serviço, crie uma e conceda a ela permissão para o Artifact Registry ou o Container Registry:

   Artifact Registry

   Conceda à conta de serviço o papel do IAM de leitor do Artifact Registry (roles/artifactregistry.reader).

   Container Registry

   Conceda à conta de serviço o papel de IAM de agente de serviço (roles/containerregistry.ServiceAgent) do Container Registry.

2. 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 \
       --role roles/iam.workloadIdentityUser \
       --member "serviceAccount:PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]" \
   GSA_NAME@PROJECT_ID.iam.gserviceaccount.com
   

   Substitua:

   • PROJECT_ID: se você está usando a identidade da carga de trabalho do GKE, esse é o ID do projeto da sua organização. Se você usa a Identidade da carga de trabalho da frota, é possível utilizar dois IDs de projetos diferentes. Em serviceAccount:PROJECT_ID, adicione o ID do projeto da frota em que o cluster está registrado. Em GSA_NAME@PROJECT_ID, adicione um ID para qualquer projeto que tenha acesso de leitura ao repositório no Cloud Source Repositories.
   • KSA_NAME: a conta de serviço do Kubernetes do reconciliador.
     • Para repositórios raiz, se o nome RootSync for root-sync, adicione root-reconciler. Caso contrário, adicione root-reconciler-ROOT_SYNC_NAME.
     • Para repositórios de namespace, se o nome RepoSync for repo-sync, adicione ns-reconciler-NAMESPACE. Caso contrário, adicione ns-reconciler-NAMESPACE-REPO_SYNC_NAME.
   • GSA_NAME: a conta de serviço personalizada do Google que você quer usar para se conectar ao Artifact Registry ou ao Container Registry.
     • Para o Artifact Registry, a conta de serviço precisa ter o papel do IAM de leitor do Artifact Registry (roles/artifactregistry.reader).
     • Para o Container Registry, a conta de serviço precisa ter o papel do IAM de agente de serviço do Container Registry (roles/containerregistry.ServiceAgent).
   Observação: a criação dessa vinculação de política requer a permissão iam.serviceAccounts.setIamPolicy.

Configurar o operador de uma autoridade certificadora

No caso dos servidores Git configurados com certificados de uma autoridade certificadora (CA, na sigla em inglês) que ainda não é confiável, o Config Sync pode ser configurado para usar um certificado CA para verificar as conexões HTTPS com o servidor Git.

Se o servidor Git já estiver usando uma CA confiável ou se você não estiver se conectando por HTTPS, pule esta etapa e deixe caCertSecretRef não definido.

RootSync

1. Busque e salve o certificado de CA usado para emitir o certificado do seu servidor Git.

2. Para objetos RootSync, o Secret precisa ser criado no namespace config-management-system. Exemplo:

   kubectl create ns config-management-system && 
   
   kubectl create secret generic ROOT_CA_CERT_SECRET_NAME 
   
    --namespace=config-management-system 
   
    --from-file=cert=/path/to/CA_CERT_FILE
   

3. Ao configurar o operador, defina o valor do campo spec.git.caCertSecretRef.name no objeto RootSync como ROOT_CA_CERT_SECRET_NAME.

RepoSync

1. Busque e salve o certificado de CA usado para emitir o certificado do seu servidor Git.

2. Para objetos RepoSync, o Secret precisa ser criado no mesmo namespace que o RepoSync. Exemplo:

   kubectl create ns REPO_SYNC_NAMESPACE && 
   
   kubectl create secret generic NAMESPACE_CA_CERT_SECRET_NAME 
   
    --namespace=REPO_SYNC_NAMESPACE 
   
    --from-file=cert=/path/to/CA_CERT_FILE
   

3. Ao configurar o RepoSync, defina o valor do campo spec.git.caCertSecretRef.name no objeto RepoSync como NAMESPACE_CA_CERT_SECRET_NAME.

Conceder ao operador acesso somente leitura ao Git

Visualização

Esse recurso é coberto pelos Termos de ofertas pré-GA dos Termos de Serviço do Google Cloud. Os recursos pré-GA podem ter suporte limitado, e as mudanças realizadas podem não ser compatíveis com outras versões pré-GA. Para mais informações, consulte as descrições da fase de lançamento.

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
• gcenode

• gcpserviceaccount

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 controlador.
• USERNAME: o nome de usuário do repositório do Helm.
• PASSWORD: a senha do repositório do Helm.

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

gcenode

Se o cluster for um cluster do GKE e a Identidade da carga de trabalho não estiver ativada, use gcenode como o 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. Salve o número do projeto em uma variável de ambiente:

   export PROJECT_NUMBER=$(gcloud projects describe PROJECT_ID --format='value(projectNumber)')
   

   Substitua PROJECT_ID pelo ID do projeto.

2. 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:[e-mail] \
       --role=roles/artifactregistry.reader
   

gcpserviceaccount

Se você armazenar o gráfico do Helm no Artifact Registry e o cluster usar Identidade da carga de trabalho do GKE ouIdentidade da carga de trabalho da frota ,gcpserviceaccount como seu tipo de autenticação.

1. Se você ainda não tiver uma conta de serviço, crie uma conta de serviço e conceda a ela o papel do IAM Leitor de Artifact Registry (roles/artifactregistry.reader). 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.

2. 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 \
       --role roles/iam.workloadIdentityUser \
       --member "serviceAccount:PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]" \
   GSA_NAME@PROJECT_ID.iam.gserviceaccount.com
   

   Substitua:

   • PROJECT_ID: se você está usando a identidade da carga de trabalho do GKE, esse é o ID do projeto da sua organização. Se você usa a Identidade da carga de trabalho da frota, é possível utilizar dois IDs de projetos diferentes. Em serviceAccount:PROJECT_ID, adicione o ID do projeto da frota em que o cluster está registrado. Em GSA_NAME@PROJECT_ID, adicione um ID para qualquer projeto que tenha acesso de leitura ao repositório no Cloud Source Repositories.
   • KSA_NAME: a conta de serviço do Kubernetes do reconciliador.
     • Para repositórios raiz, se o nome RootSync for root-sync, adicione root-reconciler. Caso contrário, adicione root-reconciler-ROOT_SYNC_NAME.
     • Para repositórios de namespace, se o nome RepoSync for repo-sync, adicione ns-reconciler-NAMESPACE. Caso contrário, adicione ns-reconciler-NAMESPACE-REPO_SYNC_NAME.
   • 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).
   Observação: a criação dessa vinculação de política requer a permissão iam.serviceAccounts.setIamPolicy.

Configure o operador

Para configurar a sincronização a partir do repositório raiz, é preciso ativar o modo de vários repositórios no objeto ConfigManagement e criar um objeto RootSync que sincroniza o repositório raiz ao cluster. Só é possível criar um repositório raiz por cluster, e ele pode ser um repositório não estruturado ou um repositório hierárquico.

1. Se você estiver usando o webhook de admissão do Config Sync (o webhook de admissão está desativado por padrão) e instalando o Config Sync em um cluster particular, adicione uma regra de firewall para permitir a porta 10250. O webhook de admissão do Config Sync usa a porta 10250 para prevenção de deslocamento.

2. Crie um arquivo chamado config-management.yaml e copie o arquivo YAML a seguir nele:

   # config-management.yaml
   apiVersion: configmanagement.gke.io/v1
   kind: ConfigManagement
   metadata:
     name: config-management
   spec:
     # The `enableMultiRepo` field is set to true to enable RootSync and RepoSync APIs.
     enableMultiRepo: true
     preventDrift: PREVENT_DRIFT
   

   Substitua:

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

3. Aplique as alterações:

   kubectl apply -f config-management.yaml
   

4. Aguarde até que os CRDs RootSync e RepoSync estejam disponíveis:

   until kubectl get customresourcedefinitions rootsyncs.configsync.gke.io reposyncs.configsync.gke.io; do date; sleep 1; echo ""; done
   

5. Salve um dos seguintes manifestos como root-sync.yaml. Use a versão do manifesto que corresponda ao tipo da fonte de verdade 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: adicione a revisão do Git (tag ou hash) para check-out. Este campo é opcional e o valor padrão é HEAD.
   • ROOT_BRANCH: adicione a ramificação do repositório com que sincronizar. Este campo é opcional e o valor padrão é master.
   • 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 ou no Container 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. Esse campo é compatível com o Anthos Config Management 1.13.1 e versões mais recentes. 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 ou no Container 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.

6. Aplique as alterações:

   kubectl apply -f root-sync.yaml
   

Verifique o status de sincronização do repositório raiz

Use o comando nomos status para inspecionar o status de sincronização do repositório raiz:

nomos status

O resultado será semelhante a:

my_managed_cluster-1
  --------------------
  <root>   [e-mail]:foo-corp/acme/admin@main
  SYNCED   f52a11e4

Verificar a instalação do RootSync

Quando você cria um objeto RootSync, o Config Sync cria um reconciliador com o prefixo root-reconciler. Um reconciliador é um pod implantado como uma implantação. Ele sincroniza manifestos de um repositório Git com um cluster.

Para verificar se o objeto RootSync está funcionando corretamente, verifique o status da implantação do root-reconciler:

kubectl get -n config-management-system deployment \
    -l configsync.gke.io/sync-name=ROOT_SYNC_NAME

Substitua ROOT_SYNC_NAME pelo nome de RootSync.

O resultado será semelhante a:

NAME              READY   UP-TO-DATE   AVAILABLE   AGE
root-reconciler   1/1     1            1           3h42m

Para conhecer outras formas de explorar o status do objeto RootSync, consulte Como monitorar objetos RootSync e RepoSync.

Depois de concluir a configuração do repositório raiz, será possível configurar a sincronização a partir de vários repositórios. Esses repositórios são úteis se você quiser um repositório que contenha configurações com escopo de namespace sincronizadas com um namespace específico nos clusters.

Fazer upgrade do Config Sync

Observação: o upgrade de uma versão anterior à 1.10.0 removerá todos os recursos de webhook de admissão do Config Sync.

Para fazer upgrade do Config Sync, execute estes comandos para cada cluster inscrito:

1. Faça o download do manifesto do Anthos Config Management e dos comandos nomos para a nova versão.

2. Aplique o manifesto do Anthos Config Management:

   kubectl apply -f config-management-operator.yaml
   

   Esse comando atualiza a imagem do Anthos Config Management. O Kubernetes recupera a nova versão e reinicia o pod do Anthos Config Management usando a nova versão. Quando o Anthos Config Management é iniciado, ele executa um loop de reconciliação que aplica o conjunto de manifestos agrupados na nova imagem. Isso atualiza e reinicia o pod de cada componente.

3. Substitua o comando nomos em todos os clientes com a nova versão. Essa mudança garante que o comando nomos sempre consiga o status de todos os clusters registrados e valide as configurações para eles.

Desinstalar o Config Sync

Cuidado: é um problema conhecido que excluir um objeto RootSync ou RepoSync não limpa as anotações e os rótulos do Config Sync. e o webhook de admissão do Config Sync nega solicitações que tentem excluir esses recursos se o Config Sync ainda estiver ativado no cluster. A solução alternativa é cancelar o gerenciamento ou excluir esses recursos gerenciados antes de excluir o objeto RootSync ou RepoSync correspondente.

Para desinstalar o Config Sync, conclua as etapas a seguir:

1. Um administrador central deve remover o repositório raiz:

   1. Remova ou exclua os recursos gerenciados pelo objeto RootSync seguindo as instruções de solução.

   2. Exclua o objeto RootSync executando o seguinte comando:

      kubectl delete -f root-sync.yaml
      

2. Remova todos os repositórios.

3. Remova o campo spec.enableMultiRepo do arquivo config-management.yaml.

4. Aplique o arquivo config-management.yaml ao cluster.

Observação: a desativação desse recurso não afeta as configurações aplicadas anteriormente pelo Config Sync aos clusters.

Se você quiser desinstalar totalmente o Anthos Config Management, consulte Como remover o Config Management Operator.

A seguir

• Descubra como configurar a sincronização a partir de vários repositórios.