Sincronizar desde varios repositorios

Habilitar el modo de varios repositorios en el Sincronizador de configuración te permite sincronizar configuraciones de varios repositorios con el mismo conjunto de clústeres. Para usar el modo de varios repositorios, debes crear un único repositorio raíz y, de manera opcional, puedes crear repositorios de espacio de nombres. Un repositorio raíz puede sincronizar archivos de configuración con permisos de clúster y con permisos de espacio de nombres y, por lo general, lo administra un administrador. Los repositorios de espacios de nombres contienen archivos de configuración con permiso de espacio de nombres que están sincronizados con un espacio de nombres particular en todos los clústeres. Para obtener más información sobre estos tipos de repositorios, consulta la sección Repositorios en la descripción general de Sincronizador de configuración.

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:

  • Crear repositorios de Git o tener acceso a estos.
  • Crear un proyecto de Google Cloud o tener acceso a este.
  • Crear un clúster de Google Kubernetes Engine (GKE) que cumpla con los siguientes requisitos o tener acceso a este:
    • Es un clúster estándar. El Sincronizador de configuración no es compatible con los clústeres de Autopilot.
    • Usa una versión de GKE entre 1.18 y 1.20.
    • Tiene un grupo de nodos que usa un tipo de máquina con al menos 4 CPU virtuales.
  • Usa una versión de Sincronizador de configuración de 1.5.3 o posterior.

Limitaciones

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

Configura la sincronización desde el repositorio raíz

Para configurar la sincronización desde el repositorio raíz, debes habilitar el modo de varios repositorios en el objeto ConfigManagement y crear un objeto RootSync que sincronice el repositorio raíz con el clúster. Solo puedes crear un repositorio raíz por clúster, y el repositorio raíz puede ser un repositorio no estructurado o un repositorio jerárquico.

En las siguientes secciones, se describen tres métodos diferentes para habilitar el modo de varios repositorios:

  1. Si no instalaste el Sincronizador de configuración, crea una nueva configuración del repositorio de Git raíz.
  2. Si instalaste el Sincronizador de configuración, mueve la configuración del repositorio de Git raíz a RootSync.
  3. Si instalaste Config Sync y necesitas usar los campos spec.git, conserva la configuración del repositorio de Git raíz en el archivo YAML de ConfigManagement.

1. Nueva configuración

Si todavía no instalaste el Sincronizador de configuración, completa las siguientes tareas para habilitar el modo de varios repositorios:

  1. Completa las siguientes secciones en Instala el Sincronizador de configuración:

    1. Antes de comenzar
    2. Implementa el operador
    3. Otorga al operador acceso de solo lectura a Git
  2. Si usas la versión 1.7.0 o posterior y estás instalando el Sincronizador de configuración en un clúster privado, agrega una regla de firewall para permitir el puerto 8676. El webhook de admisión del Sincronizador de configuración usa el puerto 8676 para la prevención de desvíos.

  3. Crea un archivo llamado config-management.yaml y copia el siguiente archivo YAML en él:

    # 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 un 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
    

    Reemplaza lo siguiente:

    • FORMAT: agrega unstructured para usar un repositorio no estructurado o agrega hierarchy a fin de usar un repositorio jerárquico. Estos valores distinguen entre mayúsculas y minúsculas. Este campo es opcional y el valor predeterminado es hierarchy. Te recomendamos que agregues unstructured, ya que este formato te permite organizar la configuración de la manera que te resulte más conveniente.
    • REPOSITORY: Agrega la URL del repositorio de Git para usarlo como repositorio raíz. Puedes ingresar las URL con el protocolo HTTPS o SSH. Por ejemplo, https://github.com/GoogleCloudPlatform/csp-config-management/ usa el protocolo HTTPS. Si no ingresas un protocolo, la URL se trata como una URL HTTPS. 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 en el repositorio de Git al directorio raíz que contiene la configuración con la que deseas 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
      • gcenode: si Workload Identity está habilitada en el clúster, no puedes usar gcenode. Este campo es obligatorio.
    • SECRET_NAME: agrega el nombre del secreto. Si usas un Secret, debes agregar la clave pública de Secret al proveedor de Git. Este campo es opcional.

  6. Aplique los cambios:

    kubectl apply -f root-sync.yaml
    

2. Mueve la configuración

Si ya instalaste el Sincronizador de configuración, puedes mover las configuraciones del repositorio de Git del objeto ConfigManagement existente a un objeto RootSync.

