Helm-grafieken pushen en ophalen naar een Azure-containerregister

Als u snel toepassingen voor Kubernetes wilt beheren en implementeren, kunt u het opensource Helm-pakketbeheer gebruiken. Met Helm worden toepassingspakketten gedefinieerd als grafieken, die worden verzameld en opgeslagen in een Helm-grafiekopslagplaats.

In dit artikel leest u hoe u Helm-grafiekenopslagplaatsen in een Azure-containerregister host, met behulp van Helm 3-opdrachten en grafieken opslaat als OCI-artefacten. In veel scenario's bouwt en uploadt u uw eigen grafieken voor de toepassingen die u ontwikkelt. Zie de handleiding voor ontwikkelaars van grafieksjablonen voor meer informatie over het bouwen van uw eigen Helm-grafieken. U kunt ook een bestaande Helm-grafiek opslaan vanuit een andere Helm-opslagplaats.

Notitie

Dit artikel is bijgewerkt met Helm 3-opdrachten. Helm 3.7 bevat wijzigingen in Helm CLI-opdrachten en OCI-ondersteuning die is geïntroduceerd in eerdere versies van Helm 3. Door ontwerp helm verder te gaan met versie-updates. U wordt aangeraden 3.7.2 of hoger te gebruiken.

Belangrijk

• In november 2020 bereikte Helm 2 het einde van de levensduur. Vanaf 30 maart 2025 biedt Azure Container Registry geen ondersteuning meer voor Helm 2. Daarom wordt de verouderde functionaliteit 'Helm-opslagplaatsen' ook buiten gebruik gesteld. U wordt aangeraden onmiddellijk over te stappen op Helm 3.
• Vanaf 21 januari 2025 wordt de CLI-opdracht az acr helm push buiten gebruik gesteld om te voorkomen dat nieuwe Helm-grafieken naar verouderde Helm-opslagplaatsen worden gepusht.
• Vanaf 30 maart 2025 wordt de CLI-opdrachtgroep az acr helm buiten gebruik gesteld, waardoor alle verouderde mogelijkheden voor Helm-opslagplaatsen in Azure Container Registry worden beëindigd.
• Alle Helm-grafieken die niet zijn opgeslagen als een OCI-artefact, worden op 30 maart 2025 verwijderd uit Azure Container Registry.
• Meer informatie over het vinden van alle Helm-grafieken die zijn opgeslagen in een Helm-opslagplaats: az acr helm list. Als de Helm-grafiek die u gebruikt, wordt weergegeven, wordt deze opgeslagen in een verouderde Helm-opslagplaats en loopt het risico dat deze wordt verwijderd.

Helm 3 of Helm 2?

Als u Helm-grafieken wilt opslaan, beheren en installeren, gebruikt u opdrachten in de Helm CLI. Belangrijke Helm-releases zijn Helm 3 en Helm 2. Zie de veelgestelde vragen over de versie voor meer informatie over de verschillen in versies.

Helm 3 moet worden gebruikt voor het hosten van Helm-grafieken in Azure Container Registry. Met Helm 3 kunt u het volgende doen:

• Kan Helm-grafieken opslaan en beheren in opslagplaatsen in een Azure-containerregister
• Helm-grafieken opslaan in uw register als OCI-artefacten. Azure Container Registry biedt GA-ondersteuning voor OCI-artefacten, waaronder Helm-grafieken.
• Verifieer met uw register met behulp van de helm registry login of az acr login opdracht.
• Opdrachten gebruiken helm om Helm-grafieken in een register te pushen, op te halen en te beheren
• Hiermee helm install installeert u grafieken in een Kubernetes-cluster vanuit het register.

Functieondersteuning

Azure Container Registry biedt ondersteuning voor specifieke Helm-grafiekbeheerfuncties, afhankelijk van of u Helm 3 (huidige) of Helm 2 (afgeschaft) gebruikt.

Functie	Helm 2	Helm 3
Grafieken beheren met behulp van az acr helm opdrachten	✔️
Grafieken opslaan als OCI-artefacten		✔️
Grafieken beheren met behulp van az acr repository opdrachten en de blade Opslagplaatsen in Azure Portal		✔️

Compatibiliteit met grafiekversies

De volgende Helm-grafiekversies kunnen worden opgeslagen in Azure Container Registry en kunnen worden geïnstalleerd door de Helm 2- en Helm 3-clients.

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

Migreren van Helm 2 naar Helm 3

