Acerca de los paquetes de flota

En esta página, se explican los paquetes de flota, la API de FleetPackage y cómo se relacionan con el Sincronizador de configuración.

Una FleetPackage es una API declarativa que te permite administrar paquetes en una flota. Un paquete de flota es un conjunto de manifiestos YAML de Kubernetes que definen la configuración del clúster. Si usas paquetes de flota, puedes implementarlos a través de un lanzamiento progresivo o simultáneo en los clústeres registrados en tu flota.

Defines cada objeto FleetPackage una vez y, luego, puedes actualizar ese paquete con una nueva revisión. Cuando aplicas una nueva revisión, el servicio de paquetes de flota toma esos cambios y los implementa en tus clústeres.

Beneficios

Usa paquetes de flota para implementar recursos de Kubernetes en clústeres registrados en una flota. Después de crear y aplicar un paquete de flota, este implementa automáticamente los archivos de configuración de Kubernetes en el repositorio de Git en el clúster nuevo. Los paquetes de flota se basan en los beneficios del Sincronizador de configuración, como la corrección automática de la desviación, y ofrecen las siguientes ventajas únicas:

• Automatiza el lanzamiento de recursos: Después de configurar un paquete de flota, el servicio de paquetes de flota implementa automáticamente los recursos de Kubernetes a los que apunta en todos los clústeres.

• Configura clústeres nuevos automáticamente: Si configuras un paquete de flota y, luego, agregas clústeres nuevos a una flota, los recursos definidos por el paquete de flota se implementan automáticamente en el clúster nuevo.

• Administra la configuración de Kubernetes a gran escala: En lugar de administrar los clústeres de uno en uno, usa paquetes de flota para implementar recursos en toda una flota de clústeres.

• Minimiza el impacto de los cambios incorrectos: Elige una cantidad máxima de clústeres en los que implementar recursos a la vez. Puedes supervisar de cerca los cambios en cada clúster para asegurarte de que los cambios incorrectos no afecten a toda tu flota.

• Simplifica la configuración del Sincronizador de configuración: Los paquetes de flota usan Cloud Build para autenticarse en Git, lo que significa que te autenticas una vez por proyecto en lugar de una vez por objeto RootSync o RepoSync.

Es posible que prefieras usar el Sincronizador de configuración con objetos RootSync o RepoSync en lugar de paquetes de flota si se aplica una o más de las siguientes situaciones:

• Administras una pequeña cantidad de clústeres.

• Necesitas más control sobre la forma en que se implementan los recursos en tus clústeres, más allá de lo que proporciona la API de paquetes de flota con etiquetas y variantes.

Requisitos y limitaciones

• Solo se admiten repositorios de Git como la fuente de información cuando se configura un paquete de flota.

• Los recursos de Kubernetes almacenados en Git deben representar el estado final del recurso. No se admiten superposiciones adicionales para transformar el recurso almacenado en Git. Para obtener más información sobre las diferencias en estos recursos, consulta Práctica recomendada: Crea WET.

• La API de FleetPackage solo está disponible en la región us-central1. Aun así, puedes realizar implementaciones en clústeres de diferentes regiones, pero debes configurar Cloud Build y gcloud CLI en us-central1.

• La cantidad máxima de paquetes de flota es de 300 por proyecto y por región.

Arquitectura

Puedes usar la API de FleetPackage para implementar manifiestos de Kubernetes en una flota de clústeres. La API de FleetPackage usa Cloud Build para sincronizar y recuperar recursos de Kubernetes de tu repositorio de Git. Luego, el servicio de paquetes de flota implementa esos recursos en tus clústeres.

Cómo se generan las variantes

Los paquetes de flota usan un sistema de variantes para implementar diferentes configuraciones de recursos de Kubernetes en diferentes clústeres o grupos de clústeres dentro de tu flota, pero desde el mismo repositorio de Git.

Existen dos campos en la especificación FleetPackage que controlan el comportamiento de las variantes:

1. resourceBundleSelector.cloudBuildRepository.variantsPattern: Es un patrón glob que se usa para encontrar archivos y directorios en tu repositorio de Git (en la path especificada o en la raíz del repositorio si se omite path). Este patrón determina qué archivos o directorios se convierten en variantes y qué contenido incluyen.
2. variantSelector.variantNameTemplate: Es una expresión que asigna cada clúster de tu flota a uno de los nombres de variantes generados por variantsPattern. Esta selección se basa en los metadatos de la membresía de la flota del clúster.

Coincidencia de variantsPattern

El campo variantsPattern es obligatorio para especificar cómo generar variantes a partir de las configuraciones almacenadas en tu repositorio. La coincidencia usa la siguiente lógica:

• Coincidencia de archivos: Si el patrón coincide con un archivo YAML, se crea una variante.

  • Nombre de la variante: Es el nombre del archivo sin la extensión (por ejemplo, prod-config.yaml se convierte en la variante prod-config).
  • Contenido de la variante: Es el contenido de este único archivo.

• Coincidencia de directorios: Si el patrón coincide con un directorio, se crea una variante.

  • Nombre de la variante: Es el nombre del directorio (por ejemplo, el directorio dev se convierte en la variante dev).
  • Contenido de la variante: Es la combinación de todos los archivos YAML que se encuentran dentro de este directorio y todos sus subdirectorios, de forma recursiva.

Los patrones de coincidencia de archivos tienen las siguientes limitaciones:

