Implementa paquetes de flota

En esta página, se explica cómo usar paquetes de flota de Sincronizador de configuración para implementar recursos de Kubernetes en clústeres registrados en una flota. Después de crear y, luego, implementar un paquete de flota, cuando agregues un clúster nuevo a tu flota, el paquete de flota implementará automáticamente los archivos de configuración de Kubernetes en el repositorio de Git en el clúster nuevo.

Un FleetPackage es una API declarativa para implementar manifiestos sin procesar de Kubernetes en una flota de clústeres. Todos los recursos de Kubernetes que desees implementar con un paquete de flota deben estar ya hidratados (WET).

Antes de comenzar

Crea un repositorio de Git con los recursos de Kubernetes que deseas implementar en una flota, o asegúrate de tener acceso a uno.
Instala e inicializa Google Cloud CLI, que proporciona los comandos gcloud y nomos. Si usas Cloud Shell, Google Cloud CLI ya está instalada. Si ya instalaste la Google Cloud CLI, ejecuta gcloud components update para obtener la versión más reciente.

Nota: Para las instalaciones existentes de gcloud CLI, asegúrate de establecer las propiedades compute/region y compute/zone. Cuando configuras las ubicaciones predeterminadas, puedes evitar errores en gcloud CLI como el siguiente: One of [--zone, --region] must be supplied: Please specify location.
Habilita la API de Sincronizador de configuración (anthosconfigmanagement) y la API de ConfigDelivery:
```
gcloud services enable anthosconfigmanagement.googleapis.com configdelivery.googleapis.com
```
Establece una ubicación predeterminada:
```
gcloud config set config_delivery/location us-central1
```
Nota: La única ubicación disponible para la API de ConfigDelivery es us-central1.
Sigue estos pasos para establecer un proyecto predeterminado:
```
gcloud config set project PROJECT_ID
```
Reemplaza PROJECT_ID por el ID del proyecto host de la flota.
Asegúrate de que tus clústeres estén registrados en una flota.
Usa repositorios de Cloud Build para crear una conexión a un proveedor compatible, como GitHub o GitLab. Cuando usas un paquete de flota, debes configurar Cloud Build solo una vez por cada repositorio que quieras sincronizar.

Importante: Tu conexión de Cloud Build debe estar ubicada en us-central1, ya que la conexión de Git y FleetPackage deben estar en la misma región. La API de ConfigDelivery solo está disponible en us-central1.

Revisa los requisitos del clúster

Antes de instalar Sincronizador de configuración en tu clúster, revisa las recomendaciones y los requisitos de configuración del clúster.

Prepara el entorno

Para preparar tu entorno para los paquetes de flotas de Sincronizador de configuración, otorga los roles de IAM necesarios al usuario que registra el clúster.

Instalar el Sincronizador de configuración

Puedes instalar Sincronizador de configuración con la Google Cloud consola o Google Cloud CLI.

Console

Para instalar Sincronizador de configuración, todos los clústeres deben estar registrados en una flota. Cuando instalas Sincronizador de configuración en la consola Google Cloud , la selección de clústeres individuales los registra automáticamente en tu flota.

En la Google Cloud consola, ve a la página Config en la sección Features.

Ir a Configuración

Haz clic en Instalar Config Sync.
En Opciones de instalación, selecciona Instalar el Sincronizador de configuración en toda la flota (recomendado).
Haz clic en Instalar el Sincronizador de configuración. En la pestaña Configuración, después de unos minutos, deberías ver Habilitado en la columna Estado para los clústeres de tu flota.

gcloud

Habilita la función de flota ConfigManagement:

gcloud beta container fleet config-management enable

Para habilitar Sincronizador de configuración, crea un archivo llamado apply-spec.yaml con el siguiente contenido:
```
applySpecVersion: 1
spec:
  configSync:
    enabled: true
```
Aplica el archivo apply-spec.yaml:
```
gcloud beta container fleet config-management apply \
    --membership=MEMBERSHIP_NAME \
    --config=apply-spec.yaml
```
Reemplaza MEMBERSHIP_NAME por el nombre de membresía de la flota que elegiste cuando registraste tu clúster. Para encontrar el nombre de la membresía, ejecuta el comando gcloud container fleet memberships list.

Crea una cuenta de servicio para Cloud Build

Los paquetes de flota usan Cloud Build para recuperar los recursos de Kubernetes de tu repositorio de Git y, luego, implementarlos en tus clústeres. Cloud Build requiere una cuenta de servicio que tenga los permisos para ejecutar este trabajo. Para crear la cuenta de servicio y otorgar los permisos necesarios, completa los siguientes pasos:

Crea la cuenta de servicio:
```
gcloud iam service-accounts create "SERVICE_ACCOUNT_NAME"
```
Reemplaza SERVICE_ACCOUNT_NAME por un nombre para la cuenta de servicio. El nombre debe ser un ID alfanumérico de entre 6 y 30 caracteres, por ejemplo, my-service-account. Después de crear una cuenta de servicio, no podrás cambiar su nombre.

Agrega una vinculación de política de IAM para el rol de publicador de paquetes de recursos:

gcloud projects add-iam-policy-binding PROJECT_ID \
   --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
   --role='roles/configdelivery.resourceBundlePublisher'

Si se te solicita, selecciona None como la condición de la política.

Agrega una vinculación de política de IAM para el rol de escritor de registros:

gcloud projects add-iam-policy-binding PROJECT_ID \
   --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
   --role='roles/logging.logWriter'

Si se te solicita, selecciona None como la condición de la política.

Agrega una vinculación de política de IAM para el rol de escritor de Artifact Registry:

gcloud projects add-iam-policy-binding PROJECT_ID \
   --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
   --role='roles/artifactregistry.writer'

Si se te solicita, selecciona None como la condición de la política.

Crea un paquete de flota

Para crear un paquete de flota, debes definir una especificación FleetPackage que apunte al repositorio con los recursos de Kubernetes que conectaste a Cloud Build. Luego, aplicas el FleetPackage, que recupera los recursos de Git y los implementa en toda la flota.

Crea un archivo llamado fleetpackage-spec.yaml con el siguiente contenido:
```
resourceBundleSelector:
  cloudBuildRepository:
    name: projects/PROJECT_ID/locations/us-central1/connections/CONNECTION_NAME/repositories/REPOSITORY_NAME
    tag: TAG
    serviceAccount: projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
    path: CONFIG_FILE_PATH
    # Match all files and directories to generate variants
    variantsPattern: "*"
target:
  fleet:
    project: projects/PROJECT_ID
rolloutStrategy:
  rolling:
    maxConcurrent: MAX_CLUSTERS
variantSelector:
  variantNameTemplate: "VARIANT_NAME"
# set the state to SUSPENDED to pause new rollouts
# set the state back to ACTIVE to resume rollouts
# state: SUSPENDED
```
Reemplaza lo siguiente:
- CONNECTION_NAME: Es el nombre que elegiste cuando conectaste tu host de Git a Cloud Build. Puedes ver todas las conexiones de Cloud Build en tu proyecto ejecutando gcloud builds connections list o abriendo la página Repositorios en la consola de Google Cloud :
  
  Abrir la página repositorios
- REPOSITORY_NAME: el nombre de tu repositorio. Debe ser idéntico al valor que ingresaste cuando configuraste tu conexión de Cloud Build.
- TAG: Es la etiqueta de Git de tu repositorio. El formato debe ser la versión semántica completa con el número de versión principal, secundaria y de parche. Por ejemplo, v1.0.0 es una etiqueta válida, mientras que v1 o v1.0 no lo son.
- CONFIG_FILE_PATH: Es la ruta de acceso a tus recursos de Kubernetes en el repositorio. Si tus archivos están en la raíz del repositorio, puedes omitir este campo.
- MAX_CLUSTERS: Es la cantidad máxima de clústeres en los que se pueden implementar recursos de Kubernetes al mismo tiempo. Por ejemplo, si estableces este parámetro en 1, los paquetes de recursos se implementarán en un clúster a la vez.
- VARIANT_NAME: Es la variante que se implementará en tus clústeres. El nombre debe coincidir con una variante de tu repositorio (el nombre de archivo sin extensión o el nombre del directorio). Por ejemplo, si tienes un archivo llamado prod.yaml, establece este campo en prod. Para usar el comportamiento predeterminado (por ejemplo, implementar la misma configuración en todos los clústeres de una flota), establece este campo en default y asegúrate de que tu repositorio contenga un archivo llamado default.yaml.
  
  Para obtener una lista completa de todos los campos que puedes configurar, consulta la documentación de referencia de FleetPackage.
