Como sincronizar com vários repositórios

A ativação do modo de vários repositórios no Config Sync permite sincronizar configurações de vários repositórios com o mesmo conjunto de clusters. Para usar o modo de vários repositórios, você precisa criar um único repositório raiz e, opcionalmente, criar repositórios de namespace. Um repositório raiz pode sincronizar configs de escopo de cluster e de namespace e geralmente é gerenciado por um administrador. Os repositórios de namespace contêm configurações com escopo de namespace sincronizadas com um namespace específico entre os clusters. Para saber mais sobre esses tipos de repositórios, consulte a seção Repositórios na visão geral do Config Sync.

Cada repositório tem uma única referência do Git (uma ramificação de repositório, confirmação ou tag e tupla de diretórios) que pode ser gerenciada separadamente. Essa configuração separa o ciclo de vida da implantação de configuração para diferentes equipes. Ele também oferece mais autonomia para você escolher onde colocar o repositório e como estruturá-lo.

O diagrama a seguir mostra uma visão geral de como as equipes podem usar um repositório raiz e repositórios de namespace:

Um administrador central que controla várias configurações e operadores de apps
que controlam as próprias configurações de namespace.

Neste diagrama, um administrador central gerencia a infraestrutura centralizada da organização e aplica políticas no cluster e em todos os namespaces na organização.

Os operadores, que são responsáveis por gerenciar implantações ativas, aplicam configurações aos aplicativos nos namespaces em que trabalham.

Antes de começar

Conclua as seguintes tarefas antes de ativar o modo de vários repositórios:

  • Criar ou ter acesso a repositórios do Git.
  • Criar ou ter acesso a um projeto do Google Cloud.
  • Crie ou tenha acesso a um cluster do Google Kubernetes Engine (GKE) que atenda aos seguintes requisitos:
    • É um cluster padrão. O Config Sync não é compatível com clusters do piloto automático.
    • Usa uma versão do GKE entre 1.18 e 1.20.
    • Tem um pool de nós que usa um tipo de máquina com pelo menos quatro vCPUs.
  • Use uma versão do Config Sync de 1.5.3 ou posterior.

Limitações

Considere as seguintes limitações ao usar o modo de vários repositórios:

Como configurar a sincronização a partir do repositório raiz

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.

As seções a seguir descrevem três métodos diferentes para ativar o modo de vários repositórios:

  1. Se você não instalou o Config Sync anteriormente, crie uma nova configuração de repositório Git raiz.
  2. Se você tiver instalado o Config Sync, mova a configuração do repositório Git raiz para o RootSync.
  3. Se você tiver instalado o Config Sync e precisar usar os campos spec.git, mantenha a configuração do repositório Git raiz no arquivo YAML do ConfigManagement.

1. Nova configuração

Se você não tiver instalado o Config Sync, conclua as seguintes tarefas para ativar o modo de vários repositórios:

  1. Preencha as seguintes seções em Como instalar o Config Sync:

    1. Antes de começar
    2. Como implantar o Operator
    3. Como conceder ao Operator acesso somente leitura ao Git
  2. Se você estiver usando a versão 1.7.0 ou posterior 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.

  3. 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:
      enableMultiRepo: true
    
  4. Aplique as alterações:

    kubectl apply -f config-management.yaml
    
  5. Crie um objeto RootSync:

    # 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: REPOSITORY
        revision: REVISION
        branch: BRANCH
        dir: "DIRECTORY"
        auth: AUTH_TYPE
        secretRef:
          name: SECRET_NAME
    

    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 maneira mais conveniente para você.
    • 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/csp-config-management/ usa o protocolo HTTPS. Se você não inserir um protocolo, o URL será tratado como um URL HTTPS. Este campo é obrigatório.
    • REVISION: adicione a revisão do Git (tag ou hash) para check-out. Este campo é opcional e o valor padrão é HEAD.
    • BRANCH: adicione a ramificação do repositório com que sincronizar. Este campo é opcional e o valor padrão é master.
    • 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.
    • AUTH_TYPE: adicione um dos seguintes tipos de autenticação:

      • none
      • ssh
      • cookiefile
      • token
      • gcenode: se a Identidade da carga de trabalho estiver ativada no cluster, não será possível usar gcenode. Este campo é obrigatório.
    • 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.

  6. Aplique as alterações:

    kubectl apply -f root-sync.yaml
    

2. Configuração de movimentação

Se você já instalou o Config Sync, mova as configurações do repositório Git do objeto ConfigManagement existente para um objeto RootSync.

