Instalar el Sincronizador de configuración

Con el Sincronizador de configuración, puedes administrar recursos de Kubernetes con archivos de configuración almacenados en una fuente de confianza. El Sincronizador de configuración admite repositorios de Git, imágenes de OCI y gráficos de Helm como fuente de información. En esta página, se muestra cómo habilitar y configurar el Sincronizador de configuración para que se sincronice desde tu repositorio raíz. El Sincronizador de configuración está disponible con la edición Google Kubernetes Engine (GKE) Enterprise.

Cuando instalas el Sincronizador de configuración con la consola de Google Cloud o Google Cloud CLI, las APIs de RootSync y RepoSync están habilitadas de forma predeterminada. Este operador te proporciona funciones adicionales, como la sincronización de varios repositorios y la sincronización de configuraciones de Kustomize y Helm.

Antes de comenzar

Antes de instalar el Sincronizador de configuración, prepara tu entorno, asegúrate de cumplir con los requisitos del clúster y otorgar los roles de usuario adecuados.

Prepara el entorno local

Completa las siguientes tareas para preparar tu entorno local:

  1. Crea una fuente de información fiable o asegúrate de tener acceso a ella. Aquí es donde agregas los parámetros de configuración que se sincronizan con el Sincronizador de configuración. Para obtener más información sobre cómo establecer los parámetros de configuración y la fuente de información, consulta una de las siguientes guías:
  2. Instala e inicializa Google Cloud CLI, que proporciona los comandos gcloud y nomos. Si usas Cloud Shell, Google Cloud CLI viene preinstalada. Si instalaste Google Cloud CLI con anterioridad, ejecuta gcloud components update para obtener la versión más reciente.

  3. Habilita la API de GKE Enterprise.

    Habilita la API de GKE Enterprise

Requisitos del clúster

Crear un clúster que cumpla con los siguientes requisitos o tener acceso a él:

  • El clúster está en una plataforma y versión compatibles de Google Kubernetes Engine (GKE) Enterprise.

  • Si usas clústeres de Autopilot, Autopilot ajusta los requisitos de los recursos del contenedor para cumplir con las siguientes reglas:

    Debido a estas reglas, para los clústeres de Autopilot, el Sincronizador de configuración realiza las siguientes acciones:

  • El clúster tiene habilitada la función Workload Identity si usas clústeres de GKE. Workload Identity es la forma recomendada de acceder a los servicios de Google Cloud desde aplicaciones que se ejecutan dentro de GKE debido a sus propiedades de seguridad y capacidad de administración mejoradas. Los clústeres de Autopilot tienen Workload Identity habilitada de forma predeterminada.

  • Otorga los permisos de escritura de métricas correctos para que el Sincronizador de configuración pueda enviar métricas a Cloud Monitoring. Este paso es obligatorio si deseas usar las actualizaciones automáticas.

  • Si deseas actualizar automáticamente la versión del Sincronizador de configuración, asegúrate de que tu clúster de GKE esté inscrito en un canal de versiones. Un clúster que no usa canales de versiones de GKE se trata como un clúster que usa el canal de versiones estable.

  • Si deseas usar un clúster de GKE privado, configura Cloud NAT para permitir la salida desde nodos de GKE privados. Para obtener más detalles, consulta Ejemplo de configuración de GKE. Como alternativa, puedes habilitar el Acceso privado a Google para conectarte al conjunto de direcciones IP externas que usan los servicios y las API de Google.

  • Si deseas usar una cuenta de servicio de Google cuando le otorgas acceso al Sincronizador de configuración a tu fuente de información, debes incluir el permiso de solo lectura en los permisos de acceso de los nodos del clúster para Cloud Source Repositories.

    Puedes agregar el permiso de solo lectura si incluyes cloud-source-repos-ro en la lista --scopes especificada en el momento de la creación del clúster o si usas el permiso cloud-platform en el momento de la creación del clúster. Por ejemplo:

    gcloud container clusters create CLUSTER_NAME --scopes=cloud-platform

    No puedes modificar los permisos de acceso luego de crear un grupo de nodos. Sin embargo, puedes crear un grupo de nodos nuevo con el permiso de acceso adecuado mientras usas el mismo clúster. El permiso gke-default predeterminado no incluye cloud-source-repos-ro.

  • Si tienes requisitos estrictos de firewall de VPC que bloquean el tráfico innecesario, debes crear reglas de firewall que permitan el siguiente tráfico en clústeres de GKE públicos:

    • TCP: Permite la entrada y la salida en los puertos 53 y 443.

    • UDP: Permite la salida en el puerto 53.

    Si no incluyes estas reglas, el Sincronizador de configuración no se sincroniza de forma correcta y nomos status informa el siguiente error:

    Error: KNV2004: unable to sync repo Error in the git-sync container

    Puedes omitir estos pasos si usas un clúster de GKE privado.

  • Debes ejecutar el Sincronizador de configuración en un grupo de nodos amd64. Las imágenes de contenedor del componente de backend del Sincronizador de configuración solo se compilan, distribuyen y prueban para la arquitectura de máquina de amd64. Si un componente del Sincronizador de configuración está programado en un nodo ARM, experimenta el error exec format y falla.

    Si tienes nodos ARM en tu clúster, agrega uno o más nodos amd64 al clúster y, si no usas un clúster de GKE, agrega un taint a tus nodos arm64 para evitar programar Pods en tus nodos arm64 sin tolerancia específica. Los nodos del grupo de GKE ya tienen un taint predeterminado, por lo que no necesitas agregar uno.

Prepara tu clúster

Después de crear un clúster adecuado, completa los siguientes pasos:

  1. Otorga las funciones de IAM necesarias al usuario que registra el clúster.

  2. Si planeas usar Google Cloud CLI para configurar el Sincronizador de configuración o usar clústeres fuera de Google Cloud, asegúrate de que tus clústeres de GKE o los clústeres fuera de Google Cloud estén registrados ahora en una flota. Si planeas usar la consola de Google Cloud, puedes registrar clústeres de GKE cuando configures el Sincronizador de configuración.

Instalar el Sincronizador de configuración

En las siguientes secciones, otorgas acceso al Sincronizador de configuración a una de las siguientes fuentes de información:

Después de otorgar el acceso, puedes configurar el Sincronizador de configuración.

Otorga acceso a Git

El Sincronizador de configuración necesita acceso de solo lectura a tu repositorio de Git para que pueda leer las configuraciones confirmadas en el repositorio y aplicarlas a tus clústeres.

Si el repositorio no requiere autenticación para el acceso de solo lectura, puedes continuar con la configuración del Sincronizador de configuración y usar none como el tipo de autenticación. Por ejemplo, si puedes explorar el repositorio con una interfaz web sin acceder, o si puedes usar git clone para crear un clon del repositorio de forma local sin proporcionar credenciales ni usar credenciales guardadas, no es necesario que realices la autenticación. En este caso, no necesitas crear un Secret.

Sin embargo, la mayoría de los usuarios deben crear credenciales porque el acceso de lectura a su repositorio está restringido. Si se requieren credenciales, se almacenan en el Secret git-creds en cada clúster inscrito (a menos que uses una cuenta de servicio de Google). El Secret debe llamarse git-creds, ya que este es un valor fijo.

El Sincronizador de configuración admite los siguientes mecanismos de autenticación:

  • Par de claves SSH (ssh)
  • Archivo cookie (cookiefile)
  • Token (token)
  • Cuenta de servicio de Google (gcpserviceaccount)
  • Cuenta de servicio predeterminada de Compute Engine (gcenode)

El mecanismo que elijas dependerá de lo que admita tu repositorio. Por lo general, recomendamos usar un par de claves SSH. GitHub y Bitbucket son compatibles con un par de claves SSH. Sin embargo, si usas un repositorio en Cloud Source Repositories, te recomendamos que uses una cuenta de servicio de Google, ya que el proceso es más simple. Si tu organización aloja tu repositorio y no sabes qué métodos de autenticación se admiten, comunícate con tu administrador.

Si deseas usar un repositorio en Cloud Source Repositories como repositorio del Sincronizador de configuración, completa los siguientes pasos para recuperar la URL de Cloud Source Repositories:

  1. Enumera todos los repositorios:

    gcloud source repos list

  2. Copia la URL del repositorio que deseas usar desde el resultado: Por ejemplo:

    REPO_NAME  PROJECT_ID  URL