Als u grafieken eerder hebt opgeslagen en geïmplementeerd met Helm 2 en Azure Container Registry, raden we u aan om te migreren naar Helm 3. Zie:

• Helm 2 migreren naar 3 in de Helm-documentatie.
• Migreer uw register om Helm OCI-artefacten op te slaan, verderop in dit artikel

Vereisten

De volgende resources zijn nodig voor het scenario in dit artikel:

• Een Azure-containerregister in uw Azure-abonnement. Maak indien nodig een register met behulp van Azure Portal of de Azure CLI.
• Helm-clientversie 3.7 of hoger : voer deze helm version uit om uw huidige versie te vinden. Zie Helm installeren en upgraden voor meer informatie over het installeren en upgraden van Helm. Als u een upgrade uitvoert van een eerdere versie van Helm 3, raadpleegt u de opmerkingen bij de release.
• Een Kubernetes-cluster waarin u een Helm-grafiek installeert. Maak indien nodig een AKS-cluster met behulp van de Azure CLI, Azure PowerShell of azure Portal.
• Azure CLI versie 2.0.71 of hoger : voer deze opdracht uit az --version om de versie te vinden. Als u Azure CLI 2.0 wilt installeren of upgraden, raadpleegt u Azure CLI 2.0 installeren.

Helm-client instellen

Gebruik de helm version opdracht om te controleren of u Helm 3 hebt geïnstalleerd:

helm version

Notitie

De aangegeven versie moet ten minste 3.8.0 zijn, omdat OCI-ondersteuning in eerdere versies experimenteel was.

Stel de volgende omgevingsvariabelen in voor het doelregister. De ACR_NAME is de naam van de registerresource. Als de ACR-register-URL is myregistry.azurecr.io, stelt u de ACR_NAME in op myregistry

ACR_NAME=<container-registry-name>

Een voorbeeldgrafiek maken

Maak een testgrafiek met behulp van de volgende opdrachten:

mkdir helmtest

cd helmtest
helm create hello-world

Als basisvoorbeeld wijzigt u de map in de templates map en verwijdert u eerst de inhoud daar:

cd hello-world/templates
rm -rf *

Maak in de map een bestand met de templates naam configmap.yaml, door de volgende opdracht uit te voeren:

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

Zie Aan de slag in de Helm-documenten voor meer informatie over het maken en uitvoeren van dit voorbeeld.

Grafiek opslaan in lokaal archief

Wijzig de map in de hello-world submap. Voer vervolgens uit helm package om de grafiek op te slaan in een lokaal archief.

In het volgende voorbeeld wordt de grafiek opgeslagen met de naam en versie in Chart.yaml.

cd ..
helm package .

De uitvoer ziet er ongeveer zo uit:

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

Verifiëren met het register

Voer helm registry login uit om te verifiëren met het register. U kunt registerreferenties doorgeven die geschikt zijn voor uw scenario, zoals referenties van de service-principal, gebruikersidentiteit of een token met opslagplaatsbereik.

• Verifieer met een Microsoft Entra-service-principal met pull- en pushmachtigingen (AcrPush-rol) voor het register.

  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)
  

• Verifieer met uw afzonderlijke Microsoft Entra-identiteit om Helm-grafieken te pushen en op te halen met behulp van een AD-token.

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

• Verifiëren met een token met een bereik van de opslagplaats (preview).

  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)
  

• Geef vervolgens de referenties op aan helm registry login.

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

Grafiek naar register pushen als OCI-artefact

Voer de helm push opdracht uit in de Helm 3 CLI om het grafiekarchief naar de volledig gekwalificeerde doelopslagplaats te pushen. Scheid de woorden in de grafieknamen en gebruik alleen kleine letters en cijfers. In het volgende voorbeeld is helm/hello-worldde naamruimte van de doelopslagplaats en wordt de grafiek getagd 0.1.0:

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

Na een geslaagde push is de uitvoer vergelijkbaar met:

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

Grafieken weergeven in de opslagplaats

Net als bij installatiekopieën die zijn opgeslagen in een Azure-containerregister, kunt u az acr repository-opdrachten gebruiken om de opslagplaatsen weer te geven die als host fungeren voor uw grafieken en grafiektags en -manifesten.

Voer bijvoorbeeld az acr repository show uit om de eigenschappen te bekijken van de opslagplaats die u in de vorige stap hebt gemaakt:

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

De uitvoer ziet er ongeveer zo uit:

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

