Esta página se ha traducido con Cloud Translation API.

Desplegar paquetes de flota

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

Un FleetPackage es una API declarativa para desplegar manifiestos sin formato de Kubernetes en una flota de clústeres. Los recursos de Kubernetes que quieras desplegar con un paquete de flota deben estar hidratados (WET).

Antes de empezar

Crea un repositorio Git con los recursos de Kubernetes que quieras desplegar 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á preinstalado. Si ya has instalado la CLI de Google Cloud, obtén la versión más reciente ejecutando gcloud components update.

Nota: Si ya tienes instalado gcloud CLI, asegúrate de definir las propiedades compute/region y compute/zone. Si defines ubicaciones predeterminadas, puedes evitar errores en la CLI de gcloud como el siguiente: One of [--zone, --region] must be supplied: Please specify location.

Habilita la API Config Sync (anthosconfigmanagement) y la API ConfigDelivery:

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

Definir una ubicación predeterminada:
```
gcloud config set config_delivery/location us-central1
```
Nota: La única ubicación disponible para la API ConfigDelivery es us-central1.
Definir un proyecto predeterminado:
```
gcloud config set project PROJECT_ID
```
Sustituye 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 los repositorios de Cloud Build para crear una conexión con un proveedor compatible, como GitHub o GitLab. Cuando usas un paquete de flota, solo tienes que configurar Cloud Build una vez por cada repositorio que quieras sincronizar.

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

Revisar los requisitos de los clústeres

Antes de instalar Config Sync en tu clúster, consulta las recomendaciones y los requisitos de configuración del clúster.

Prepara tu entorno

Para preparar tu entorno para los paquetes de flota de Config Sync, concede los roles de gestión de identidades y accesos necesarios al usuario que registre el clúster.

Instalar Config Sync

Puedes instalar Config Sync con la Google Cloud consola o con la CLI de Google Cloud.

Consola

Para instalar Config Sync, todos los clústeres deben estar registrados en una flota. Cuando instalas Config Sync en la consola, al seleccionar clústeres individuales, estos se registran automáticamente en tu flota. Google Cloud

En la Google Cloud consola, ve a la página Config (Configuración) de la sección Features (Funciones).

Ir a Configuración

Haz clic en Instalar Config Sync.
En Opciones de instalación, selecciona Instalar Config Sync en toda la flota (recomendado).
Haz clic en Instalar Config Sync. En la pestaña Configuración, al cabo de unos minutos, debería aparecer Habilitado en la columna Estado de los clústeres de tu flota.

gcloud

Habilita la función de flota ConfigManagement:

gcloud beta container fleet config-management enable

Para habilitar Config Sync, 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
```
Sustituye MEMBERSHIP_NAME por el nombre de la pertenencia a la flota que elegiste al registrar tu clúster. Para encontrar el nombre de la suscripción, ejecuta el comando gcloud container fleet memberships list.

Crear una cuenta de servicio para Cloud Build

Los paquetes de flotas usan Cloud Build para obtener los recursos de Kubernetes de tu repositorio de Git y desplegarlos 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 conceder los permisos necesarios, sigue estos pasos:

Crea la cuenta de servicio:
```
gcloud iam service-accounts create "SERVICE_ACCOUNT_NAME"
```
Sustituye SERVICE_ACCOUNT_NAME por el nombre de la cuenta de servicio. El nombre debe ser un ID alfanumérico de entre 6 y 30 caracteres. Por ejemplo, my-service-account. Una vez que hayas creado una cuenta de servicio, no podrás cambiar su nombre.

Añade una vinculación de política de gestión de identidades y accesos para el rol Editor 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 pide, selecciona None como condición de la política.

Añade una vinculación de política de gestión de identidades y accesos para el rol 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 pide, selecciona None como condición de la política.

Añade una vinculación de política de gestión de identidades y accesos para el rol ArtifactRegistry Writer:

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 pide, selecciona None como condición de la política.

Crear un paquete de flotas

Para crear un paquete de flota, debes definir una especificación de FleetPackage que apunte al repositorio con tus recursos de Kubernetes que hayas conectado a Cloud Build. A continuación, aplica el FleetPackage, que obtiene los recursos de Git y los despliega 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
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
```
Haz los cambios siguientes:
- CONNECTION_NAME: el nombre que elegiste cuando conectaste tu host de Git a Cloud Build. Puedes ver todas las conexiones de Cloud Build de tu proyecto ejecutando gcloud builds connections list o abriendo la página Repositorios en la consola: Google Cloud
  
  Abre la página Repositorios.