my-repo    my-project  https://source.developers.google.com/p/my-project/r/my-repo-csr

    Debes usar esta URL cuando configures el Sincronizador de configuración en la siguiente sección. Si configuras el Sincronizador de configuración con la consola de Google Cloud, agrega la URL en el campo URL. Si configuras el Sincronizador de configuración con Google Cloud CLI, debes agregar la URL al campo syncRepo del archivo de configuración.

Par de claves SSH

Un par de claves SSH consta de dos archivos, una clave pública y una clave privada. Por lo general, la clave pública tiene una extensión .pub.

Para usar un par de claves SSH, completa los siguientes pasos:

  1. Crea un par de claves SSH para permitir que el Sincronizador de configuración se autentique en tu repositorio de Git. Este paso es necesario si necesitas autenticarte en el repositorio para clonarlo o leer de él. Omite este paso si un administrador de seguridad te proporciona un par de claves. Puedes usar un solo par de claves para todos los clústeres o un par de claves por clúster, según tus requisitos de seguridad y cumplimiento.

    El siguiente comando crea una clave RSA de 4096 bits. No se recomiendan valores más bajos:

    ssh-keygen -t rsa -b 4096 \
-C "GIT_REPOSITORY_USERNAME" \
-N '' \
-f /path/to/KEYPAIR_FILENAME

    Reemplaza lo siguiente:

    • GIT_REPOSITORY_USERNAME: El nombre de usuario que deseas que el Sincronizador de configuración use para autenticarse en el repositorio.
    • /path/to/KEYPAIR_FILENAME: Una ruta de acceso al par de claves.

    Si usas un host del repositorio de Git de terceros, como GitHub, o deseas usar una cuenta de servicio con Cloud Source Repositories, te recomendamos que uses una cuenta distinta.

  2. Configura el repositorio para que reconozca la clave pública que acabas de crear. Consulta la documentación de tu proveedor de hosting de Git. Se incluyen instrucciones para algunos proveedores de hosting de Git populares para mayor comodidad:

  3. Agrega la clave privada a un Secret nuevo del clúster:

    kubectl create ns config-management-system && \
kubectl create secret generic git-creds \
 --namespace=config-management-system \
 --from-file=ssh=/path/to/KEYPAIR_PRIVATE_KEY_FILENAME

    Reemplaza /path/to/KEYPAIR_PRIVATE_KEY_FILENAME por el nombre de la clave privada (la que no tiene el sufijo .pub).

  4. Recomendado: Para configurar la verificación de hosts conocidos con la autenticación SSH, puedes agregar la clave de hosts conocidos al campo data.known_hosts en el secreto git_creds. Para inhabilitar la verificación de known_hosts, puedes quitar el campo known_hosts del secreto. Para agregar la clave de hosts conocidos, ejecuta el siguiente comando:

    kubectl edit secret git-creds \
 --namespace=config-management-system

    Luego, en data, agrega la entrada de hosts conocidos:

    known_hosts: KNOWN_HOSTS_KEY

  5. Borra la clave privada del disco local o protégela.

  6. Cuando configures el Sincronizador de configuración y agregues la URL de tu repositorio de Git, usa el protocolo SSH. Si usas un repositorio en Cloud Source Repositories, debes usar el siguiente formato cuando ingreses tu URL:

    ssh://EMAIL@source.developers.google.com:2022/p/PROJECT_ID/r/REPO_NAME

    Reemplaza lo siguiente:

    • EMAIL: Tu nombre de usuario de Google Cloud
    • PROJECT_ID: El ID del proyecto de Google Cloud en el que se encuentra el repositorio
    • REPO_NAME: Es el nombre del repositorio

Archivo cookie

El proceso de adquisición de un cookiefile depende de la configuración del repositorio. Para ver un ejemplo, consulta Genera credenciales estáticas en la documentación de Cloud Source Repositories. Por lo general, las credenciales se almacenan en el archivo .gitcookies en el directorio de tu página principal, o las puede proporcionar un administrador de seguridad.

Para usar un cookiefile, completa los siguientes pasos:

  1. Después de crear y obtener el cookiefile, agrégalo a un Secret nuevo en el clúster.

    Si no usas el proxy HTTPS, crea el Secret con el siguiente comando:

    kubectl create ns config-management-system && \
kubectl create secret generic git-creds \
 --namespace=config-management-system \
 --from-file=cookie_file=/path/to/COOKIEFILE

    Si necesitas usar un proxy HTTPS, agrégalo al Secret junto con cookiefile mediante la ejecución del siguiente comando:

    kubectl create ns config-management-system && \
kubectl create secret generic git-creds \
 --namespace=config-management-system \
 --from-file=cookie_file=/path/to/COOKIEFILE \
 --from-literal=https_proxy=HTTPS_PROXY_URL

    Reemplaza lo siguiente:

    • /path/to/COOKIEFILE: La ruta de acceso y el nombre de archivo adecuados
    • HTTPS_PROXY_URL: La URL del proxy HTTPS que usas cuando te comunicas con el repositorio de Git

  2. Protege el contenido de cookiefile, si aún lo necesitas usar de forma local. De lo contrario, bórralo.

Token

Si tu organización no permite el uso de claves SSH, se recomienda usar un token. Con el Sincronizador de configuración, puedes usar tokens de acceso personales (PAT) de GitHub, PAT o claves de implementación de GiLab, o la contraseña de la aplicación de Bitbucket como token.

Para crear un Secret con tu token, completa estos pasos:

  1. Crea un token mediante GitHub, GitLab, o Bitbucket.

  2. Después de crear y obtener el token, agrégalo a un Secreto nuevo en el clúster.

    Si no usas el proxy HTTPS, crea el Secret con el siguiente comando:

    kubectl create ns config-management-system && \
kubectl create secret generic git-creds \
  --namespace="config-management-system" \
  --from-literal=username=USERNAME \
  --from-literal=token=TOKEN

    Reemplaza lo siguiente:

    • USERNAME: El nombre de usuario que deseas usar
    • TOKEN: El token que creaste en el paso anterior

    Si necesitas usar un proxy HTTPS, agrégalo al Secret junto con username y token mediante la ejecución del siguiente comando:

    kubectl create ns config-management-system && \
kubectl create secret generic git-creds \
 --namespace=config-management-system \
 --from-literal=username=USERNAME \
  --from-literal=token=TOKEN \
 --from-literal=https_proxy=HTTPS_PROXY_URL

    Reemplaza lo siguiente:

    • USERNAME: El nombre de usuario que deseas usar
    • TOKEN: El token que creaste en el paso anterior
    • HTTPS_PROXY_URL: La URL del proxy HTTPS que usas cuando te comunicas con el repositorio de Git

  3. Protege el token si lo necesitas de forma local. De lo contrario, bórralo.

Cuenta de servicio de Google

Si tu repositorio se encuentra en Cloud Source Repositories y tu clúster usa Workload Identity de GKE o Fleet Workload Identity, puedes otorgar al Sincronizador de configuración acceso a un repositorio en el mismo proyecto que tu clúster administrado mediante una cuenta de servicio de Google.

  1. Si aún no tienes una cuenta de servicio, crea una.

  2. Otorga la función de IAM de lector de Cloud Source Repositories (roles/source.reader) a la cuenta de servicio de Google. Si deseas obtener más información sobre las funciones y los permisos de Cloud Source Repositories, consulta Otorga permisos para ver los repositorios.

    • Otorga permiso para todo el proyecto si se aplican los mismos permisos a todos los repositorios del proyecto.

      gcloud projects add-iam-policy-binding PROJECT_ID \
  --role=roles/source.reader \
  --member="serviceAccount:GSA_NAME@PROJECT_ID.iam.gserviceaccount.com"

    • Otorga permisos específicos del repositorio cuando desees que las cuentas de servicio tengan diferentes niveles de acceso para cada repositorio de tu proyecto.

      gcloud source repos set-iam-policy REPOSITORY POLICY_FILE --project=PROJECT_ID

  3. Si configuras el Sincronizador de configuración con la consola de Google Cloud, selecciona Workload Identity como el Tipo de autenticación y, luego, agrega el correo electrónico de la cuenta de servicio.

    Si configuras el Sincronizador de configuración con Google Cloud CLI, agrega gcpserviceaccount como secretType y, luego, agrega el correo electrónico de tu cuenta de servicio a gcpServiceAccountEmail.

  4. Después de configurar el Sincronizador de configuración, crea una vinculación de política de IAM entre la cuenta de servicio de Kubernetes y la cuenta de servicio de Google. La cuenta de servicio de Kubernetes no se creará hasta que configures el Sincronizador de configuración por primera vez.

    Si usas clústeres que están registrados en una flota, solo tienes que crear la vinculación de política una vez por flota. Todos los clústeres registrados en una flota comparten el mismo Workload Identitypool. Con el concepto de similitud de la flota, si agregas la política de IAM a tu cuenta de servicio de Kubernetes en un clúster, la cuenta de servicio de Kubernetes del mismo espacio de nombres en otros clústeres de la misma flota también obtendrá la misma política de IAM.

    Esta vinculación permite que la cuenta de servicio del Sincronizador de configuración de Kubernetes funcione como la cuenta de servicio de Google:

    gcloud iam service-accounts add-iam-policy-binding \
    GSA_NAME@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/iam.workloadIdentityUser \
    --member="serviceAccount:FLEET_HOST_PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]" \
    --project=PROJECT_ID