Si, para configurar el repositorio raíz, se mueve la configuración, completa las siguientes tareas:

  1. Si usas la versión 1.7.0 o una posterior y, luego, instalaste el Sincronizador de configuración en un clúster privado, agrega una regla de firewall para permitir el puerto 8676. El webhook de admisión del Sincronizador de configuración usa el puerto 8676 para la prevención de desvíos.
  2. Abre el objeto ConfigManagement.
  3. Haz una copia de los valores en los campos spec.git. Usa estos valores cuando crees el objeto RootSync.
  4. Quita todos los campos spec.git (incluido git:) del objeto ConfigManagement.
  5. En el objeto ConfigManagement, establece el campo spec.enableMultiRepo en true:

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

    kubectl apply -f config-management.yaml
    
  7. Con los valores que copiaste del objeto ConfigManagement, crea el objeto RootSync. Por ejemplo:

    # 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
    

    Reemplaza lo siguiente:

    • FORMAT: Agrega unstructured para usar un repositorio no estructurado o agrega hierarchy a fin de usar un repositorio jerárquico. Estos valores distinguen entre mayúsculas y minúsculas. Este campo es opcional y el valor predeterminado es hierarchy. Te recomendamos que agregues unstructured, ya que este formato te permite organizar la configuración de la manera que te resulte más conveniente.
    • REPOSITORY: Agrega la URL del repositorio de Git para usarlo como repositorio raíz. Puedes ingresar las URL con el protocolo HTTPS o SSH. Por ejemplo, https://github.com/GoogleCloudPlatform/csp-config-management/ usa el protocolo HTTPS. Si no ingresas un protocolo, la URL se trata como una URL HTTPS. 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 en el repositorio de Git al directorio raíz que contiene la configuración con la que deseas 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
      • gcenode: si Workload Identity está habilitada en el clúster, no puedes usar gcenode. Este campo es obligatorio.
    • SECRET_NAME: agrega el nombre del secreto. Si usas un Secret, debes agregar la clave pública de Secret al proveedor de Git. Este campo es opcional.

  8. Aplique los cambios:

    kubectl apply -f root-sync.yaml
    

3. Mantén la configuración

Si ya instalaste el Sincronizador de configuración, puedes mantener un repositorio de Git raíz existente configurado en el objeto ConfigManagement. Sin embargo, no se recomienda este método, ya que dejará de estar disponible.

Para configurar el repositorio raíz manteniendo el repositorio raíz en el objeto ConfigManagement, completa las siguientes tareas:

  1. Si usas la versión 1.7.0 o una posterior y, luego, instalaste el Sincronizador de configuración en un clúster privado, agrega una regla de firewall para permitir el puerto 8676. El webhook de admisión del Sincronizador de configuración usa el puerto 8676 para la prevención de desvíos.

  2. En el objeto ConfigManagement, configura los campos spec.enableMultiRepo y spec.enableLegacyFields en true, configuraspec.sourceFormat en unstructured para usar un repositorio no estructurado o hierarchy usa un repositorio jerárquico. Estos valores distinguen entre mayúsculas y minúsculas. Este campo es opcional y el valor predeterminado es hierarchy. Te recomendamos que agregues unstructured, ya que este formato te permite organizar la configuración de la manera que te resulte más conveniente.

    # 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. Aplica los cambios:

    kubectl apply -f config-management.yaml
    

Aplicar config-management.yaml con enableMultiRepo: true y enableLegacyFields: true establecidos de forma automática genera el objeto RootSync en el clúster. No cambies la configuración de RootSync que se genera.

Para agregar repositorios de espacios de nombres opcionales, ve a la sección Configura la sincronización desde repositorios de espacios de nombres. Si solo deseas sincronizar desde un único repositorio y seguir usando el flujo de trabajo actual, puedes omitir esa sección.

Verifica el estado de sincronización del repositorio raíz

Puedes usar el comando nomos status para inspeccionar el estado de sincronización del repositorio raíz:

nomos status

Deberías ver un resultado similar al siguiente:

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

Verifica la instalación de RootSync

Cuando creas un objeto RootSync, el Sincronizador de configuración crea un conciliador llamado root-reconciler. Un conciliador es un Pod que se implementa como una implementación. Sincroniza los manifiestos de un repositorio de Git a un clúster.

Para verificar que el objeto RootSync funcione correctamente, verifica el estado de la implementación de root-reconciler:

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

Deberías ver un resultado similar al siguiente:

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

Para conocer más formas de explorar el estado del objeto RootSync, consulta la sección Explora los objetos RootSync y RepoSync.