Crea el paquete de flota:
```
gcloud container fleet packages create FLEET_PACKAGE_NAME \
    --source=fleetpackage-spec.yaml
```
Reemplaza FLEET_PACKAGE_NAME por un nombre para el lanzamiento del paquete de la flota.
Verifica que se haya creado el paquete de la flota:
```
gcloud container fleet packages list
```
El resultado muestra el estado del activador de compilación. Después de unos segundos, el campo MESSAGE se actualiza con un resultado similar al siguiente:
```
MESSAGES: Build status: WORKING. The release is still being built; see the build status on the following page:
```
Puedes hacer clic en el vínculo proporcionado para ver los registros de transmisión del trabajo de Cloud Build. Cloud Build puede tardar unos minutos en procesar el activador de compilación.

Si el activador de compilación se ejecuta correctamente, el paquete de flota comienza a implementar los recursos de Kubernetes en tu flota.

Cuando el activador de compilación se completa correctamente, el resultado de gcloud container fleet packages list es similar al siguiente:

NAME               STATE   CREATE_TIME           ACTIVE_ROLLOUT            LAST_COMPLETED_ROLLOUT  MESSAGES
my-fleet-package   ACTIVE  2024-07-09T15:15:56   rollout-20240709-153621

El paquete de flota comienza a implementar los recursos de Kubernetes en tu flota.

Ahora que implementaste un paquete de flota, cuando agregues un clúster nuevo a tu flota, los recursos de Kubernetes definidos en el paquete de flota se implementarán automáticamente en el clúster nuevo.

Actualiza un paquete de flota

Puedes actualizar un paquete de flota para cambiar la configuración o los recursos que implementa, como en los siguientes ejemplos:

Cambia la estrategia de lanzamiento modificando el valor del campo maxConcurrent.
Establece state: SUSPENDED para pausar temporalmente un paquete de la flota. Cuando se suspende un paquete de la flota, continúan las versiones en curso. No se crearán ni programarán nuevos lanzamientos hasta que vuelvas a cambiar el estado a ACTIVE.
Actualiza los recursos de Kubernetes que implementa el paquete de flota actualizando el campo tag para extraer datos de una etiqueta de Git diferente.

Para actualizar un paquete de flota, completa los siguientes pasos:

Actualiza la especificación de FleetPackage con tus cambios.
Actualiza el paquete de flota:
```
gcloud container fleet packages update FLEET_PACKAGE_NAME \
    --source=fleetpackage-spec.yaml
```
El cambio puede tardar unos minutos en implementarse y comenzar a lanzarse en tus clústeres.

Inspecciona los paquetes de recursos y los lanzamientos

Cuando creas o actualizas un paquete de flota basado en tu repositorio de Git, la API de FleetPackages crea automáticamente recursos de paquete de recursos y de versión. Inspeccionar estos recursos es útil para solucionar problemas, en especial si necesitas verificar las variantes generadas desde tu repositorio.

Para inspeccionar los paquetes y las versiones de recursos, usa uno o más de los siguientes comandos:

Para ver información detallada sobre un paquete de recursos específico, haz lo siguiente:

gcloud container fleet packages resource-bundles describe flpkg-rb-FLEET_PACKAGE_NAME

Enumera todas las versiones asociadas con un paquete de recursos:

gcloud container fleet packages resource-bundles releases list \
    --resource-bundle flpkg-rb-FLEET_PACKAGE_NAME

Consulta información detallada sobre una versión específica, incluido el paquete de recursos que usa. Este comando es particularmente útil para depurar problemas relacionados con las variantes, ya que te permite inspeccionar exactamente qué variantes se incluyeron en una versión específica:
```
gcloud container fleet packages resource-bundles releases describe RELEASE_NAME\
    --resource-bundle flpkg-rb-FLEET_PACKAGE_NAME
```

Reemplaza lo siguiente:

FLEET_PACKAGE_NAME: El nombre de tu paquete de flota. El nombre del paquete de recursos se agrega automáticamente con el prefijo flpkg-rb-.
RELEASE_NAME: Es el nombre de la versión del resultado del comando list.

Administra los lanzamientos de paquetes de la flota

Puedes supervisar el progreso de las implementaciones de paquetes de la flota y administrar los lanzamientos activos. Cuando se cambia un paquete de la flota, se crea automáticamente un nuevo lanzamiento. Los siguientes comandos te ayudan a obtener información detallada sobre los lanzamientos. Por ejemplo, si necesitas depurar un problema de implementación, puedes examinar los detalles del lanzamiento y pausar o cancelar un lanzamiento si es necesario.

Si enumeras un lanzamiento, podrás ver el estado de todos los lanzamientos vinculados a un paquete, incluidos los errores que podrían provocar que un lanzamiento falle. Para enumerar los lanzamientos y ver su estado, ejecuta el siguiente comando:

gcloud container fleet packages rollouts list --fleet-package FLEET_PACKAGE_NAME