Reemplaza lo siguiente:

  • PROJECT_ID: El ID del proyecto de la organización
  • FLEET_HOST_PROJECT_ID: Si usas Workload Identity de GKE, es lo mismo que PROJECT_ID. Si usas Workload Identity de la flota, este es el ID del proyecto de la flota en la que está registrado el clúster.
  • GSA_NAME: La cuenta de servicio de Google personalizada que deseas usar para conectarte a Artifact Registry. La cuenta de servicio debe tener el rol de IAM de lector de Artifact Registry (roles/artifactregistry.reader).
  • KSA_NAME: Es la cuenta de servicio de Kubernetes para el conciliador.
    • Para los repositorios raíz, si el nombre de RootSync es root-sync, usa root-reconciler. De lo contrario, usa root-reconciler-ROOT_SYNC_NAME. Si instalas el Sincronizador de configuración con la consola de Google Cloud o Google Cloud CLI, el Sincronizador de configuración crea automáticamente un objeto RootSync llamado root-sync.
  • REPOSITORY: Es el nombre del repositorio.
  • POLICY_FILE: Es el archivo JSON o YAML con la política de Identity and Access Management.

Cuenta de servicio predeterminada de Compute Engine

Si tu repositorio se encuentra en Cloud Source Repositories y tu clúster es GKE en Google Cloud con Workload Identity inhabilitada, puedes usar gcenode como el tipo de autenticación.

Si configuras el Sincronizador de configuración con la consola de Google Cloud, selecciona Google Cloud Repository como el Tipo de autenticación.

Si configuras el Sincronizador de configuración con Google Cloud CLI, agrega gcenode como secretType.

Si seleccionas Google Cloud Repository o gcenode, puedes usar la cuenta de servicio predeterminada de Compute Engine. Debes otorgar la función de IAM de lector de Cloud Source Repositories (roles/source.reader) a la cuenta de servicio predeterminada de Compute Engine. Si deseas obtener más información sobre las funciones y los permisos de Cloud Source Repositories, consulta Otorga permisos para ver los repositorios.

gcloud projects add-iam-policy-binding PROJECT_ID \
  --role=roles/source.reader \
  --member="serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com"

Reemplaza PROJECT_ID por el ID del proyecto de tu organización y PROJECT_NUMBER por el número del proyecto de tu organización.

Otorgar al Sincronizador de configuración acceso de solo lectura a la OCI

El Sincronizador de configuración necesita acceso de solo lectura a tu imagen OCI almacenada en Artifact Registry para que pueda leer los archivos de configuración incluidos en la imagen y aplicarlos a tus clústeres.

Si la imagen no requiere autenticación para el acceso de solo lectura, puedes continuar con la configuración del Sincronizador de configuración y usar none como el tipo de autenticación. Por ejemplo, si tu imagen es pública y cualquier persona puede acceder a ella desde Internet, no necesitas autenticarte.

Sin embargo, la mayoría de los usuarios deben crear credenciales para acceder a imágenes restringidas. El Sincronizador de configuración admite los siguientes mecanismos de autenticación:

  • Cuenta de servicio de Kubernetes (k8sserviceaccount)
  • Cuenta de servicio de Google (gcpserviceaccount)

  • Cuenta de servicio predeterminada de Compute Engine (gcenode)

Cuenta de servicio de Kubernetes

Si almacenas tu imagen OCI en Artifact Registry y tu clúster usa Workload Identity de GKE o Fleet Workload Identity, puedes usar k8sserviceaccount como tipo de autenticación en la versión 1.17.2 y versiones posteriores. Esta opción se recomienda en lugar de gcpserviceaccount debido a su proceso de configuración simplificado.

  1. Otorga el rol de IAM de lector de Artifact Registry (roles/artifactregistry.reader) a la cuenta de servicio de Kubernetes con el grupo de Workload Identity. Para obtener más información sobre los roles y permisos de Artifact Registry, consulta Configura roles y permisos para Artifact Registry.

    • Otorga permiso para todo el proyecto si se aplican los mismos permisos a todos los repositorios del proyecto.

      gcloud projects add-iam-policy-binding PROJECT_ID \
      --role=roles/artifactregistry.reader \
      --member="serviceAccount:FLEET_HOST_PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]"

    • Otorga permisos específicos del repositorio cuando desees que las cuentas de servicio tengan diferentes niveles de acceso para cada repositorio de tu proyecto.

      gcloud artifacts repositories add-iam-policy-binding REPOSITORY \
   --location=LOCATION \
   --role=roles/artifactregistry.reader \
   --member="serviceAccount:FLEET_HOST_PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]" \
   --project=PROJECT_ID

    Reemplaza lo siguiente:

    • PROJECT_ID: El ID del proyecto de la organización
    • FLEET_HOST_PROJECT_ID: Si usas Workload Identity de GKE, es lo mismo que PROJECT_ID. Si usas Workload Identity de la flota, este es el ID del proyecto de la flota en la que está registrado el clúster.
    • KSA_NAME: Es la cuenta de servicio de Kubernetes para el conciliador.
      • Para los repositorios raíz, si el nombre de RootSync es root-sync, usa root-reconciler. De lo contrario, usa root-reconciler-ROOT_SYNC_NAME. Si instalas el Sincronizador de configuración con la consola de Google Cloud o Google Cloud CLI, el Sincronizador de configuración crea automáticamente un objeto RootSync llamado root-sync.
    • REPOSITORY: El ID del repositorio
    • LOCATION: Es la ubicación regional o multirregional del repositorio.

Cuenta de servicio de Google

Si almacenas tu imagen OCI en Artifact Registry y tu clúster usa Workload Identity de GKE o Fleet Workload Identity, puedes usar gcpserviceaccount como tipo de autenticación. A partir de la versión 1.17.2, se recomienda usar k8sserviceaccount en su lugar. Esta opción elimina los pasos adicionales para crear una cuenta de servicio de Google y la vinculación de política de IAM asociada.

  1. Si aún no tienes una cuenta de servicio, crea una.

  2. Otorga el rol de IAM de lector de Artifact Registry (roles/artifactregistry.reader) a la cuenta de servicio de Google. Para obtener más información sobre los roles y permisos de Artifact Registry, consulta Configura roles y permisos para Artifact Registry.

    • Otorga permiso para todo el proyecto si se aplican los mismos permisos a todos los repositorios del proyecto.

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

    • Otorga permisos específicos del repositorio cuando desees que las cuentas de servicio tengan diferentes niveles de acceso para cada repositorio de tu proyecto.

      gcloud artifacts repositories add-iam-policy-binding REPOSITORY \
   --location=LOCATION \
   --role=roles/artifactregistry.reader \
   --member="serviceAccount:GSA_NAME@PROJECT_ID.iam.gserviceaccount.com" \
   --project=PROJECT_ID

  3. Para crear una vinculación de políticas de IAM entra la cuenta de servicio de Kubernetes y la cuenta de servicio de Google, ejecutando el siguiente comando:

    gcloud iam service-accounts add-iam-policy-binding
  GSA_NAME@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/iam.workloadIdentityUser \
    --member="serviceAccount:FLEET_HOST_PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]" \
    --project=PROJECT_ID