Se você quiser configurar o repositório raiz movendo a configuração, conclua as seguintes tarefas:

  1. Se você estiver usando a versão 1.7.0 ou posterior e instalou 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.
  2. Abra o objeto ConfigConfig.
  3. Faça uma cópia dos valores nos campos de spec.git. Use esses valores ao criar o objeto RootSync.
  4. Remova todos os campos spec.git, incluindo git:, do objeto ConfigManagement.
  5. No objeto ConfigManagement, defina o campo spec.enableMultiRepo como true:

    # config-management.yaml
    apiVersion: configmanagement.gke.io/v1
    kind: ConfigManagement
    metadata:
      name: config-management
    spec:
      enableMultiRepo: true
    
  6. Aplique as alterações:

    kubectl apply -f config-management.yaml
    
  7. Usando os valores copiados do objeto ConfigManagement, crie o objeto RootSync. Exemplo:

    # 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: REPOSITORY
        revision: REVISION
        branch: BRANCH
        dir: "DIRECTORY"
        auth: AUTH_TYPE
        secretRef:
          name: SECRET_NAME
    

    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 maneira mais conveniente para você.
    • 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/csp-config-management/ usa o protocolo HTTPS. Se você não inserir um protocolo, o URL será tratado como um URL HTTPS. Este campo é obrigatório.
    • REVISION: adicione a revisão do Git (tag ou hash) para check-out. Este campo é opcional e o valor padrão é HEAD.
    • BRANCH: adicione a ramificação do repositório com que sincronizar. Este campo é opcional e o valor padrão é master.
    • 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.
    • AUTH_TYPE: adicione um dos seguintes tipos de autenticação:

      • none
      • ssh
      • cookiefile
      • token
      • gcenode: se a Identidade da carga de trabalho estiver ativada no cluster, não será possível usar gcenode. Este campo é obrigatório.
    • 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.

  8. Aplique as alterações:

    kubectl apply -f root-sync.yaml
    

3. Manter a configuração

Se já tiver instalado o Config Sync, você poderá manter um repositório Git raiz existente configurado no objeto ConfigManagement. No entanto, esse método não é recomendado porque se tornou obsoleto.

Para configurar o repositório raiz mantendo o repositório raiz no objeto ConfigManagement, conclua as seguintes tarefas:

  1. Se você estiver usando a versão 1.7.0 ou posterior e instalou 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.

  2. No objeto ConfigManagement, defina os campos spec.enableMultiRepo e spec.enableLegacyFields como true, defina spec.sourceFormat como 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ê.

    # config-management.yaml
    apiVersion: configmanagement.gke.io/v1
    kind: ConfigManagement
    metadata:
      name: config-management
    spec:
      enableMultiRepo: true
      enableLegacyFields: true
      sourceFormat: FORMAT
      git:
        syncRepo: REPO
        syncBranch: BRANCH
        secretType: TYPE
        policyDir: "DIRECTORY"
    # ...other fields...
    
  3. Aplique as alterações:

    kubectl apply -f config-management.yaml
    

Aplicar config-management.yaml com enableMultiRepo: true e enableLegacyFields: true define automaticamente o objeto RootSync no cluster. Não altere a configuração de RootSync que é gerada.

Para adicionar repositórios de namespace opcionais, vá para a seção Como configurar a sincronização a partir de repositórios de namespace. Se você quiser sincronizar de apenas um único repositório e continuar usando o fluxo de trabalho atual, pule essa seção.

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

Como verificar a instalação do RootSync

Quando você cria um objeto do RootSync, o Config Sync cria um reconciliador chamado 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 root-reconciler:

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

O resultado será semelhante a:

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

Para outras maneiras de explorar o status do seu objeto RootSync, consulte a seção Como explorar os objetos RootSync e RepoSync.

Como configurar a sincronização a partir de repositórios de namespace

Depois de configurar seu repositório raiz, será possível configurar repositórios de namespace que os usuários não administrativos podem controlar. Os repositórios de namespace precisam ser não estruturados.

Para configurar repositórios de namespace, você precisa atribuir permissões e criar um objeto RepoSync que sincroniza seu repositório de namespace com o cluster. É possível escolher entre dois métodos de configuração de repositórios de namespace:

  • Controlar repositórios de namespace no repositório raiz. Esse método centraliza toda a configuração de repositórios de namespace no repositório raiz, permitindo que um administrador central tenha o controle total da configuração.

  • Controlar repositórios de namespace com a API Kubernetes. Esse método delega o controle do repositório de namespaces aos proprietários do namespace.

Como controlar repositórios de namespace no repositório raiz

