Mendorong dan menarik bagan Helm ke registri kontainer Azure

  • Artikel

Untuk mengelola dan menerapkan aplikasi dengan cepat untuk Kubernetes, kamu dapat menggunakan pengelola paket Helm sumber terbuka. Dengan Helm, paket aplikasi didefinisikan sebagai bagan, yang dikumpulkan dan disimpan dalam repositori bagan Helm.

Artikel ini menunjukkan kepada Anda cara menghosting repositori bagan Helm di registri kontainer Azure, menggunakan perintah Helm 3 dan menyimpan bagan sebagai artefak OCI. Dalam banyak situasi, Anda akan membuat dan mengunggah bagan Anda sendiri untuk aplikasi yang Anda kembangkan. Untuk informasi selengkapnya tentang cara membuat bagan Helm Anda sendiri, lihat Panduan Pengembang Templat Bagan. Anda juga dapat menyimpan bagan Helm yang ada dari repositori Helm lain.

Penting

Artikel ini telah diperbarui dengan perintah Helm 3. Helm 3.7 mencakup perubahan pada perintah CLI Helm serta dukungan OCI yang diperkenalkan dalam versi Helm 3 yang sebelumnya. Berdasarkan desain helm bergerak maju seiring versi. Sebaiknya gunakan 3.7.2 atau versi yang lebih baru.

Helm 3 atau Helm 2?

Untuk menyimpan, mengelola, dan menginstal bagan Helm, Anda menggunakan perintah di CLI Helm. Rilis utama Helm termasuk Helm 3 dan Helm 2. Untuk detail tentang perbedaan versinya, lihat FAQ versi.

Helm 3 harus digunakan untuk meng-host bagan Helm di Azure Container Registry. Dengan Helm 3, Anda:

  • Dapat menyimpan dan mengelola bagan Helm di repositori dalam registri kontainer Azure
  • Menyimpan bagan Helm dalam registri Anda sebagai artefak OCI. Azure Container Registry menyediakan dukungan GA untuk artefak OCI, termasuk bagan Helm.
  • Autentikasi dengan registri Anda menggunakan perintah helm registry login atau az acr login.
  • Gunakan perintah helm untuk mendorong, menarik, dan mengelola bagan Helm dalam registri
  • Gunakan helm install untuk memasang bagan ke kluster Kube dari registri.

Dukungan fitur

Azure Container Registry mendukung fitur manajemen bagan Helm tertentu tergantung pada apakah Anda menggunakan Helm 3 (saat ini) atau Helm 2 (tidak digunakan lagi).

Fitur Helm 2 Helm 3
Mengelola bagan menggunakan perintah az acr helm ✔️
Menyimpan bagan sebagai artefak OCI ✔️
Mengelola bagan menggunakan perintah az acr repository dan blade Repositori di portal Microsoft Azure ✔️

Catatan

Pada Helm 3, perintah az acr helm yang digunakan dengan klien Helm 2 sedang tidak digunakan lagi. Pemberitahuan minimal 3 bulan akan diberikan sebelum penghapusan perintah.

Kompatibilitas versi bagan

Versi bagan Helm berikut dapat disimpan di Azure Container Registry dan dapat diinstal oleh klien Helm 2 dan Helm 3.

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

Memigrasikan dari Helm 2 ke Helm 3

Jika sebelumnya Anda telah menyimpan dan menyebarkan bagan menggunakan Helm 2 dan Azure Container Registry, sebaiknya migrasikan ke Helm 3. Lihat:

Prasyarat

Sumber daya berikut diperlukan untuk kondisi dalam artikel ini:

Menyiapkan klien Helm

Gunakan perintah helm version untuk memverifikasi bahwa Anda telah menginstal Helm 3:

helm version

Catatan

Versi yang ditunjukkan harus minimal 3.8.0, karena dukungan OCI di versi sebelumnya bersifat eksperimental.

Atur variabel lingkungan berikut untuk registri target. ACR_NAME adalah nama sumber daya registri. Jika url registri ACR adalah myregistry.azurecr.io, atur ACR_NAME ke myregistry

ACR_NAME=<container-registry-name>

Membuat bagan sampel

Buat bagan uji menggunakan perintah berikut:

mkdir helmtest

cd helmtest
helm create hello-world

Sebagai contoh dasar, ubah direktori ke folder templates dan hapus terlebih dahulu isinya:

cd hello-world/templates
rm -rf *

Di folder templates, buat file yang disebut configmap.yaml, dengan menjalankan perintah berikut ini:

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

Untuk informasi selengkapnya tentang membuat dan menjalankan contoh ini, lihat Memulai di Helm Docs.

Menyimpan bagan ke arsip lokal

Mengubah direktori menjadi subdirektori hello-world. Lalu, jalankan helm package untuk menyimpan bagan ke arsip lokal.

Dalam contoh berikut, bagan disimpan dengan nama dan versi di Chart.yaml.

cd ..
helm package .

Output kurang lebih seperti:

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

Autentikasi dengan registri

Jalankan helm registry login untuk mengautentikasi dengan registri. Anda dapat meneruskan informasi masuk registri yang sesuai untuk skenario Anda, seperti kredensial perwakilan layanan, identitas pengguna, atau token cakupan repositori.

  • Autentikasi dengan perwakilan layanan Microsoft Entra dengan izin tarik dan dorong (peran AcrPush) ke registri . 
    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)
  • Autentikasi dengan identitas Microsoft Entra individual Anda untuk mendorong dan menarik bagan Helm menggunakan token AD. 
    USER_NAME="00000000-0000-0000-0000-000000000000"
