Inserción y extracción de gráficos de Helm en Azure Container Registry

Artículo
09/23/2024

Para administrar e implementar rápidamente aplicaciones de Kubernetes, puede usar el administrador de paquetes de código abierto de Helm. Con Helm, los paquetes de aplicación se definen como gráficos que se recopilan y almacenan en un repositorio de gráficos de Helm.

En este artículo se muestra cómo hospedar repositorios gráficos de Helm en un registro de contenedor de Azure mediante comandos de Helm 3 y el almacenamiento de los gráficos como artefactos de OCI. En la mayoría de los escenarios, creará y cargará sus propios gráficos para las aplicaciones que desarrolla. Para obtener más información sobre cómo crear sus propios gráficos de Helm, consulte la guía para desarrolladores de plantillas de gráficos (en inglés). También puede almacenar un gráfico de Helm existente desde otro repositorio de Helm.

Nota:

Este artículo se ha actualizado con comandos de Helm 3. Helm 3.7 incluye cambios en los comandos de la CLI de Helm y la compatibilidad con OCI introducida en versiones anteriores de Helm 3. Por diseño helm avanza con las actualizaciones de versiones. Se recomienda usar la versión 3.7.2 o posterior.

Importante

En noviembre de 2020, Helm 2 llegó al final de su vida. A partir del 30 de marzo de 2025, Azure Container Registry ya no admitirá Helm 2. Por lo tanto, también se retirará la funcionalidad heredada "repositorios de Helm". Se recomienda realizar la transición a Helm 3 inmediatamente.
A partir del 21 de enero de 2025, el comando de la CLI az acr helm push se retirará para evitar insertar nuevos gráficos de Helm en repositorios de Helm heredados.
A partir del 30 de marzo de 2025, el grupo de comandos az acr helm de la CLI se retirará, finalizando así todas las funcionalidades heredadas del repositorio de Helm en Azure Container Registry.
Todos los gráficos de Helm no almacenados como artefacto de OCI se eliminarán de Azure Container Registry el 30 de marzo de 2025.
Aprenda cómo encontrar todos los gráficos de Helm almacenados en un repositorio de Helm aquí: az acr helm list. Si el gráfico de Helm que usa se muestra en esta lista, significa que se almacena en un repositorio de Helm heredado y corre el riesgo de eliminación.

¿Helm 3 o Helm 2?

Para almacenar, administrar e instalar gráficos de Helm, se usan comandos en la CLI de Helm. Las versiones principales de Helm incluyen Helm 3 y Helm 2. Para obtener más información sobre las diferencias de versión, vea las preguntas más frecuentes sobre la versión.

Helm 3 se debe usar para hospedar gráficos de Helm en Azure Container Registry. Con Helm 3:

Puede almacenar y administrar gráficos de Helm en repositorios de un registro de contenedor de Azure.
Almacenar gráficos de Helm en el registro como artefactos de OCI. Azure Container Registry proporciona compatibilidad con GA para artefactos OCI, incluidos los gráficos de Helm.
Autenticarse con el registro mediante el comando helm registry login o az acr login.
Usar comandos helm para insertar, extraer y administrar gráficos de Helm en un registro.
Use helm install para instalar gráficos en un clúster de Kubernetes desde el Registro.

Compatibilidad de características

Azure Container Registry admite características específicas para la administración de gráficos de Helm en función de si usa Helm 3 (actual) o Helm 2 (en desuso).

Característica	Helm 2	Helm 3
Administración de gráficos con comandos `az acr helm`	✔️
Almacenamiento de gráficos como artefactos de OCI		✔️
Administración de gráficos con comandos `az acr repository` y la hoja Repositorios de Azure Portal		✔️

Compatibilidad con versiones de gráficos

Las versiones de gráficos de Helm siguientes se pueden almacenar en Azure Container Registry y los clientes de Helm 2 y Helm 3 pueden instalarlas.

Versión	Helm 2	Helm 3
apiVersion v1	✔️	✔️
apiVersion v2		✔️

