Sincroniza gráficos de Helm desde Artifact Registry

En esta página, se muestra cómo sincronizar gráficos de Helm desde Artifact Registry creando y enviando un gráfico de Helm a un repositorio en Artifact Registry. También contiene una configuración de muestra para sincronizar un gráfico desde tu repositorio de Helm.

Término clave: Helm es un administrador de paquetes para Kubernetes que te ayuda a definir, instalar y actualizar aplicaciones. El Sincronizador de configuración puede sincronizar gráficos de Helm directamente desde Artifact Registry con la API de Helm o renderizar gráficos de Helm especificados en las configuraciones de Kustomize.

Puedes configurar el Sincronizador de configuración para sincronizar desde repositorios de Helm. Puedes almacenar gráficos de Helm en Artifact Registry, que es el repositorio de Helm recomendado para Google Cloud. Para usar esta función, debes habilitar las API de RootSync y RepoSync. El Sincronizador de configuración renderiza gráficos de Helm con helm template y, por lo tanto, no admite la administración completa del ciclo de vida de Helm.

En Versiones de Helm y Kustomize en paquetes, se enumeran las versiones de Kustomize y Helm incluidas en la versión correspondiente del Sincronizador de configuración.

Antes de comenzar

Accede a tu cuenta de Google Cloud . Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.

Instala Google Cloud CLI.

Nota: Si ya instalaste gcloud CLI, ejecuta gcloud components update para asegurarte de tener la versión más reciente.

Si usas un proveedor de identidad externo (IdP), primero debes acceder a la gcloud CLI con tu identidad federada.

Para inicializar gcloud CLI, ejecuta el siguiente comando:

gcloud init

Crea o selecciona un Google Cloud proyecto.

Roles necesarios para seleccionar o crear un proyecto

• Selecciona un proyecto: Para seleccionar un proyecto, no se requiere un rol de IAM específico. Puedes seleccionar cualquier proyecto en el que se te haya otorgado un rol.
• Crear un proyecto: Para crear un proyecto, necesitas el rol de Creador de proyectos (roles/resourcemanager.projectCreator), que contiene el permiso resourcemanager.projects.create. Obtén más información para otorgar roles.

Nota: Si no planeas conservar los recursos que creaste durante este procedimiento, crea un proyecto en lugar de seleccionar uno existente. Cuando termines, puedes borrar el proyecto y quitar todos los recursos asociados con él.

• Crea un proyecto de Google Cloud :

  gcloud projects create PROJECT_ID

  Reemplaza PROJECT_ID por un nombre para el proyecto Google Cloud que estás creando.

• Selecciona el proyecto Google Cloud que creaste:

  gcloud config set project PROJECT_ID

  Reemplaza PROJECT_ID por el nombre de tu Google Cloud proyecto.

Verifica que la facturación esté habilitada para tu proyecto de Google Cloud .

Habilita las APIs de GKE, Sincronizador de configuración y Artifact Registry:

Roles necesarios para habilitar las APIs

Para habilitar las APIs, necesitas el rol de IAM de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin), que contiene el permiso serviceusage.services.enable. Obtén más información para otorgar roles.

gcloud services enable container.googleapis.com  anthosconfigmanagement.googleapis.com  artifactregistry.googleapis.com

Instala Google Cloud CLI.

Nota: Si ya instalaste gcloud CLI, ejecuta gcloud components update para asegurarte de tener la versión más reciente.

Si usas un proveedor de identidad externo (IdP), primero debes acceder a la gcloud CLI con tu identidad federada.

Para inicializar gcloud CLI, ejecuta el siguiente comando:

gcloud init

Crea o selecciona un Google Cloud proyecto.

Roles necesarios para seleccionar o crear un proyecto

• Selecciona un proyecto: Para seleccionar un proyecto, no se requiere un rol de IAM específico. Puedes seleccionar cualquier proyecto en el que se te haya otorgado un rol.
• Crear un proyecto: Para crear un proyecto, necesitas el rol de Creador de proyectos (roles/resourcemanager.projectCreator), que contiene el permiso resourcemanager.projects.create. Obtén más información para otorgar roles.