Nesse método, o administrador central gerencia a configuração de repositórios de namespace diretamente do repositório raiz. Como o Config Sync gerencia os objetos do repositório de namespace, esse método impede qualquer alteração local nas definições do repositório de namespace.

Para usar esse recurso, conclua as seguintes tarefas:

  1. No repositório raiz, declare uma configuração namespace:

    # ROOT_REPO/namespaces/NAMESPACE/namespace.yaml
    apiVersion: v1
    kind: Namespace
    metadata:
      name: NAMESPACE
    

    Substitua NAMESPACE por um nome para o namespace.

  2. No repositório raiz, crie um objeto RepoSync no mesmo namespace:

    # ROOT_REPO/namespaces/NAMESPACE/repo-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: RepoSync
    metadata:
      name: repo-sync
      namespace: NAMESPACE
    spec:
      # Since this is for a namespace repository, the format should be unstructured
      sourceFormat: unstructured
      git:
       repo: REPOSITORY
       revision: REVISION
       branch: BRANCH
       dir: "DIRECTORY"
       auth: AUTH_TYPE
       secretRef:
         name: SECRET_NAME
    

    Substitua:

    • NAMESPACE: adicione o nome do namespace.
    • REPOSITORY: adicione o URL do repositório Git para usar como repositório raiz do namespace. É possível inserir URLs usando o protocolo HTTPS ou SSH. Por exemplo, https://github.com/GoogleCloudPlatform/csp-config-management/ usa o protocolo HTTPS. Se você não inserir um protocolo, o URL será tratado como um URL HTTPS. Este campo é obrigatório.
    • REVISION: adicione a revisão do Git (tag ou hash) para check-out. Este campo é opcional e o valor padrão é HEAD.
    • BRANCH: adicione a ramificação do repositório com que sincronizar. Este campo é opcional e o valor padrão é master.
    • 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.
    • AUTH_TYPE: adicione um dos seguintes tipos de autenticação:

      • none
      • ssh
      • cookiefile
      • token
      • gcenode: se a Identidade da carga de trabalho estiver ativada no cluster, não será possível usar gcenode.

      Este campo é obrigatório.

    • SECRET_NAME: adicione o nome que você pretende dar ao secret; Este campo é opcional.

    Pode haver no máximo um objeto RepoSync por namespace. Para aplicar essa restrição, o objeto name precisa ser repo-sync. Todas as configurações contidas no diretório referenciado pelo RepoSync também precisam estar no mesmo namespace que o objeto RepoSync.

  3. No repositório raiz, declare uma configuração RoleBinding que conceda à conta de serviço ns-reconciler-NAMESPACE permissão para gerenciar objetos no namespace. O Config Sync cria automaticamente a conta de serviço ns-reconciler-NAMESPACE quando a configuração RepoSync é sincronizada com o cluster.

    Para declarar o RoleBinding, crie o seguinte objeto:

    # ROOT_REPO/namespaces/NAMESPACE/sync-rolebinding.yaml
     kind: RoleBinding
     apiVersion: rbac.authorization.k8s.io/v1
     metadata:
       name: syncs-repo
       namespace: NAMESPACE
     subjects:
     - kind: ServiceAccount
       name: ns-reconciler-NAMESPACE
       namespace: config-management-system
     roleRef:
       kind: ClusterRole
       name: RECONCILER_ROLE
       apiGroup: rbac.authorization.k8s.io
    

    Substitua:

    • NAMESPACE: adicione o nome do namespace.
    • RECONCILER_ROLE: como administrador central, é possível definir o RECONCILER_ROLE para impor quais tipos de configuração podem ser sincronizados a partir do repositório de namespace. É possível escolher um dos seguintes papéis:

      • Um ClusterRole padrão:

        • admin
        • edit

        Para saber mais, consulte Papéis voltados para o usuário.

      • Um ClusterRole ou Role definido pelo usuário declarado no repositório raiz. Esse papel permite permissões detalhadas.

  4. Confirme antes as mudanças no repositório:

     git add .
     git commit -m 'Setting up new namespace repository.'
     git push
    
  5. Se necessário, crie um secret com base no método de autenticação de sua preferência. Se você usou none como tipo de autenticação, pule esta etapa.

    O secret precisa atender aos seguintes requisitos:

    • Crie o secret no mesmo namespace que o RepoSync.
    • O nome do secret precisa corresponder ao nome spec.git.secretRef que você definiu em repo-sync.yaml.
    • Você precisa adicionar a chave pública do secret ao provedor Git.
  6. Para verificar a configuração, use kubectl get em um dos objetos no repositório de namespace. Exemplo:

    kubectl get rolebindings -n NAMESPACE
    