Migración de Helm 2 a Helm 3

Si anteriormente almacenó e implementó gráficos con Helm 2 y Azure Container Registry, se recomienda migrar a Helm 3. Vea:

Migración de Helm 2 a 3 en la documentación de Helm.
Migración del registro para almacenar artefactos de OCI de Helm, más adelante en este artículo

Requisitos previos

Los siguientes recursos son necesarios para el escenario de este artículo:

Una instancia de Azure Container Registry en la suscripción a Azure. Si es necesario, cree un registro mediante Azure Portal o la CLI de Azure.
Versión de cliente de Helm 3.7 o posterior: ejecute helm version para buscar la versión actual. Para más información sobre cómo instalar y usar Helm, consulte Instalación de Helm. Si realiza la actualización desde una versión anterior de Helm 3, revise las notas de la versión.
Un clúster de Kubernetes donde instalar un gráfico de Helm. Si es necesario, cree un clúster de AKS mediante la CLI de Azure, Azure PowerShell o Azure Portal.
CLI de Azure versión 2.0.71 o posterior: ejecute az --version para buscar la versión. Si necesita instalarla o actualizarla, vea Instalación de la CLI de Azure.

Configuración del cliente de Helm

Use el comando helm version para comprobar que tiene instalado Helm 3:

helm version

Nota:

La versión indicada debe ser al menos la 3.8.0, ya que la compatibilidad con OCI en versiones anteriores era experimental.

Establezca las siguientes variables de entorno para el registro de destino. ACR_NAME es el nombre del recurso del Registro. Si la dirección URL del registro de ACR myregistry.azurecr.io, establezca el valor de ACR_NAME en myregistry.

ACR_NAME=<container-registry-name>

Crear un gráfico de ejemplo

Cree un gráfico de prueba con los siguientes comandos:

mkdir helmtest

cd helmtest
helm create hello-world

Como ejemplo básico, cambie el directorio a la carpeta templates y, en primer lugar, elimine el contenido aquí:

cd hello-world/templates
rm -rf *

En la carpeta templates, cree un archivo llamado configmap.yaml mediante la ejecución del comando siguiente:

cat <<EOF > configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: hello-world-configmap
data:
  myvalue: "Hello World"
EOF

Para más información sobre cómo crear y ejecutar este ejemplo, consulte Introducción en los documentos de Helm.

Guardar el gráfico en un archivo local

Cambie el directorio al subdirectorio hello-world. A continuación, ejecute helm package para guardar el gráfico en un archivo local.

En el ejemplo siguiente, el gráfico se guarda con el nombre y la versión en Chart.yaml.

cd ..
helm package .

La salida es parecida a esta:

Successfully packaged chart and saved it to: /my/path/hello-world-0.1.0.tgz

Autenticación con el registro

Ejecute helm registry login para autenticarse con el registro. Puede pasar las credenciales de registro adecuadas para el escenario, como las credenciales de la entidad de servicio, una identidad de usuario o un token con ámbito de repositorio.

Autentíquese con una entidad de servicio de Microsoft Entra con permisos de extracción e inserción (rol AcrPush) para el registro.

SERVICE_PRINCIPAL_NAME=<acr-helm-sp>
ACR_REGISTRY_ID=$(az acr show --name $ACR_NAME --query id --output tsv)
PASSWORD=$(az ad sp create-for-rbac --name $SERVICE_PRINCIPAL_NAME \
          --scopes $(az acr show --name $ACR_NAME --query id --output tsv) \
           --role acrpush \
          --query "password" --output tsv)
USER_NAME=$(az identity show -n $SERVICE_PRINCIPAL_NAME -g $RESOURCE_GROUP_NAME --subscription $SUBSCRIPTION_ID --query "clientId" -o tsv)

Autentíquese con la identidad individual de Microsoft Entra para insertar y extraer gráficos de Helm mediante un token de AD.

