Sincronizar desde varios repositorios

Habilitar el modo de varios repositorios en el Sincronizador de configuración te permite sincronizar la configuración de varios repositorios al mismo conjunto de clústeres. Puedes usar los siguientes tipos de repositorios:

  • Repositorio raíz: Este repositorio te permite sincronizar archivos de configuración con permisos de clúster y permisos de espacio de nombres. El repositorio raíz usa credenciales de nivel de administrador para aplicar políticas en los espacios de nombres de la aplicación y anular los cambios locales que se desvían del estado deseado. Un administrador central rige el repositorio raíz. Solo puede existir un repositorio raíz para cada clúster.

  • Repositorios de espacios de nombres: Los repositorios de espacios de nombres son opcionales y pueden contener archivos de configuración con permisos de espacio de nombres que están sincronizados con un espacio de nombres particular en todos los clústeres. Puedes delegar la configuración y el control de un repositorio de espacio de nombres a usuarios no administrativos.

Cada repositorio tiene una sola referencia de Git (una rama de repositorio, una confirmación o una etiqueta, y una tupla de directorio) que puedes administrar por separado. Esta configuración separa el ciclo de vida de la implementación de configuración para los diferentes equipos. También te brinda más autonomía para elegir dónde deseas alojar el repositorio y cómo estructurarlo.

En el siguiente diagrama, se muestra una descripción general de cómo los equipos pueden usar un repositorio raíz y repositorios de espacios de nombres:

Un administrador central que controla varias configuraciones y operadores de apps que controlan sus propias configuraciones de espacios de nombres.

En este diagrama, un administrador central administra la infraestructura centralizada de la organización y aplica políticas en el clúster y en todos los espacios de nombres de la organización.

Los operadores de la aplicación, que son responsables de administrar las implementaciones en vivo, aplican configuraciones a las aplicaciones en los espacios de nombres en los que operan.

Antes de comenzar

Completa las siguientes tareas antes de habilitar el modo de varios repositorios:

  • Usa la versión 1.5.1 del Sincronizador de configuración o una posterior.

Limitaciones

Ten en cuenta las siguientes limitaciones cuando uses el modo de varios repositorios:

  • El campo spec.enableMultiRepo no es compatible con el campo spec.git. Si aún necesitas usar spec.git, consulta la sección Usa campos de spec.git heredados.
  • ClusterSelectors y namespaceSelectors (incluidas las anotaciones que apuntan a los selectores) solo funcionan en el repositorio raíz.
  • No puedes usar gcenode en el campo auth de tus configuraciones de RootSync o RepoSync.

Configura la sincronización desde el repositorio raíz

Recomendamos que muevas las configuraciones del repositorio de Git desde tu archivo config-management.yaml existente a un archivo YAML de RootSync cuando habilites el modo de repositorios múltiples.

