Eseguire il push e il pull dei grafici Helm in un registro Azure Container

Per gestire e distribuire rapidamente applicazioni per Kubernetes, è possibile usare il gestore pacchetti open source Helm. Con Helm, i pacchetti dell'applicazione vengono definiti come grafici, che vengono raccolti e archiviati in un repository di grafici Helm.

Questo articolo illustra come ospitare i repository dei grafici Helm in un registro Contenitori di Azure usando i comandi Helm 3 e archiviando i grafici come artefatti OCI. In molti scenari è necessario compilare e caricare i propri grafici per le applicazioni sviluppate. Per altre informazioni su come creare grafici Helm personalizzati, vedere la Guida per sviluppatori di modelli di grafico. È anche possibile archiviare un grafico Helm esistente da un altro repository Helm.

Helm 3 o Helm 2?

Per archiviare, gestire e installare i grafici Helm, usare i comandi nell'interfaccia della riga di comando di Helm. Le versioni principali di Helm includono Helm 3 e Helm 2. Per informazioni dettagliate sulle differenze di versione, vedere le domande frequenti sulla versione.

Helm 3 deve essere usato per ospitare grafici Helm in Registro Azure Container. Con Helm 3, è possibile:

• Archiviare e gestire grafici Helm nei repository in un registro Azure Container
• Archiviare i grafici Helm nel registro come artefatti OCI. Registro Azure Container offre il supporto GA per gli artefatti OCI, inclusi i grafici Helm.
• Eseguire l'autenticazione con il registro usando il comando helm registry login o az acr login.
• Usare i comandi helm per eseguire il push, il pull e la gestione dei grafici Helm in un registro
• Usare helm install per installare grafici in un cluster Kubernetes dal Registro di sistema.

Supporto funzionalità

Registro Azure Container supporta funzionalità specifiche di gestione dei grafici Helm a seconda che si usi Helm 3 (corrente) o Helm 2 (deprecato).

Compatibilità delle versioni del grafico

Le versioni del Helm seguenti possono essere archiviate in Registro Azure Container e possono essere installate dai client Helm 2 e Helm 3.

Eseguire la migrazione da Helm 2 a Helm 3

Se i grafici sono stati archiviati e distribuiti in precedenza con Helm 2 e Registro Azure Container, è consigliabile eseguire la migrazione a Helm 3. Vedere:

• Migrazione di Helm 2 a 3 nella documentazione di Helm.
• Eseguire la migrazione del Registro di sistema per archiviare gli artefatti OCI Helm, più avanti in questo articolo

Prerequisiti

Per lo scenario in questo articolo sono necessarie le risorse seguenti:

• Registro Azure Container nella sottoscrizione di Azure. Se necessario, creare un registro usando il portale di Azure o l'interfaccia della riga di comando di Azure.
• Client Helm versione 3.7 o successiva: eseguire helm version per trovare la versione corrente. Per altre informazioni su come installare e aggiornare Helm, vedere Installing Helm (Installazione di Helm). Se si esegue l'aggiornamento da una versione precedente di Helm 3, esaminare le note sulla versione.
• un cluster Kubernetes in cui verrà installato un grafico Helm. Se necessario, creare un cluster del servizio Azure Kubernetes usando l'interfaccia della riga di comando di Azure, usando Azure PowerShell o usando il portale di Azure.
• Interfaccia della riga di comando di Azure versione 2.0.71 o successiva - Eseguire az --version per trovare la versione. Se è necessario eseguire l'installazione o l'aggiornamento, vedere Installare l'interfaccia della riga di comando di Azure.

Configurare il client Helm

Usare il comando helm version per verificare di aver installato Helm 3:

helm version

Impostare le variabili di ambiente seguenti per il Registro di sistema di destinazione. Il ACR_NAME è il nome della risorsa del Registro di sistema. Se l'URL del Registro Azure Container è myregistry.azurecr.io, impostare il ACR_NAME su myregistry

ACR_NAME=<container-registry-name>

Creare un grafico di esempio

Creare un grafico di test usando i comandi seguenti:

mkdir helmtest

cd helmtest
helm create hello-world

Come esempio di base, passare alla cartella templates e prima eliminare il contenuto:

cd hello-world/templates
rm -rf *

Nella cartella templates creare un file denominato configmap.yaml eseguendo il comando seguente:

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

Per altre informazioni sulla creazione e l'esecuzione di questo esempio, vedere Introduzione alla documentazione Helm.

Salvare il grafico nell'archivio locale

Passare alla sottodirectory hello-world. Eseguire quindi helm package per salvare il grafico in un archivio locale.

Nell'esempio seguente il grafico viene salvato con il nome e la versione in Chart.yaml.

cd ..
helm package .

L'output è simile a:

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

Eseguire l'autenticazione con il Registro di sistema

Eseguire helm registry login per eseguire l'autenticazione con il Registro di sistema. È possibile passare le credenziali del Registro di sistema appropriate per lo scenario, ad esempio credenziali dell'entità servizio, identità utente o token con ambito repository.

