Acerca de los paquetes de flota

En esta página, se explican los paquetes de flotas, la API de FleetPackage y su relación con el Sincronizador de configuración.

Un FleetPackage es una API declarativa que te permite administrar paquetes en una flota. Un paquete de flota es un conjunto de manifiestos de Kubernetes en formato YAML que definen la configuración del clúster. Con los paquetes de flota, puedes implementar paquetes 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 revisión nueva, el servicio de paquetes de la flota recoge esos cambios y los implementa en tus clústeres.

Beneficios

Usa paquetes de flota para implementar recursos de Kubernetes en los 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 flotas 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 la implementación de recursos: Después de configurar un paquete de flota, el servicio de paquetes de flota implementa automáticamente en todos los clústeres los recursos de Kubernetes a los que apunta.

• Configura clústeres nuevos automáticamente: Si configuras un paquete de flota y, luego, agregas clústeres nuevos a una flota, todos 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 uno o más de los siguientes casos:

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

• Necesitas más control sobre cómo se implementan los recursos en tus clústeres, más allá de lo que proporciona la API del paquete 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 la 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 repositorios 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 desde 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.

Hay dos campos en la especificación de 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 el path especificado 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 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 correlación usa la siguiente lógica:

• Coincidencia de archivo: 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 directorio: 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 en este directorio y todos sus subdirectorios, de forma recursiva.

Los patrones de coincidencia de archivos tienen las siguientes limitaciones:

• No se admiten comodines recursivos (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 intentarán crear una variante llamada deploy, lo que provocará 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 la flota, por ejemplo:

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

  • common-ingress (desde el 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. Variante generada:

  • common-ingress

• variantsPattern: "us-*": Coincide con us-central1-a y us-central1-b. Genera 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 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 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 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 sincronizará nada.

Combinación de variantsPattern y variantNameTemplate

Para que la implementación se realice correctamente, debes asegurarte de que los nombres de las variantes que genera tu variantsPattern sean nombres con 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 implementación

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 cómo aplicar paquetes de flota, consulta Implementa paquetes de flota.

Deployment en todos los clústeres de una flota

El siguiente FleetPackage usa una estrategia de implementación continua para implementar recursos de Kubernetes en tres clústeres a la vez y se dirige a 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