- REPOSITORY_NAME: el nombre de tu repositorio. Debe ser idéntico al valor introducido al configurar la conexión de Cloud Build.
- TAG: 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: la ruta a los recursos de Kubernetes en el repositorio. Si los archivos están en la raíz del repositorio, puedes omitir este campo.
- MAX_CLUSTERS: número máximo de clústeres en los que se pueden implementar recursos de Kubernetes a la vez. Por ejemplo, si lo define como 1, los paquetes de recursos se desplegarán en un clúster cada vez.
  
  Para ver 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

Sustituye FLEET_PACKAGE_NAME por el nombre del lanzamiento del paquete de tu flota.

Verifica que se haya creado el paquete de flota:
```
gcloud container fleet packages list
```
En la salida se muestra el estado del activador de compilación. Al cabo de unos segundos, el campo MESSAGE se actualizará con un resultado similar al siguiente:
```
MESSAGES: Build status: WORKING. The release is still being built; see the build status on the following page:
```
Puede hacer clic en el enlace proporcionado para ver los registros de streaming 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 empezará a implementar los recursos de Kubernetes en toda la 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 empieza a implementar los recursos de Kubernetes en toda la flota.

Ahora que has desplegado un paquete de flota, cuando añadas un nuevo clúster a tu flota, los recursos de Kubernetes definidos en el paquete de flota se desplegarán automáticamente en el nuevo clúster.

Actualizar un paquete de flota

Puedes actualizar un paquete de flota para cambiar los ajustes 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 configurando state: SUSPENDED. Cuando se suspende un paquete de flota, los lanzamientos en curso continúan. 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 la flota modificando el campo tag para extraer datos de otra etiqueta de Git.

Para actualizar un paquete de flota, sigue estos pasos:

Actualiza tu FleetPackageespecificación con los 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 aplicarse y empezar a implementarse en tus clústeres.

Gestionar los lanzamientos de paquetes de la flota

Puedes monitorizar el progreso de las implementaciones de paquetes de la flota y gestionar las implementaciones activas. Cuando se cambia un paquete de flota, se crea automáticamente una nueva implementación. Los siguientes comandos te ayudan a obtener información detallada sobre los lanzamientos. Por ejemplo, si necesitas depurar un problema de implementación, puedes consultar los detalles del lanzamiento y pausarlo o cancelarlo si es necesario.

Al mostrar un lanzamiento, puedes ver el estado de todos los lanzamientos vinculados a un paquete, incluidos los errores que pueden provocar que falle un lanzamiento. Para ver una lista de las implementaciones y su estado, ejecuta el siguiente comando:

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

La salida es similar a la 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

Al describir un lanzamiento, obtienes información detallada sobre un lanzamiento específico, incluido el estado de cada clúster de destino 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

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

La salida es similar a la 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

Puedes gestionar los lanzamientos activos ejecutando los siguientes comandos:
- Si suspendes un lanzamiento, este pasa al estado SUSPENDED. Las actualizaciones de paquetes en curso continuarán 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
```
- Si reanudas un lanzamiento, este pasará 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á inmediatamente 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
```

Usar etiquetas para implementar en diferentes clústeres