Configura la sincronización desde repositorios de espacios de nombres

Una vez que hayas configurado el repositorio raíz, puedes optar por configurar repositorios de espacios de nombres que los usuarios no administrativos puedan controlar. Los repositorios de espacios de nombres deben ser no estructurados.

Para configurar los repositorios de espacios de nombres, debes asignar permisos y crear un objeto RepoSync que sincronice el repositorio de espacio de nombres con el clúster. Puedes elegir entre dos métodos 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, crea un objeto RepoSync en el mismo espacio de nombres:

    # 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
    

    Reemplaza lo siguiente:

    • NAMESPACE: Agrega el nombre de tu espacio de nombres.
    • REPOSITORY: Agrega la URL del repositorio de Git para usarlo como repositorio de espacio de nombres. Puedes ingresar las URL con el protocolo HTTPS o SSH. Por ejemplo, https://github.com/GoogleCloudPlatform/csp-config-management/ usa el protocolo HTTPS. Si no ingresas un protocolo, la URL se trata como una URL HTTPS. 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 en el repositorio de Git al directorio raíz que contiene la configuración con la que deseas 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
      • gcenode: si Workload Identity está habilitada en el clúster, no puedes usar gcenode.

      Este campo es obligatorio.

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

    Puede haber, como máximo, un objeto RepoSync por espacio de nombres. Para aplicar esta restricción, el objeto name 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.

      • Un ClusterRole o Role definido por el usuario declarado en el repositorio raíz. Esta función admite permisos detallados.

  4. Confirme los cambios en el repositorio raíz:

     git add .
     git commit -m 'Setting up new namespace repository.'
     git push
    
  5. Si es necesario, crea un Secret según tu método de autenticación preferido. Si usaste none como el tipo de autenticación, puedes omitir este paso.

    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: USERNAME
       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.
    • USERNAME: 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. Esta función admite permisos detallados.

  3. Confirme los cambios 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. Si es necesario, crea un Secret según tu método de autenticación preferido. Si usaste none como el tipo de autenticación, puedes omitir este paso.

    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 root-sync.yaml.
    • Debes agregar la clave pública del Secret al proveedor de Git.
  4. Declara una configuración de 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
    

    Reemplaza lo siguiente:

    • REPOSITORY: Agrega la URL del repositorio de Git para usarlo como repositorio de espacio de nombres. Puedes ingresar las URL con el protocolo HTTPS o SSH. Por ejemplo, https://github.com/GoogleCloudPlatform/csp-config-management/ usa el protocolo HTTPS. Si no ingresas un protocolo, la URL se trata como una URL HTTPS. 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 en el repositorio de Git al directorio raíz que contiene la configuración con la que deseas 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
      • gcenode: si Workload Identity está habilitada en el clúster, no puedes usar gcenode.

      Este campo es obligatorio.

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

    Puede haber, como máximo, un objeto RepoSync por espacio de nombres. Para hacer esto, el name 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
    

Verifica el estado de sincronización del repositorio del espacio de nombres

Puedes usar el comando nomos status para inspeccionar el estado de sincronización del repositorio de espacio de nombres:

nomos status

Deberías ver un resultado similar al siguiente:

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

En este resultado de ejemplo, el repositorio del espacio de nombres se configura para el espacio de nombres llamado bookstore.

Verifica la instalación de RepoSync

Cuando creas un objeto RepoSync, el Sincronizador de configuración crea un conciliador llamado ns-reconciler-NAMESPACE, en el que NAMESPACE es el espacio de nombres en el que creaste el objeto RepoSync.

Para verificar que el objeto RepoSync funcione correctamente, verifica el estado de la implementación de ns-reconciler-NAMESPACE:

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

Reemplaza NAMESPACE por el espacio de nombres en el que creaste el repositorio de espacio de nombres.

Para conocer más formas de explorar el estado del objeto RepoSync, consulta la sección Explora los objetos RootSync y RepoSync.

Detener y reanudar la sincronización

En las secciones siguientes, se muestra cómo detener y reanudar la sincronización de forma temporal. Es posible que debas 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 las siguientes secciones, se muestra cómo detener la sincronización para el 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.

Ignora las mutaciones de objetos

En la versión 1.7 y las versiones posteriores del Sincronizador de configuración, si no quieres que el Sincronizador de configuración mantenga el estado del objeto en el clúster después de su existencia, puedes agregar la anotación client.lifecycle.config.k8s.io/mutation: ignore al objeto en el que deseas que el Sincronizador de configuración ignore las mutaciones. Esta acción es útil cuando quieres que el Sincronizador de configuración cree un objeto y, luego, ignore cualquier cambio conflictivo en este objeto en el clúster.

