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.

Se você configurar o Config Sync usando os comandos kubectl descritos nesta página, mais tarde poderá fazer alterações de configuração usando o Console do Google Cloud ou a Google Cloud CLI. No entanto, ao fazer alterações de configuração usando o console do Google Cloud ou a CLI gcloud, não é possível voltar a usar comandos kubectl para alterações de configuração.

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:

  • Crie ou tenha acesso a um repositório Git que possa conter os configs a que o Config Sync sincroniza.

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

Registrar um cluster

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

  1. Implante o operador
  2. Conceder ao Operator acesso somente leitura ao Git
  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.

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.

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. 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://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 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.
  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.

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

    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, PROJECT_ID-compute@developer.gserviceaccount.com, 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:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
      --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.

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 a versão 1.7 e estiver instalando o Config Sync em um cluster particular, adicione uma regra de firewall para permitir a porta 8676. O webhook de admissão do Config Sync usa a porta 8676 para prevenção de deslocamento. A partir da versão 1.8.0, a porta é alterada para 10250 e é aberta por padrão em clusters particulares. A partir da versão 1.10.0, o webhook de admissão do Config Sync está desativado por padrão.

  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
      # The `preventDrift` field is supported in Anthos Config Management version 1.10.0 and later.
      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. Crie um objeto RootSync:

    # root-sync.yaml
    # If you are using a Config Sync version earlier than 1.7.0,
    # use: apiVersion: configsync.gke.io/v1alpha1
    apiVersion: configsync.gke.io/v1beta1
    kind: RootSync
    metadata:
      name: ROOT_SYNC_NAME
      namespace: config-management-system
    spec:
      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
        # the `noSSLVerify` field is supported in Anthos Config Management version 1.8.2 and later.
        noSSLVerify: ROOT_NO_SSL_VERIFY
    

    Substitua:

    • ROOT_SYNC_NAME: adicione o nome do objeto RootSync. Para versões anteriores à 1.11.0, use root-sync. Para a versão 1.11.0 ou mais recente, especifique o nome que preferir.
    • 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 você estiver usando um secret, adicione 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.

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

  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>   git@github.com: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:

Para a versão anterior ao 1.11.0 do Config Sync:

kubectl get -n config-management-system deployment/root-reconciler

Para o Config Sync versão 1.11.0 e mais recentes:

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

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. Nas versões 1.9.0 e posteriores, o Config Management Operator é instalado no namespace config-management-system, não no namespace kube-system. Se você estiver fazendo upgrade de uma versão anterior à 1.9.0 para uma versão 1.9.0 ou posterior, exclua o antigo Config Management Operator do namespace kube-system:

    kubectl delete -n kube-system serviceaccounts config-management-operator
    kubectl delete -n kube-system deployments config-management-operator
    
  4. 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

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.

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

A seguir