Para configurar el repositorio raíz, completa las siguientes tareas:

  1. Abre el archivo config-management.yaml.
  2. Toma nota de los campos spec.git y quítalos del archivo config-management.yaml (puedes usar estos archivos de configuración cuando crees la RootSync a continuación).
  3. Configura el campo spec.enableMultiRepo como true:

    # config-management.yaml
    apiVersion: configmanagement.gke.io/v1
    kind: ConfigManagement
    metadata:
      name: config-management
    spec:
      enableMultiRepo: true
    
  4. Aplique los cambios:

    kubectl apply -f config-management.yaml
    
  5. Crea el archivo root-sync.yaml. Por ejemplo:

    # 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
    

    Reemplaza lo siguiente:

    • REPOSITORY: agrega la URL del repositorio de Git para usarlo como repositorio raíz. Este campo es obligatorio.
    • REVISION: Agrega la revisión de Git (etiqueta o hash) que deseas consultar. Este campo es opcional y el valor predeterminado es HEAD.
    • BRANCH: Agrega la rama del repositorio desde la que se realiza la sincronización. Este campo es opcional y el valor predeterminado es master.
    • DIRECTORY: Agrega la ruta de acceso dentro del repositorio de Git que representa el nivel superior del repositorio al que se sincronizará. Este campo es opcional y el predeterminado es el directorio raíz del repositorio.
    • AUTH_TYPE: Agrega uno de los siguientes tipos de autenticación:

      • none
      • ssh
      • cookiefile
      • token

      Este campo es obligatorio.

    • SECRET_NAME: Agrega el nombre que deseas darle a tu objeto Secret. Este campo es obligatorio.

  6. Crea un Secret en función de tu método de autenticación preferido.

    El Secret debe cumplir con los siguientes requisitos:

    • El nombre del Secret debe coincidir con el nombre de spec.git.secretRef que definiste en repo-sync.yaml.
    • Debes agregar la clave pública del Secret al proveedor de Git.
  7. Aplica la configuración:

    kubectl apply -f root-sync.yaml
    
  8. Verifica la instalación:

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

    Deberías ver un resultado similar al siguiente:

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

Puedes mantener configurado tu repositorio raíz de Git existente en el archivo config-management.yaml y habilitar el modo de repositorios múltiples en lugar de moverlo a RootSync. No se recomienda, ya que esto dejará de estar disponible en el futuro.

  1. Establece los campos spec.enableMultiRepo y spec.enableLegacyFields en 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 obtener más información sobre estos campos, consulta campos de config-management.yaml.

  2. Aplique los cambios:

    kubectl apply -f config-management.yaml

Implementar este archivo YAML también genera automáticamente el recurso RootSync en el clúster. No cambies la configuración RootSync. Continúa con Configura la sincronización de repositorios de espacios de nombres a fin de agregar repositorios de espacio de nombres adicionales.

Configura la sincronización desde repositorios de espacios de nombres

Hay dos opciones para configurar repositorios de espacios de nombres:

  • Controla los repositorios de espacio de nombres en el repositorio raíz. Este método centraliza toda la configuración de los repositorios de espacios de nombres en el repositorio raíz, lo que le proporciona a un administrador central el control completo de la configuración.

  • Controla los repositorios de espacios de nombres con la API de Kubernetes. Este método delega el control del repositorio de espacios de nombres a los propietarios de los espacios de nombres.

Controla los repositorios de espacio de nombres en el repositorio raíz

En este método, el administrador central administra la configuración de los repositorios de espacios de nombres directamente desde el repositorio raíz. Debido a que el Sincronizador de configuración administra los recursos del repositorio de espacios de nombres, este método evita cualquier cambio local en las definiciones del repositorio de espacios de nombres.