Nota: Si no planeas conservar los recursos que creaste durante este procedimiento, crea un proyecto en lugar de seleccionar uno existente. Cuando termines, puedes borrar el proyecto y quitar todos los recursos asociados con él.

• Crea un proyecto de Google Cloud :

  gcloud projects create PROJECT_ID

  Reemplaza PROJECT_ID por un nombre para el proyecto Google Cloud que estás creando.

• Selecciona el proyecto Google Cloud que creaste:

  gcloud config set project PROJECT_ID

  Reemplaza PROJECT_ID por el nombre de tu Google Cloud proyecto.

Verifica que la facturación esté habilitada para tu proyecto de Google Cloud .

Habilita las APIs de GKE, Sincronizador de configuración y Artifact Registry:

Roles necesarios para habilitar las APIs

Para habilitar las APIs, necesitas el rol de IAM de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin), que contiene el permiso serviceusage.services.enable. Obtén más información para otorgar roles.

gcloud services enable container.googleapis.com  anthosconfigmanagement.googleapis.com  artifactregistry.googleapis.com

1. Crea un clúster que cumpla con los requisitos del Sincronizador de configuración y que tenga la versión más reciente del Sincronizador de configuración, o bien accede a uno.
2. Instala la CLI de nomos o actualízala a la versión más reciente.
3. Instala Helm 3.8.0 o una versión posterior. En versiones anteriores de Helm, la compatibilidad con gráficos en formato OCI es una función experimental.
4. Habilita Workload Identity Federation for GKE en tu clúster.

Limitaciones

• No puedes cambiar ningún campo inmutable en una configuración solo cambiando el valor en la fuente de la verdad. Si necesitas actualizar un campo inmutable, primero realiza el cambio en la fuente de información y, luego, borra manualmente el objeto en el clúster. Luego, el Sincronizador de configuración puede volver a crear el objeto con el nuevo valor del campo.

• Los siguientes gráficos de Helm incluyen trabajos y no se recomiendan para la implementación con el Sincronizador de configuración:

  • secrets-store-csi-driver
  • cert-manager

  Para obtener más información sobre por qué no se recomienda usar Jobs con el Sincronizador de configuración, consulta Evita administrar Jobs con el Sincronizador de configuración.

Crea un repositorio de Artifact Registry

En esta sección, crearás un repositorio de Artifact Registry. Para obtener más información sobre cómo crear repositorios de Artifact Registry, consulta Crea repositorios.

1. Habilita la API de Artifact Registry:

   gcloud services enable artifactregistry.googleapis.com --project=PROJECT_ID
   

2. Crea un repositorio de Artifact Registry:

   gcloud artifacts repositories create AR_REPO_NAME \
      --repository-format=docker \
      --location=AR_REGION \
      --description="Config Sync Helm repo" \
      --project=PROJECT_ID
   

Reemplaza lo siguiente:

• PROJECT_ID: El ID del proyecto de la organización.
• AR_REPO_NAME: Es el ID del repositorio.
• AR_REGION: es la ubicación regional o multirregional del repositorio.

Variables que se usan en las siguientes secciones:

• FLEET_HOST_PROJECT_ID: Si usas Workload Identity Federation for GKE, esto es lo mismo que PROJECT_ID. Si usas la flota Workload Identity Federation for GKE, este es el ID del proyecto de la flota en la que está registrado tu clúster.
• GSA_NAME: Es el nombre de la cuenta de servicio personalizada de Google que deseas usar para conectarte a Artifact Registry.
• KSA_NAME: Es la cuenta de servicio de Kubernetes para el conciliador.
  • Para los repositorios raíz, si el nombre RootSync es root-sync, agrega root-reconciler. De lo contrario, agrega root-reconciler-ROOT_SYNC_NAME.
  • Para los repositorios de espacios de nombres, si el nombre de RepoSync es repo-sync, agrega ns-reconciler-NAMESPACE. De lo contrario, agrega ns-reconciler-NAMESPACE-REPO_SYNC_NAME-REPO_SYNC_NAME_LENGTH, donde REPO_SYNC_NAME_LENGTH es la cantidad de caracteres en REPO_SYNC_NAME.