Las etiquetas son pares clave-valor que se adjuntan a los objetos. Los paquetes de flotas solo admiten etiquetas de miembros de flotas. No se admiten etiquetas de clústeres de GKE.

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

Añadir etiquetas de miembro del canal

Para añadir una etiqueta de miembro, sigue estos pasos:

Obtener una lista de las membresías de la flota:
```
gcloud container fleet memberships list
```
Añade una etiqueta a la suscripción:
```
gcloud container fleet memberships update MEMBERSHIP_NAME \
    --update-labels=KEY=VALUE
```
Haz los cambios siguientes:
- MEMBERSHIP_NAME: el nombre del clúster registrado en la flota.
- KEY y VALUE: la etiqueta que se va a añadir a la suscripción. Si existe una etiqueta, se modifica su valor. De lo contrario, se creará una nueva etiqueta. Las claves deben empezar por un carácter en minúscula y solo pueden contener guiones (-), guiones bajos (_), caracteres en minúscula y números. Los valores solo pueden contener guiones (-), guiones bajos (_), caracteres en minúscula y números.
Repite este comando con cada suscripción a la que quieras añadir una etiqueta.

Desplegar en un subconjunto de clústeres

Puedes implementar en un subconjunto de clústeres especificando el campo target.fleet.selector.matchLabels con tu par clave-valor. Por ejemplo, si define matchLabels como country: "us", el servicio de paquetes de flotas desplegará sus recursos solo en clústeres con la etiqueta country que coincida con "us".

Para implementar un paquete de flota en un subconjunto de clústeres, sigue estos pasos:

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:

Crear un paquete de flota

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

Actualizar un paquete de flota

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

Desplegar recursos de variantes en clústeres

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

Puedes usar etiquetas de pertenencia u otros metadatos de pertenencia, como la ubicación, el proyecto o el nombre, para que coincidan las variantes.

Para implementar un paquete de flota con variantes, sigue estos pasos:

Cree o actualice su archivo 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

Haz los cambios siguientes:

VARIANT_PATTERN: el patrón de la variante, por ejemplo, "variants/*.yaml" o "us-*".
VARIANT_NAME_TEMPLATE : cadena de plantilla que hace referencia a variables que contienen metadatos de pertenencia a clústeres, como la ubicación, el proyecto, el nombre o la etiqueta, para determinar el nombre de la variante de un clúster de destino. Para ver más ejemplos, consulta la documentación de referencia de FleetPackage.

Crea o actualiza el paquete de flota:

Crear un paquete de flota

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

Actualizar un paquete de flota

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

Eliminar un paquete de flota

Si eliminas un paquete de flota, también se eliminarán los siguientes recursos:

Los recursos de Kubernetes desplegados en tus clústeres
Historial de lanzamiento de paquetes de la flota

Para eliminar un paquete de flota, ejecuta el siguiente comando:

gcloud container fleet packages delete FLEET_PACKAGE_NAME --force

Solucionar problemas

Para encontrar métodos que te ayuden a diagnosticar y resolver errores relacionados con Cloud Build, consulta el artículo Solucionar problemas de errores de compilación.

Siguientes pasos

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

Desplegar paquetes de flota Organízate con las colecciones Guarda y clasifica el contenido según tus preferencias.

Antes de empezar

Revisar los requisitos de los clústeres

Prepara tu entorno

Instalar Config Sync

Consola

gcloud

Crear una cuenta de servicio para Cloud Build

Crear un paquete de flotas

Actualizar un paquete de flota

Gestionar los lanzamientos de paquetes de la flota

Usar etiquetas para implementar en diferentes clústeres

Añadir etiquetas de miembro del canal

Desplegar en un subconjunto de clústeres

Crear un paquete de flota

Actualizar un paquete de flota

Desplegar recursos de variantes en clústeres

Crear un paquete de flota

Actualizar un paquete de flota

Eliminar un paquete de flota

Solucionar problemas

Siguientes pasos

Desplegar paquetes de flota