Como instalar o Anthos Config Management

O Config Management Operator é um controlador que gerencia o Anthos Config Management em um cluster do Kubernetes. Siga estas etapas para instalar e configurar o Operator em cada cluster que você quer gerenciar usando o Anthos Config Management.

Antes de começar

Nesta seção, descrevemos os pré-requisitos necessários para você registrar os clusters compatíveis no Anthos Config Management.

Como preparar o ambiente local

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

  • O Anthos Config Management requer um direito ativo do Anthos. Para mais informações, consulte Preços para o Anthos.

  • Instale o SDK do Cloud, que fornece os comandos gcloud, gsutil e kubectl usados nestas instruções.

  • O kubectl não é instalado por padrão pelo SDK do Cloud. Para instalar o kubectl, use o seguinte comando:

    gcloud components install kubectl
    
  • Instale o comando nomos para usar o subcomando nomos status e detectar problemas durante a instalação e a configuração.

  • Para fazer o download dos componentes do Anthos Config Management, esteja autenticado no Google Cloud usando o comando gcloud auth login.

  • Configure o comando kubectl para se conectar aos seus clusters. As etapas para isso são diferentes para os clusters GKE e GKE no local:

  • A API Anthos precisa estar ativada para o projeto:

gcloud

Para ativar a API Anthos, execute o seguinte comando:

gcloud services enable anthos.googleapis.com

Console

Ativar a API Anthos

Clusters

  • Seus clusters precisam estar em uma plataforma e versão compatíveis com o Anthos.

  • Seus clusters precisam ser registrados em um ambiente Anthos usando o Connect. O ambiente do seu projeto fornece uma maneira unificada de visualizar e gerenciar seus clusters e suas cargas de trabalho como parte do Anthos, incluindo clusters fora do Google Cloud. As cobranças do Anthos se aplicam apenas aos seus clusters registrados. Veja aqui como registrar um cluster.

Permissões

O usuário do Google Cloud que instala o Anthos Config Management precisa de permissões de gerenciamento de identidade e acesso (IAM) para criar novos papéis no seu cluster.

Como registrar um cluster

Para registrar um cluster no Anthos Config Management, siga estas etapas:

  1. Implante o operador
  2. Conceder ao Operator acesso somente leitura ao Git
  3. Configure o operador

Como implantar o Operator

Se você estiver instalando o Config Management Operator usando o Console do Google Cloud, o Operator será implantado automaticamente. Continue para Criar o secret git-creds.

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-management-operator.yaml config-management-operator.yaml
    
  2. Aplique o CRD:

    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 Operator precisa de acesso somente leitura ao repositório Git (o repo) para ler os configs confirmados no repo e aplicá-los aos clusters. Se as credenciais forem necessárias, elas serão armazenadas no secret git-creds em cada cluster registrado.

Se o repo não exigir autenticação ou autorização para acesso somente leitura, você não precisará criar um secret git-creds. É possível pular para Como configurar o Anthos Config Management e definir SecretType como none.

A maioria dos usuários precisa criar credenciais porque o acesso de leitura ao repositório é restrito. O Anthos Config Management é compatível com os seguintes mecanismos de autenticação:

O mecanismo que você escolhe depende do suporte que seu repo oferece. Se todos os mecanismos estiverem disponíveis, recomendamos usar um par de chaves SSH. No momento em que este artigo foi escrito, o GitHub, o Cloud Source Repositories e o Bitbucket permitiam o uso de um par de chaves SSH. Se o repo for hospedado pela sua organização e você não souber quais métodos de autenticação são compatíveis, entre em contato com o administrador.

Depois de criar a credencial, adicione-a ao cluster como um secret. Como você cria o secret depende do método de autenticação. Para mais informações, consulte a seção referente ao seu método de autenticação abaixo.

Escolha o melhor método para autorizar seu repo dentre as opções abaixo. O método escolhido também determina o secretType usado ao configurar o Operator.

Como usar um par de chaves SSH