Otorga permiso de lector

Para autenticarte en Artifact Registry con una cuenta de servicio de Kubernetes, completa los siguientes pasos:

Otorga el rol de IAM de lector de Artifact Registry (roles/artifactregistry.reader) a la cuenta de servicio de Kubernetes que tiene el grupo de Workload Identity Federation for GKE:

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

Envía un gráfico de Helm al repositorio de Artifact Registry

En esta sección, descargarás un gráfico de Helm público y lo enviarás a Artifact Registry.

1. Recupera el paquete mysql-9.3.1.tgz del repositorio público de Helm y descárgalo de forma local:

   helm pull mysql --repo https://charts.bitnami.com/bitnami --version 9.3.1
   

2. Autentica con un token de acceso:

   Linux/macOS

   gcloud auth print-access-token | helm registry login -u oauth2accesstoken \
   --password-stdin https://AR_REGION-docker.pkg.dev
   

   Windows

   gcloud auth print-access-token
   ya29.8QEQIfY_...
   
   helm registry login -u oauth2accesstoken -p "ya29.8QEQIfY_..." \
   https://AR_REGION-docker.pkg.dev/PROJECT_ID/AR_REPO_NAME
   

   En este comando, oauth2accesstoken es el nombre de usuario que se usará para la autenticación con un token de acceso y gcloud auth print-access-token es el comando para obtener el token de acceso. El token de acceso es la contraseña para la autenticación. La autenticación con un token de acceso es el método de autenticación más seguro.

3. Envía el gráfico de Helm a Artifact Registry:

   helm push mysql-9.3.1.tgz oci://AR_REGION-docker.pkg.dev/PROJECT_ID/AR_REPO_NAME
   

Configura el Sincronizador de configuración para que se sincronice desde tu gráfico de Helm

En esta sección, crearás un objeto RootSync y configurarás el Sincronizador de configuración para sincronizar desde el gráfico de Helm.

Si deseas anular los valores predeterminados del gráfico de Helm, puedes hacerlo especificando valores en el campo spec.helm.values o agregando una referencia a un ConfigMap con el campo spec.helm.valuesFileRefs. Para obtener más información sobre los campos opcionales, consulta Configuración del repositorio de Helm.

Nota: Si deseas usar los valores predeterminados del gráfico, puedes usar cualquiera de los ejemplos y omitir los campos spec.helm.values o spec.helm.valuesFileRefs.

valores

1. Crea un objeto RootSync con un nombre único:

   cat <<EOF>> ROOT_SYNC_NAME.yaml
   apiVersion: configsync.gke.io/v1beta1
   kind: RootSync
   metadata:
     name: ROOT_SYNC_NAME
     namespace: config-management-system
   spec:
     sourceFormat: unstructured
     sourceType: helm
     helm:
       repo: oci://AR_REGION-docker.pkg.dev/PROJECT_ID/AR_REPO_NAME
       chart: mysql
       version: 9.3.1
       releaseName: my-mysql
       namespace: test
       auth: k8sserviceaccount
       # Use the optional field spec.helm.values to override default values.
       # You can use the same format as the default values file to override
       # default values.
       values:
         image:
           pullPolicy: Always
         primary:
           resources:
             limits:
               cpu: 250m
               memory: 256Mi
             requests:
               cpu: 250m
               memory: 256Mi
   EOF
   

   Reemplaza ROOT_SYNC_NAME por el nombre de tu objeto RootSync. El nombre debe ser único en el clúster y no debe tener más de 26 caracteres. Si instalaste el Sincronizador de configuración con la consola de Google Cloud o Google Cloud CLI, elige un nombre que no sea root-sync.

   En este ejemplo, el gráfico de Helm se implementa en el espacio de nombres test porque sus recursos contienen namespace: {{ .Release.Namespace }} en sus plantillas.

   Puedes usar helm.values para anular los valores predeterminados. Para obtener información sobre los campos opcionales, consulta Configuración del repositorio de Helm.

