Como sincronizar com vários repositórios

A ativação do modo de vários repositórios no Config Sync permite sincronizar a configuração de vários repositórios com o mesmo conjunto de clusters. É possível utilizar os seguintes tipos de repositórios:

  • Repositório raiz: este repositório permite sincronizar configurações com escopo de cluster e namespace. O repositório raiz usa credenciais de nível de administrador para aplicar políticas em namespaces de aplicativos e substituir alterações locais que fluem do estado desejado. Um administrador central rege o repositório raiz. Só pode haver um repositório raiz para cada cluster.

  • Repositórios de namespace: são opcionais e podem conter configurações com escopo de namespace sincronizadas com um namespace específico entre os clusters. É possível delegar a configuração e o controle de um repositório de namespace para usuários não administrativos.

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. Ela também oferece mais autonomia para escolher onde você quer armazenar 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:

  • Use o Config Sync versão 1.5.1 ou posterior.

Limitações

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

  • O campo spec.enableMultiRepo não é compatível com o campo spec.git. Se você ainda precisar usar spec.git, consulte a seção Como usar campos spec.git legados.
  • ClusterSelectors e namespaceSelectors (incluindo anotações que apontam para seletores) só funcionam no repositório raiz.
  • Não é possível usar gcenode no campo auth das suas configurações do RootSync ou do RepoSync.

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

Recomendamos que você mova as configurações do repositório Git do arquivo config-management.yaml atual para um arquivo YAML RootSync ao ativar o modo de vários repositórios.

Para configurar o repositório raiz, conclua as seguintes tarefas:

  1. Abra o arquivo config-management.yaml.
  2. Anote os campos spec.git e remova-os do arquivo config-management.yaml. É possível usar essas configurações ao criar o RootSync em seguida.
  3. Defina o campo spec.enableMultiRepo como true:

    # 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 o arquivo root-sync.yaml. Exemplo:

    # root-sync.yaml
    apiVersion: configsync.gke.io/v1alpha1
    kind: RootSync
    metadata:
      name: root-sync
      namespace: config-management-system
    spec:
      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. 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 dentro do repositório Git que representa o nível superior do repositório para 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

      Este campo é obrigatório.

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

  6. Crie um secret com base no método de autenticação de sua preferência.

    O secret precisa atender aos seguintes requisitos:

    • 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.
  7. Aplique a configuração:

    kubectl apply -f root-sync.yaml
    
  8. Verifique a instalação:

    kubectl -n config-management-system get pods | grep reconciler-manager
    

    O resultado será semelhante a:

    reconciler-manager-6f988f5fdd-4r7tr 1/1 Running 0 26s
    

É possível manter o repositório Git raiz existente configurado no arquivo config-management.yaml e ativar o modo de vários repositórios, em vez de movê-lo para o RootSync. Isso não é recomendado porque será suspenso no futuro.

  1. Defina os campos spec.enableMultiRepo e spec.enableLegacyFields como true:

    # config-management.yaml
    apiVersion: configmanagement.gke.io/v1
    kind: ConfigManagement
    metadata:
      name: config-management
    spec:
      enableMultiRepo: true
      enableLegacyFields: true
      git:
        syncRepo: REPO
        syncBranch: BRANCH
        secretType: TYPE
        policyDir: "DIRECTORY"
    # ...other fields...
    

    Para saber mais sobre esses campos, consulte campos config-management.yaml.

  2. Aplique as alterações:

    kubectl apply -f config-management.yaml

A implantação desse arquivo YAML também gera o recurso RootSync automaticamente no cluster. Não altere a configuração de RootSync. Prossiga em Como configurar a sincronização a partir de repositórios de namespace para adicionar outros repositórios de namespace.

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

Há duas opções para configurar 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 recursos 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, declare uma configuração RepoSync no mesmo namespace:

    # ROOT_REPO/namespaces/NAMESPACE/repo-sync.yaml
    apiVersion: configsync.gke.io/v1alpha1
    kind: RepoSync
    metadata:
      name: repo-sync
      namespace: NAMESPACE
    spec:
      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. 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 dentro do repositório Git que representa o nível superior do repositório para 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

      Este campo é obrigatório.

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

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

  3. No repositório raiz, declare uma configuração RoleBinding que conceda à conta de serviço ns-reconciler-NAMESPACE permissão para gerenciar recursos 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:

    # 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 papel definido pelo usuário declarado no repositório raiz. Esse papel permite permissões detalhadas.

  4. Confirme as alterações anteriores no repositório raiz:

     git add .
     git commit -m 'Setting up new namespace repository.'
     git push
    
  5. Crie um secret com base no método de autenticação de sua preferência.

    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 arquivo 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 configuração 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: USER_NAME
       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.
    • USER_NAME: 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. Assim é possível realizar permissões refinadas.

  3. Confirme as alterações anteriores no repositório raiz:

     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 recursos 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. Crie um secret com base no método de autenticação de sua preferência.

    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.
  4. Declare uma configuração RepoSync:

    # repo-sync.yaml
    apiVersion: configsync.gke.io/v1alpha1
    kind: RepoSync
    metadata:
      name: repo-sync
      namespace: NAMESPACE
    spec:
      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. 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 dentro do repositório Git que representa o nível superior do repositório para 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

      Este campo é obrigatório.

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

    Pode haver no máximo um recurso RepoSync por namespace. Para impor isso, o nome do objeto precisa ser repo-sync. Todas as configurações contidas no diretório referenciado pelo RepoSync também precisam estar no mesmo namespace que o recurso 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 interromper e retomar a sincronização

Esta seção mostra como parar temporariamente e retomar a sincronização. 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

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

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 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 arquivo RootSync. Por exemplo,

kubectl delete -f root-sync.yaml

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

Resolução de conflitos

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

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.

A seguir