• Eseguire l'autenticazione con un'entità servizio con autorizzazioni pull e push Microsoft Entra (ruolo AcrPush) nel Registro di sistema.

  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)
  

• Eseguire l'autenticazione con la singola identità di Microsoft Entra per eseguire il push e il pull dei grafici Helm usando un token di Active Directory.

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

• Eseguire l'autenticazione con un token con ambito repository (anteprima).

  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)
  

• Specificare quindi le credenziali a helm registry login.

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

Eseguire il push del grafico nel Registro di sistema come artefatto OCI

Eseguire il comando helm push nell'interfaccia della riga di comando di Helm 3 per eseguire il push dell'archivio del grafico nel repository di destinazione completo. Separare le parole nei nomi dei grafici e usare solo lettere minuscole e numeri. Nell'esempio seguente lo spazio dei nomi del repository di destinazione è helm/hello-worlde il grafico è contrassegnato: 0.1.0

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

Dopo un push riuscito, l'output è simile al seguente:

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

Elencare i grafici nel repository

Come per le immagini archiviate in un registro Azure Container, è possibile usare i comandi az acr repository per visualizzare i repository che ospitano i grafici e i tag e i manifesti del grafico.

Ad esempio, eseguire az acr repository show per visualizzare le proprietà del repository creato nel passaggio precedente:

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

L'output è simile a:

{
  "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
}

Eseguire il comando az acr manifest list-metadata per visualizzare i dettagli del grafico archiviato nel repository. Ad esempio:

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

Output, abbreviato in questo esempio, mostra un configMediaType di 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"
    ]

Installare il grafico Helm

Eseguire helm install per installare il grafico Helm di cui è stato eseguito il push nel Registro di sistema. Il tag del grafico viene passato usando il parametro --version. Specificare un nome di versione, ad esempio myhelmtest o passare il parametro --generate-name. Ad esempio:

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

L'output dopo l'installazione del grafico è simile al seguente:

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

Per verificare l'installazione, eseguire il comando helm get manifest.

helm get manifest myhelmtest

Il comando restituisce i dati YAML nel file modello di configmap.yaml.

Eseguire helm uninstall per disinstallare la versione del grafico nel cluster:

helm uninstall myhelmtest

Eseguire il pull del grafico nell'archivio locale

Facoltativamente, è possibile eseguire il pull di un grafico dal registro contenitori a un archivio locale usando helm pull. Il tag del grafico viene passato usando il parametro --version. Se esiste un archivio locale nel percorso corrente, questo comando lo sovrascrive.

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

Eliminare il grafico dal Registro di sistema

Per eliminare un grafico dal registro contenitori, usare il comando az acr repository delete. Eseguire il comando seguente e confermare l'operazione quando richiesto:

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

Eseguire la migrazione del registro per archiviare gli artefatti OCI Helm

Se in precedenza si configura il Registro Azure Container come repository grafico usando Helm 2 e i comandi az acr helm, è consigliabile aggiornare al client Helm 3. Seguire quindi questa procedura per archiviare i grafici come artefatti OCI nel Registro di sistema.

Abilitare il supporto OCI (abilitato per impostazione predefinita in Helm v3.8.0)

Assicurarsi di usare il client Helm 3:

helm version

Se si usa Helm v3.8.0 o versione successiva, questa opzione è abilitata per impostazione predefinita. Se si usa una versione precedente, è possibile abilitare il supporto OCI impostando la variabile di ambiente:

export HELM_EXPERIMENTAL_OCI=1

Elencare i grafici correnti

Elencare i grafici attualmente archiviati nel Registro di sistema, denominato myregistry:

helm search repo myregistry

L'output mostra i grafici e le versioni del grafico:

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...
[...]

Eseguire il pull degli archivi del grafico in locale

Per ogni grafico nel repository, eseguire il pull dell'archivio grafico in locale e prendere nota del nome file:

helm pull myregisry/ingress-nginx
ls *.tgz

Viene creato un archivio grafico locale, ad esempio ingress-nginx-3.20.1.tgz.

Eseguire il push dei grafici come artefatti OCI nel Registro di sistema

Accedere al Registro di sistema:

az acr login --name $ACR_NAME

Eseguire il push di ogni archivio grafico nel Registro di sistema. Esempio:

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

Dopo aver eseguito il push di un grafico, verificare che sia archiviato nel Registro di sistema:

az acr repository list --name $ACR_NAME

Dopo aver eseguito il push di tutti i grafici, rimuovere facoltativamente il repository dei grafici in stile Helm 2 dal Registro di sistema. In questo modo si riduce l'archiviazione nel Registro di sistema:

helm repo remove $ACR_NAME

Passaggi successivi

• Per altre informazioni su come creare e distribuire grafici Helm, vedere Developing Helm charts (Distribuzione di grafici Helm).
• Per altre informazioni sull'installazione di applicazioni con Helm, vedere Servizio Azure Kubernetes (AKS).
• I grafici Helm possono essere usati come parte del processo di compilazione del contenitore. Per altre informazioni, vedere Usare Attività del Registro Azure Container.