En el siguiente ejemplo, se muestra cómo agregar la anotación a un objeto:

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

No puedes modificar de forma manual esta anotación en los objetos administrados del clúster.

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.

Si se produce este conflicto, RootSync no informará ningún problema, ya que el repositorio raíz tiene prioridad. RepoSync informa un error KNV 1060 en su estado.

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.

Explora los objetos RootSync y RepoSync

En las siguientes secciones, se muestran diferentes formas de explorar los objetos RootSync y RepoSync.

Cómo ver registros

Para obtener más información sobre posibles errores, puedes ver los registros de los objetos RootSync y RepoSync.

Para ver los registros del conciliador de RootSync, ejecuta el siguiente comando:

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

Reemplaza CONTAINER_NAME por git-sync, reconciler o otel-agent. El contenedor git-sync extrae los archivos de configuración de un repositorio de Git a un directorio local del que puede leer el contenedor del conciliador. El contenedor reconciler aplica esos archivos de configuración al clúster. El contenedor otel-agent es un agente de OpenTelemetry para recuperar y exportar las métricas del Sincronizador de configuración.

Para ver los registros del conciliador de RepoSync, ejecuta el siguiente comando:

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

Reemplaza lo siguiente:

  • NAMESPACE: el espacio de nombres en el que creaste el repositorio del espacio de nombres.
  • CONTAINER_NAME: Ya sea git-sync, reconciler o otel-agent.

Visualiza las confirmaciones sincronizadas

Puedes comprobar qué confirmación se sincroniza con el clúster.

Para ver los detalles de RootSync, ejecuta el siguiente comando:

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

Para ver los detalles de RepoSync, ejecuta el siguiente comando:

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

Deberías ver un resultado similar al siguiente:

NAME        SOURCECOMMIT                               SYNCCOMMIT
root-sync   66882815f0ef5517df27e864fb1315e97756ab72   66882815f0ef5517df27e864fb1315e97756ab72

El valor en la columna SOURCECOMMIT es la confirmación del repositorio de Git que se debe sincronizar con el clúster. El valor en la columna SYNCCOMMIT es la confirmación que se implementa actualmente en el clúster. Si los dos valores de las columnas SOURCECOMMIT y SYNCCOMMIT son los mismos, la confirmación esperada se implementó en el clúster.

Visualiza los detalles del objeto

Para ver los detalles de los objetos RootSync y RepoSync, usa kubectl describe. Este comando puede brindarte más información sobre posibles errores.

Para ver los detalles del objeto RootSync, ejecuta el siguiente comando:

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

Para ver los detalles del objeto RepoSync, ejecuta el siguiente comando:

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

Visualiza si un recurso está listo

Para saber si los recursos sincronizados con el clúster están listos, consulta el estado de conciliación. Por ejemplo, este comando puede mostrarte si una implementación sincronizada está lista para entregar el tráfico.

Para un repositorio de Git sincronizado con el clúster, el estado de conciliación de todos los recursos se agrega en un recurso llamado ResourceGroup. Para cada objeto RootSync o RepoSync, se genera un ResourceGroup a fin de capturar el conjunto de recursos aplicados al clúster y los estados agregados.

Para ver el estado de conciliación del objeto RootSync, ejecuta el siguiente comando:

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

Para ver el estado de conciliación del objeto RepoSync, ejecuta el siguiente comando:

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

En el resultado, verás todos los estados de los recursos de ResourceGroup. Por ejemplo, el siguiente resultado muestra que una implementación llamada nginx-deployment está lista:

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

Soluciona problemas

Las siguientes secciones te ayudan a solucionar problemas cuando sincronizas desde varios repositorios.

Error: el webhook de admisión rechazó una solicitud

Si recibes el siguiente error cuando intentas aplicar un cambio en un campo que administra el Sincronizador de configuración, es posible que hayas realizado un cambio conflictivo:

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

Cuando declaras un campo en una configuración y el repositorio se sincroniza con un clúster, el Sincronizador de configuración administra ese campo. Cualquier cambio que intentes hacer en ese campo es un cambio conflictivo.

Por ejemplo, si tienes una configuración de implementación en el repositorio con una etiqueta environment:prod y tratas de cambiar esa etiqueta a environment:dev en el clúster, habrá un cambio conflictivo y recibirás el mensaje de error anterior. Sin embargo, si agregas una etiqueta nueva (por ejemplo, tier:frontend) a la implementación, no habrá un conflicto.

