Usa paquetes de flota en Distributed Cloud conectado

En esta página, se explica cómo usar los paquetes de flotas del Sincronizador de configuración en tu entorno de Google Distributed Cloud conectado, versión 1.12.0. Los paquetes de flota son una herramienta que usa un repositorio de Git como la única fuente de información para la configuración de tu clúster.

Los paquetes de flotas en Distributed Cloud Connected usan la misma tecnología y los mismos comandos subyacentes que los clústeres estándar de Google Kubernetes Engine. En la documentación de GKE, se explica cómo crear y administrar paquetes de flotas en la página Implementa paquetes de flotas. En esta página, se explica cómo adaptar esa guía a tu entorno conectado de Distributed Cloud.

En las siguientes secciones, se explica qué debes hacer de manera diferente para Distributed Cloud Connected y qué pasos de la documentación de GKE puedes seguir sin cambios.

Requisitos

El uso de paquetes de flota de Sincronizador de configuración en Distributed Cloud Connected tiene los siguientes requisitos:

• Debido a que el controlador de lanzamiento reside en la nube, se debe poder acceder a tu repositorio de Git a través de Internet pública. No se admiten servidores Git internos o locales que no estén expuestos públicamente.
• Distributed Cloud Connected solo admite el uso de la federación de identidades para cargas de trabajo de la flota para autenticarse con los servicios de Google Cloud . No se admiten otros métodos de autenticación del Sincronizador de configuración, como las claves SSH o las cookies, para la conexión entre tus clústeres y el repositorio de paquetes versionados. Para obtener más información, consulta Autenticación de clústeres con Workload Identity.
• Todos los clústeres de una flota deben estar en el mismo proyecto. Distributed Cloud Connected no admite el registro de clústeres en varios proyectos en un solo proyecto central para la administración de flotas.
• Tus manifiestos de Kubernetes deben cumplir con las limitaciones de las cargas de trabajo conectadas de Distributed Cloud. El controlador de admisión del clúster bloquea los manifiestos que incumplen estas restricciones.
• Los paquetes de flota requieren la versión 1.16.0 o posterior del Sincronizador de configuración.

Comportamiento del sistema

Los paquetes de flotas en Distributed Cloud Connected tienen los siguientes comportamientos:

• Los paquetes de flota transforman tus manifiestos de Kubernetes en imágenes OCI versionadas. Estas imágenes se almacenan en un repositorio administrado de Artifact Registry llamado fleet-packages, que se crea automáticamente en tu proyecto. Tus clústeres extraen estas imágenes directamente del repositorio para garantizar una entrega coherente y confiable.
• Los paquetes de flota heredan el comportamiento de corrección de desviación del Sincronizador de configuración. Los cambios manuales realizados en los recursos de un clúster se reemplazan automáticamente para que coincidan con los paquetes de OCI versionados.
• Si un clúster conectado de Distributed Cloud entra en el modo de supervivencia, el agente del Sincronizador de configuración sigue aplicando la última configuración sincronizada correctamente de forma local. Sin embargo, los lanzamientos o las actualizaciones nuevos del paquete de la flota se pausarán hasta que se restablezca la conectividad a la nube.
• Los paquetes de flota heredan el comportamiento de eliminación automática de recursos del Sincronizador de configuración. Cuando creas una etiqueta nueva en tu repositorio de Git y actualizas la configuración del paquete de la flota con la etiqueta nueva para iniciar una sincronización, el agente del Sincronizador de configuración borra el recurso correspondiente de tu clúster si quitas un manifiesto de tu repositorio de Git.
• Si varios paquetes de la flota administran el mismo recurso, se produce un conflicto de propiedad. Si intentas borrar un paquete de flota mientras se encuentra en un conflicto de propiedad, es posible que la eliminación se detenga. Para resolver este problema, modifica uno de los paquetes de la flota en competencia para quitar el recurso en conflicto antes de intentar borrar el paquete.

Requisitos previos de Distributed Cloud conectado

Antes de seguir los pasos que se indican en Implementa paquetes de flota, asegúrate de que tu entorno conectado de Distributed Cloud y los permisos de usuario estén configurados correctamente.

Herramientas de redes y seguridad

Tu entorno de red debe cumplir con los siguientes requisitos:

• Controles del servicio de VPC. Si tu proyecto está protegido por un perímetro de servicio de VPC, asegúrate de que tus agentes de servicio de Cloud Build y Config Delivery, por ejemplo, [e-mail], estén autorizados para cruzar el perímetro y extraer imágenes de Artifact Registry. Para obtener más información, consulta Configura la integración de los Controles del servicio de VPC.
• Acceso de salida. Tus clústeres conectados de Distributed Cloud deben tener acceso de salida a us-central1-docker.pkg.dev. Los paquetes de flota almacenan tus paquetes de manifiesto como imágenes OCI en Artifact Registry. Los clústeres deben poder extraer estas imágenes directamente de Artifact Registry.

Configuración del repositorio

El repositorio de Artifact Registry que contiene los paquetes del manifiesto debe estar en el mismo proyecto que el paquete de la flota y debe ubicarse en us-central1.

Permisos necesarios

