En esta página, se explica cómo usar los paquetes de flota del Sincronizador de configuración en tu entorno de Google Distributed Cloud conectado. 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 flota en Distributed Cloud conectado 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 flota en la página Implementa paquetes de flota. En esta página, se explica cómo adaptar esa guía para tu entorno de Distributed Cloud conectado.
En las siguientes secciones, se explica qué debes hacer de manera diferente para Distributed Cloud conectado y qué pasos de la documentación de GKE puedes seguir sin cambios.
Requisitos
El uso de paquetes de flota del Sincronizador de configuración en Distributed Cloud conectado 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 de Git internos o locales que no estén expuestos de forma pública.
- Distributed Cloud conectado solo admite el uso de la flota Federación de identidades para cargas de trabajo para autenticarse con Google Cloud servicios. No se admiten otros métodos de autenticación del Sincronizador de configuración, como las llaves SSH o las cookies, para la conexión entre tus clústeres y el repositorio de paquetes con versiones. Para obtener más información, consulta Autenticación de clústeres de Workload Identity.
- Todos los clústeres de una flota deben estar en el mismo proyecto. Distributed Cloud conectado no admite el registro de clústeres en varios proyectos en un solo proyecto central para la administración de la flota.
- Tus manifiestos de Kubernetes deben cumplir con las limitaciones de carga de trabajo de Distributed Cloud conectado. El controlador de admisión de clústeres bloquea los manifiestos que infringen estas restricciones.
- Los paquetes de flota requieren la versión 1.16.0 del Sincronizador de configuración o una posterior.
Comportamiento del sistema
Los paquetes de flota en Distributed Cloud conectado tienen los siguientes comportamientos:
- Los paquetes de flota transforman tus manifiestos de Kubernetes en imágenes OCI con versiones. 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 desvío 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 OCI con versiones.
- Si un clúster de Distributed Cloud conectado ingresa al modo de capacidad de supervivencia, el agente del Sincronizador de configuración continúa aplicando la última configuración sincronizada correctamente de forma local. Sin embargo, se pausan los lanzamientos o las actualizaciones nuevas del paquete de flota 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 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 flota administran el mismo recurso, se produce un conflicto de propiedad. Si intentas borrar un paquete de flota mientras está en un conflicto de propiedad, es posible que la eliminación se detenga. Para resolver este problema, modifica uno de los paquetes de flota en conflicto para quitar el recurso en conflicto antes de intentar borrar el paquete.
Requisitos previos de Distributed Cloud conectado
Antes de seguir los pasos en Implementa paquetes de flota, asegúrate de que tu entorno de Distributed Cloud conectado 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,
service-PROJECT_NUMBER@gcp-sa-configdelivery.iam.gserviceaccount.com, 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 de Distributed Cloud conectado 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 tus paquetes de manifiesto debe estar en el mismo proyecto que el paquete de flota y debe ubicarse en us-central1.
Permisos necesarios
Para completar los pasos en el entorno de Distributed Cloud conectado, debes tener los siguientes roles de IAM en el proyecto:
- Administrador de Config Delivery (
roles/configdelivery.admin): Es necesario para crear y administrar paquetes de flota y lanzamientos. - Administrador de Developer Connect (
roles/developerconnect.admin): Es necesario para crear y administrar conexiones de repositorios. - Administrador de IAM de proyecto (
roles/resourcemanager.projectIamAdmin): Es necesario 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 de Distributed Cloud conectado. Para habilitar las APIs requeridas, ejecuta
el siguiente
gcloud services enable
comando:
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 con versiones.connectgateway.googleapis.com: Proporciona una conexión segura entre el servicio de Config Delivery y tus clústeres de Distributed Cloud conectado.developerconnect.googleapis.com: Permite conexiones seguras a tu host de repositorio de Git externo.artifactregistry.googleapis.com: Almacena los paquetes con versiones como imágenes OCI en tu proyecto.
Configuración predeterminada del entorno
La API de Config Delivery para paquetes de flota solo es compatible con us-central1. Para asegurarte de que tus comandos se enruten correctamente, usa el
gcloud config set comando para establecer tu
proyecto y ubicación predeterminados:
Configura el proyecto predeterminado:
gcloud config set project PROJECT_ID
Reemplaza
PROJECT_IDpor el ID del proyecto. Google CloudEstablece la ubicación predeterminada para los paquetes de flota. Todas las conexiones de repositorios de Cloud Build que se usan 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 flota a tu entorno de Distributed Cloud conectado.
| Paso estándar | Ajuste de Distributed Cloud conectado |
|---|---|
| Registra clústeres en una flota | Omite este paso. Los clústeres de Distributed Cloud conectado se registran automáticamente en una flota de tu proyecto cuando se crean. |
| Instala Sincronizador de configuración | Sigue los pasos estándar, pero te recomendamos que uses el
Install on entire fleet (fleet default) método. Configura este
método en los parámetros de configuración de Hub o Fleet en la Google Cloud consola.
Esta implementación garantiza que cualquier nodo de Distributed Cloud conectado existente o futuro
en tu zona reciba automáticamente
el agente del 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 roles/artifactregistry.reader en el proyecto
para que el agente del Sincronizador de configuración pueda extraer paquetes de manifiesto del
repositorio administrado fleet-packages. |
| Crea 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 el paquete de flota. Te recomendamos
que uses los siguientes comandos:
|
| Identifica el nombre de la membresía | Cuando un comando solicite un MEMBERSHIP_NAME, usa el
nombre de tu clúster de Distributed Cloud conectado. Puedes
encontrar el nombre del clúster ejecutando el
gcloud container fleet memberships list
comando. |
| Identifica un clúster | Antes de segmentar un clúster con un paquete de flota, si tus cargas de trabajo
requieren una configuración de red a nivel del host, como HugePages o SR-IOV,
aplica y verifica los
NodeSystemConfigUpdate
recursos en cada nodo del clúster.
|
| Identifica etiquetas de Git | El controlador de lanzamiento requiere que las etiquetas de Git estén en 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 clústeres específicos | Aunque los clústeres se registran automáticamente, debes agregar etiquetas de forma manual a las membresías del clúster 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. Para
Distributed Cloud conectado, 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 de Distributed Cloud
conectado. Los siguientes metadatos de membresía específicos de Distributed Cloud están disponibles para su uso en plantillas de variantes:
|
Procedimientos compartidos
Para las siguientes tareas operativas, la sintaxis del comando y el comportamiento del servicio son los mismos para Distributed Cloud conectado y GKE estándar. 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
FleetPackagepara recuperar e implementar tu configuración. - Actualiza un paquete de flota: Modifica tu paquete para implementar cambios o actualizar la configuración.
- Administra lanzamientos de paquetes de flota: Suspende, reanuda o anula los lanzamientos activos.
- Inspecciona paquetes de recursos y 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 la entrega correcta a tu
hardware de Distributed Cloud conectado, usa el
gcloud container fleet memberships get-credentialscomando para obtener acceso a tu clúster, y, luego, usakubectlpara inspeccionar el estadoRootSyncen 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
RootSyncadministrados asociados con el paquete de flota se quiten 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
gcloud container fleet packages rollouts describe
comando para ver un mensaje de estado detallado para 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: El nombre del lanzamiento.FLEET_PACKAGE_NAME: El nombre del paquete de flota.
Si una compilación falla o se bloquea, puedes encontrar un vínculo a los registros de transmisión
del trabajo de Cloud Build en el resultado del
gcloud container fleet packages list
comando. Si un lanzamiento permanece en un estado PENDING o STALLED, verifica la conectividad de 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 problemas de errores de compilación.
Verifica el estado de sincronización en el clúster
Para verificar que tu clúster se sincronice correctamente con el paquete de 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
Una sincronización correcta muestra un estado SYNCED. Si ves un estado Error, para obtener más detalles, ejecuta el siguiente comando:
kubectl describe rootsync FLEET_PACKAGE_NAME -n config-management-system
Para obtener más información, consulta Supervisa los objetos RepoSync y RootSync 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.