Como instalar o Config Sync

O Config Sync 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.

Observação: esta página mostra como instalar o Config Sync como um produto independente. Se você tiver o Anthos, saiba como instalar o Config Sync com o Anthos Config Management.

Solicitações de recursos

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.

Componente	CPU	Memória
Operador do Config Sync	100 m	20 Mi
Config Sync	360 m	210 Mi

Antes de começar

Nesta seção, descrevemos os pré-requisitos que você precisa cumprir antes de instalar o Config Sync no GKE.

Como preparar o ambiente local

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

• Instale e inicialize o SDK do Cloud, que fornece os comandos gcloud, gsutil, kubectl e nomos usados nessas instruções. Se você usa o Cloud Shell, o SDK do Cloud vem pré-instalado.

• O kubectl não é instalado por padrão pelo SDK do Cloud. 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.

Como preparar os clusters

Os clusters precisam executar o GKE versão 1.14.x ou posterior.

Como preparar permissões

O usuário do Google Cloud que está instalando o Config Sync precisará de permissões de gerenciamento de identidade e acesso (IAM, na sigla em inglês) para criar novos papéis no cluster.

Como 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

Como implantar o Operator

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 do CRD 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-sync-operator.yaml config-sync-operator.yaml
   

2. Aplique o CRD:

   kubectl apply -f config-sync-operator.yaml

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

Como conceder ao Operator 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 as credenciais forem necessárias, elas serão armazenadas no secret git-creds em cada cluster registrado.

Se seu repositório não exigir autenticação para acesso somente leitura, será possível continuar a configurar o Config Sync e definir secretType como none. 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 git-creds.

Porém, a maioria dos usuários precisa criar credenciais porque o acesso de leitura ao repositório é restrito. 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. Se todos os mecanismos estiverem disponíveis, recomendamos o uso de um par de chaves SSH. O GitHub, o Cloud Source Repositories e o Bitbucket são compatíveis com o uso de um par de chaves SSH. 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. É 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: adicione o nome de usuário que você quer que o Config Sync use para a autenticação no repositório.
   • /path/to/KEYPAIR_FILENAME: adicione 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 que use 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.

cookiefile

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

O processo para adquirir um cookiefile depende da configuração do seu 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 usar um cookiefile, siga estas etapas:

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

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

   Substitua /path/to/COOKIEFILE pelo caminho e nome de arquivo adequados.

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 (PAT, na sigla em inglês) do GitHub ou a senha do app do Bitbucket como token.

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

1. Crie um token usando o GitHub 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.

   • Bitbucket: Crie uma senha de app.

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

   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: adicione o nome de usuário que você quer usar.
   • TOKEN: adicione o token que você criou na etapa anterior.

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

Conta de serviço do Google

Observação: o secretType gcenode só funciona no GKE no Google Cloud.

Se seu repositório estiver em um Cloud Source Repositories, use o secretType: gcenode para conceder acesso ao Config Sync a um repositório no mesmo projeto que o cluster gerenciado.

Pré-requisitos

Antes de começar, verifique se os seguintes pré-requisitos foram atendidos.

• Os escopos de acesso dos nós no cluster precisam incluir cloud-source-repos-ro. 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, mas, se necessário, é possível adicionar o papel com o seguinte comando:

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

  Substitua:

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

• Os escopos de acesso dos nós no cluster precisam incluir cloud-source-repos-ro. É possível adicionar esse escopo 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:

  gcloud container clusters create example-cluster --scopes=cloud-platform
  

Observaçã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.

Como usar um Cloud Source Repositories como o SyncRepo

Depois que esses pré-requisitos forem atendidos, defina spec.git.syncRepo para o URL do Cloud Source Repositories que você quer configurar o operador.

Para usar um Cloud Source Repositories como seu SyncRepo, siga estas etapas:

1. Liste todos os repositórios:

   gcloud source repos list
   

2. Na saída, copie o URL do repositório que você quer usar:

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

3. Adicione o URL como syncRepo. Exemplo:

   spec.git.syncRepo: https://source.developers.google.com/p/my-project/r/my-repo-csr
   

Como usar um Cloud Source Repositories com identidade de carga de trabalho

Se a Identidade da carga de trabalho estiver ativada no cluster, serão necessárias etapas adicionais para usar secretType: gcenode. Depois de concluir as etapas anteriores e configurar o Config Sync, que você faz na seção a seguir, 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. A conta de serviço do Kubernetes não será criada até que você configure o Config Sync pela primeira vez.

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

gcloud iam service-accounts add-iam-policy-binding \
  --role roles/iam.workloadIdentityUser \
  --member "serviceAccount:PROJECT_ID.svc.id.goog[config-management-system/importer]" \
  [e-mail]

Substitua o seguinte: * PROJECT_ID: ID do projeto da organização * PROJECT_NUMBER: número do projeto da organização

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

Depois de criar a vinculação, adicione um annotation à conta de serviço do Kubernetes do Config Sync usando o endereço de e-mail da conta de serviço padrão do Compute Engine:

kubectl annotate serviceaccount -n config-management-system importer \
  iam.gke.io/gcp-service-account=[e-mail]

Substitua PROJECT_NUMBER pelo número do projeto do cluster.

Como configurar o Operator

Para configurar o comportamento do Config Sync, crie um arquivo de configuração para o ConfigManagement CustomResource e aplique-o usando o comando kubectl apply:

1. Crie um arquivo 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:
     # clusterName is required and must be unique among all managed clusters
     clusterName: CLUSTER_NAME
     git:
       syncRepo: REPO
       syncBranch: BRANCH
       secretType: TYPE
       policyDir: "DIRECTORY"
   

   Substitua:

   • CLUSTER_NAME: adicione o nome do cluster registrado ao qual você quer aplicar essa configuração.
   • REPO: adicione o URL do repositório Git para usar como fonte. Este campo é obrigatório.
   • BRANCH: adicione a ramificação do repositório com que sincronizar. O padrão é a ramificação principal (mestre).

   • TYPE: adicione uma das seguintes SecretTypes:

     • none
     • ssh
     • cookiefile
     • token
     • gcenode

   • DIRECTORY: adicione o caminho no repositório para o topo da hierarquia de políticas para sincronizar. O padrão é o diretório raiz do repositório.

   Observação: para armazenar config-management.yaml no seu repositório Git, defina policyDir como um subdiretório e coloque todos configs dentro dele. Não coloque o arquivo config-management.yaml no subdiretório policyDir.

   Para uma lista completa de campos que podem ser adicionados ao campo spec, consulte a seção Configuração do repositório Git a seguir. Não altere os valores de configuração fora do campo de especificação.

2. Aplique a configuração com o comando kubectl apply:

   kubectl apply -f config-management.yaml
   

   Pode ser necessário criar arquivos de configuração separados para cada cluster ou cada tipo de cluster. É possível especificar o cluster usando a opção --context.

   kubectl apply -f config-management1.yaml --context=CLUSTER_NAME
   

   Substitua CLUSTER_NAME pelo nome do cluster que você quer usar.

Configuração para o repositório Git

Chave	Descrição
spec.git.syncRepo	O URL do repositório Git para usar como fonte. Obrigatório.
spec.git.syncBranch	A ramificação do repositório com que sincronizar. Padrão: master.
spec.git.policyDir	O caminho no repositório Git que representa o nível superior do repo que será sincronizado. Padrão: o diretório raiz do repositório.
spec.git.syncWait	Período em segundos entre sincronizações consecutivas. Padrão: 15.
spec.git.syncRev	Revisão Git (tag ou hash) para check-out. Padrão HEAD.
spec.git.secretType	O tipo de secret configurado para acesso ao repositório Git. Um de ssh, cookiefile, token, gcenode ou none. Obrigatório.
spec.sourceFormat	Quando definido como unstructured, configura um repo não hierárquico. Padrão: hierarchy.

Configuração de proxy para o repositório Git

Se as políticas de segurança da organização exigirem que você direcione o tráfego por meio de um proxy HTTP(S), é possível configurar o Config Sync para se comunicar com o host do Git usando o URI do proxy.

Chave	Descrição
spec.git.proxy.httpProxy	httpProxy define uma variável de ambiente HTTP_PROXY usada para acessar o repo Git.
spec.git.proxy.httpsProxy	httpsProxy define uma variável de ambiente HTTPS_PROXY usada para acessar o repo Git.

Se os campos httpProxy e httpsProxy forem especificados, httpProxy será ignorado.

Configuração para comportamento do objeto ConfigManagement

Chave	Descrição
spec.clusterName	O nome definido pelo usuário para o cluster usado por ClusterSelectors para agrupar clusters. Exclusivo em uma instalação do Config Sync.

Como verificar a instalação

Use o comando nomos status para verificar se o Operator foi instalado. Uma instalação válida sem problemas tem o status PENDING ou SYNCED. Uma instalação inválida ou incompleta tem o status NOT INSTALLED OU NOT CONFIGURED. A saída também inclui todos os erros informados.

Quando o Operator é implantado com sucesso, ele é executado em um pod com o nome que começa com config-management-operator, no namespace kube-system. O pod pode levar alguns instantes para ser inicializado. Verifique se ele está em execução:

kubectl -n kube-system get pods | grep config-management

Se o pod estiver em execução, a resposta do comando será semelhante, mas não idêntica à seguinte:

config-management-operator-6f988f5fdd-4r7tr 1/1 Running 0 26s

Também é possível verificar se o namespace config-management-system existe:

kubectl get ns | grep 'config-management-system'

A resposta do comando é semelhante à seguinte:

config-management-system Active 1m

Se os comandos não retornarem uma resposta semelhante à mostrada aqui, consulte os registros para ver o que deu errado:

kubectl -n kube-system logs -l k8s-app=config-management-operator

Também é possível usar kubectl get events para verificar se o Config Sync criou eventos.

kubectl get events -n kube-system

É possível ter uma configuração inválida que não é detectada imediatamente, como um secret git-creds ausente ou inválido. Para ver as etapas de solução de problemas, consulte Objeto ConfigManagement válido, mas incorreto na seção "Solução de problemas" deste tópico.