2. Aplica el objeto RootSync:

   kubectl apply -f ROOT_SYNC_NAME.yaml
   

3. Verifica que el Sincronizador de configuración se sincronice desde la imagen:

   nomos status --contexts=$(kubectl config current-context)
   

   El resultado es similar a este:

   Connecting to clusters...
   
   *cluster-name
     --------------------
     <root>:root-sync   oci://AR_REGION-docker.pkg.dev/PROJECT_ID/AR_REPO_NAME/mysql:9.3.1
     SYNCED             9.3.1
     Managed resources:
         NAMESPACE  NAME                       STATUS    SOURCEHASH
         default    configmap/my-mysql         Current   9.3.1
         default    secret/my-mysql            Current   9.3.1
         default    service/my-mysql           Current   9.3.1
         default    service/my-mysql-headless  Current   9.3.1
         default    serviceaccount/my-mysql    Current   9.3.1
         default    statefulset.apps/my-mysql  Current   9.3.1
   

   Ya sincronizaste correctamente el gráfico de Helm con tu clúster.

valuesFileRefs

1. Crea un objeto RootSync con un nombre único:

   cat <<EOF>> ROOT_SYNC_NAME.yaml
   apiVersion: configsync.gke.io/v1beta1
   kind: RootSync
   metadata:
     name: ROOT_SYNC_NAME
     namespace: config-management-system
   spec:
     sourceFormat: unstructured
     sourceType: helm
     helm:
       repo: oci://AR_REGION-docker.pkg.dev/PROJECT_ID/AR_REPO_NAME
       chart: mysql
       version: 9.3.1
       releaseName: my-mysql
       auth: k8sserviceaccount
       # use the optional field spec.helm.valuesFilesRefs to override default values
       # by referencing a ConfigMap
       valuesFileRefs:
       - name: CONFIGMAP_NAME
         dataKey: DATA_KEY
   
   EOF
   

   Reemplaza lo siguiente:

   • ROOT_SYNC_NAME: Es el nombre de tu objeto RootSync. El nombre debe ser único en el clúster y no debe tener más de 26 caracteres. Si instalaste el Sincronizador de configuración con la consola de Google Cloud o Google Cloud CLI, elige un nombre que no sea root-sync.
   • CONFIGMAP_NAME: Es el nombre de tu ConfigMap. Puede ser cualquier nombre de ConfigMap válido que acepte Kubernetes y que sea único en tu clúster.
   • (Opcional) DATA_KEY: Es la clave de datos en tu ConfigMap desde la que deseas leer los valores. El valor predeterminado es values.yaml.

2. Crea el objeto ConfigMap con tus valores:

   Nota: El ConfigMap es inmutable y debe estar en el mismo espacio de nombres que el RootSync o RepoSync que lo referencia.

   cat <<EOF>> CONFIGMAP_NAME.yaml
   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: CONFIGMAP_NAME
     namespace: config-management-system
   immutable: true
   # You can use the same format as the default values file to override
   # default values.
   data:
     DATA_KEY: |-
       image:
         pullPolicy: Always
       primary:
         resources:
           limits:
             cpu: 250m
             memory: 256Mi
           requests:
             cpu: 250m
             memory: 256Mi
   
   EOF
   

   Si no especificaste un valor para DATA_KEY en RootSync, debería ser el valor predeterminado values.yaml.

3. Aplica el objeto ConfigMap:

   kubectl apply -f CONFIGMAP_NAME.yaml
   

4. Aplica el objeto RootSync:

   kubectl apply -f ROOT_SYNC_NAME.yaml
   