Si quieres que el Sincronizador de configuración ignore los cambios en un objeto, puedes agregar la anotación que se describe en Ignora las mutaciones de objetos.

Error: se agotó el tiempo de espera de E/S de la solicitud de webhook

Si recibes el siguiente error cuando el conciliador intenta aplicar una configuración al clúster:

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

Esto puede deberse a que el firewall bloquea el puerto del webhook de admisión 8676 en la red del plano de control. A fin de resolver este problema, agrega una regla de firewall para permitir el puerto 8676, que el webhook de admisión del Sincronización de configuración usa para la prevención de desvíos.

Error: se rechazó la conexión de webhook de admisión

Si recibes el siguiente error cuando el conciliador intenta aplicar una configuración al clúster:

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

Esto significa que el webhook de admisión aún no está listo. Es un error transitorio que podrías ver cuando inicias el Sincronizador de configuración.

Si el problema persiste, consulta la implementación del webhook de admisión para ver si sus pods se pueden programar y están en buen estado.

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

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

Los campos ResourceGroup cambian constantemente

En ocasiones, ResourceGroup puede ingresar un bucle que continúa con la actualización del spec de ResourceGroup. Si esto sucede, es posible que observes los siguientes problemas:

  • El metadata.generation de un ResourceGroup sigue aumentando en un período breve.
  • El ResourceGroup spec cambia constantemente.
  • El ResourceGroup spec no incluye el status.resourceStatuses de los recursos que se están sincronizando con el clúster.

Si observas estos problemas, significa que algunos de los recursos en los repositorios de Git no se aplicaron al clúster. La causa de estos problemas es que no tienes los permisos necesarios para aplicar esos recursos.

Para verificar que faltan los permisos, obtén el estado de los recursos de RepoSync:

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

Reemplaza NAMESPACE por el espacio de nombres en el que creaste el repositorio de espacio de nombres.

Si ves los siguientes mensajes en el estado, significa que el conciliador en NAMESPACE carece del permiso necesario para aplicar el 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 solucionar este problema, debes declarar una configuración de RoleBinding que otorgue a la cuenta de servicio ns-reconciler-NAMESPACE permiso para administrar el recurso con errores en ese espacio de nombres. Los detalles sobre cómo agregar un RoleBinding se incluyen en la sección Configura la sincronización desde repositorios de espacios de nombres.

Gran cantidad de recursos en el repositorio de Git

Cuando el repositorio de Git sincronizado por los objetos RepoSync o RootSync contiene la configuración para más de unos miles de recursos, puede hacer que ResourceGroup supere el límite de tamaño de los objetos etcd. Cuando esto sucede, no puedes ver el estado agregado para los recursos de el repositorio de Git. Si bien no podrás ver el estado agregado, el repositorio seguirá estando sincronizado. Si no ves errores en los objetos RepoSync o RootSync, significa que el repositorio de Git se sincroniza con el clúster de manera correcta.

Para verificar si el recurso de ResourceGroup supera el límite de tamaño de los objetos etcd, debes verificar el estado del recurso de ResourceGroup y el registro del controlador de ResourceGroup:

  1. Verifica el estado de ResourceGroup con el siguiente comando:

    • Para verificar RootSync, ejecuta el siguiente comando:
     kubectl get resourcegroup.kpt.dev root-sync -n config-management-system
    
    • Para verificar RepoSync, ejecuta el siguiente comando:
    # For the RepoSync:
    kubectl get resourcegroup.kpt.dev repo-sync -n NAMESPACE
    

    Deberías ver un resultado similar al siguiente:

    NAME        RECONCILING   STALLED   AGE
    root-sync   True          False     35m
    

    Si el valor en la columna RECONCILING es True, significa que el recurso de ResourceGroup todavía se encuentra en conciliación.

  2. Verifica los registros del controlador de ResourceGroup con el siguiente comando:

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

    Si ves el siguiente error en el resultado, el recurso de ResourceGroup es demasiado grande y supera el límite de tamaño de los objetos etcd:

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

Para evitar que ResourceGroup se vuelva demasiado grande, reduce la cantidad de recursos en el repositorio de Git. Por ejemplo, divide el repositorio y usa un objeto RootSync con varios objetos RepoSync en lugar de usar solo un objeto RootSync para sincronizar todos los recursos.

¿Qué sigue?