Se seu repo tiver suporte para o uso de um par de chaves SSH para autorização, siga as etapas desta seção para criar os materiais do secret. Caso contrário, siga as instruções usando um cookiefile.

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.

  1. Crie um par de chaves SSH para permitir que o Operator faça a autenticação no seu repositório Git. Isso será necessário 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. Substitua [GIT REPOSITORY USERNAME] e /path/to/[KEYPAIR-FILENAME] pelos valores que você quer que o Operator use para se autenticar no repositório. Recomenda-se usar uma conta separada se estiver usando um host de repositório Git de terceiros, como o GitHub, ou usar uma conta de serviço se estiver usando o Cloud Source Repositories.

    ssh-keygen -t rsa -b 4096 \
     -C "[GIT REPOSITORY USERNAME]" \
     -N '' \
     -f [/path/to/KEYPAIR-FILENAME]
    
  2. Configure seu repo 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. Substitua o nome da chave privada (aquela sem o sufixo .pub) onde houver /path/to/[KEYPAIR-PRIVATE-KEY-FILENAME].

    kubectl create secret generic git-creds \
    --namespace=config-management-system \
    --from-file=ssh=/path/to/[KEYPAIR-PRIVATE-KEY-FILENAME]
    
  4. Exclua a chave privada do disco local ou a proteja.

Como usar o cookiefile

Se o repo não for compatível com o uso de um par de chaves SSH para autorização, será possível usar um cookiefile ou um token de acesso pessoal.

Siga as etapas nesta seção para criar os materiais de secret do cookiefille.

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

  1. Depois de criar e conseguir o arquivo cookiefile, adicione-o a um novo secret no cluster. Substitua /path/to/[COOKIEFILE] pelo caminho e nome de arquivo adequados.

    kubectl create secret generic git-creds \
    --namespace=config-management-system \
    --from-file=cookie_file=/path/to/[COOKIEFILE]
    
  2. Certifique-se de proteger o conteúdo do cookiefile se você ainda precisar dele localmente. Caso contrário, exclua-o.

Como usar um token

Se sua organização não permitir o uso de chaves SSH, talvez você prefira usar um token. Com o Anthos Config Management, é 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. Substitua [USERNAME] pelo nome de usuário desejado e [TOKEN] pelo token que você criou na etapa anterior.

    kubectl create secret generic git-creds \
        --namespace="config-management-system" \
        --from-literal=username=[USERNAME] \
        --from-literal=token=[TOKEN]
    
  3. Proteja o token se você ainda precisar dele localmente. Caso contrário, exclua-o.

Como usar uma conta de serviço do Google com um Google Source Repository

Se o repo estiver em um Google Source Repository, use secretType: gcenode para conceder ao Anthos Config Management acesso a um repositório no mesmo projeto do cluster gerenciado.

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

  • A conta de serviço padrão PROJECT_NUMBER-compute@developer.gserviceaccount.com do Compute Engine para o cluster precisa ter acesso source.reader ao repositório.

    gcloud projects add-iam-policy-binding [PROJECT_ID] \
    --member serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role roles/source.reader
    
  • Os escopos de acesso dos nós no cluster precisam incluir cloud-source-repos-ro. Para isso, inclua cloud-source-repos-ro na lista --scopes especificada no momento da criação do cluster ou use o escopo cloud-platform no momento da criação do cluster:

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

Quando esses pré-requisitos forem atendidos, defina spec.git.syncRepo como o URL do Google Source Repository pretendido ao configurar o operador. Exemplo:

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

exigiria o seguinte:

spec.git.syncRepo: https://source.developers.google.com/p/my-project/r/my-repo-csr
Como usar um Google Source Repository com Identidade da 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 Operator na seção a seguir, crie uma vinculação de política do IAM entre as contas de serviço do Kubernetes e do Google. A conta de serviço do Kubernetes não será criada até que você configure o Operator para ativar o Anthos Config Management pela primeira vez.

Essa vinculação permite que a conta de serviço do Kubernetes do Anthos Config Management 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

Por fim, adicione um annotation à conta de serviço do Anthos Config Management Kubernetes 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

Como usar a opção sem autenticação

Se o repo não exigir autenticação para acesso somente leitura, será possível continuar a configurar o Operator e definir spec.git.secretType como none.

Como configurar o Operator

É possível configurar o Operator para o cluster usando kubectl ou o Console do Google Cloud.

kubectl

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

Por exemplo, crie um arquivo config-management.yaml e copie o arquivo YAML a seguir.

# 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: my-cluster
  git:
    syncRepo: git@github.com:my-github-username/csp-config-management.git
    syncBranch: 1.0.0
    secretType: ssh
    policyDir: "foo-corp"

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.

Para aplicar a configuração, use 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-1
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 Anthos Config Management 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 Anthos Config Management.
Configuração para integrações

Esses campos permitem a integração com o Config Connector e o Policy Controller.