Reemplaza lo siguiente:

  • PROJECT_ID: El ID del proyecto de la organización
  • FLEET_HOST_PROJECT_ID: Si usas Workload Identity de GKE, es lo mismo que PROJECT_ID. Si usas Workload Identity de la flota, este es el ID del proyecto de la flota en la que está registrado el clúster.
  • GSA_NAME: La cuenta de servicio de Google personalizada que deseas usar para conectarte a Artifact Registry. La cuenta de servicio debe tener el rol de IAM de lector de Artifact Registry (roles/artifactregistry.reader).
  • KSA_NAME: Es la cuenta de servicio de Kubernetes para el conciliador.
    • Para los repositorios raíz, si el nombre de RootSync es root-sync, usa root-reconciler. De lo contrario, usa root-reconciler-ROOT_SYNC_NAME. Si instalas el Sincronizador de configuración con la consola de Google Cloud o Google Cloud CLI, el Sincronizador de configuración crea automáticamente un objeto RootSync llamado root-sync.
  • REPOSITORY: El ID del repositorio
  • LOCATION: Es la ubicación regional o multirregional del repositorio.

Cuenta de servicio predeterminada de Compute Engine

Si almacenas tu gráfico de Helm en Artifact Registry y tu clúster es GKE en Google Cloud con Workload Identity inhabilitada, puedes usar gcenode como tu tipo de autenticación. El Sincronizador de configuración usa la cuenta de servicio predeterminada de Compute Engine. Debes otorgar a tu cuenta de servicio predeterminada de Compute Engine acceso de lectura a Artifact Registry.

  1. Para otorgar permiso de lectura a la cuenta de servicio de Compute Engine a Artifact Registry, ejecuta el siguiente comando:

    gcloud projects add-iam-policy-binding PROJECT_ID \
   --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
   --role=roles/artifactregistry.reader

    Reemplaza PROJECT_ID por el ID del proyecto de tu organización y PROJECT_NUMBER por el número del proyecto de tu organización.

Otorga acceso de solo lectura al Sincronizador de configuración a Helm.

El Sincronizador de configuración necesita acceso de solo lectura a tu repositorio de Helm para poder leer los gráficos de Helm en tu repositorio y, luego, instalarlos en tus clústeres.

Si el repositorio no requiere autenticación para el acceso de solo lectura, puedes continuar con la configuración del Sincronizador de configuración y usar none como tipo de autenticación. Por ejemplo, si tu repositorio de Helm es público y cualquier persona puede acceder a él desde Internet, no es necesario que te autentiques.

Sin embargo, la mayoría de los usuarios necesita crear credenciales para acceder a los repositorios privados de Helm. El Sincronizador de configuración admite los siguientes mecanismos de autenticación:

  • Token (token)
  • Cuenta de servicio de Kubernetes (k8sserviceaccount)
  • Cuenta de servicio de Google (gcpserviceaccount)
  • Cuenta de servicio predeterminada de Compute Engine (gcenode)

Token

Crea un Secret con un nombre de usuario y una contraseña del repositorio de Helm:

kubectl create secret generic SECRET_NAME \
    --namespace=config-management-system \
    --from-literal=username=USERNAME \
    --from-literal=password=PASSWORD

Reemplaza lo siguiente:

  • SECRET_NAME: Es el nombre que deseas darle a tu secreto.
  • USERNAME: Es el nombre de usuario del repositorio de Helm.
  • PASSWORD: Es la contraseña del repositorio de Helm.

Cuando configures el operador de ConfigManagement, usarás el nombre del Secret que elegiste para spec.helm.secretRef.name.

Cuenta de servicio de Kubernetes

Si almacenas tu gráfico de Helm en Artifact Registry y tu clúster usa Workload Identity de GKE o Fleet Workload Identity, puedes usar k8sserviceaccount como tipo de autenticación en la versión 1.17.2 y versiones posteriores. Esta opción se recomienda en lugar de gcpserviceaccount debido a su proceso de configuración simplificado.

  1. Otorga el rol de IAM de lector de Artifact Registry (roles/artifactregistry.reader) a la cuenta de servicio de Kubernetes con el grupo de Workload Identity. Para obtener más información sobre los roles y permisos de Artifact Registry, consulta Configura roles y permisos para Artifact Registry.

    • Otorga permiso para todo el proyecto si se aplican los mismos permisos a todos los repositorios del proyecto.

      gcloud projects add-iam-policy-binding PROJECT_ID \
   --role=roles/artifactregistry.reader \
   --member="serviceAccount:FLEET_HOST_PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]"

    • Otorga permisos específicos del repositorio cuando desees que las cuentas de servicio tengan diferentes niveles de acceso para cada repositorio de tu proyecto.

      gcloud artifacts repositories add-iam-policy-binding REPOSITORY \
   --location=LOCATION \
   --role=roles/artifactregistry.reader \
   --member="serviceAccount:FLEET_HOST_PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]" \
   --project=PROJECT_ID

    Reemplaza lo siguiente:

    • PROJECT_ID: El ID del proyecto de la organización
    • FLEET_HOST_PROJECT_ID: Si usas Workload Identity de GKE, es lo mismo que PROJECT_ID. Si usas Workload Identity de la flota, este es el ID del proyecto de la flota en la que está registrado el clúster.
    • KSA_NAME: Es la cuenta de servicio de Kubernetes para el conciliador.
      • Para los repositorios raíz, si el nombre de RootSync es root-sync, usa root-reconciler. De lo contrario, usa root-reconciler-ROOT_SYNC_NAME.
    • REPOSITORY: El ID del repositorio
    • LOCATION: Es la ubicación regional o multirregional del repositorio.

Cuenta de servicio de Google

Si almacenas tu gráfico de Helm en Artifact Registry y tu clúster usa Workload Identity de GKE o Fleet Workload Identity, puedes usar gcpserviceaccount como tipo de autenticación. A partir de la versión 1.17.2, se recomienda usar k8sserviceaccount en su lugar. Esta opción elimina los pasos adicionales para crear una cuenta de servicio de Google y la vinculación de política de IAM asociada.

  1. Si aún no tienes una cuenta de servicio, crea una.

  2. Otorga el rol de IAM de lector de Artifact Registry (roles/artifactregistry.reader) a la cuenta de servicio de Google. Para obtener más información sobre los roles y permisos de Artifact Registry, consulta Configura roles y permisos para Artifact Registry.

    • Otorga permiso para todo el proyecto si se aplican los mismos permisos a todos los repositorios del proyecto.

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

    • Otorga permisos específicos del repositorio cuando desees que las cuentas de servicio tengan diferentes niveles de acceso para cada repositorio de tu proyecto.

      gcloud artifacts repositories add-iam-policy-binding REPOSITORY \
   --location=LOCATION \
   --role=roles/artifactregistry.reader \
   --member="serviceAccount:GSA_NAME@PROJECT_ID.iam.gserviceaccount.com" \
   --project=PROJECT_ID

  3. Para crear una vinculación de políticas de IAM entra la cuenta de servicio de Kubernetes y la cuenta de servicio de Google, ejecutando el siguiente comando:

    gcloud iam service-accounts add-iam-policy-binding
  GSA_NAME@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/iam.workloadIdentityUser \
    --member="serviceAccount:FLEET_HOST_PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]"
    --project=PROJECT_ID

Reemplaza lo siguiente:

  • PROJECT_ID: El ID del proyecto de la organización
  • FLEET_HOST_PROJECT_ID: Si usas Workload Identity de GKE, es lo mismo que PROJECT_ID. Si usas Workload Identity de la flota, este es el ID del proyecto de la flota en la que está registrado el clúster.
  • GSA_NAME: La cuenta de servicio de Google personalizada que deseas usar para conectarte a Artifact Registry. La cuenta de servicio debe tener el rol de IAM de lector de Artifact Registry (roles/artifactregistry.reader).
  • KSA_NAME: Es la cuenta de servicio de Kubernetes para el conciliador.
    • Para los repositorios raíz, si el nombre de RootSync es root-sync, usa root-reconciler. De lo contrario, usa root-reconciler-ROOT_SYNC_NAME.
  • REPOSITORY: El ID del repositorio
  • LOCATION: Es la ubicación regional o multirregional del repositorio.

Cuenta de servicio predeterminada de Compute Engine

Si almacenas tu gráfico de Helm en Artifact Registry y tu clúster es GKE en Google Cloud con Workload Identity inhabilitada, puedes usar gcenode como tu tipo de autenticación. El Sincronizador de configuración usa la cuenta de servicio predeterminada de Compute Engine. Debes otorgar a tu cuenta de servicio predeterminada de Compute Engine acceso de lectura a Artifact Registry. Es posible que debas otorgar el permiso de acceso storage-ro para otorgar permiso de solo lectura para extraer imágenes.

  1. Otorga permiso de lectura a la cuenta de servicio de Compute Engine a Artifact Registry:

    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/artifactregistry.reader

    Reemplaza PROJECT_ID por el ID del proyecto de tu organización y PROJECT_NUMBER por el número del proyecto de tu organización.