Como fazer upgrade de versões do Config Sync

Nesta seção, fornecemos instruções gerais para fazer upgrade para a versão atual. Antes de fazer upgrade, consulte as Notas de lançamento para ver instruções específicas.

Observação: não ignore as versões secundárias ao fazer upgrade.

Execute esses comandos para cada cluster inscrito.

1. Faça o download do manifesto do Operator e dos comandos nomos da nova versão.

2. Aplique o manifesto do Operator:

   kubectl apply -f config-sync-operator.yaml
   

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

3. Substitua o comando nomos ou nomos.exe em todos os clientes pela nova versão. Isso garante que o comando nomos sempre consiga o status de todos os clusters registrados e valide os configs para eles.

Como desinstalar o Operator de um cluster

Siga estas instruções para desinstalar o Operator de um cluster. Siga estas etapas para cada cluster que você não quer mais gerenciar usando o Config Sync.

Observações sobre a desinstalação do Config Sync

• Desinstalar o Config Sync não afeta os configs no seu repo nem remove os configs dos clusters.
• Antes de desinstalar o Config Sync de um cluster, o Operator precisa estar em execução.

1. Exclua o objeto ConfigManagement do cluster:

   kubectl delete configmanagement --all

   Veja a seguir o que acontece:

   • Todos os ClusterRoles e ClusterRoleBindings criados no cluster pelo Config Sync são excluídos do cluster.
   • Todas as configurações do controlador de admissão instaladas pelo Config Sync são excluídas.
   • O conteúdo do namespace config-management-system é excluído, com exceção do Secret git-creds. O Config Sync não funciona sem o namespace config-management-system. Todos os CustomResourceDefinitions criados ou modificados pelo Config Sync são removidos dos clusters em que foram criados ou modificados. Os CustomResourceDefinitions (CRDs) necessários para executar o Operator ainda existem porque, do ponto de vista do Kubernetes, eles foram adicionados pelo usuário que instalou o Operator. As informações sobre como removê-los estão na próxima etapa.

2. Neste ponto, o Operator ainda existe no cluster, mas não faz nada.

   Se você estiver usando o GKE e decidir que não quer mais usar o Config Sync, desinstale o Operator seguindo estas etapas:

   1. Verifique se o namespace config-management-system está vazio depois de excluir o objeto ConfigManagement na etapa anterior. Aguarde até que o comando kubectl -n config-management-system get all retorne No resources found.

   2. Exclua o namespace config-management-system:

      kubectl delete ns config-management-system
      

   3. Exclua a CustomResourceDefinition de ConfigManagement:

      kubectl delete crd configmanagements.configmanagement.gke.io
      

   4. Exclua todos os objetos do Config Sync do namespace kube-system:

      kubectl -n kube-system delete all -l k8s-app=config-management-operator
      

Solução de problemas

As seções a seguir ajudam você a solucionar problemas na instalação do Config Sync.

CPU insuficiente

A saída de kubectl get events pode incluir um evento com o tipo FailedScheduling. O evento será parecido com o seguinte exemplo:

LAST SEEN   TYPE      REASON              OBJECT                                             MESSAGE
9s          Warning   FailedScheduling    pod/config-management-operator-74594dc8f6    0/1 nodes are available: 1 Insufficient cpu.

Para corrigir esse erro, escolha uma das seguintes opções:

• adicionar um nó a um pool de nós do GKE atual.
• criar um pool com nós maiores.

Erro: tentativa de conceder privilégios extras

Se você receber o seguinte erro:

Error from server (Forbidden): error when creating "config-sync-operator.yaml": clusterroles.rbac.authorization.k8s.io "config-management-operator" is forbidden: attempt to grant extra privileges: [...] ruleResolutionErrors=[]

Ao tentar aplicar o arquivo config-management-operator.yaml, você terá menos permissões do que o necessário para a instalação. Consulte Como preparar permissões para garantir que você tenha as permissões necessárias.

Objeto ConfigManagement válido, mas incorreto

Se a instalação falhar por um problema com o objeto ConfigManagement que não seja causado por um erro de sintaxe YAML ou JSON, o objeto ConfigManagement talvez esteja instanciado no cluster, mas não funcione corretamente. Nesta situação, use o comando nomos status para verificar se há erros no objeto ConfigManagement.

Uma instalação válida sem problemas tem o status PENDING ou SYNCED.

Uma instalação inválida tem o status NOT CONFIGURED e lista um dos seguintes erros:

• missing git-creds Secret
• missing required syncRepo field
• git-creds Secret is missing the key specified by secretType

Para resolver o problema, corrija o erro de configuração. Dependendo do tipo de erro, talvez seja necessário reaplicar o manifesto ConfigManagement ao cluster.

Se o problema for que você esqueceu de criar o secret git-creds, o Config Sync detectará o secret assim que ele for criado, e você não precisará aplicar a configuração novamente.

A seguir

• Conheça o guia de início rápido.
• Saiba mais sobre como criar configs.
• Use o comando nomos.