Como instalar manualmente o Config Sync e o Policy Controller com kubectl

Nesta página, mostramos como instalar o Config Sync e o Policy Controller usando comandos kubectl.

Como instalar o Config Sync

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.

Antes de começar

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

Como 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 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

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

Como 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 ferramenta de linha de comando gcloud no seu sistema local, talvez seja necessário adicionar os campos --project e --zone.

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

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 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 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 o 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ê precisa usar um proxy HTTPS ou HTTP, adicione-o ao Secret com cookiefile executando 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 \
     --from-literal=https_proxy=HTTPS_PROXY_URL \
     --from-literal=http_proxy=HTTP_PROXY_URL
    

    Substitua:

*/path/to/COOKIEFILE: o caminho e o nome de arquivo apropriados *HTTPS_PROXY_URL: o URL do proxy HTTPS que você usa ao se comunicar com o repositório Git *HTTP_PROXY_URL: o URL do proxy HTTP que você usa ao se comunicar com o repositório Git

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

    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
  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 ferramenta de linha de comando gcloud, adicione o URL ao campo syncRepo do arquivo de configuração.

  2. Ao configurar o Config Sync, selecione o tipo de autenticação apropriado. Se você tiver a identidade de carga de trabalho ativada no cluster, o tipo de autenticação que precisará ser escolhido será diferente:

    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 ferramenta de linha de comando gcloud, adicione gcpserviceaccount como secretType e adicione o e-mail da sua 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.

      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/root-reconciler]" \
         GSA_NAME@PROJECT_ID.iam.gserviceaccount.com
      

      Substitua:

      • PROJECT_ID: ID do projeto da organização
      • 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 ferramenta de linha de comando gcloud, 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.

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 if you want to use ClusterSelectors and must be
      # unique among all managed clusters
      clusterName: CLUSTER_NAME
      # Enable multi-repo mode to use additional features
      enableMultiRepo: true
    

    Substitua CLUSTER_NAME pelo nome do cluster registrado ao qual você quer aplicar essa configuração.

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

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

    kubectl apply -f config-management.yaml
    

    Se você receber o seguinte erro ao tentar aplicar o arquivo, talvez tenha menos permissões do que o necessário para a instalação:

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

    Para garantir que você tenha as permissões necessárias, consulte Como preparar permissões.

    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-management.yaml --context=KUBE_CONFIG
    

    Substitua KUBE_CONFIG pelo nome do contexto do Kubernetes que você quer usar. O contexto do Kubernetes é armazenado no arquivo kubeconfig (em inglês).

  3. Crie um arquivo root-sync.yaml e copie o arquivo YAML a seguir nele:

    Para configurar a sincronização do repositório raiz, você precisa criar um objeto RootSync que sincronize seu repositório raiz com o cluster. Consulte Como sincronizar de vários repositórios para mais informações.

    # root-sync.yaml
    # If you are using a Config Sync version earlier than 1.7,
    # use: apiVersion: configsync.gke.io/v1alpha1
    apiVersion: configsync.gke.io/v1beta1
    kind: RootSync
    metadata:
      name: root-sync
      namespace: config-management-system
    spec:
      sourceFormat: FORMAT
      git:
        repo: REPO
        branch: BRANCH
        dir: "DIRECTORY"
        auth: TYPE
        secretRef:
          name: SECRET_NAME
        # the `noSSLVerify` field is supported in Anthos Config Management version 1.8.2 and later.
        noSSLVerify: SSL_VERIFY
    

    Substitua:

    • FORMAT: adicione unstructured para usar um repositório não estruturado ou hierarchy para usar um repositório hierárquico. Esses valores diferenciam maiúsculas de minúsculas. Este campo é opcional e o valor padrão é hierarchy. Recomendamos que você adicione unstructured como esse formato para organizar suas configurações da melhor maneira para você.
    • REPO: adicione o URL do repositório Git para usar como fonte. É possível inserir URLs usando o protocolo HTTPS ou SSH. Por exemplo, https://github.com/GoogleCloudPlatform/anthos-config-management-samples usa o protocolo HTTPS. Se você não inserir um protocolo, o URL será tratado como um URL HTTPS. Este campo é obrigatório.
    • BRANCH: adicione a ramificação do repositório com que sincronizar. O padrão é a ramificação principal (mestre).
    • DIRECTORY: o caminho no repositório Git ao diretório raiz que contém a configuração que você quer sincronizar. O padrão é o diretório raiz do repositório.
    • TYPE: adicione uma das seguintes SecretTypes:

      • none: não usa autenticação
      • ssh: use um par de chaves SSH
      • cookiefile: use um cookiefile
      • token: usar um token
      • 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.

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

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

  4. Aplique o RootSync ao cluster:

    kubectl apply -f root-sync.yaml