Configura Sincronizador de configuración

En esta sección, definirás la configuración de tu repositorio raíz. Si deseas sincronizar con un repositorio de Git, puedes usar la consola de Google Cloud para que te guíe a través del proceso de instalación y automatice algunos pasos.

Cuando instalas el Sincronizador de configuración con la consola de Google Cloud o Google Cloud CLI, el Sincronizador de configuración crea automáticamente un objeto RootSync llamado root-sync. Puedes usar los comandos de kubectl para modificar root-sync y agregar configuraciones del Sincronizador de configuración adicionales. Para obtener más información, consulta Configura el Sincronizador de configuración con los comandos de kubectl.

Console

Instalar el Sincronizador de configuración

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

  1. En la consola de Google Cloud, ve a la página Configuración en la sección Funciones.

    Ir a Configuración

  2. Haz clic en Instalar el Sincronizador de configuración.
  3. Selecciona Actualizaciones automáticas (Vista previa) para permitir que el Sincronizador de configuración actualice las versiones automáticamente o selecciona Actualizaciones manuales para administrar la versión del Sincronizador de configuración por tu cuenta. Para obtener más información sobre cómo funcionan las actualizaciones automáticas, consulta Actualiza el Sincronizador de configuración.
  4. En Opciones de instalación, selecciona una de las siguientes opciones:
    • Instalar el Sincronizador de configuración en toda la flota (recomendado): El Sincronizador de configuración se instalará en todos los clústeres de la flota.
    • Instala el Sincronizador de configuración en clústeres individuales: Todos los clústeres seleccionados se registrarán automáticamente en una flota. Se instalará el Sincronizador de configuración en todos los clústeres de la flota.
  5. Si instalas el Sincronizador de configuración en clústeres individuales, en la tabla Clústeres disponibles, selecciona los clústeres en los que deseas instalar el Sincronizador de configuración.
  6. 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 de los clústeres de tu flota.

Implementa un paquete

Después de registrar los clústeres, puedes implementar un paquete de una fuente de confianza en el clúster del Sincronizador de configuración. Puedes implementar un paquete en más de un clúster a la vez y agregar varios paquetes a un solo clúster.

Para implementar un paquete, completa los siguientes pasos:

  1. En la consola de Google Cloud, ve al panel del Sincronizador de configuración.

    Ir al panel del Sincronizador de configuración

  2. Haz clic en Implementar paquete.

  3. En la tabla Selecciona clústeres para la implementación de paquetes, selecciona el clúster en el que deseas implementar un paquete y, luego, haz clic en Continuar.

  4. Selecciona Paquete alojado en Git o Paquete alojado en OCI como tu tipo de fuente y, luego, haz clic en Continuar.

  5. En la sección Package details, ingresa un Package name, que identifique el objeto RootSync o RepoSync.

  6. En la sección Fuente, completa lo siguiente:

    • Para las fuentes alojadas en un repositorio de Git, ingresa los siguientes campos:

      1. Ingresa un Package name para identificar el objeto RootSync o RepoSync.
      2. Ingresa la URL del repositorio de Git que usas como fuente de información como la URL del repositorio.
      3. Opcional: Actualiza el campo Revisión para verificar si no usas el HEAD predeterminado.
      4. Opcional: Actualiza el campo Path si no deseas realizar la sincronización desde el repositorio raíz.
      5. Actualiza el campo Rama si no usas la rama main predeterminada (opcional).

    • Para las fuentes alojadas en una imagen OCI, ingresa los siguientes campos:

      1. Ingresa la URL de la imagen de OCI que usas como fuente de información como la imagen.
      2. Ingresa la ruta de acceso del directorio desde el que deseas sincronizar, en relación con el directorio raíz, como Directory.

  7. En el campo Tipo de sincronización, elige RootSync o RepoSync como el tipo de sincronización.

    Los objetos RootSync tienen alcance de clúster y los objetos RepoSync tienen alcance de espacio de nombres. Para obtener más información sobre estos objetos, consulta los campos RootSync y RepoSync.

  8. (Opcional): Expande la sección Configuración avanzada para completar las siguientes acciones:

    1. Selecciona un tipo de autenticación:

      • Ninguna: No usa autenticación.
      • SSH: Usa un par de claves SSH.
      • Cookiefile: Usa un cookiefile.
      • Token: Usa un token.
      • Google Cloud Repository: Usa una cuenta de servicio de Google para acceder a un Cloud Source Repositories. Selecciona esta opción solo si Workload Identity no está habilitado en el clúster.
      • Workload Identity: Usa una cuenta de servicio de Google para acceder a un repositorio de Cloud Source Repositories.

    2. Ingresa un número en segundos para configurar el tiempo de espera de la sincronización, que determina cuánto tiempo espera el Sincronizador de configuración entre la sincronización de la fuente de información.

    3. Ingresa una URL de proxy de Git para que el proxy HTTPS se use cuando se comunique con la fuente de información.

    4. Elige Jerarquía para cambiar el Formato de origen.

      En la mayoría de los casos, se recomienda el valor predeterminado No estructurado, ya que te permite organizar tu fuente de información de la manera que desees.

  9. Haz clic en Implementar paquete.

    Se te redireccionará a la página Paquetes del Sincronizador de configuración. Después de unos minutos, deberías ver Sincronizado en la columna Estado de sincronización del clúster que configuraste.

  10. Para actualizar un paquete, en la pestaña Packages, expande el nombre del paquete que deseas editar y, luego, haz clic en Edit.

gcloud

Antes de continuar, asegúrate de registrar tus clústeres en una flota.

  1. Habilita la función de flota ConfigManagement:

    gcloud beta container fleet config-management enable

  2. Para preparar la configuración, crea un nuevo manifiesto apply-spec.yaml o usa un manifiesto existente. El uso de un manifiesto existente te permite configurar tu clúster con la misma configuración que usa otro clúster.

    Crear manifiesto nuevo

    A fin de configurar el Sincronizador de configuración con la configuración nueva para tu clúster, crea un archivo llamado apply-spec.yaml y copia el siguiente archivo YAML en él.

    Puedes establecer todos los campos opcionales spec.configSync que necesitarás cuando crees el manifiesto y, luego, usar los comandos de kubectl para la configuración. Además, solo puedes establecer el campo spec.configSync.enabled como true y omitir los campos opcionales. Luego, puedes usar comandos de kubectl para crear objetos RootSync adicionales o RepoSync que puedes administrar por completo con los comandos de kubectl más adelante.

    # apply-spec.yaml