Para usar este método, completa las siguientes tareas:

  1. En el repositorio raíz, declara una configuración namespace:

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

    Reemplaza NAMESPACE por un nombre para el espacio de nombres.

  2. En el repositorio raíz, declara una configuración RepoSync en el mismo espacio de nombres:

    # 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
    

    Reemplaza lo siguiente:

    • NAMESPACE: Agrega el nombre de tu espacio de nombres.
    • REPOSITORY: agrega la URL del repositorio de Git para usarlo como repositorio raíz. Este campo es obligatorio.
    • REVISION: Agrega la revisión de Git (etiqueta o hash) que deseas consultar. Este campo es opcional y el valor predeterminado es HEAD.
    • BRANCH: Agrega la rama del repositorio desde la que se realiza la sincronización. Este campo es opcional y el valor predeterminado es master.
    • DIRECTORY: Agrega la ruta de acceso dentro del repositorio de Git que representa el nivel superior del repositorio al que se sincronizará. Este campo es opcional y el predeterminado es el directorio raíz del repositorio.
    • AUTH_TYPE: Agrega uno de los siguientes tipos de autenticación:

      • none
      • ssh
      • cookiefile
      • token

      Este campo es obligatorio.

    • SECRET_NAME: Agrega el nombre que deseas darle a tu objeto Secret. Este campo es obligatorio.

    Puede haber, como máximo, un recurso RepoSync por espacio de nombres. Para hacer esto, el nombre del objeto debe ser repo-sync. Todas las configuraciones que se encuentran en el directorio al que hace referencia RepoSync deben estar en el mismo espacio de nombres que el recurso RepoSync.

  3. En el repositorio raíz, declara una configuración RoleBinding que otorgue a la cuenta de servicio ns-reconciler-NAMESPACE permiso para administrar recursos en el espacio de nombres. El Sincronizador de configuración crea de forma automática la cuenta de servicio ns-reconciler-NAMESPACE cuando la configuración RepoSync se sincroniza con el clúster.

    Para declarar RoleBinding, crea el siguiente manifiesto:

    # 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
    

    Reemplaza lo siguiente:

    • NAMESPACE: Agrega el nombre de tu espacio de nombres.
    • RECONCILER_ROLE: como administrador central, puedes configurar RECONCILER_ROLE para que se apliquen los tipos de configuración que se pueden sincronizar desde el repositorio de espacios de nombres. Puedes elegir una de las siguientes funciones:

      • Una ClusterRole predeterminada:

        • admin
        • edit

        Para obtener más información, consulta Funciones orientadas al usuario.

      • Una ClusterRole o una Role definida por el usuario que se declara en el repositorio raíz. Esta función admite permisos detallados.

  4. Confirma los cambios anteriores en el repositorio raíz:

     git add .
     git commit -m 'Setting up new namespace repository.'
     git push
    
  5. Crea un Secret en función de tu método de autenticación preferido.

    El Secret debe cumplir con los siguientes requisitos:

    • Crea el Secret en el mismo espacio de nombres que RepoSync.
    • El nombre del Secret debe coincidir con el nombre de spec.git.secretRef que definiste en repo-sync.yaml.
    • Debes agregar la clave pública del Secret al proveedor de Git.
  6. Para verificar la configuración, usa kubectl get en uno de los objetos del repositorio de espacios de nombres. Por ejemplo:

    kubectl get rolebindings -n NAMESPACE
    

Controla los repositorios de espacios de nombres mediante la API de Kubernetes

En este método, el administrador central solo declara el espacio de nombres en el repositorio raíz y delega la declaración del archivo RepoSync al operador de la aplicación.

Tareas del administrador central

El administrador central completa las siguientes tareas:

  1. En el repositorio raíz, declara una configuración namespace:

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

    Reemplaza NAMESPACE por un nombre para el espacio de nombres.

  2. En el repositorio raíz, declara una configuración RoleBinding para otorgar permisos a los operadores de la aplicación. Usa la Prevención de elevación del RBAC para asegurarte de que el operador de la aplicación no pueda aplicar una vinculación de función con permisos que no otorga esta vinculación de función.

    Para declarar RoleBinding, crea el siguiente manifiesto:

    # 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
    

    Reemplaza lo siguiente:

    • NAMESPACE: Agrega el espacio de nombres que creaste al repositorio raíz.
    • USER_NAME: Agrega el nombre de usuario del operador de la aplicación.
    • OPERATOR_ROLE: Como administrador central, puedes configurar OPERATOR_ROLE para aplicar de forma forzosa los tipos de configuraciones que se pueden sincronizar desde el repositorio de espacios de nombres. Puedes elegir una de las siguientes funciones:

      • Una ClusterRole predeterminada:

        • admin
        • edit

        Para obtener más información, consulta Funciones orientadas al usuario.

      • Una ClusterRole o una Role definida por el usuario que se declara en el repositorio raíz. Esto permite el uso de permisos detallados.

  3. Confirma los cambios anteriores en el repositorio raíz:

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

Tareas del operador de la aplicación