• No hay comodines recurrentes (dobles). No se admite el patrón **.
• Si un patrón incluye un carácter de punto (.), debe ir seguido de un carácter alfanumérico.
• Los patrones no pueden incluir comillas simples (').
• Los nombres de las variantes deben ser únicos. Si tu patrón coincide con varios archivos con el mismo nombre (por ejemplo, app1/deploy.yaml y app2/deploy.yaml), ambos intentan crear una variante llamada deploy, lo que provoca una colisión de nombres.

Como ejemplo, considera un repositorio con la siguiente estructura:

repo-root/
└── FleetPackages/
    └── clusters/
        ├── common-ingress.yaml
        ├── us-central1-a/
        │   ├── gke-1/
        │   │   ├── deployment.yaml
        │   │   └── service.yaml
        │   └── gke-2/
        │       ├── deployment.yaml
        │       └── service.yaml
        └── us-central1-b/
            ├── gke-1.yaml
            └── blue-green.yaml

Puedes hacer coincidir y, por lo tanto, sincronizar con tus clústeres diferentes archivos, según el tipo de coincidencia de archivos o directorios que definas en la especificación del paquete de flota, por ejemplo:

• variantsPattern: "*": Coincide con common-ingress.yaml, us-central1-a y us-central1-b. Genera las siguientes variantes:

  • common-ingress (del archivo)
  • us-central1-a (combina todos los archivos YAML dentro de esa carpeta)
  • us-central1-b (combina todos los archivos YAML dentro de esa carpeta)

• variantsPattern: "*.yaml": Coincide con common-ingress.yaml. Genera la siguiente variante:

  • common-ingress

• variantsPattern: "us-*": Coincide con us-central1-a y us-central1-b. Genera las siguientes variantes:

  • us-central1-a
  • us-central1-b

• variantsPattern: "us-central1-b/*.yaml": Coincide con us-central1-b/gke-1.yaml y us-central1-b/blue-green.yaml. Genera las siguientes variantes:

  • gke-1
  • blue-green

Coincidencia de variantNameTemplate

Después de definir las variantes, el campo variantNameTemplate en la sección variantSelector determina qué variante se aplica a cada clúster. La plantilla puede usar variables para acceder a los siguientes metadatos de la membresía de la flota:

• ${membership.name}: Es el nombre de la membresía de la flota del clúster.
• ${membership.location}: Es la ubicación de la membresía de la flota.
• ${membership.project}: Es el proyecto de la membresía de la flota.
• ${membership.labels['KEY']}: Es el valor de la etiqueta KEY en la membresía de la flota.

Por ejemplo, considera las siguientes situaciones que usan etiquetas para hacer coincidir variantes:

• variantNameTemplate: "${membership.labels['env']}": Un clúster con la etiqueta env: prod se sincroniza con una variante llamada prod.
• variantNameTemplate: "${membership.location}": Los clústeres se sincronizan con las variantes que coinciden con su ubicación (por ejemplo, us-central1-a).
• variantNameTemplate: "default": Los clústeres se sincronizan con una variante llamada default. Este es el comportamiento predeterminado si se omite variantSelector. Si tu repositorio no contiene un archivo llamado default.yaml o un directorio llamado default, no se sincroniza nada.

Combinación de variantsPattern y variantNameTemplate

Para una implementación exitosa, debes asegurarte de que los nombres de las variantes generados por tu variantsPattern sean nombres a los que tus clústeres puedan sincronizarse haciendo coincidir el variantNameTemplate.

Por ejemplo, para realizar implementaciones en clústeres según una etiqueta de entorno, puedes estructurar tu repositorio de Git con directorios como dev, staging y prod. Luego, usarías la siguiente especificación del paquete de flota:

resourceBundleSelector:
  cloudBuildRepository:
    # ... other fields
    path: "manifests"
    variantsPattern: "*" # Matches dev, staging, prod directories
variantSelector:
  variantNameTemplate: "${membership.labels['env']}"

Con esta configuración, un clúster etiquetado como env: staging recibe el contenido del directorio manifests/staging/.

Estrategias de Deployment

Puedes usar paquetes de flota para implementar recursos desde un repositorio de Git en toda tu flota de clústeres. También puedes configurar tu paquete de flota para controlar cómo, dónde y qué tipo de recursos se implementan.

En la siguiente sección, se muestran ejemplos de diferentes configuraciones de FleetPackage. Para obtener información más detallada sobre la aplicación de paquetes de flota, consulta Implementa paquetes de flota.

Deployment en todos los clústeres de una flota

El siguiente FleetPackage usa una estrategia de lanzamiento progresivo para implementar recursos de Kubernetes en tres clústeres a la vez y segmenta todos los clústeres de una flota:

resourceBundleSelector:
  cloudBuildRepository:
    name: projects/my-project/locations/us-central1/connections/my-connection/repositories/my-repo
    tag: v1.0.0
    variantsPattern: "*.yaml"
    serviceAccount: projects/my-project/serviceAccounts/[e-mail]
target:
  fleet:
    project: projects/my-project
rolloutStrategy:
  rolling:
    maxConcurrent: 3
variantSelector:
  variantNameTemplate: deployment # matches a file named deployment.yaml

Deployment en un subconjunto de clústeres

El siguiente FleetPackage usa un selector de etiquetas para implementar recursos de Kubernetes solo en clústeres con la etiqueta de membresía country que coincida con "us" en la flota:

resourceBundleSelector:
  cloudBuildRepository:
    name: projects/my-project/locations/us-central1/connections/my-connection/repositories/my-repo
    tag: v1.0.0
    variantsPattern: "*.yaml"
    serviceAccount: projects/my-project/serviceAccounts/[e-mail]
target:
  fleet:
    project: projects/my-project
    selector:
      matchLabels:
        country: "us"
rolloutStrategy:
  rolling:
    maxConcurrent: 3

¿Qué sigue?

Implementa paquetes de flota