applySpecVersion: 1
spec:
  upgrades: UPGRADE_SETTING
  configSync:
    # Set to true to install and enable Config Sync
    enabled: true
    # If you don't have a source of truth yet, omit the
    # following fields. You can configure them later.
    sourceType: SOURCE_TYPE
    sourceFormat: FORMAT
    syncRepo: REPO
    syncRev: REVISION
    syncBranch: BRANCH
    secretType: SECRET_TYPE
    gcpServiceAccountEmail: EMAIL
    metricsGcpServiceAccountEmail: METRICS_EMAIL
    policyDir: DIRECTORY
    preventDrift: PREVENT_DRIFT

    Reemplaza lo siguiente:

    • (Vista previa) UPGRADE_SETTING: Configúralo en auto para configurar el Sincronizador de configuración para que se actualice automáticamente. Configúralo en manual para actualizar el Sincronizador de configuración de forma manual. El valor predeterminado es manual. Esta marca solo es compatible con los clústeres de GKE en Google Cloud.

    • SOURCE_TYPE: Agrega git para sincronizar desde un repositorio de Git, oci para sincronizar desde una imagen OCI o helm para sincronizar desde un gráfico de Helm. Si no se especifica ningún valor, el valor predeterminado es git.

    • FORMAT: agrega unstructured para usar un repositorio no estructurado o agrega hierarchy a fin de usar un repositorio jerárquico. Estos valores distinguen entre mayúsculas y minúsculas. Este campo es opcional y el valor predeterminado es hierarchy. Te recomendamos que agregues unstructured, ya que este formato te permite organizar la configuración de la manera que te resulte más conveniente.

    • REPO: Agrega la URL de la fuente de confianza. Las URLs del repositorio de Git y Helm usan el protocolo HTTPS o SSH. Por ejemplo, https://github.com/GoogleCloudPlatform/anthos-config-management-samples. Si planeas usar SSH como secretType, ingresa tu URL con el protocolo SSH. Este campo es obligatorio y, si no ingresas un protocolo, la URL se tratará como una URL HTTPS.

      Las URLs de OCI usan el siguiente formato: LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/PACKAGE_NAME. De forma predeterminada, la imagen se extrae de la etiqueta latest, pero puedes extraerlas mediante TAG o DIGEST. Especifica TAG o DIGEST en PACKAGE_NAME:

      • Para extraer antes del TAG: LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/PACKAGE_NAME:TAG
      • Para extraer antes del DIGEST: LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/PACKAGE_NAME@sha256:DIGEST

    • REVISION: Es la revisión de Git (etiqueta o hash) desde la que se sincroniza. Este campo es opcional, y el valor predeterminado es HEAD. A partir de la versión 1.17.0 del Sincronizador de configuración, también puedes especificar un nombre de rama en el campo syncRev. Cuando se usa un hash en la versión 1.17.0 o posterior, debe ser un hash completo y no una forma abreviada.

    • BRANCH: La rama del repositorio desde la que se realiza la sincronización. Este campo es opcional y el valor predeterminado es master. A partir de la versión 1.17.0 del Sincronizador de configuración, se recomienda usar el campo syncRev para especificar un nombre de rama para mayor simplicidad. Si se especifican los campos syncRev y syncBranch, syncRev tiene prioridad sobre syncBranch.

    • SECRET_TYPE: Uno de los siguientes secretTypes:

      git

      • none: No usa autenticación
      • ssh: Usa un par de claves SSH
      • cookiefile: Usa un objeto cookiefile
      • token: Usa un token
      • gcpserviceaccount: Usa una cuenta de servicio de Google para acceder a Cloud Source Repositories. Si seleccionas este tipo de autenticación, debes crear una vinculación de política de IAM después de que termines de configurar el Sincronizador de configuración. Para obtener más detalles, consulta la pestaña Cuenta de servicio de Google de la sección Otorga acceso de solo lectura al Sincronizador de configuración a Git.
      • gcenode: Usa una cuenta de servicio de Google para acceder a Cloud Source Repositories. Selecciona esta opción solo si Workload Identity no está habilitado en tu clúster.

      Para obtener más información sobre estos tipos de autenticación, consulta Otorga a Git acceso de solo lectura al Sincronizador de configuración.

      OCI

      • none: No usa autenticación
      • gcenode: Usa la cuenta de servicio predeterminada de Compute Engine para acceder a una imagen en Artifact Registry. Selecciona esta opción solo si Workload Identity no está habilitado en el clúster.
      • gcpserviceaccount: Usa una cuenta de servicio de Google para acceder a una imagen.

      helm

      • token: Usa un token
      • gcenode: Usa la cuenta de servicio predeterminada de Compute Engine para acceder a una imagen en Artifact Registry. Selecciona esta opción solo si Workload Identity no está habilitado en el clúster.
      • gcpserviceaccount: Usa una cuenta de servicio de Google para acceder a una imagen.

    • EMAIL: Si agregaste gcpserviceaccount como secretType, agrega la dirección de correo electrónico de la cuenta de servicio de Google. Por ejemplo, acm@PROJECT_ID.iam.gserviceaccount.com

    • METRICS_EMAIL: Es el correo electrónico de la cuenta de servicio de Google Cloud (GSA) que se usó para exportar métricas del Sincronizador de configuración a Cloud Monitoring. GS debe tener la función de IAM de escritor de métricas de supervisión (roles/monitoring.metricWriter). La cuenta de servicio de Kubernetes default en el espacio de nombres config-management-monitoring debe estar vinculada a GSA.

    • DIRECTORY: ruta del directorio desde el que se realiza la sincronización en relación con la raíz del repositorio de Git. Se incluyen todos los subdirectorios del directorio que especificas y se sincronizan con el clúster. El valor predeterminado es el directorio raíz del repositorio.

    • PREVENT_DRIFT: Si se configura como true, habilita el webhook de admisión del Sincronizador de configuración para evitar los desvíos mediante el rechazo de cambios conflictivos que se envían a clústeres activos. La configuración predeterminada es false. El Sincronizador de configuración siempre soluciona los desvíos, sin importar el valor de este campo.

    Para obtener una lista completa de los campos que puedes agregar al campo spec, consulta Campos de gcloud.

    Usar el manifiesto existente

    Para configurar tu clúster con la misma configuración que usa otro clúster, recupera la configuración de un clúster registrado:

    gcloud alpha container fleet config-management fetch-for-apply \
    --membership=MEMBERSHIP_NAME \
    --project=PROJECT_ID \
    > CONFIG_YAML_PATH

    Reemplaza lo siguiente:

    • MEMBERSHIP_NAME: El nombre de la membresía del clúster registrado que tiene la configuración del Sincronizador de configuración que deseas usar
    • PROJECT_ID: el ID de tu proyecto
    • CONFIG_YAML_PATH: Es la ruta de acceso al archivo apply-spec.yaml que contiene la configuración recuperada del clúster.

  3. Aplica el archivo apply-spec.yaml. Si usas un manifiesto existente, debes aplicar el archivo al clúster que deseas configurar con la configuración que recuperaste en el comando anterior:

    gcloud beta container fleet config-management apply \
    --membership=MEMBERSHIP_NAME \
    --config=CONFIG_YAML_PATH \
    --project=PROJECT_ID

    Reemplaza lo siguiente:

    • MEMBERSHIP_NAME: Es el nombre de la membresía de la flota que elegiste cuando registraste el clúster. Puedes encontrar el nombre con gcloud container fleet memberships list.
    • CONFIG_YAML_PATH: La ruta de acceso a tu archivo apply-spec.yaml.
    • PROJECT_ID: Es el ID de tu proyecto.

Terraform

Para cada clúster en el que desees configurar el Sincronizador de configuración, aplica un bloque de recursos google_gkehub_feature_membership que contenga un bloque configmanagement y config_sync:

git

resource "google_container_cluster" "cluster" {
 name = EXISTING_CLUSTER_NAME
 location = "EXISTING_CLUSTER_LOCATION"
}

resource "google_gke_hub_membership" "membership" {
 membership_id = "MEMBERSHIP_ID"
 endpoint {
   gke_cluster {
     resource_link = "//container.googleapis.com/${google_container_cluster.cluster.id}"
   }
 }

resource "google_gke_hub_feature" "feature" {
  name = "configmanagement"
  location = "global"
  }
}

resource "google_gke_hub_feature_membership" "feature_member" {
 location = "global"
 feature = google_gke_hub_feature.feature.name
 membership = google_gke_hub_membership.membership.membership_id
 configmanagement {
   version = "VERSION"
   config_sync {
     git {
       sync_repo = "REPO"
       sync_branch = "BRANCH"
       policy_dir = "DIRECTORY"
       secret_type = "SECRET"
     }
   }
 }
}

Reemplaza lo siguiente:

  • EXISTING_CLUSTER_NAME: Es el nombre del clúster existente.
  • EXISTING_CLUSTER_LOCATION: Es la ubicación de tu clúster existente.
  • MEMBERSHIP_ID: Es el ID de vinculación de membresía.
  • VERSION: Es el número de versión del Sincronizador de configuración (opcional). Se debe configurar en la versión 1.17.0 o posterior. Si se deja en blanco, el valor predeterminado es la última versión.
  • REPO: Es la URL al repositorio que contiene los archivos de configuración.
  • BRANCH: Es la rama del repositorio, por ejemplo main.
  • DIRECTORY: Es la ruta de acceso dentro del repositorio de Git que representa el nivel superior del repositorio que deseas sincronizar.
  • SECRET: Es el tipo de autenticación del secreto.

OCI

resource "google_container_cluster" "cluster" {
 name = EXISTING_CLUSTER_NAME
 location = "EXISTING_CLUSTER_LOCATION"
}

resource "google_gke_hub_membership" "membership" {
 membership_id = "MEMBERSHIP_ID"
 endpoint {
   gke_cluster {
     resource_link = "//container.googleapis.com/${google_container_cluster.cluster.id}"
   }
 }

resource "google_gke_hub_feature" "feature" {
  name = "configmanagement"
  location = "global"
  }
}