Como controlar repositórios de namespace com a API Kubernetes

Nesse método, o administrador central declara apenas o namespace no repositório raiz e delega a declaração do objeto RepoSync ao operador do aplicativo.

Tarefas administrativas centrais

O administrador central conclui as seguintes tarefas:

  1. No repositório raiz, declare uma configuração namespace:

    # ROOT_REPO/namespaces/NAMESPACE/namespace.yaml
     apiVersion: v1
     kind: Namespace
     metadata:
       name: NAMESPACE
    

    Substitua NAMESPACE por um nome para o namespace.

  2. No repositório raiz, declare uma RoleBinding para conceder permissões aos operadores do aplicativo. Use a prevenção de encaminhamento do RBAC para garantir que o operador do aplicativo não possa aplicar posteriormente uma vinculação de papel com permissões não concedidas por essa vinculação de papel.

    Para declarar o RoleBinding, crie o seguinte manifesto:

    # ROOT_REPO/namespaces/NAMESPACE/operator-rolebinding.yaml
     kind: RoleBinding
     # Add RBAC escalation prevention
     apiVersion: rbac.authorization.k8s.io/v1
     metadata:
       name: operator
       namespace: NAMESPACE
     subjects:
     - kind: User
       name: USERNAME
       apiGroup: rbac.authorization.k8s.io
     roleRef:
       kind: ClusterRole
       name: OPERATOR_ROLE
       apiGroup: rbac.authorization.k8s.io
    

    Substitua:

    • NAMESPACE: adicione o namespace criado no repositório raiz.
    • USERNAME: adicione o nome de usuário do operador do aplicativo.
    • OPERATOR_ROLE: como administrador central, é possível definir o OPERATOR_ROLE para impor quais tipos de configuração podem ser sincronizados a partir do repositório de namespace. É possível escolher um dos seguintes papéis:

      • Um ClusterRole padrão:

        • admin
        • edit

        Para saber mais, consulte Papéis voltados para o usuário.

      • Um ClusterRole ou papel definido pelo usuário declarado no repositório raiz. Esse papel permite permissões detalhadas.

  3. Confirme antes as mudanças no repositório:

     git add .
     git commit -m 'Setting up new namespace repository.'
     git push
    

Tarefas do operador do aplicativo

O operador do aplicativo conclui as seguintes tarefas:

  1. Declare uma configuração RoleBinding que conceda permissão de conta de serviço ns-reconciler-NAMESPACE provisionada automaticamente para gerenciar objetos no namespace. O Config Sync cria automaticamente a conta de serviço ns-reconciler-NAMESPACE quando a configuração RepoSync é sincronizada com o cluster.

    Para declarar o RoleBinding, crie o seguinte manifesto:

    # sync-rolebinding.yaml
    kind: RoleBinding
    apiVersion: rbac.authorization.k8s.io/v1
    metadata:
      name: syncs-repo
      namespace: NAMESPACE
    subjects:
    - kind: ServiceAccount
      name: ns-reconciler-NAMESPACE
      namespace: config-management-system
    roleRef:
      kind: ClusterRole
      name: RECONCILER_ROLE
      apiGroup: rbac.authorization.k8s.io
    

    Substitua:

    • NAMESPACE: adicione o namespace criado no repositório raiz.
    • RECONCILER_ROLE: como o operador do aplicativo, é possível definir RECONCILER_ROLE para impor quais tipos de configuração podem ser sincronizados a partir do repositório de namespace. Só é possível restringir ainda mais o conjunto de permissões que o administrador central concedeu a você. Como resultado, esse papel não pode ser mais permissivo do que o OPERATOR_ROLE que o administrador central declarou na seção anterior.
  2. Aplique a configuração do RoleBinding:

    kubectl apply -f sync-rolebinding.yaml
    
  3. Se necessário, crie um secret com base no método de autenticação de sua preferência. Se você usou none como tipo de autenticação, pule esta etapa.

    O secret precisa atender aos seguintes requisitos:

    • Crie o secret no mesmo namespace que o RepoSync.
    • O nome do secret precisa corresponder ao nome spec.git.secretRef que você definiu em root-sync.yaml.
    • Você precisa adicionar a chave pública do secret ao provedor Git.
  4. Declare uma configuração RepoSync:

    # repo-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: RepoSync
    metadata:
      name: repo-sync
      namespace: NAMESPACE
    spec:
      # Since this is for a namespace repository, the format should be unstructured
      sourceFormat: unstructured
      git:
       repo: REPOSITORY
       revision: REVISION
       branch: BRANCH
       dir: "DIRECTORY"
       auth: AUTH_TYPE
       secretRef:
         name: SECRET_NAME
    

    Substitua:

    • REPOSITORY: adicione o URL do repositório Git para usar como repositório raiz do namespace. É possível inserir URLs usando o protocolo HTTPS ou SSH. Por exemplo, https://github.com/GoogleCloudPlatform/csp-config-management/ usa o protocolo HTTPS. Se você não inserir um protocolo, o URL será tratado como um URL HTTPS. Este campo é obrigatório.
    • REVISION: adicione a revisão do Git (tag ou hash) para check-out. Este campo é opcional e o valor padrão é HEAD.
    • BRANCH: adicione a ramificação do repositório com que sincronizar. Este campo é opcional e o valor padrão é master.
    • 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.
    • AUTH_TYPE: adicione um dos seguintes tipos de autenticação:

      • none
      • ssh
      • cookiefile
      • token
      • gcenode: se a Identidade da carga de trabalho estiver ativada no cluster, não será possível usar gcenode.

      Este campo é obrigatório.

    • SECRET_NAME: adicione o nome que você pretende dar ao secret; Este campo é opcional.

    Pode haver no máximo um objeto RepoSync por namespace. Para impor isso, o nome do objeto name precisa ser repo-sync. Todas as configurações contidas no diretório referenciado pelo RepoSync também precisam estar no mesmo namespace que o objeto RepoSync.

  5. Aplique a configuração RepoSync:

    kubectl apply -f repo-sync.yaml
    
  6. Para verificar a configuração, use kubectl get em um dos objetos no repositório de namespace. Exemplo:

    kubectl get rolebindings -n NAMESPACE
    