El resultado se parece al que se indica a continuación:

ROLLOUT                   RELEASE  START_TIME              END_TIME                STATE     MESSAGE
rollout-20250515-132857   v2-0-0   2025-05-15T13:28:58Z                            STALLED
rollout-20250418-165528   v1-0-0   2025-04-18T16:55:29Z    2025-04-18T16:57:47Z    COMPLETED

La descripción de un lanzamiento proporciona información detallada sobre un lanzamiento específico, incluido el estado de cada clúster objetivo y los errores específicos de cada clúster. Para describir un lanzamiento, ejecuta el siguiente comando:

gcloud container fleet packages rollouts describe ROLLOUT_NAME --fleet-package FLEET_PACKAGE_NAME

Reemplaza ROLLOUT_NAME por el nombre de tu lanzamiento. Puedes obtener el nombre completo del lanzamiento del comando list del paso anterior.

El resultado se parece al que se indica a continuación:

CLUSTER    CURRENT_VERSION  SYNC_STATE  DESIRED_VERSION  START_TIME              END_TIME                STATE      MESSAGES
cluster1   v2.0.0           SYNCED      v2.0.0           2025-05-15T13:28:58Z    2025-05-15T13:30:27Z    COMPLETED
cluster2   v1.0.0           SYNCED      v2.0.0           2025-05-15T13:30:27Z                            ERROR      Membership no longer exists

Puedes administrar los lanzamientos activos con los siguientes comandos:
- Suspender un lanzamiento pone un lanzamiento en curso en estado SUSPENDED. Se continuarán las actualizaciones de paquetes en curso y no se programarán más actualizaciones de paquetes. Para suspender un lanzamiento, ejecuta el siguiente comando:
```
gcloud container fleet packages rollouts suspend ROLLOUT_NAME --fleet-package FLEET_PACKAGE_NAME
```
- Cuando se reanuda un lanzamiento, este cambia de SUSPENDED a IN_PROGRESS. Las actualizaciones de paquetes se implementan en los clústeres de destino según lo previsto. Para reanudar un lanzamiento, ejecuta el siguiente comando:
```
gcloud container fleet packages rollouts resume ROLLOUT_NAME --fleet-package FLEET_PACKAGE_NAME
```
- Si cancelas un lanzamiento en curso, este se detendrá de inmediato y pasará a un estado ABORTED. Se cancelarán todas las actualizaciones de paquetes pendientes que se hayan planificado como parte del lanzamiento. Para cancelar un lanzamiento, ejecuta el siguiente comando:
```
gcloud container fleet packages rollouts abort ROLLOUT_NAME --fleet-package FLEET_PACKAGE_NAME
```

Estrategias de implementación

Puedes implementar recursos de diferentes maneras, ya sea especificando etiquetas para implementar en un subconjunto de clústeres o usando la coincidencia de patrones de variantes para implementar diferentes recursos. Puedes combinar ambas estrategias para tener un mayor control sobre qué recursos se implementan en diferentes clústeres.

Implementa en un subconjunto de clústeres

Puedes implementar el mismo recurso en un subconjunto de clústeres si usas etiquetas y especificas el campo target.fleet.selector.matchLabels con tus etiquetas (par clave-valor). Por ejemplo, si configuras matchLabels como country: "us", el servicio de paquetes de la flota implementará tus recursos solo en los clústeres con la etiqueta country que coincida con "us".

Los paquetes de flota solo admiten etiquetas de membresía de flota. No se admiten las etiquetas de clúster de GKE.

(Opcional) Si aún no tienes las etiquetas que quieres usar, agrégalas siguiendo estos pasos:
1. Obtén una lista de las membresías de la flota:
```
gcloud container fleet memberships list
```
2. Agrega una etiqueta a la membresía:
```
gcloud container fleet memberships update MEMBERSHIP_NAME \
    --update-labels=KEY=VALUE
```
  Reemplaza lo siguiente:
  - MEMBERSHIP_NAME: Es el nombre del clúster registrado en la flota.
  - KEY y VALUE: Son las etiquetas que se agregarán a la membresía. Si existe una etiqueta, su valor se modifica. De lo contrario, se crea una etiqueta nueva. Las claves deben comenzar con un carácter en minúscula y contener solo guiones (-), guiones bajos (_), caracteres en minúscula y números. Los valores deben contener solo guiones (-), guiones bajos (_), caracteres en minúscula y números.
  Repite este comando para cada membresía a la que quieras agregar una etiqueta.