Voer de opdracht az acr manifest list-metadata uit om details te bekijken van de grafiek die is opgeslagen in de opslagplaats. Voorbeeld:

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

Uitvoer, afgekort in dit voorbeeld, toont een configMediaType van 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"
    ]

Helm-grafiek installeren

Voer helm install uit om de Helm-grafiek te installeren die u naar het register hebt gepusht. De grafiektag wordt doorgegeven met behulp van de --version parameter. Geef een releasenaam op, zoals myhelmtest, of geef de --generate-name parameter door. Voorbeeld:

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

Uitvoer na een geslaagde installatie van de grafiek is vergelijkbaar met:

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

Voer de helm get manifest opdracht uit om de installatie te controleren.

helm get manifest myhelmtest

De opdracht retourneert de YAML-gegevens in het configmap.yaml sjabloonbestand.

Voer helm uninstall deze opdracht uit om de grafiekrelease op uw cluster te verwijderen:

helm uninstall myhelmtest

Grafiek naar lokaal archief ophalen

U kunt eventueel een grafiek uit het containerregister naar een lokaal archief ophalen met behulp van helm pull. De grafiektag wordt doorgegeven met behulp van de --version parameter. Als er een lokaal archief bestaat op het huidige pad, overschrijft deze opdracht het.

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

Grafiek verwijderen uit het register

Als u een grafiek uit het containerregister wilt verwijderen, gebruikt u de opdracht az acr repository delete . Voer de volgende opdracht uit en bevestig de bewerking wanneer u hierom wordt gevraagd:

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

Uw register migreren om Helm OCI-artefacten op te slaan

Als u uw Azure-containerregister eerder hebt ingesteld als een grafiekopslagplaats met behulp van Helm 2 en de az acr helm opdrachten, raden we u aan een upgrade uit te voeren naar de Helm 3-client. Volg vervolgens deze stappen om de grafieken op te slaan als OCI-artefacten in uw register.

Belangrijk

• Nadat u de migratie van een op Index.yaml gebaseerde grafiekopslagplaats in Helm 2-stijl naar OCI-artefactopslagplaatsen hebt voltooid, gebruikt u de Helm CLI en az acr repository opdrachten om de grafieken te beheren. Zie de vorige secties in dit artikel.
• De Helm OCI-artefactopslagplaatsen kunnen niet worden gedetecteerd met behulp van Helm-opdrachten zoals helm search en helm repo list. Zie de Helm-documentatie voor meer informatie over Helm-opdrachten die worden gebruikt voor het opslaan van grafieken als OCI-artefacten.

OCI-ondersteuning inschakelen (standaard ingeschakeld in Helm v3.8.0)

Zorg ervoor dat u de Helm 3-client gebruikt:

helm version

Als u Helm v3.8.0 of hoger gebruikt, is dit standaard ingeschakeld. Als u een lagere versie gebruikt, kunt u ondersteuning voor OCI-ondersteuning inschakelen voor het instellen van de omgevingsvariabele:

export HELM_EXPERIMENTAL_OCI=1

Huidige grafieken weergeven

Vermeld de grafieken die momenteel zijn opgeslagen in het register, hier met de naam myregistry:

helm search repo myregistry

De uitvoer toont de grafieken en grafiekversies:

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

Grafiekarchieven lokaal ophalen

Voor elke grafiek in de opslagplaats haalt u het grafiekarchief lokaal op en noteert u de bestandsnaam:

helm pull myregisry/ingress-nginx
ls *.tgz

Een lokaal grafiekarchief zoals ingress-nginx-3.20.1.tgz wordt gemaakt.

Grafieken pushen als OCI-artefacten naar het register

Meld u aan bij het register:

az acr login --name $ACR_NAME

Push elk grafiekarchief naar het register. Voorbeeld:

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

Nadat u een grafiek hebt gepusht, controleert u of deze is opgeslagen in het register:

az acr repository list --name $ACR_NAME

Nadat u alle grafieken hebt gepusht, verwijdert u desgewenst de Helm 2-achtige grafiekopslagplaats uit het register. Dit vermindert de opslag in uw register:

helm repo remove $ACR_NAME

Volgende stappen

• Zie Helm-grafieken ontwikkelen voor meer informatie over het maken en implementeren van Helm-grafieken.
• Meer informatie over het installeren van toepassingen met Helm in Azure Kubernetes Service (AKS).
• Helm-grafieken kunnen worden gebruikt als onderdeel van het containerbuildproces. Zie Azure Container Registry-taken gebruiken voor meer informatie.