Organiza los archivos de configuración en una fuente de información

En esta página, se explica cómo organizar las configuraciones en una fuente de verdad.

A medida que tu organización crece, es probable que necesites administrar configuraciones en una flota de clústeres y admitir varios equipos que trabajan en los mismos repositorios. Una parte clave de una estrategia de GitOps exitosa es garantizar que las configuraciones se apliquen a los clústeres correctos y que los equipos puedan trabajar sin interferir entre sí.

Acerca de los archivos de configuración

El Sincronizador de configuración está diseñado para operadores de clúster que administran muchos clústeres. Puedes asegurarte de que tus clústeres cumplan con los estándares empresariales y de cumplimiento si permites que el Sincronizador de configuración administre espacios de nombres, roles, RoleBindings, ResourceQuotas y otros objetos importantes de Kubernetes en toda tu flota.

Cuando el Sincronizador de configuración administra estos recursos, mantiene los clústeres inscritos sincronizados mediante archivos de configuración. Un archivo de configuración es un archivo YAML o JSON en una fuente de verdad. El Sincronizador de configuración admite repositorios de Git, imágenes de OCI y gráficos de Helm como fuente de información. Los archivos de configuración contienen el mismo tipo de detalles de configuración que puedes aplicar de forma manual a un clúster con el comando kubectl apply. Puedes crear un archivo de configuración para cualquier objeto de Kubernetes que pueda existir en un clúster. Sin embargo, algunos objetos de Kubernetes, como los Secrets, contienen información sensible, y puede ser inapropiado almacenarlos en una fuente de información. Considera cuidadosamente si debes administrar estos tipos de objetos con Sincronizador de configuración.

Requisitos y limitaciones

  • Algunos recursos de Kubernetes contienen campos inmutables, como los selectores de Pod en un objeto Deployment. No puedes cambiar ningún campo inmutable en una configuración cambiando el valor en la fuente de la verdad. Si intentas realizar ese cambio, se producirá un error KNV2009. Si necesitas cambiar un campo inmutable, borra el objeto de tu fuente de información, espera a que el Sincronizador de configuración lo borre del clúster y, luego, vuelve a crear el objeto en tu fuente de información con tus actualizaciones.

  • Si usas submódulos de Git, debes otorgar acceso al Sincronizador de configuración a todos los repositorios, incluidos los submódulos.

  • No puedes usar el Sincronizador de configuración para administrar directamente los ClusterRoles integrados de Kubernetes. GKE incluye algunos roles orientados al usuario integrados, como cluster-admin, admin, edit y view. No puedes administrar directamente estos ClusterRoles con el Sincronizador de configuración, ya que, de lo contrario, este entraría en conflicto con GKE. Para agregar permisos a los ClusterRoles integrados, usa la agregación de roles para modificarlos de forma indirecta. Para modificar los roles, crea un ClusterRole con un nombre único en tu fuente de verdad con las anotaciones adecuadas.

Organiza tu fuente de información

Puedes configurar el Sincronizador de configuración para que se sincronice desde un repositorio completo o desde carpetas o ramas específicas. Debido a esta flexibilidad, organiza tus archivos de configuración según las necesidades de tu equipo o tu organización.

Te recomendamos que, cuando configures el Sincronizador de configuración, establezcas sourceFormat en unstructured. El tipo de fuente estructurada (jerárquica) requiere una estructura de carpetas muy específica para sincronizar correctamente tus configuraciones y agrega una complejidad innecesaria en la mayoría de los casos.

La mayor parte de la documentación del Sincronizador de configuración, incluida esta página, usa el formato no estructurado de forma predeterminada, pero puedes encontrar información sobre el formato jerárquico, si es necesario, en Usa un repositorio jerárquico.

Cuando usas una fuente no estructurada, tienes la flexibilidad de organizar tus archivos de configuración para que se adapten al flujo de trabajo de tu equipo. En esta sección, se proporcionan algunos patrones comunes para estructurar tu repositorio.

Diseño basado en el entorno

Un enfoque común es organizar tu repositorio por entorno.

├── cluster-essentials/
│   ├── crds/
│   └── namespace.yaml
├── environments/
│   ├── dev/
│   │   ├── backend/
│   │   └── frontend/
│   ├── staging/
│   │   ├── backend/
│   │   └── frontend/
│   └── prod/
│       ├── backend/
│       └── frontend/
└── system/
    └── monitoring/

En este ejemplo, la fuente de confianza se organiza de la siguiente manera:

  • cluster-essentials/: Contiene la configuración que se aplica a todos los clústeres, independientemente del entorno. Esto puede incluir recursos como las definiciones de recursos personalizados (CRD) y los espacios de nombres esenciales.
  • environments/: Es el directorio principal de todas las configuraciones específicas del entorno.
  • system/: Contiene configuraciones para servicios a nivel del sistema, como la supervisión.