Chave Descrição
spec.configConnector.enabled Se true, instala o Config Connector. O padrão é false.
spec.policyController.enabled Se true, ativa o Policy Controller. O padrão é false.
spec.policyController.templateLibraryInstalled Se true, instala a biblioteca de modelos de restrição. O padrão é true.

Console

Limitações

A configuração do Anthos Config Management no Console do Google Cloud tem as seguintes limitações:

  • Não é possível instalar ou configurar:
    • Policy Controller
    • Config Connector
    • Controlador de hierarquia
  • Somente um subconjunto de opções de configuração do Config Sync é compatível. As configurações não compatíveis com o Config Sync incluem:
    • spec.git.proxy
    • spec.git.secretType: gcenode
    • spec.git.secretType: token
    • spec.sourceFormat

Se você quiser usar uma dessas opções, não use o Console do Cloud.

Como configurar o Operator

Para configurar o Operator no Console do Cloud, conclua as seguintes etapas:

  1. Acesse o menu do Anthos Config Management no Console do Google Cloud.

    Acessar o menu do Anthos Config Management

  2. Selecione os clusters registrados e clique em Configurar.

  3. Na seção Autenticação de repositório do Git para ACM, conclua estas etapas:

    1. Em Tipo de secret, selecione uma das seguintes opções:

      • Nenhuma Selecione se o repo não exige autenticação para acesso somente leitura.
      • SSH
      • cookiefile

      Se você quiser selecionar token ou gcenode, configure o Operator usando kubectl.

    2. Clique em Continuar.

  4. Na seção Configurações do ACM para os clusters, faça o seguinte:

    1. No campo URL, adicione o URL do repositório Git para usar como fonte. Este campo é obrigatório.
    2. No campo ramificação, adicione a ramificação do repositório para sincronizar. O padrão é o mestre. Este campo é obrigatório.
    3. No arquivo Tag/Commit, adicione a revisão do Git (tag ou hash) para finalizar. O padrão é HEAD.
    4. Clique em Exibir opções avançadas.
    5. No campo Diretório de políticas, adicione o caminho dentro do repositório no topo da hierarquia de políticas para sincronizar. O padrão é o diretório raiz do repositório.
    6. No campo Espera de sincronização, adicione o período em segundos entre as sincronizações consecutivas. O padrão é 15 segundos.
  5. Clique em Concluído. Você será redirecionado ao menu do Anthos Config Management. Após alguns minutos, atualize a página e você verá Synced na coluna de status ao lado dos clusters configurados.

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 saída semelhante à mostrada aqui, visualize 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 Anthos Config Management criou algum evento.

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.

Solução de problemas

Nas seções a seguir, você verá como solucionar problemas de instalação do Anthos Config Management.

CPU insuficiente

A saída de kubectl get events pode incluir um evento com o tipo FailedScheduling. O evento é semelhante ao seguinte:

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, você precisa:

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

Erro: tentativa de conceder privilégios extras

kubectl apply -f config-management-operator.yaml
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=[]

Esse erro indica que o usuário atual tem menos permissões do que o necessário para a instalação. Consulte a seção "Pré-requisitos" para o controle de acesso baseado em papéis no GKE.

Objeto ConfigManagement válido, mas incorreto

Se a instalação falhar por um problema com o objeto ConfigManagement que não é devido ao 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

Outros erros podem ser adicionados no futuro.

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 Operator detectará o secret assim que ele for criado, e você não precisará aplicar a configuração novamente.

Como fazer upgrade

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.

Execute esses comandos para cada cluster registrado.

  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-management-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 Anthos Config Management.

  1. Exclua o objeto ConfigManagement do cluster:

    kubectl delete configmanagement --all

    Veja a seguir o que acontece:

    • Quaisquer ClusterRoles e ClusterRoleBindings criados no cluster pelo Anthos Config Management são excluídos dele.
    • Todas as configurações do controlador de permissão instaladas pelo Anthos Config Management são excluídas.
    • O conteúdo do namespace config-management-system é excluído, com exceção do Secret git-creds. O Anthos Config Management não funciona sem o namespace config-management-system. Quaisquer CustomResourceDefinitions criados ou modificados pelo Anthos Config Management são removidos dos clusters onde 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 no local, não será possível remover o Operator manualmente.

    Se você estiver usando o GKE e decidir que não quer mais usar o Anthos Config Management, poderá desinstalar 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 Anthos Config Management do namespace kube-system:

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

A seguir