El operador de la aplicación completa las siguientes tareas:

  1. Declara una configuración RoleBinding que otorga el permiso ns-reconciler-NAMESPACE de la cuenta de servicio aprovisionado de forma automática para administrar los recursos en el espacio de nombres. El Sincronizador de configuración crea de forma automática la cuenta de servicio ns-reconciler-NAMESPACE cuando la configuración RepoSync se sincroniza con el clúster.

    Para declarar RoleBinding, crea el siguiente manifiesto:

    # 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
    

    Reemplaza lo siguiente:

    • NAMESPACE: Agrega el espacio de nombres que creaste al repositorio raíz.
    • RECONCILER_ROLE: Como operador de la aplicación, puedes configurar RECONCILER_ROLE para aplicar los tipos de configuración que se pueden sincronizar desde el repositorio de espacios de nombres. Solo puedes restringir aún más el conjunto de permisos que te otorgó el administrador central. Como resultado, esta función no puede ser más permisiva que la OPERATOR_ROLE que el administrador central declaró en la sección anterior.
  2. Aplica la configuración de RoleBinding:

    kubectl apply -f sync-rolebinding.yaml
    
  3. Crea un Secret en función de tu método de autenticación preferido.

    El Secret debe cumplir con los siguientes requisitos:

    • Crea el Secret en el mismo espacio de nombres que RepoSync.
    • El nombre del Secret debe coincidir con el nombre de spec.git.secretRef que definiste en repo-sync.yaml.
    • Debes agregar la clave pública del Secret al proveedor de Git.
  4. Declara una configuración de 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
    

    Reemplaza lo siguiente:

    • REPOSITORY: agrega la URL del repositorio de Git para usarlo como repositorio raíz. Este campo es obligatorio.
    • REVISION: Agrega la revisión de Git (etiqueta o hash) que deseas consultar. Este campo es opcional y el valor predeterminado es HEAD.
    • BRANCH: Agrega la rama del repositorio desde la que se realiza la sincronización. Este campo es opcional y el valor predeterminado es master.
    • DIRECTORY: Agrega la ruta de acceso dentro del repositorio de Git que representa el nivel superior del repositorio al que se sincronizará. Este campo es opcional y el predeterminado es el directorio raíz del repositorio.
    • AUTH_TYPE: Agrega uno de los siguientes tipos de autenticación:

      • none
      • ssh
      • cookiefile
      • token

      Este campo es obligatorio.

    • SECRET_NAME: Agrega el nombre que deseas darle a tu objeto Secret. Este campo es obligatorio.

    Puede haber, como máximo, un recurso RepoSync por espacio de nombres. Para hacer esto, el nombre del objeto debe ser repo-sync. Todas las configuraciones que se encuentran en el directorio al que hace referencia RepoSync deben estar en el mismo espacio de nombres que el recurso RepoSync.

  5. Aplica la configuración de RepoSync:

    kubectl apply -f repo-sync.yaml
    
  6. Para verificar la configuración, usa kubectl get en uno de los objetos del repositorio de espacios de nombres. Por ejemplo:

    kubectl get rolebindings -n NAMESPACE
    

Detener y reanudar la sincronización

En esta sección, se muestra cómo detener y reanudar la sincronización de forma temporal. También puedes hacer esto si una configuración incorrecta se confirma accidentalmente en tu repositorio.

Solo un administrador central puede detener la sincronización en el repositorio raíz.

La capacidad de detener la sincronización en repositorios de espacios de nombres depende del método de configuración que se usó para tus repositorios de espacios de nombres.

  • Si se usó el método de control de los repositorios de espacios de nombres en el repositorio raíz, un administrador central es el único que puede detener y reanudar la sincronización.

  • Si se usó el método de control de los repositorios de espacios de nombres con la API de Kubernetes, los operadores de la aplicación pueden detener y reanudar la sincronización desde los repositorios de espacios de nombres en los que operan.