Este enfoque es sencillo de comprender y navegar, y proporciona una ruta de promoción clara para los cambios de un entorno a otro.

Cuando configuras el Sincronizador de configuración en esta situación, creas varios objetos RootSync en cada clúster. Por ejemplo, un clúster de desarrollo tiene objetos RootSync que se sincronizan desde cluster-essentials/, system/ y environments/dev/.

Diseño basado en clústeres

Si te enfocas en administrar una flota de clústeres individuales con configuraciones distintas, un diseño basado en clústeres podría ser más adecuado.

├── clusters/
│   ├── cluster-a/
│   │   ├── apps/
│   │   └── networking/
│   ├── cluster-b/
│   │   ├── apps/
│   │   └── networking/
│   └── cluster-c/
│       ├── apps/
│       └── networking/
└── shared/
    ├── roles/
    └── policies/

En este ejemplo, la fuente de confianza se organiza de la siguiente manera:

  • clusters/: Contiene un directorio para cada clúster que administras.
  • shared/: Contiene configuraciones que son comunes a todos los clústeres, como los roles de RBAC y las políticas de seguridad.

Este enfoque es eficaz para administrar muchos clústeres si todos tienen configuraciones únicas, ya que proporciona una propiedad clara y un aislamiento de las configuraciones. Este enfoque puede ser más complejo de administrar si tienes muchas configuraciones de clúster compartidas.

Cuando configures Sincronizador de configuración en esta situación, puedes usar un RepoSync para configurar cada clúster de modo que se sincronice desde shared y el directorio específico del clúster.

Diseño basado en equipos

Para las organizaciones en las que diferentes equipos administran diferentes aplicaciones o servicios, un diseño basado en equipos puede ser eficaz. Este enfoque alinea la estructura de la fuente de información con la estructura de tu organización.

├── teams/
│   ├── team-alpha/
│   │   ├── app-one/
│   │   └── app-two/
│   ├── team-beta/
│   │   ├── service-a/
│   │   └── service-b/
│   └── team-gamma/
│       ├── data-pipeline/
│       └── dashboard/
└── platform/
    ├── cluster-roles/
    └── storage-classes/

En este ejemplo, la fuente de verdad se organiza de la siguiente manera:

  • teams/: Organiza la configuración por equipo, y cada equipo administra sus propias configuraciones de aplicaciones y servicios.
  • platform/: Contiene configuraciones de todo el clúster que administra un equipo central de la plataforma y que usan todos los equipos.

Este enfoque permite que los equipos administren sus propios ciclos de configuración y lanzamiento, y reduce la posibilidad de que los cambios de un equipo afecten accidentalmente a otro. Sin embargo, este enfoque requiere una administración cuidadosa de las dependencias entre los equipos de la app y los equipos de la plataforma.

Cuando configuras el Sincronizador de configuración, en este caso, cada equipo usa un objeto RootSync para sincronizar la configuración, por ejemplo, team-alpha se sincroniza desde teams/team-alpha/.

Valida los archivos de configuración

Después de crear, organizar y agregar archivos de configuración a una fuente de información, usa el comando nomos vet --source-format=unstructured para verificar la sintaxis y la validez de tus archivos de configuración. Esto te ayuda a evitar errores durante o después de la sincronización.

Ignora mutaciones de objetos

Si no quieres que el Sincronizador de configuración mantenga el estado del objeto en el clúster después de su existencia, agrega 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.

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.

Convierte un repositorio jerárquico en un repositorio no estructurado

Si usas un repositorio jerárquico y deseas convertirlo en un repositorio no estructurado, ejecuta el siguiente comando:

nomos hydrate PATH

Reemplaza PATH por la ruta de acceso a tu directorio.

Esto crea un directorio compiled/ en el directorio de trabajo actual. Dentro de ese directorio, se crea un subdirectorio para cada clúster inscrito. Estos subdirectorios contienen los archivos de configuración completamente resueltos y se pueden usar en un repositorio no estructurado.

Para obtener más detalles, consulta Comandos nomos.

Si prefieres convertir tu repositorio de forma manual, completa las siguientes instrucciones:

  1. Quita las configuraciones Repo en el directorio system/ de tu repositorio de Git. El recurso Repo no es necesario para un repositorio no estructurado.

  2. El directorio de espacio de nombres abstracto no es compatible con un repositorio no estructurado. Por lo tanto, declara el espacio de nombres de todos los recursos incluidos originalmente en el directorio namespaces/ y sus subdirectorios.

  3. No se admite la herencia de espacios de nombres en el repositorio no estructurado. Por lo tanto, declara todos los recursos que se heredaron originalmente en los espacios de nombres descendientes (los que estaban originalmente en el directorio namespaces/).

¿Qué sigue?