Como verificar o status de sincronização do repositório de namespace

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

nomos status

O resultado será semelhante a:

my_managed_cluster-1
  --------------------
  <root>   git@github.com:foo-corp/acme/admin@main
  SYNCED   f52a11e4
  --------------------
  bookstore  git@github.com:foo-corp/acme/bookstore@v1
  SYNCED     34d1a8c8

Nesta saída de exemplo, o repositório de namespace é configurado para o namespace chamado bookstore.

Como verificar a instalação do RepoSync

Quando você cria um objeto do RepoSync, o Config Sync cria um reconciliador chamado ns-reconciler-NAMESPACE, em que NAMESPACE é o namespace no qual você criou o objeto o RepoSync.

Para verificar se o objeto RepoSync está funcionando corretamente, verifique o status da implantação ns-reconciler-NAMESPACE:

kubectl get -n config-management-system deployment/ns-reconciler-NAMESPACE

Substitua NAMESPACE pelo namespace em que você criou seu repositório de namespace.

Para outras maneiras de explorar o status do seu objeto RepoSync, consulte a seção Como explorar os objetos RootSync e RepoSync.

Como interromper e retomar a sincronização

As seções a seguir mostram como parar e retomar a sincronização temporariamente. Talvez seja necessário fazer isso se uma configuração incorreta estiver confirmada acidentalmente para seu repositório.

Apenas um administrador central pode interromper a sincronização no repositório raiz.

A capacidade de interromper a sincronização em repositórios de namespace depende do método de configuração usado para seus repositórios de namespace.

  • Se o método Controlar repositórios de namespace no repositório raiz foi usado, um administrador central é o único que poderá parar e retomar a sincronização.

  • Se o método Controlar repositórios de namespace com a API Kubernetes for usado, os operadores do aplicativo poderão parar e retomar a sincronização dos repositórios de namespace em que eles trabalham.

Como interromper a sincronização

As seções a seguir mostram como parar de sincronizar os repositórios de raiz e de repositórios.

Como interromper a sincronização do repositório raiz

Para interromper a sincronização do repositório raiz, um administrador central pode executar o seguinte comando:

kubectl -n config-management-system scale deployment root-reconciler --replicas=0

Esse comando reduz a contagem de replicas na implantação root-reconciler para 0.

Como interromper a sincronização de repositórios de namespace

Selecione a guia do método de repositório raiz ou do método da API Kubernetes para ver as instruções relevantes.

Método do repositório raiz

Se o método Controlar repositórios de namespace no repositório raiz foi usado, os administradores centrais poderão executar os seguintes comandos para interromper a sincronização de um repositório de namespace:

kubectl -n config-management-system scale deployment ns-reconciler-NAMESPACE --replicas=0

O comando reduz a contagem de réplicas na implantação ns-reconciler-NAMESPACE para 0.

Método da API Kubernetes