5. Verifica que el Sincronizador de configuración se sincronice desde la imagen:

   nomos status --contexts=$(kubectl config current-context)
   

   El resultado es similar a este:

   Connecting to clusters...
   
   *cluster-name
     --------------------
     <root>:root-sync   oci://AR_REGION-docker.pkg.dev/PROJECT_ID/AR_REPO_NAME/mysql:9.3.1
     SYNCED             9.3.1
     Managed resources:
         NAMESPACE  NAME                       STATUS    SOURCEHASH
         default    configmap/my-mysql         Current   9.3.1
         default    secret/my-mysql            Current   9.3.1
         default    service/my-mysql           Current   9.3.1
         default    service/my-mysql-headless  Current   9.3.1
         default    serviceaccount/my-mysql    Current   9.3.1
         default    statefulset.apps/my-mysql  Current   9.3.1
   

   Ya sincronizaste correctamente el gráfico de Helm con tu clúster.

   También puedes consultar el imagePullPolicy en uno de los recursos sincronizados del clúster para verificar que se hayan usado los valores del ConfigMap para renderizar el gráfico:

   kubectl get statefulset -n test my-mysql -o yaml | grep imagePullPolicy
   

6. Debido a que el ConfigMap es inmutable, para cambiar los valores, debes crear un ConfigMap nuevo y actualizar spec.helm.valuesFileRefs en la especificación de RootSync o RepoSync para que apunte al ConfigMap nuevo. Crear un ConfigMap nuevo garantiza que los cambios en los valores hagan que el gráfico de Helm se vuelva a renderizar, lo que resulta útil cuando se deben actualizar varios ConfigMaps a los que se hace referencia en spec.helm.valuesFileRefs al mismo tiempo durante el nuevo renderizado. Para cambiar los valores que se usan para renderizar tu gráfico, crea un ConfigMap nuevo con un nombre diferente:

   cat <<EOF>> CONFIGMAP_NAME-2.yaml
   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: CONFIGMAP_NAME-2
     namespace: config-management-system
   immutable: true
   # You can use the same format as the default values file to override
   # default values.
   data:
     DATA_KEY: |-
       image:
         pullPolicy: Never
       primary:
         resources:
           limits:
             cpu: 100m
             memory: 256Mi
           requests:
             cpu: 250m
             memory: 200Mi
   
   EOF
   

7. Actualiza tu objeto RootSync para que haga referencia al nuevo ConfigMap:

   cat <<EOF>> ROOT_SYNC_NAME.yaml
   apiVersion: configsync.gke.io/v1beta1
   kind: RootSync
   metadata:
     name: ROOT_SYNC_NAME
     namespace: config-management-system
   spec:
     sourceFormat: unstructured
     sourceType: helm
     helm:
       repo: oci://AR_REGION-docker.pkg.dev/PROJECT_ID/AR_REPO_NAME
       chart: mysql
       version: 9.3.1
       releaseName: my-mysql
       namespace: test
       auth: k8sserviceaccount
       # use the optional field spec.helm.valuesFilesRefs to override default values
       # by referencing a ConfigMap
       valuesFileRefs:
       - name: CONFIGMAP_NAME-2
         dataKey: DATA_KEY
   
   EOF
   

8. Aplica el objeto ConfigMap:

   kubectl apply -f CONFIGMAP_NAME-2.yaml
   

9. Aplica el objeto RootSync:

   kubectl apply -f ROOT_SYNC_NAME.yaml
   

10. Verifica que el Sincronizador de configuración se sincronice desde la imagen:

    nomos status --contexts=$(kubectl config current-context)
    

    También puedes consultar el imagePullPolicy en uno de los recursos sincronizados del clúster para verificar que se hayan usado los valores nuevos del ConfigMap actualizado para renderizar el gráfico:

    Nota: La sincronización completa de los recursos puede tardar unos minutos.

    kubectl get statefulset -n test my-mysql -o yaml | grep imagePullPolicy
    

¿Qué sigue?

• Obtén más información sobre cómo instalar el Sincronizador de configuración.