Como usar o Cloud Source Repositories com a identidade da carga de trabalho

Se a Identidade da carga de trabalho estiver ativada no cluster e você tiver usado uma conta de serviço do Google como tipo de autenticação, será necessário concluir outras etapas.

Após concluir as etapas acima, 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]" \
    PROJECT_NUMBER-compute@developer.gserviceaccount.com

Substitua:

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

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=PROJECT_NUMBER-compute@developer.gserviceaccount.com

Substitua PROJECT_NUMBER pelo número do projeto da sua organização.

Como verificar a instalação do Config Sync

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 de 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 Anthos Config Management versões 1.9.0 ou mais recente, esse pod está no namespace config-management-system. em versões anteriores, ela está no namespace kube-system. O pod pode levar alguns instantes para ser inicializado.

Para verificar se o pod está em execução no Anthos Config Management versões 1.9.0 ou posterior:

kubectl -n config-management-system get pods -l k8s-app=config-management-operator

Para verificar se o pod está sendo executado em versões anteriores à 1.9.0:

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

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 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 página "Solução de problemas".

Como 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 ou nomos.exe em todos os clientes pela 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.

Como desinstalar o Config Sync

Para desinstalar o Config Sync, edite a configuração do Anthos Config Management no arquivo config-management.yaml, remova a seção git e aplique ao cluster.

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

Como instalar o Policy Controller

As instruções a seguir mostram como instalar o Policy Controller.

Por padrão, o Policy Controller instala uma biblioteca de modelos de restrição para tipos de política comuns. Para pular a instalação dos modelos de restrição, remova a marca de comentário da linha que começa com templateLibraryInstalled no manifesto.

  1. Defina o valor de enabled no objeto spec.policyController como true no arquivo de configuração do Anthos Config Management:

    # config-management.yaml
    
    apiVersion: configmanagement.gke.io/v1
    kind: ConfigManagement
    metadata:
      name: config-management
    spec:
      # Set to true to install and enable Policy Controller
      policyController:
        enabled: true
        # Uncomment to prevent the template library from being installed
        # templateLibraryInstalled: false
        # Uncomment to enable support for referential constraints
        # referentialRulesEnabled: true
        # Uncomment to disable audit, adjust value to set audit interval
        # auditIntervalSeconds: 0
        # Uncomment to log all denies and dryrun failures
        # logDeniesEnabled: true
        # Uncomment to exempt namespaces
        # exemptableNamespaces: ["namespace-name"]
      # ...other fields...
    

    O suporte para restrições referenciais está desativado por padrão. Antes de ativá-lo, confirme se você entendeu as advertências sobre consistência posterior.

  2. Aplique a configuração usando kubectl apply.

    kubectl apply -f config-management.yaml
    

Como verificar o Policy Controller

Se o Policy Controller foi instalado corretamente, o pod está em execução. O pod pode ser reiniciado várias vezes antes de estar disponível.

Como o pod do Policy Controller é executado no namespace gatekeeper-system, é possível visualizar o status dele executando o seguinte comando:

kubectl get pods -n gatekeeper-system

O resultado será semelhante a:

NAME                              READY   STATUS    RESTARTS   AGE
gatekeeper-controller-manager-0   1/1     Running   1          53s

Como desinstalar o Policy Controller

Para desinstalar o Policy Controller, edite a configuração do Anthos Config Management no seu arquivo config-management.yaml e defina policyController.enabled como false. Depois que o Anthos Config Management remover o finalizador policycontroller.configmanagement.gke.io, a desinstalação será concluída.

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