Detén la sincronización

En esta sección, se muestra cómo detener la sincronización del repositorio raíz y los repositorios de espacios de nombres.

Detén la sincronización desde el repositorio raíz

Para detener la sincronización desde el repositorio raíz, un administrador central puede ejecutar el siguiente comando:

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

Mediante este comando, se reduce el recuento de replicas en el Deployment de root-reconciler a 0.

Detén la sincronización desde repositorios de espacios de nombres

Selecciona la pestaña Método del repositorio raíz o Método de la API de Kubernetes para ver las instrucciones relevantes.

Método del repositorio raíz

Si se usó el método de Control de los repositorios de espacios de nombres en el repositorio raíz, los administradores centrales pueden ejecutar los siguientes comandos para detener la sincronización desde un repositorio de espacios de nombres:

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

Mediante el comando, se reduce el recuento de réplicas en el Deployment de ns-reconciler-NAMESPACE a 0.

Método de la API de Kubernetes

Si se usó el método de control de los repositorios de espacios de nombres con la API de Kubernetes, los operadores de la aplicación pueden detener la sincronización mediante la ejecución de los siguientes comandos:

  1. Recupera la configuración de RepoSync y guárdala para usarla más adelante cuando quieras reanudar la sincronización:

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

    Reemplaza NAMESPACE por el espacio de nombres de RepoSync.

  2. Borra la configuración de RepoSync:

    kubectl -n NAMESPACE delete reposyncs repo-sync
    

    Mediante este comando, se activa el Administrador de conciliadores para quitar el conciliador de espacios de nombres (ns-reconciler-NAMESPACE) de NAMESPACE y se detiene la sincronización.

Reanuda la sincronización

En esta sección, se muestra cómo reanudar la sincronización del repositorio raíz y los repositorios de espacios de nombres.

Reanuda la sincronización desde el repositorio raíz

Para reanudar la sincronización desde un repositorio raíz, un administrador central puede ejecutar el siguiente comando:

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

Este comando escala el Deployment root-reconciler a 1 réplica.

Reanuda la sincronización desde un repositorio de espacios de nombres

Selecciona la pestaña Método del repositorio raíz o Método de la API de Kubernetes para ver las instrucciones relevantes.

Método del repositorio raíz

Si usaste el método de Control de los repositorios de espacios de nombres en el repositorio raíz, un administrador central puede ejecutar el siguiente comando:

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

Este comando escala el Deployment ns-reconciler-NAMESPACE a 1 réplica.

Método de la API de Kubernetes

Si usaste el método de Control de los repositorios de espacios de nombres con la API de Kubernetes, los operadores de la aplicación pueden reanudar la sincronización si vuelven a aplicar el archivo repo-sync.yaml que contiene la configuración de RepoSync:

kubectl apply -f repo-sync.yaml

Con este comando, se activa el administrador de conciliadores para crear un proceso de conciliación de espacios de nombres y crear un Deployment ns-reconciler-NAMESPACE.

Quita los repositorios raíz y de espacios de nombres

Para quitar el repositorio raíz, borra el archivo RootSync. Por ejemplo:

kubectl delete -f root-sync.yaml

Para desinstalar un repositorio de espacios de nombres, borra un archivo RepoSync. Esta acción desinstala el repositorio de espacios de nombres que coincide.

Resolución de conflictos

Cuando trabajas con dos repositorios, pueden surgir conflictos cuando el mismo recurso (grupos, tipos, nombres y espacios de nombres que coinciden) se declara en el repositorio raíz y en el de espacios de nombres. Cuando esto sucede, solo la declaración en el repositorio raíz se aplica al clúster.

Como el repositorio raíz siempre tiene prioridad, puedes resolver el conflicto si actualizas el repositorio raíz para que coincida con el repositorio de espacios de nombres, o si borras el objeto en conflicto en el repositorio de espacios de nombres.

¿Qué sigue?