resource "google_gke_hub_feature_membership" "feature_member" {
 location = "global"
 feature = google_gke_hub_feature.feature.name
 membership = google_gke_hub_membership.membership.membership_id
 configmanagement {
   version = "VERSION"
   config_sync {
     oci {
       sync_repo = "REPO"
       policy_dir = "DIRECTORY"
       secret_type = "SECRET"
     }
   }
 }
}

Reemplaza lo siguiente:

  • EXISTING_CLUSTER_NAME: Es el nombre del clúster existente.
  • EXISTING_CLUSTER_LOCATION: Es la ubicación de tu clúster existente.
  • MEMBERSHIP_ID: Es el ID de vinculación de membresía.
  • VERSION: Es el número de versión del Sincronizador de configuración (opcional). Si se deja en blanco, el valor predeterminado es la última versión.
  • REPO: Es la URL al repositorio de imágenes de OCI que contiene tus archivos de configuración.
  • DIRECTORY: Es la ruta de acceso absoluta del directorio que contiene los recursos que deseas sincronizar. Déjalo en blanco para usar el directorio raíz.
  • SECRET: Es el tipo de autenticación del secreto.

Repite este proceso para cada clúster que desees sincronizar.

Cuando termines de configurar el repositorio raíz, puedes elegir configurar la sincronización desde varios repositorios, incluidos otros repositorios raíz y de espacios de nombres. Los repositorios de espacio de nombres son útiles si deseas tener un repositorio que contenga archivos de configuración con alcance de espacio de nombres sincronizados con un espacio de nombres en particular en los clústeres.

Configura los valores predeterminados a nivel de la flota

Si habilitaste la edición Google Kubernetes Engine (GKE) Enterprise, puedes habilitar y configurar el Sincronizador de configuración como un valor predeterminado a nivel de la flota para tus clústeres. Esto significa que cada clúster nuevo de GKE en Google Cloud creado en la flota tendrá habilitado el Sincronizador de configuración en el clúster con la configuración que especifiques. Puedes obtener más información sobre la configuración predeterminada de la flota en Administra las funciones a nivel de la flota.

Si solo usas la consola de Google Cloud, puedes habilitar el Sincronizador de configuración de forma predeterminada en tus clústeres y establecer la versión del Sincronizador de configuración para tu flota. Si usas Terraform, puedes habilitar el Sincronizador de configuración de forma predeterminada en tus clústeres, establecer la versión del Sincronizador de configuración para tu flota y establecer la conexión a tu repositorio de Git o de imágenes de OCI.

Si deseas configurar los valores predeterminados a nivel de la flota para el Sincronizador de configuración, completa los siguientes pasos:

Console

  1. En la consola de Google Cloud, ve a la página Administrador de funciones.

    Ir a Administrador de funciones

  2. En el panel del Sincronizador de configuración, haz clic en Configurar.

  3. Revisa la configuración a nivel de la flota. Todos los clústeres nuevos que creas en la flota heredan esta configuración.

  4. Opcional: Para cambiar la configuración predeterminada, haz clic en Personalizar la configuración de la flota. En el cuadro de diálogo que aparece, haz lo siguiente:

  5. Selecciona Actualizaciones automáticas (Vista previa) para que las versiones de actualización del Sincronizador de configuración se actualicen automáticamente o selecciona Actualizaciones manuales para administrar la versión del Sincronizador de configuración por tu cuenta. Para obtener más información sobre cómo funcionan las actualizaciones automáticas, consulta Actualiza el Sincronizador de configuración.

  6. Si seleccionaste Actualizaciones manuales, en la lista Versión, selecciona la versión del Sincronizador de configuración que desees usar.

  7. Haz clic en Guardar cambios.

  8. Haz clic en Configurar.

  9. En el diálogo de confirmación Configuración de la flota, haz clic en Confirmar. Si no habilitaste el Sincronizador de configuración antes, hacer clic en Confirmar también habilita la API de anthosconfigmanagement.googleapis.com.

Terraform

  1. Crear un directorio para los archivos de Terraform de configuración predeterminados de la flota. A ese directorio, agrega un archivo main.tf con el siguiente recurso que establece la configuración del Sincronizador de configuración:

    git

    terraform {
  required_providers {
    google = {
      source = "hashicorp/google"
      version = ">=5.16.0"
      }
    }
  }

provider "google" {
  project = "PROJECT_ID"
}

resource "google_gke_hub_feature" "feature" {
  name = "configmanagement"
  location = "global"
  provider = google
  fleet_default_member_config {
    configmanagement {
    version = "VERSION"
    config_sync {
    source_format = "unstructured"
      git {
        sync_repo = "REPO"
        sync_branch = "BRANCH"
        policy_dir = "DIRECTORY"
        secret_type = "SECRET"
      }
    }
    }
  }
}

    Reemplaza lo siguiente:

    • PROJECT_ID: El ID del proyecto host de la flota.
    • VERSION: Es el número de versión del Sincronizador de configuración (opcional). Si se deja en blanco, el valor predeterminado es la última versión.
    • REPO: Es la URL al repositorio que contiene los archivos de configuración.
    • BRANCH: Es la rama del repositorio, por ejemplo main.
    • DIRECTORY: Es la ruta de acceso dentro del repositorio de Git que representa el nivel superior del repositorio que deseas sincronizar.
    • SECRET: Es el tipo de autenticación del secreto.

    Para obtener una lista completa de los parámetros de configuración compatibles con el bloque git del Sincronizador de configuración, consulta la documentación de referencia de Terraform para las funciones de GKE Hub.

    OCI

    terraform {
  required_providers {
    google = {
      source = "hashicorp/google"
      version = ">=5.16.0"
      }
    }
  }

provider "google" {
  project = "PROJECT_ID"
}

resource "google_gke_hub_feature" "feature" {
  name = "configmanagement"
  location = "global"
  provider = google
  fleet_default_member_config {
    configmanagement {
    version = "VERSION"
    config_sync {
    source_format = "unstructured"
      oci {
        sync_repo = "REPO"
        policy_dir = "DIRECTORY"
        secret_type = "SECRET"
      }
    }
    }
  }
}

    Reemplaza lo siguiente:

    • PROJECT_ID: El ID del proyecto host de la flota.
    • VERSION: Es el número de versión del Sincronizador de configuración. Se debe configurar en la versión 1.17.0 o posterior. Si se deja en blanco, el valor predeterminado es la última versión.
    • REPO: Es la URL al repositorio de imágenes de OCI que contiene los archivos de configuración.
    • DIRECTORY: Es la ruta de acceso absoluta del directorio que contiene los recursos que deseas sincronizar. Déjalo en blanco para usar el directorio raíz.
    • SECRET: Es el tipo de autenticación del secreto.

    Para obtener una lista completa de los parámetros de configuración compatibles con el bloque oci del Sincronizador de configuración, consulta la documentación de referencia de Terraform para las funciones de GKE Hub.

  2. Inicializa Terraform en el directorio que creaste:

    terraform init

  3. Verifica que los cambios que propones con Terraform coincidan con el plan esperado:

    terraform plan

  4. Crea las configuraciones predeterminadas de los miembros de la flota:

    terraform apply

Si tienes clústeres existentes que deseas actualizar para usar la configuración predeterminada del Sincronizador de configuración, usa la consola de Google Cloud para sincronizar los clústeres seleccionados de la flota con los valores predeterminados. Como alternativa, puedes configurar de forma manual cada clúster con la misma configuración mediante Terraform o gcloud CLI. Para ello, sigue las instrucciones para configurar el Sincronizador de configuración. Si antes usaste Terraform para especificar los valores predeterminados de la flota, usa los mismos bloques configmanagement y config_sync que usaste para establecer los valores predeterminados a fin de configurar los clústeres que elegiste.

Para sincronizar la configuración predeterminada del Sincronizador de configuración en tu flota, sigue estos pasos:

  1. Ve al Administrador de funciones:

    Ir a Feature Manager: Sincronizador de configuración

  2. En la tabla de clústeres, selecciona los clústeres que deseas sincronizar con la configuración de la flota.

  3. Haz clic en Sincronizar con la configuración de la flota.

