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

  • Articolo

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 grafici personalizzati 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.

Importante

Questo articolo è stato aggiornato con i comandi Helm 3. Helm 3.7 include modifiche ai comandi dell'interfaccia della riga di comando Helm e al supporto OCI introdotto nelle versioni precedenti di Helm 3. Per impostazione predefinita helm si sposta avanti con la versione. È consigliabile usare la versione 3.7.2 o successiva.

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:

  • Può archiviare e gestire grafici Helm nei repository in un registro Azure Container
  • Archiviare i grafici Helm nel registro come artefatti OCI. Registro Azure Container fornisce il supporto ga per gli artefatti OCI, inclusi i grafici Helm.
  • Eseguire l'autenticazione con il registro usando il helm registry login comando o az acr login .
  • Usare helm i comandi 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).

Funzionalità Helm 2 Helm 3
Gestire i grafici usando az acr helm i comandi ✔️
Archiviare i grafici come artefatti OCI ✔️
Gestire i grafici usando az acr repository i comandi e il pannello Repository in portale di Azure ✔️

Nota

A partire da Helm 3, i comandi az acr helm da usare con il client Helm 2 sono deprecati. Un preavviso di almeno 3 mesi verrà fornito in anticipo alla rimozione dei comandi.

Compatibilità delle versioni del grafico

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

Versione Helm 2 Helm 3
apiVersion v1 ✔️ ✔️
apiVersion v2 ✔️

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:

Prerequisiti

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

Configurare il client Helm

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

helm version

Nota

La versione indicata deve essere almeno 3.8.0, perché il supporto OCI nelle versioni precedenti era sperimentale.

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, modificare la directory nella templates cartella e prima eliminare il contenuto:

cd hello-world/templates
rm -rf *

templates Nella cartella 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 Getting Started in the Helm Docs (Introduzione alla documentazione Helm).

Salvare il grafico nell'archivio locale

Passare alla hello-world sottodirectory. 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 le credenziali dell'entità servizio, l'identità utente o un token con ambito repository.

  • Eseguire l'autenticazione con un'entità servizio Microsoft Entra con autorizzazioni pull e push (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 helm push comando 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

L'output, abbreviato in questo esempio, mostra un configMediaType valore 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 --version parametro . Specificare un nome di versione, ad esempio myhelmtest, o passare il --generate-name parametro . 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 helm get manifest comando .

helm get manifest myhelmtest

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

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 --version parametro . 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 di grafici usando Helm 2 e i az acr helm comandi, è consigliabile eseguire l'aggiornamento al client Helm 3. Seguire quindi questa procedura per archiviare i grafici come artefatti OCI nel Registro di sistema.

Importante

  • Dopo aver completato la migrazione da un repository di grafici in stile Helm 2 (basato su index.yaml) ai repository degli artefatti OCI, usare l'interfaccia della riga di comando Helm e az acr repository i comandi per gestire i grafici. Vedere le sezioni precedenti in questo articolo.
  • I repository degli artefatti Helm OCI non sono individuabili usando comandi Helm, helm search ad esempio e helm repo list. Per altre informazioni sui comandi Helm usati per archiviare i grafici come artefatti OCI, vedere la documentazione di Helm.

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 ingress-nginx-3.20.1.tgz esempio .

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