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

  1. Crea un repositorio de Git con los recursos de Kubernetes que deseas implementar en una flota, o asegúrate de tener acceso a uno.

  2. 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 Google Cloud CLI, ejecuta gcloud components update para obtener la versión más reciente.

  3. Habilita la API de Sincronizador de configuración (anthosconfigmanagement) y la API de ConfigDelivery:

    gcloud services enable anthosconfigmanagement.googleapis.com configdelivery.googleapis.com

  4. Establece una ubicación predeterminada:

    gcloud config set config_delivery/location us-central1

  5. 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.

  6. Asegúrate de que tus clústeres estén registrados en una flota.

  7. Usa repositorios de Cloud Build para crear una conexión con 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.

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 Google Cloud consola, la selección de clústeres individuales los registra automáticamente en tu flota.

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

    Ir a Configuración

  2. Haz clic en Instalar Config Sync.

  3. En Opciones de instalación, selecciona Instalar el Sincronizador de configuración en toda la flota (recomendado).

  4. 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

  1. Habilita la función de flota ConfigManagement:

    gcloud beta container fleet config-management enable

  2. Para habilitar Sincronizador de configuración, crea un archivo llamado apply-spec.yaml con el siguiente contenido:

    applySpecVersion: 1
spec:
  configSync:
    enabled: true

  3. 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:

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  1. 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
target:
  fleet:
    project: projects/PROJECT_ID
rolloutStrategy:
  rolling:
    maxConcurrent: MAX_CLUSTERS
# 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 configuras este parámetro en 1, los paquetes de recursos se implementarán en un clúster a la vez.

      Para obtener una lista completa de todos los campos que puedes configurar, consulta la documentación de referencia de FleetPackage.

  2. 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.

  3. 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.

  4. 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.
  • Pausa temporalmente un paquete de flota estableciendo state: SUSPENDED. 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:

  1. Actualiza la especificación de FleetPackage con tus cambios.

  2. 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.

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.

  1. 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 ve de la manera siguiente:

    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

  2. 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 ve de la manera siguiente:

    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

  3. 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á al 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

Usa etiquetas para implementar en diferentes clústeres

Las etiquetas son pares clave-valor que adjuntas a los objetos. Los paquetes de flota solo admiten etiquetas de membresía de flota. No se admiten las etiquetas de clúster de GKE.

Puedes usar etiquetas para implementar un paquete de flota en un subconjunto de clústeres de tu flota.

Cómo agregar etiquetas de membresía

Para agregar una etiqueta de membresía, completa los siguientes 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.

Implementa en un subconjunto de clústeres

Puedes realizar la implementación en un subconjunto de clústeres si especificas el campo target.fleet.selector.matchLabels con tu par clave-valor. Por ejemplo, si configuras matchLabels como country: "us", el servicio de paquetes de la flota implementa tus recursos solo en los clústeres con la etiqueta country que coincide con "us".

Para implementar un paquete de flota en un subconjunto de clústeres, completa los siguientes pasos:

  1. 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

  2. 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

Las variantes son versiones diferentes de un recurso. Estos recursos pueden tener valores diferentes según la ubicación, el proyecto o el nombre del clúster. Puedes implementar recursos de variantes en diferentes clústeres especificando los campos variantsPattern y variantNameTemplate.

Puedes usar etiquetas de membresía o cualquier otro metadato de membresía, como la ubicación, el proyecto o el nombre, para hacer coincidir las variantes.

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

  1. Crea o actualiza tu especificación FleetPackage con los detalles de la variante:

    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 el patrón de la variante, por ejemplo, "variants/*.yaml" o "us-*".
    • VARIANT_NAME_TEMPLATE : Es una cadena de plantilla que hace referencia a variables que contienen metadatos de membresía del clúster, como la ubicación, el proyecto, el nombre o la etiqueta, para determinar el nombre de la variante para un clúster de destino. Para obtener más ejemplos, consulta la documentación de referencia de FleetPackage.

  2. 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?