La configuración predeterminada del Sincronizador de configuración se aplicará a cualquier clúster que selecciones. Aunque la consola de Google Cloud muestra solo un subconjunto de parámetros de configuración, como la versión del Sincronizador de configuración, toda la configuración a nivel de la flota se sincroniza con los clústeres. Por ejemplo, si configuras el Sincronizador de configuración para que se sincronice con un repositorio de Git mediante Terraform, ese parámetro de configuración se sincronizará con tus clústeres, pero no se mostrará en la consola de Google Cloud.

Verifique la instalación

Después de instalar y configurar el Sincronizador de configuración, puedes verificar que la instalación se haya completado correctamente.

Console

Completa los siguientes pasos:

  1. En la consola de Google Cloud, ve a la página Configuración en la sección Funciones.

    Ir a Configuración

  2. En la pestaña Paquetes, verifica la columna Estado de sincronización en la tabla de clústeres. Si la instalación del Sincronizador de configuración es exitosa, tiene el estado Installed. Una fuente de confianza configurada correctamente tiene el estado Sincronizada.

gcloud

Ejecuta el siguiente comando:

gcloud beta container fleet config-management status \
    --project=PROJECT_ID

Reemplaza PROJECT_ID por el ID del proyecto.

Si la instalación se realiza correctamente, tendrá el estado SYNCED. A partir de la versión 1.18.0 del Sincronizador de configuración, el resultado también muestra qué versión del Sincronizador de configuración está instalada y los parámetros de configuración de actualización del Sincronizador de configuración.

Si ves un error después de ejecutar el comando anterior, asegúrate de haber creado el Secret git-creds. Si creaste el Secret, vuelve a ejecutar el siguiente comando:

gcloud beta container fleet config-management apply

También puedes usar el comando nomos status para verificar si el Sincronizador de configuración se instaló correctamente. Una instalación válida sin problemas tiene el estado PENDING o SYNCED. Una instalación no válida o incompleta tiene el estado NOT INSTALLED o NOT CONFIGURED. La salida también incluye cualquier error informado.

Controles de acceso basados en roles (RBAC) y permisos

El controlador de políticas, el Sincronizador de configuración y el controlador de configuración incluyen cargas de trabajo con muchos privilegios. En la siguiente tabla, se enumeran los permisos para estas cargas de trabajo:

Componente Espacio de nombres Cuenta de servicio Permisos Descripción
Operador de ConfigManagement config-management-system config-management-operator cluster-admin El operador de ConfigManagement instala los otros componentes de esta tabla. Algunos de esos componentes requieren permisos de administrador de clúster, por lo que el operador de ConfigManagement también los requiere.
Sincronizador de configuración config-management-system Consulta los permisos del Sincronizador de configuración para conocer los permisos necesarios.

Solicitudes de recursos

En la siguiente sección, se enumeran las solicitudes de recursos del Sincronizador de configuración.

En la siguiente tabla, se enumeran los requisitos de los recursos de Kubernetes para los componentes del Sincronizador de configuración. Si deseas obtener más información, consulta Administra los recursos para contenedores en la documentación de Kubernetes.

No se crearon todos los componentes enumerados. Las siguientes condiciones hacen que se programe cada componente:

  • config-management-operator se instala cuando el Sincronizador de configuración está habilitado.
  • reconciler-manager se instala cuando el Sincronizador de configuración está habilitado.
  • admission-webhook se instala cuando la prevención de desvíos está habilitada.
  • Se instala un reconciler para cada RootSync y RepoSync.
  • otel-collector se instala cuando el Sincronizador de configuración está habilitado.

Para obtener más información sobre estos componentes, consulta Arquitectura del Sincronizador de configuración.

1.17

Nombre de la implementación Solicitud de CPU (m) por réplica Solicitud de memoria (Mi) por réplica
config-management-operator 100 100
resource-group-controller-manager 110 300
admission-webhook1 10 100
otel-collector 200 400
reconciler-manager 20 150
reconciler (uno por RootSync y RepoSync) Consulta Implementación del conciliador para obtener más detalles.

1 El webhook de admisión tiene dos réplicas, por lo que, cuando calculas el total de solicitudes de recursos, debes duplicar el valor si usas el webhook de admisión. El webhook de admisión está inhabilitado de forma predeterminada.

1.16

Nombre de la implementación Solicitud de CPU (m) por réplica Solicitud de memoria (Mi) por réplica
config-management-operator 100 100
resource-group-controller-manager 110 300
admission-webhook1 10 100
otel-collector 200 400
reconciler-manager 20 150
reconciler (uno por RootSync y RepoSync) Consulta Implementación del conciliador para obtener más detalles.

1 El webhook de admisión tiene dos réplicas, por lo que, cuando calculas el total de solicitudes de recursos, debes duplicar el valor si usas el webhook de admisión. El webhook de admisión está inhabilitado de forma predeterminada.

1.15

Nombre de la implementación Solicitud de CPU (m) por réplica Solicitud de memoria (Mi) por réplica
config-management-operator 100 100
resource-group-controller-manager 110 300
admission-webhook1 10 100
otel-collector 200 400
reconciler-manager 20 150
reconciler (uno por RootSync y RepoSync) Consulta Implementación del conciliador para obtener más detalles.

1 El webhook de admisión tiene dos réplicas, por lo que, cuando calculas el total de solicitudes de recursos, debes duplicar el valor si usas el webhook de admisión. El webhook de admisión está inhabilitado de forma predeterminada.

Implementación del conciliador

Para cada objeto RootSync y RepoSync, el Sincronizador de configuración crea una implementación de conciliador independiente para controlar la sincronización. La implementación del conciliador consta de varios contenedores. Para obtener más información sobre estos contenedores, consulta Contenedores de conciliador.

En la versión 1.17.0 y posteriores del Sincronizador de configuración, las solicitudes de recursos predeterminadas para los conciliadores son diferentes para los clústeres de Standard y Autopilot. Todos los demás tipos de clústeres usan los valores predeterminados.

Clústeres estándar

1.17

Nombre del contenedor Solicitud de CPU (m) Solicitud de memoria (Mi)
reconciler 50 200
otel-agent 10 100
hydration-controller (opcional) 10 100
git-sync 10 16
gcenode-askpass-sidecar (opcional) 10 20
helm-sync 75 128
oci-sync 25 32

1.16

Nombre del contenedor Solicitud de CPU (m) Solicitud de memoria (Mi)
reconciler 50 200
otel-agent 10 100
hydration-controller (opcional) 10 100
git-sync 10 200
gcenode-askpass-sidecar (opcional) 10 20
helm-sync 50 256
oci-sync 10 200

1.15

Nombre del contenedor Solicitud de CPU (m) Solicitud de memoria (Mi)
reconciler 50 200
otel-agent 10 100
hydration-controller (opcional) 10 100
git-sync 10 200
gcenode-askpass-sidecar (opcional) 10 20
helm-sync 50 256
oci-sync 10 200

Clústeres de Autopilot

1.17

Nombre del contenedor Solicitud y límite de CPU (m) Solicitud de memoria y límite (Mi)
reconciler 700 512
otel-agent 10 64
hydration-controller (opcional) 200 256
git-sync 20 32
gcenode-askpass-sidecar (opcional) 50 64
helm-sync 150 256
oci-sync 50 64

1.16

En las versiones del Sincronizador de configuración anteriores a la 1.17.0, las solicitudes de recursos son las mismas para Standard y Autopilot.

1.15

En las versiones del Sincronizador de configuración anteriores a la 1.17.0, las solicitudes de recursos son las mismas para Standard y Autopilot.

Para aprender a anular las solicitudes y los límites de recursos predeterminados, consulta Anulaciones de recursos.

Versiones de Helm y Kustomize en paquetes

El Sincronizador de configuración aprovecha los ejecutables de Helm y Kustomize para procesar las opciones de configuración internas. En la siguiente tabla, se proporciona una lista de las versiones del Sincronizador de configuración que admiten la función de procesamiento, junto con las versiones de Helm y Kustomize empaquetadas.

Versiones del Sincronizador de configuración Versión de Helm Versión de Kustomize
1.16.0 y posteriores v3.11.3 v5.1.1
1.15.0 a 1.15.3 v3.11.3 v5.0.1
1.11.0 a 1.14.3 v3.6.3 v4.5.2

Para obtener información sobre cómo renderizar Helm a través de Kustomize, consulta Cómo configurar Kubernetes con Kustomize. Para obtener información sobre el uso de la API de Helm, consulta Sincroniza gráficos de Helm desde Artifact Registry.

¿Qué sigue?