Para completar los pasos en el entorno conectado de Distributed Cloud, debes tener los siguientes roles de IAM en el proyecto:

• Administrador de Config Delivery (roles/configdelivery.admin): Se requiere para crear y administrar paquetes y lanzamientos de flotas.
• Administrador de Developer Connect (roles/developerconnect.admin): Se requiere para crear y administrar conexiones de repositorios.
• Administrador de IAM de proyecto (roles/resourcemanager.projectIamAdmin): Se requiere para otorgar los roles necesarios a la cuenta de servicio.

Para obtener más información sobre cómo otorgar roles, consulta Otorga, cambia y revoca el acceso a los recursos.

APIs requeridas

Debes habilitar las APIs para las conexiones de repositorios y la comunicación segura con los clústeres conectados de Distributed Cloud. Para habilitar las APIs requeridas, ejecuta el siguiente comando gcloud services enable:

gcloud services enable anthosconfigmanagement.googleapis.com \
    configdelivery.googleapis.com \
    cloudbuild.googleapis.com \
    connectgateway.googleapis.com \
    developerconnect.googleapis.com \
    artifactregistry.googleapis.com

Estas APIs son necesarias para los siguientes componentes:

• anthosconfigmanagement.googleapis.com: Administra el agente del Sincronizador de configuración en tus clústeres.
• configdelivery.googleapis.com: Coordina el lanzamiento de recursos de Kubernetes en tu flota de clústeres.
• cloudbuild.googleapis.com: Recupera tus manifiestos de Kubernetes de Git y los empaqueta en paquetes versionados.
• connectgateway.googleapis.com: Proporciona una conexión segura entre el servicio de Config Delivery y tus clústeres conectados de Distributed Cloud.
• developerconnect.googleapis.com: Permite conexiones seguras al host de tu repositorio externo de Git
• artifactregistry.googleapis.com: Almacena los paquetes versionados como imágenes OCI en tu proyecto.

Configuración predeterminada del entorno

La API de Config Delivery para paquetes de flota solo se admite en us-central1. Para asegurarte de que tus comandos se enruten correctamente, usa el comando gcloud config set para configurar tu proyecto y ubicación predeterminados:

1. Configura el proyecto predeterminado:

   gcloud config set project PROJECT_ID
   

   Reemplaza PROJECT_ID por el ID del proyecto de Google Cloud .

2. Establece la ubicación predeterminada de los paquetes de la flota. Todas las conexiones de repositorios de Cloud Build que se usen con paquetes de flota deben estar en la región us-central1.

   gcloud config set config_delivery/location us-central1
   

Diferencias de procedimiento

Usa la siguiente tabla para comprender cómo aplicar los pasos en Implementa paquetes de flotas a tu entorno conectado de Distributed Cloud.

Paso estándar	Ajuste de Distributed Cloud conectado
Registra clústeres en una flota	Omitir este paso Los clústeres conectados de Distributed Cloud se registran automáticamente en una flota de tu proyecto cuando se crean.
Instala Config Sync	Sigue los pasos estándar, pero te recomendamos que uses el método Instalar en toda la flota (predeterminado de la flota). Configura este método en los parámetros de configuración de Hub o Fleet en la consola de Google Cloud . Esta implementación garantiza que todos los nodos conectados de Distributed Cloud existentes o futuros en tu zona reciban automáticamente el agente de Sincronizador de configuración. Para el tipo de miembro de autenticación, debes seleccionar Workload Identity. La cuenta de servicio que usas para Workload Identity debe tener el rol de roles/artifactregistry.reader en el proyecto para que el agente de Sincronizador de configuración pueda extraer paquetes de manifiestos del repositorio fleet-packages administrado.
Crear una cuenta de servicio	Sigue las instrucciones para crear una cuenta de servicio para Cloud Build y otorgar los permisos necesarios. La cuenta de servicio debe estar en el mismo proyecto que tu paquete de flota. Te recomendamos que uses los siguientes comandos: Para crear la cuenta de servicio, ejecuta el comando gcloud iam service-accounts create: gcloud iam service-accounts create "SERVICE_ACCOUNT_NAME" Reemplaza SERVICE_ACCOUNT_NAME por un nombre para la cuenta de servicio. Agrega los roles obligatorios de Identity and Access Management ejecutando el comando gcloud projects add-iam-policy-binding para cada uno de los siguientes roles. Para obtener más información sobre IAM, consulta la descripción general de IAM. roles/configdelivery.resourceBundlePublisher: Permite que la cuenta de servicio cree y administre paquetes de recursos y versiones. roles/cloudbuild.connectionUser: Permite que la cuenta de servicio use la conexión del repositorio de Cloud Build. roles/logging.logWriter: Permite que la cuenta de servicio escriba registros de compilación. roles/artifactregistry.writer: Permite que la cuenta de servicio envíe paquetes versionados a Artifact Registry. roles/developerconnect.connectionUser: Permite que la cuenta de servicio use la conexión de Developer Connect. La cuenta de servicio también necesita permiso para leer desde tu repositorio de Git conectado en tu proveedor de Git. Para obtener información sobre cómo autorizar la conexión, consulta Conéctate a un repositorio.
Identifica el nombre de la membresía	Cuando un comando solicite un MEMBERSHIP_NAME, usa el nombre de tu clúster conectado de Distributed Cloud. Puedes encontrar el nombre del clúster ejecutando el comando gcloud container fleet memberships list.
Cómo identificar un clúster	Antes de segmentar un clúster con un paquete de flota, si tus cargas de trabajo requieren configuración de redes a nivel del host, como HugePages o SR-IOV, aplica y verifica los recursos de NodeSystemConfigUpdate en cada nodo del clúster.
Cómo identificar etiquetas de Git	El controlador de lanzamiento requiere que las etiquetas de Git tengan un formato de versión semántica completo (major.minor.patch). Por ejemplo, v1.0.0 es válido, mientras que v1 no lo es.
Segmenta anuncios para clústeres específicos	Aunque los clústeres se registran automáticamente, debes agregar etiquetas de forma manual a las membresías de los clústeres si deseas segmentar subconjuntos de clústeres con selectores de etiquetas.
Estrategias de implementación	Usa etiquetas y variantes para segmentar clústeres específicos. En el caso de Distributed Cloud Connected, las variables de metadatos de membresía, como el proyecto y la ubicación, que se usan en tus plantillas de variantes hacen referencia a los recursos del lado de la nube asociados con tu clúster conectado a Distributed Cloud. Los siguientes metadatos de membresía específicos de Distributed Cloud están disponibles para su uso en plantillas de variantes: cluster_name: Es el nombre de tu clúster conectado de Distributed Cloud. location: Es la Google Cloud región asociada con el clúster. project: Es el ID del proyecto en el que se registró el clúster. labels: Cualquier etiqueta que hayas aplicado a la membresía del clúster