Se o método Controlar repositórios de namespace com a API Kubernetes for usado, os operadores do aplicativo poderão interromper a sincronização executando os seguintes comandos:

  1. Recupere e salve a configuração RepoSync para usá-la mais tarde, quando quiser retomar a sincronização:

    kubectl -n NAMESPACE get reposyncs repo-sync -oyaml > repo-sync.yaml
    

    Substitua NAMESPACE pelo namespace do objeto RepoSync.

  2. Exclua a configuração RepoSync:

    kubectl -n NAMESPACE delete reposyncs repo-sync
    

    Este comando aciona o Reconciler Manager para remover o conciliador de namespace (ns-reconciler-NAMESPACE) de NAMESPACE e parar a sincronização.

Como retomar a sincronização

Nesta seção, você verá como retomar a sincronização do repositório raiz e dos repositórios de namespace.

Como retomar a sincronização do repositório raiz

Para retomar a sincronização a partir de um repositório raiz, um administrador central pode executar o seguinte comando:

kubectl -n config-management-system scale deployment root-reconciler --replicas=1

Esse comando escalona a implantação root-reconciler do operador para uma réplica.

Como retomar a sincronização de um repositório de namespace

Selecione a guia do método de repositório raiz ou do método da API Kubernetes para ver as instruções relevantes.

Método do repositório raiz

Se você usou o método Controlar repositórios de namespace no repositório raiz, um administrador central poderá executar o comando a seguir:

kubectl -n config-management-system scale deployment ns-reconciler-NAMESPACE --replicas=1

Este comando escalona a implantação ns-conciliation-NAMESPACE para uma réplica.

Método da API Kubernetes

Se você usou o método Controlar repositórios de namespace com a API Kubernetes, os operadores de aplicativo poderão retomar a sincronização reaplicando repo-sync.yaml, que contém a configuração RepoSync:

kubectl apply -f repo-sync.yaml

Esse comando aciona o Reconciler Manager para criar um processo de reconciliação de namespace e criar uma implantação ns-reconciler-NAMESPACE.

Como remover repositórios raiz e de namespace

Para remover o repositório raiz, exclua o objeto RootSync. Por exemplo,

kubectl delete -f root-sync.yaml

Para desinstalar um repositório de namespace, exclua um objeto RepoSync. Esta ação desinstala o repositório de namespace correspondente.

Como ignorar mutações de objetos

Nas versões 1.7 e posteriores do Config Sync, se você não quiser que o Config Sync mantenha o estado do objeto e um cluster, após ele existir, adicione a anotação client.lifecycle.config.k8s.io/mutation: ignore no objeto em que você quer que o Config Sync ignore as mutações. Essa ação é útil quando você quer que o Config Sync crie um objeto e, em seguida, ignore todas as alterações conflitantes nesse objeto no cluster.

O exemplo a seguir mostra como adicionar a anotação a um objeto:

metadata:
  annotations:
    client.lifecycle.config.k8s.io/mutation: ignore 

Não é possível modificar manualmente essa anotação em objetos gerenciados no cluster.

Resolução de conflitos

Quando você trabalha com dois repositórios, pode haver conflitos quando o mesmo objeto (grupos, tipos, nomes e namespaces correspondentes) é declarado tanto no repositório raiz quanto no repositório de namespaces. Quando esse conflito acontece, somente a declaração no repositório raiz é aplicada ao cluster.

Se esse conflito ocorrer, o RootSync não reportará problemas, pois o repositório raiz tem precedência. O RepoSync informa o erro KNV 1060 no status.

Como o repositório raiz sempre tem precedência, é possível resolver o conflito atualizando o repositório raiz para corresponder ao repositório de namespace ou excluindo o objeto conflitante no repositório de namespace.

Como explorar os objetos RootSync e RepoSync

As seções a seguir mostram diferentes maneiras de explorar os objetos RootSync e RepoSync.

Como ver registros

Para mais informações sobre possíveis erros, veja os registros dos objetos RootSync e RepoSync.

Para ver os registros do validador RootSync, execute o seguinte comando:

kubectl logs -n config-management-system deployment/root-reconciler CONTAINER_NAME

Substitua CONTAINER_NAME por git-sync, reconciler ou otel-agent. O contêiner git-sync extrai as configurações de um repositório Git em um diretório local que pode ser lido pelo contêiner de reconciliador. O contêiner reconciler aplica essas configurações ao cluster. O contêiner otel-agent é um agente do OpenTelemetry para recuperar e exportar métricas do Config Sync.

Para ver os registros do validador do RepoSync, execute o seguinte comando:

kubectl logs -n config-management-system deployment/ns-reconciler-NAMESPACE CONTAINER_NAME

Substitua:

  • NAMESPACE: o namespace em que você criou seu repositório de namespace.
  • CONTAINER_NAME: git-sync, reconciler, ou otel-agent.

Como visualizar confirmações sincronizadas

Verifique qual confirmação está sincronizada com o cluster.

Para visualizar os detalhes da RootSync, execute o seguinte comando:

kubectl get rootsync root-sync -n config-management-system

Para ver os detalhes do RepoSync, execute o seguinte comando:

kubectl get reposync repo-sync -n config-management-system

O resultado será semelhante a:

NAME        SOURCECOMMIT                               SYNCCOMMIT
root-sync   66882815f0ef5517df27e864fb1315e97756ab72   66882815f0ef5517df27e864fb1315e97756ab72

O valor na coluna SOURCECOMMIT é a confirmação do repositório Git que precisa ser sincronizada com o cluster. O valor na coluna SYNCCOMMIT é a confirmação implantada no cluster. Se os dois valores nas colunas SOURCECOMMIT e SYNCCOMMIT forem os mesmos, a confirmação esperada foi implantada no cluster.

Como visualizar detalhes do objeto

Para visualizar detalhes dos objetos RootSync e RepoSync, use kubectl describe. Esse comando pode fornecer mais informações sobre possíveis erros.

Para visualizar os detalhes do objeto RootSync, execute o seguinte comando:

kubectl describe rootsync root-sync -n config-management-system

Para ver os detalhes do objeto do RepoSync, execute o seguinte comando:

kubectl describe reposync repo-sync -n config-management-system

Como ver se um recurso está pronto

Para saber se os recursos sincronizados com o cluster estão prontos, visualize o status da reconciliação. Por exemplo, este comando pode mostrar se uma implantação sincronizada está pronta para exibir o tráfego.

Para um repositório Git sincronizado com o cluster, o status de reconciliação de todos os recursos é agregado a um recurso denominado ResourceGroup. Para cada objeto RootSync ou RepoSync, um ResourceGroup é gerado para capturar o conjunto de recursos aplicados ao cluster e agregar os status deles.

Para visualizar o status de reconciliação do objeto RootSync, execute o seguinte comando:

kubectl get resourcegroup.kpt.dev root-sync -n config-management-system -o yaml

Para ver o status de reconciliação do objeto do RepoSync, execute o seguinte comando:

kubectl get resourcegroup.kpt.dev repo-sync -n NAMESPACE -o yaml

Na saída, você verá todos os status de recursos de ResourceGroup. Por exemplo, a saída a seguir mostra que uma implantação chamada nginx-deployment está pronta:

resourceStatuses:
- group: apps
  kind: Deployment
  name: nginx-deployment
  namespace: default
  status: Current

Solução de problemas

As seções a seguir ajudam a solucionar problemas quando você estiver sincronizando de vários repositórios.

Erro: o webhook de admissão negou uma solicitação

Se você receber o seguinte erro ao tentar aplicar uma alteração a um campo que o Config Sync gerencia, é possível que tenha feito uma alteração conflitante:

error: OBJECT could not be patched: admission webhook "v1.admission-webhook.configsync.gke.io"
denied the request: fields managed by Config Sync can not be modified

Quando você declara um campo em uma configuração e seu repositório é sincronizado com um cluster, o Config Sync gerencia esse campo. Qualquer alteração que você tentar fazer nesse campo será uma alteração conflitante.

Por exemplo, se você tiver uma configuração de implantação no seu repositório com um rótulo environment:prod e tentar alterar esse rótulo para environment:dev no seu cluster, haverá um conflito e a mensagem de erro anterior. No entanto, se você adicionar um novo rótulo (por exemplo, tier:frontend) à implantação, não haverá conflito.

Para que o Config Sync ignore qualquer alteração em um objeto, adicione a anotação descrita em Como ignorar mutações de objetos.

Erro: tempo limite de E/S da solicitação de webhook de admissão

Se você receber o seguinte erro quando o regulador tentar aplicar uma configuração ao cluster:

KNV2009: Internal error occurred: failed calling webhook "v1.admission-webhook.configsync.gke.io": Post https://admission-webhook.config-management-system.svc:8676/admission-webhook?timeout=3s: dial tcp 10.1.1.186:8676: i/o timeout

Isso pode ocorrer devido ao bloqueio da porta 8676 do webhook de admissão pelo firewall para a rede do plano de controle. Para resolver esse problema, adicione uma regra de firewall para autorizar a porta 8676, que o webhook de admissão do Config Sync usa para a prevenção de deslocamento.