USER_NAME="00000000-0000-0000-0000-000000000000"
PASSWORD=$(az acr login --name $ACR_NAME --expose-token --output tsv --query accessToken)

Autentíquese con un token con ámbito de repositorio (versión preliminar).

USER_NAME="helmtoken"
PASSWORD=$(az acr token create -n $USER_NAME \
                  -r $ACR_NAME \
                  --scope-map _repositories_admin \
                  --only-show-errors \
                  --query "credentials.passwords[0].value" -o tsv)

A continuación, proporcione las credenciales a helm registry login.

helm registry login $ACR_NAME.azurecr.io \
  --username $USER_NAME \
  --password $PASSWORD

Inserción del gráfico en el Registro como artefacto de OCI

Ejecute el comando helm push de la CLI de Helm 3 para insertar el archivo de gráfico en el repositorio de destino completo. Separe las palabras de los nombres del gráfico y use solo letras minúsculas y números. En el ejemplo siguiente, el espacio de nombres del repositorio de destino es helm/hello-world y el gráfico está etiquetado como 0.1.0:

helm push hello-world-0.1.0.tgz oci://$ACR_NAME.azurecr.io/helm

Después de una inserción correcta, la salida es similar a:

Pushed: <registry>.azurecr.io/helm/hello-world:0.1.0
digest: sha256:5899db028dcf96aeaabdadfa5899db02589b2899b025899b059db02

Lista de gráficos en el repositorio

Al igual que con las imágenes almacenadas en una instancia de Azure Container Registry, puede usar comandos az acr repository para mostrar los repositorios que hospedan sus gráficos, así como los manifiestos y las etiquetas de estos.

Por ejemplo, ejecute az acr repository show para ver las propiedades del repositorio que creó en el paso anterior:

az acr repository show \
  --name $ACR_NAME \
  --repository helm/hello-world

La salida es parecida a esta:

{
  "changeableAttributes": {
    "deleteEnabled": true,
    "listEnabled": true,
    "readEnabled": true,
    "writeEnabled": true
  },
  "createdTime": "2021-10-05T12:11:37.6701689Z",
  "imageName": "helm/hello-world",
  "lastUpdateTime": "2021-10-05T12:11:37.7637082Z",
  "manifestCount": 1,
  "registry": "mycontainerregistry.azurecr.io",
  "tagCount": 1
}

Ejecute el comando az acr manifest list-metadata para ver los detalles del gráfico almacenado en el repositorio. Por ejemplo:

az acr manifest list-metadata \
  --registry $ACR_NAME \
  --name helm/hello-world

La salida, abreviada en este ejemplo, muestra un valor de configMediaType de application/vnd.cncf.helm.config.v1+json:

[
  {
    [...]
    "configMediaType": "application/vnd.cncf.helm.config.v1+json",
    "createdTime": "2021-10-05T12:11:37.7167893Z",
    "digest": "sha256:0c03b71c225c3ddff53660258ea16ca7412b53b1f6811bf769d8c85a1f0663ee",
    "imageSize": 3301,
    "lastUpdateTime": "2021-10-05T12:11:37.7167893Z",
    "mediaType": "application/vnd.oci.image.manifest.v1+json",
    "tags": [
      "0.1.0"
    ]

Instalar el gráfico de Helm

Ejecute helm install para instalar el gráfico de Helm que ha inserido en el Registro. La etiqueta del gráfico se pasa mediante el parámetro --version. Especifique un nombre de versión, como myhelmtest o bien pase el parámetro --generate-name. Por ejemplo:

helm install myhelmtest oci://$ACR_NAME.azurecr.io/helm/hello-world --version 0.1.0

La salida después de la instalación correcta del gráfico es similar a:

NAME: myhelmtest
LAST DEPLOYED: Tue Oct  4 16:59:51 2021
NAMESPACE: default
STATUS: deployed
REVISION: 1
TEST SUITE: None

Para comprobar la instalación, ejecute el comando helm get manifest.

helm get manifest myhelmtest

El comando devuelve los datos de YAML en el archivo de plantilla configmap.yaml.

Ejecute helm uninstall para desinstalar la versión del gráfico en el clúster:

helm uninstall myhelmtest

Extracción del gráfico en el archivo local

Opcionalmente, puede extraer un gráfico del registro de contenedor en un archivo local mediante helm pull. La etiqueta del gráfico se pasa mediante el parámetro --version. Si existe un archivo local en la ruta de acceso actual, este comando lo sobrescribe.

helm pull oci://$ACR_NAME.azurecr.io/helm/hello-world --version 0.1.0

Eliminación del gráfico del registro

Para eliminar un gráfico del registro de contenedor, use el comando az acr repository delete. Ejecute el siguiente comando y confirme la operación cuando se le solicite:

az acr repository delete --name $ACR_NAME --image helm/hello-world:0.1.0

Migración del registro para almacenar artefactos de OCI de Helm

Si previamente configuró el registro de contenedor de Azure como un repositorio de gráficos con Helm 2 y los comandos az acr helm, se recomienda actualizar al cliente de Helm 3. A continuación, siga estos pasos para almacenar los gráficos como artefactos de OCI en el registro.

Importante

Una vez que complete la migración desde un repositorio de gráficos con el estilo de Helm 2 (basado en index.yaml) hasta repositorios de artefactos de OCI, use la CLI de Helm y los comandos az acr repository para administrar los gráficos. Consulte las secciones anterior de este artículo.
Los repositorios de artefactos de OCI de Helm no se detectan con comandos de Helm como helm search y helm repo list. Para más información sobre los comandos de Helm que se utilizan para almacenar gráficos como artefactos de OCI, consulte la documentación sobre Helm.

Habilitación de la compatibilidad con OCI (habilitada de forma predeterminada en Helm v3.8.0)

Asegúrese de utilizar el cliente de Helm 3:

helm version

Si usa Helm v3.8.0 o una versión posterior, está habilitado de forma predeterminada. Para versiones anteriores, habilite la compatibilidad con OCI con la variable de entorno:

export HELM_EXPERIMENTAL_OCI=1

Enumeración de los gráficos actuales

Enumere los gráficos actualmente almacenados en el registro, que aquí se denomina myregistry:

helm search repo myregistry

En la salida se muestran los gráficos y sus versiones:

NAME                            CHART VERSION   APP VERSION     DESCRIPTION                                       
myregistry/ingress-nginx        3.20.1          0.43.0          Ingress controller for Kubernetes...
myregistry/wordpress            9.0.3           5.3.2           Web publishing platform for building...
[...]

Extracción de archivos de gráficos localmente

Para cada gráfico del repositorio, extraiga el archivo de gráfico localmente y anote el nombre de archivo:

helm pull myregisry/ingress-nginx
ls *.tgz

Se crea el archivo de gráfico local ingress-nginx-3.20.1.tgz.

Inserción de gráficos como artefactos de OCI en el Registro

Inicie sesión en el registro:

az acr login --name $ACR_NAME

Inserte cada archivo de gráfico en el Registro. Ejemplo:

helm push ingress-nginx-3.20.1.tgz oci://$ACR_NAME.azurecr.io/helm

Después de insertar un gráfico, confirme que esté almacenado en el registro:

az acr repository list --name $ACR_NAME

Después de insertar todos los gráfico, también puede quitar del registro el repositorio de gráficos con el estilo de Helm 2. Al hacerlo, se reduce el almacenamiento en el registro:

helm repo remove $ACR_NAME

Pasos siguientes

Para obtener más información sobre cómo crear e implementar sus propios gráficos de Helm, consulte cómo desarrollar gráficos de Helm.
Más información sobre la instalación de aplicaciones con Helm en Azure Kubernetes Service (AKS).
Los gráficos de helm pueden usarse como parte del proceso de compilación de contenedor. Para más información, consulte Uso de Azure Container Registry Tasks.

Compartir a través de