Procedimientos compartidos

Para las siguientes tareas operativas, la sintaxis del comando y el comportamiento del servicio son los mismos para GKE estándar y conectado a Distributed Cloud. Cuando sigas estas instrucciones, usa la configuración y los valores definidos en la tabla de la sección Diferencias de procedimiento de este documento.

• Crea un paquete de flota: Define el recurso FleetPackage para recuperar e implementar tu configuración.
• Actualiza un paquete de flota: Modifica tu paquete para lanzar cambios o actualizar la configuración.
• Administra los lanzamientos de paquetes de la flota: Suspende, reanuda o aborta los lanzamientos activos.
• Inspecciona los paquetes de recursos y las versiones: Depura la generación y el control de versiones de variantes. Los paquetes de recursos son contenedores para tus configuraciones, y las versiones son instancias con versiones de esos paquetes. Para verificar que la entrega se haya realizado correctamente en tu hardware de Distributed Cloud conectado, usa el comando gcloud container fleet memberships get-credentials para obtener acceso a tu clúster y, luego, usa kubectl para inspeccionar el estado de RootSync en el clúster.
• Borra un paquete de flota: Quita un paquete de flota y sus recursos administrados. Para garantizar una eliminación limpia, verifica que los objetos RootSync administrados asociados con el paquete de la flota se hayan quitado de tus clústeres.

Supervisa y soluciona problemas

Para supervisar las implementaciones de manera más eficaz, usa la marca --format con el comando gcloud para obtener mensajes de estado detallados durante un lanzamiento.

Por ejemplo, ejecuta el siguiente comando gcloud container fleet packages rollouts describe para ver un mensaje de estado detallado de cada clúster de tu flota:

gcloud container fleet packages rollouts describe ROLLOUT_NAME \
    --fleet-package=FLEET_PACKAGE_NAME \
    --format=json

Reemplaza los siguientes valores:

• ROLLOUT_NAME: Es el nombre del lanzamiento.
• FLEET_PACKAGE_NAME: Es el nombre del paquete de la flota.

Si una compilación falla o se detiene, puedes encontrar un vínculo a los registros de transmisión del trabajo de Cloud Build en el resultado del comando gcloud container fleet packages list. Si una versión permanece en estado PENDING o STALLED, verifica la conectividad del hardware de Distributed Cloud conectado, como se describe en Soluciona problemas de Distributed Cloud conectado.

Para obtener más información sobre el diagnóstico de errores relacionados con Cloud Build, consulta Soluciona errores de compilación.

Verifica el estado de la sincronización en el clúster

Para verificar que tu clúster se sincronice correctamente con el paquete de la flota, examina el recurso RootSync en el clúster. El nombre del objeto RootSync en el clúster es idéntico al FLEET_PACKAGE_NAME que elegiste para tu paquete.

Para verificar el estado, ejecuta el siguiente comando:

kubectl get rootsync FLEET_PACKAGE_NAME -n config-management-system

Si la sincronización se realiza correctamente, se muestra el estado SYNCED. Si ves el estado Error, ejecuta el siguiente comando para obtener más detalles:

kubectl describe rootsync FLEET_PACKAGE_NAME -n config-management-system

Para obtener más información, consulta Supervisa los objetos RootSync y RepoSync en la documentación de GKE.

Para obtener ayuda para decodificar códigos de error específicos en el resultado, consulta la referencia de errores del Sincronizador de configuración.