Erro: conexão do webhook de admissão recusada

Se você receber o seguinte erro quando o regulador tentar aplicar uma configuração ao cluster:

KNV2009: Internal error occurred: failed calling webhook "v1.admission-webhook.configsync.gke.io": Post "https://admission-webhook.config-management-system.svc:8676/admission-webhook?timeout=3s": dial tcp 10.92.2.14:8676: connect: connection refused

Isso significa que o webhook de admissão ainda não está pronto. É um erro temporário que você talvez você veja ao inicializar o Config Sync.

Se o problema persistir, consulte a implantação do webhook de admissão para ver se os pods podem ser programados e estão íntegros.

kubectl describe deploy admission-webhook -n config-management-system

kubectl get pods -n config-management-system -l app=admission-webhook

Os campos de ResourceGroup continuam mudando

Finalmente, seu ResourceGroup pode entrar em um loop que continua atualizando o spec do ResourceGroup. Se isso acontecer, você poderá notar os seguintes problemas:

  • O metadata.generation de um ResourceGroup continua aumentando em um curto período.
  • O ResourceGroup spec está sempre mudando.
  • O ResourceGroup spec não inclui o status.resourceStatuses dos recursos que estão sendo sincronizados com o cluster.

Se você observar esses problemas, isso significa que alguns dos recursos nos seus repositórios Git não foram aplicados ao cluster. A causa desses problemas é a falta de permissões necessárias para aplicar esses recursos.

Você pode verificar se as permissões estão ausentes recebendo o status do recurso RepoSync:

kubectl get reposync repo-sync -n NAMESPACE -o yaml

Substitua NAMESPACE pelo namespace em que você criou seu repositório de namespace.

Se as mensagens a seguir aparecerem no status, significa que o reconciliação em NAMESPACE não tem a permissão necessária para aplicar o recurso:

errors:
  - code: "2009"
    errorMessage: |-
      KNV2009: deployments.apps "nginx-deployment" is forbidden: User "system:serviceaccount:config-management-system:ns-reconciler-     default" cannot get resource "deployments" in API group "apps" in the namespace "default"

      For more information, see https://g.co/cloud/acm-errors#knv2009

Para corrigir esse problema, é preciso declarar uma configuração RoleBinding que concede à conta de serviço ns-reconciler-NAMESPACE permissão para gerenciar o recurso com falha nesse namespace. Detalhes sobre como adicionar um RoleBinding estão incluídos na seção Como configurar a sincronização de repositórios de namespace.

Grande número de recursos no repositório Git

Quando o repositório Git sincronizado pelos objetos RepoSync ou RootSync contém configuração para mais de alguns milhares de recursos, ele pode fazer com que o ResourceGroup exceda o limite de tamanho de objeto etcd. Quando isso acontece, não é possível visualizar o status agregado dos recursos no seu repositório Git. Embora não seja possível visualizar o status agregado, seu repositório ainda está sincronizado. Se não houver erros nos objetos RepoSync ou RootSync, isso significa que o repositório Git foi sincronizado com o cluster.

Para verificar se o recurso ResourceGroup excede o limite de tamanho de objeto etcd, é necessário verificar o status do recurso ResourceGroup e o registro do controlador ResourceGroup:

  1. Verifique o status de "GroupGroup" com o seguinte comando:

    • Para verificar o status do RootSync, execute o comando a seguir:
     kubectl get resourcegroup.kpt.dev root-sync -n config-management-system
    
    • Para verificar o status do RootSync, execute o comando a seguir:
    # For the RepoSync:
    kubectl get resourcegroup.kpt.dev repo-sync -n NAMESPACE
    

    O resultado será semelhante a:

    NAME        RECONCILING   STALLED   AGE
    root-sync   True          False     35m
    

    Se o valor da coluna RECONCILING for True, significa que o recurso ResourceGroup ainda está fazendo a reconciliação.

  2. Verifique os registros do controlador ResourceGroup com o seguinte comando:

    kubectl logs deployment/resource-group-controller-manager -c manager -n resource-group-system
    

    Se você vir o seguinte erro na saída, o recurso ResourceGroup é muito grande e excede o limite de tamanho de objeto etcd:

    "error":"etcdserver: request is too large"
    

Para evitar que o ResourceGroup seja muito grande, reduza o número de recursos no seu repositório Git. Por exemplo, divida o repositório e use um objeto RootSync com vários objetos RepoSync em vez de usar apenas um objeto RootSync para sincronizar todos os recursos.

A seguir