PASSWORD=$(az acr login --name $ACR_NAME --expose-token --output tsv --query accessToken)
  • Mengautentikasi dengan token cakupan repositori (Pratinjau). 
    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)
  • Kemudian berikan kredensial ke helm registry login. 
    helm registry login $ACR_NAME.azurecr.io \
  --username $USER_NAME \
  --password $PASSWORD

Melakukan pendorongan bagan ke registri sebagai artefak OCI

Jalankan perintah helm push di CLI Helm 3 untuk mendorong arsip bagan ke repositori target yang telah memenuhi syarat. Pisahkan kata-kata dalam nama bagan dan gunakan hanya huruf kecil dan angka. Dalam contoh berikut, namespace layanan repositori target adalah helm/hello-world, dan bagan ditandai sebagai 0.1.0:

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

Setelah dorongan berhasil, output kurang lebih seperti:

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

Daftar bagan di repositori

Seperti halnya gambar yang disimpan dalam registri kontainer Azure, Anda dapat menggunakan perintah repositori az acr untuk menunjukkan repositori yang meng-hosting bagan Anda, serta tag dan manifes bagan.

Misalnya, jalankan tampilkan repositori az acr untuk melihat properti repositori yang Anda buat di langkah sebelumnya:

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

Output kurang lebih seperti:

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

Jalankan perintah az acr manifest list-metadata untuk melihat detail bagan yang disimpan di repositori. Contohnya:

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

Output, yang disingkat dalam contoh ini, menunjukkan configMediaType dari 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"
    ]

Memasang bagan Helm

Jalankan helm install untuk memasang bagan Helm yang telah Anda dorong ke registri. Tag bagan diteruskan dengan menggunakan parameter --version. Tentukan nama rilisan seperti myhelmtest, atau lewati parameter --generate-name. Contohnya:

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

Output setelah pemasangan bagan berhasil kurang lebih seperti:

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

Untuk memverifikasi pemasangan, jalankan perintah helm get manifest.

helm get manifest myhelmtest

Perintah tersebut akanmengembalikan data YAML dalam file templat configmap.yaml Anda.

Jalankan helm uninstall untuk menghapus instalasi rilisan bagan pada kluster Anda:

helm uninstall myhelmtest

Melakukan penarikan bagan ke arsip lokal

Anda dapat secara opsional menarik bagan dari registri kontainer ke arsip lokal dengan menggunakan helm pull. Tag bagan diteruskan dengan menggunakan parameter --version. Jika ada arsip lokal di jalur saat ini, perintah ini akan menimpanya.

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

Menghapus bagan dari registri

Untuk menghapus bagan dari registri kontainer, gunakan perintah hapus repositori az acr. Jalankan perintah berikut dan konfirmasikan operasi ketika diminta:

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

Memigrasikan registri Anda untuk menyimpan artefak OCI Helm

Jika sebelumnya Anda menyiapkan registri kontainer Azure Anda sebagai repositori bagan menggunakan Helm 2 dan perintah az acr helm, sebaiknya Anda memutakhirkan ke klien Helm 3. Kemudian, ikuti langkah-langkah ini untuk menyimpan bagan sebagai artefak OCI di registri Anda.

Penting

  • Setelah Anda menyelesaikan migrasi dari repositori bagan bergaya Helm 2 (berbasis index.yaml) ke repositori artefak OCI, gunakan CLI Helm dan perintah az acr repository untuk mengelola bagan. Lihat bagian sebelumnya dalam artikel ini.
  • Repositori artefak OCI Helm tidak dapat ditemukan menggunakan perintah Helm seperti helm search dan helm repo list. Untuk informasi selengkapnya tentang perintah Helm yang digunakan untuk menyimpan bagan sebagai artefak OCI, lihat dokumentasi Helm.

Mengaktifkan dukungan OCI (diaktifkan secara default di Helm v3.8.0)

Pastikan Anda menggunakan klien Helm 3:

helm version

Jika Anda menggunakan Helm v3.8.0 atau lebih tinggi, ini diaktifkan secara default. Jika Anda menggunakan versi yang lebih rendah, Anda dapat mengaktifkan pengaturan dukungan OCI pada variabel lingkungan:

export HELM_EXPERIMENTAL_OCI=1

Cantumkan bagan saat ini

Cantumkan bagan yang saat ini disimpan dalam registri, di sini bernama myregistry:

helm search repo myregistry

Output memperlihatkan bagan dan versi bagan:

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

Melakukan penarikan arsip bagan secara lokal

Untuk setiap bagan dalam repositori, tarik arsip bagan secara lokal, dan perhatikan nama file:

helm pull myregisry/ingress-nginx
ls *.tgz

Arsip bagan lokal, misalnya ingress-nginx-3.20.1.tgz dibuat.

Melakukan pendorongan bagan sebagai artefak OCI ke registri

Masuk ke registri:

az acr login --name $ACR_NAME

Dorong setiap arsip bagan ke registri. Contoh:

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

Setelah mendorong bagan, konfirmasikan bahwa bagan sudah tersimpan di registri:

az acr repository list --name $ACR_NAME

Setelah mendorong semua bagan, hapus repositori bagan bergaya Helm 2 secara opsional dari registri. Melakukan hal ini dapat mengurangi penyimpanan di registri Anda:

helm repo remove $ACR_NAME

Langkah berikutnya