Crea o actualiza tu especificación FleetPackage con el selector de etiquetas:

resourceBundleSelector:
  cloudBuildRepository:
    name: projects/PROJECT_ID/locations/us-central1/connections/CONNECTION_NAME/repositories/REPOSITORY_NAME
    tag: TAG
    serviceAccount: projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
    path: CONFIG_FILE_PATH
target:
  fleet:
    project: projects/PROJECT_ID
    selector:
      matchLabels:
        KEY: "VALUE"
rolloutStrategy:
  rolling:
    maxConcurrent: MAX_CLUSTERS

Crea o actualiza el paquete de flota:

Crea un paquete de flota

gcloud container fleet packages create FLEET_PACKAGE_NAME \
    --source=fleetpackage-spec.yaml

Actualiza un paquete de flota

gcloud container fleet packages update FLEET_PACKAGE_NAME \
    --source=fleetpackage-spec.yaml

Implementa recursos de variantes en clústeres

Puedes implementar configuraciones únicas en diferentes clústeres (por ejemplo, dev en comparación con prod) agregando definiciones de variantes a tu paquete de flota.

Para obtener una descripción general conceptual de cómo se generan las variantes a partir de la estructura de tu repositorio, consulta Cómo se generan las variantes.

Para implementar un paquete de flota con variantes, completa los siguientes pasos:

Crea o actualiza tu especificación de FleetPackage para incluir los campos variantsPattern y variantNameTemplate:
```
resourceBundleSelector:
  cloudBuildRepository:
    name: projects/PROJECT_ID/locations/us-central1/connections/CONNECTION_NAME/repositories/REPOSITORY_NAME
    tag: TAG
    serviceAccount: projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
    path: CONFIG_FILE_PATH
    variantsPattern: VARIANT_PATTERN
target:
  fleet:
    project: projects/PROJECT_ID
rolloutStrategy:
  rolling:
    maxConcurrent: MAX_CLUSTERS
target:
  fleet:
    project: projects/PROJECT_ID
 variantSelector:
  variantNameTemplate: VARIANT_NAME_TEMPLATE
```
Reemplaza lo siguiente:
- VARIANT_PATTERN: Es un patrón glob para generar variantes desde tu repositorio, como * (coincide con todos los archivos y directorios) o *.yaml (coincide solo con los archivos). Para obtener más información sobre los patrones admitidos, consulta Coincidencia de variantsPattern.
- VARIANT_NAME_TEMPLATE : Es una cadena o plantilla para seleccionar una variante para cada clúster. Puedes usar variables de metadatos como ${membership.labels['env']} o ${membership.location}.
Nota: Asegúrate de que tu variantsPattern genere nombres de variantes únicos. Si dos archivos se asignan al mismo nombre (por ejemplo, app1/deploy.yaml y app2/deploy.yaml, ambos se resuelven en deploy), es posible que falle el lanzamiento debido a una colisión de nombres.

Crea o actualiza el paquete de flota:

Crea un paquete de flota

gcloud container fleet packages create FLEET_PACKAGE_NAME \
    --source=fleetpackage-spec.yaml

Actualiza un paquete de flota

gcloud container fleet packages update FLEET_PACKAGE_NAME \
    --source=fleetpackage-spec.yaml

Borra un paquete de flota

Si borras un paquete de flota, también se borrarán los siguientes recursos:

Los recursos de Kubernetes implementados en tus clústeres
Historial de lanzamiento del paquete de flota

Para borrar un paquete de la flota, ejecuta el siguiente comando:

gcloud container fleet packages delete FLEET_PACKAGE_NAME --force

Solucionar problemas

Si deseas encontrar métodos para diagnosticar y resolver errores relacionados con Cloud Build, consulta Soluciona problemas de errores de compilación.

¿Qué sigue?

Consulta la página de referencia de los campos de FleetPackage.

Implementa paquetes de flota Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Antes de comenzar

Revisa los requisitos del clúster

Prepara el entorno

Instalar el Sincronizador de configuración

Console

gcloud

Crea una cuenta de servicio para Cloud Build

Crea un paquete de flota

Actualiza un paquete de flota

Inspecciona los paquetes de recursos y los lanzamientos

Administra los lanzamientos de paquetes de la flota

Estrategias de implementación

Implementa en un subconjunto de clústeres

Crea un paquete de flota

Actualiza un paquete de flota

Implementa recursos de variantes en clústeres

Crea un paquete de flota

Actualiza un paquete de flota

Borra un paquete de flota

Solucionar problemas

¿Qué sigue?

Implementa paquetes de flota