Azure 컨테이너 레지스트리에 Helm 차트 푸시 및 끌어오기

Kubernetes용 애플리케이션을 빠르게 관리하고 배포하려는 경우 오픈 소스 Helm 패키지 관리자를 사용할 수 있습니다. Helm 사용 시 애플리케이션 패키지는 Helm 차트 리포지토리에 수집되고 저장되는 차트로 정의됩니다.

이 문서에서는 Helm 3 명령을 사용하고 차트를 OCI 아티팩트로 저장하여 Azure Container Registry에서 Helm 차트 리포지토리를 호스트하는 방법을 보여 줍니다. 대부분의 시나리오에서는 개발하는 애플리케이션용으로 차트를 직접 작성하여 업로드합니다. 사용자 고유의 Helm 차트를 작성하는 방법에 대한 자세한 내용은 차트 템플릿 개발자 가이드를 참조하세요. 다른 Helm 리포지토리의 기존 Helm 차트를 저장할 수도 있습니다.

참고 항목

이 문서는 Helm 3 명령으로 업데이트되었습니다. Helm 3.7에는 Helm CLI 명령에 대한 변경 내용과 이전 버전의 Helm 3에서 도입된 OCI 지원이 포함됩니다. helm은 버전 업데이트와 함께 설계되었습니다. 3.7.2 이상을 사용하는 것이 좋습니다.

Important

• 2020년 11월에 Helm 2의 수명이 종료되었습니다. 2025년 3월 30일부터 Azure Container Registry는 더 이상 Helm 2를 지원하지 않습니다. 따라서 레거시의 "Helm 리포지토리" 기능도 더 이상 지원되지 않습니다. Helm 3으로 즉시 전환하는 것이 좋습니다.
• 2025년 1월 21일부터 새 Helm 차트를 레거시 Helm 리포지토리로 푸시하지 않도록 CLI 명령 az acr helm push 가 사용 중지됩니다.
• 2025년 3월 30일부터 CLI 명령 그룹 az acr helm이 사용 중지되며 Azure Container Registry의 모든 레거시 Helm 리포지토리 기능이 사용 중지됩니다.
• OCI 아티팩트로 저장되지 않은 모든 Helm 차트는 2025년 3월 30일에 Azure Container Registry에서 삭제됩니다.
• Helm 리포지토리에 저장된 모든 Helm 차트를 찾는 방법은 az acr Helm list에서 확인합니다. 사용 중인 Helm 차트가 나열되어 있는 경우 해당 차트는 레거시 Helm 리포지토리에 저장되어 삭제될 위험이 있습니다.

Helm 3 또는 Helm 2?

Helm 차트를 저장, 관리 및 설치하려면 Helm CLI에서 명령을 사용합니다. 주요 Helm 릴리스에는 Helm 3 및 Helm 2가 포함됩니다. 버전 차이점에 대한 자세한 내용은 버전 FAQ를 참조하세요.

Helm 3은 Azure Container Registry에서 Helm 차트를 호스트하는 데 사용해야 합니다. Helm 3을 사용하여 다음을 수행합니다.

• Azure Container Registry의 리포지토리에 Helm 차트를 저장하고 관리할 수 있습니다.
• Helm 차트를 레지스트리에 OCI 아티팩트로 저장합니다. Azure Container Registry는 Helm 차트를 포함하여 OCI 아티팩트에 대한 GA 지원을 제공합니다.
• helm registry login 또는 az acr login 명령을 사용하여 레지스트리로 인증합니다.
• helm 명령을 사용하여 레지스트리에서 Helm 차트 푸시, 풀 및 관리
• helm install을 사용하여 레지스트리에서 Kubernetes 클러스터에 차트를 설치합니다.

기능 지원

Azure Container Registry는 Helm 3(현재) 또는 Helm 2(더 이상 사용되지 않음)를 사용하는지 여부에 따라 특정 Helm 차트 관리 기능을 지원합니다.

기능	Helm 2	Helm 3
az acr helm 명령을 사용하여 차트 관리	✔️
차트를 OCI 아티팩트로 저장		✔️
Azure Portal에서 az acr repository 명령과 리포지토리 블레이드를 사용하여 차트 관리		✔️

차트 버전 호환성

다음 Helm 차트 버전은 Azure Container Registry에 저장할 수 있으며 Helm 2 및 Helm 3 클라이언트에서 설치할 수 있습니다.

버전	Helm 2	Helm 3
apiVersion v1	✔️	✔️
apiVersion v2		✔️

Helm 2에서 Helm 3으로 마이그레이션

이전에 Helm 2 및 Azure Container Registry를 사용하여 차트를 저장하고 배포한 경우 Helm 3으로 마이그레이션하는 것이 좋습니다. 참조

• Helm 문서의 Helm 2에서 3으로 마이그레이션
• 레지스트리를 마이그레이션하여 Helm OCI 아티팩트 저장(이 문서 뒷부분)

필수 조건

이 문서의 시나리오에는 다음 리소스가 필요합니다.

• Azure 구독의 Azure 컨테이너 레지스트리 필요한 경우 Azure Portal 또는 Azure CLI를 사용하여 레지스트리를 만듭니다.
• Helm 클라이언트 버전 3.7 이상 - helm version을 실행하여 현재 버전을 찾습니다. Helm을 설치하고 업그레이드하는 방법에 대한 자세한 내용은 Helm 설치를 참조하세요. 이전 버전의 Helm 3에서 업그레이드하는 경우 릴리스 정보를 검토합니다.
• Helm 차트를 설치하는 Kubernetes 클러스터 필요한 경우 AKS 클러스터 Azure CLI 사용, Azure PowerShell 사용 또는 Azure Portal 사용을 만듭니다.
• Azure CLI 버전 2.0.71 이상 - az --version을 실행하여 버전을 확인합니다. 설치 또는 업그레이드해야 하는 경우 Azure CLI 설치를 참조하세요.

Helm 클라이언트 설정

helm version 명령을 사용하여 Helm 3을 설치했는지 확인합니다.

helm version

참고 항목

이전 버전의 OCI 지원이 실험적이었기 때문에 표시된 버전은 3.8.0 이상이어야 합니다.

대상 레지스트리에 대해 다음 환경 변수를 설정합니다. ACR_NAME은 레지스트리 리소스 이름입니다. ACR 레지스트리 URL이 myregistry.azurecr.io인 경우 ACR_NAME을 myregistry로 설정합니다.

ACR_NAME=<container-registry-name>

샘플 차트 만들기

다음 명령을 사용하여 테스트 차트를 만듭니다.

mkdir helmtest

cd helmtest
helm create hello-world

기본 예제로 디렉터리를 templates 폴더로 변경하고 해당 콘텐츠를 먼저 삭제합니다.

cd hello-world/templates
rm -rf *

templates 폴더에서 다음 명령을 실행하여 configmap.yaml이라는 파일을 만듭니다.

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

이 예제를 만들고 실행하는 방법에 대한 자세한 내용은 Helm 문서에서 시작을 참조하세요.

로컬 보관 파일에 차트 저장

디렉터리를 hello-world 하위 디렉터리로 변경합니다. 그런 다음 helm package를 실행하여 차트를 로컬 보관 파일에 저장합니다.

다음 예제에서 차트는 Chart.yaml의 이름 및 버전을 사용하여 저장됩니다.

cd ..
helm package .

출력은 다음과 비슷합니다.

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

레지스트리로 인증

helm registry login을 실행하여 레지스트리로 인증합니다. 서비스 주체 자격 증명, 사용자 ID 또는 리포지토리 범위 토큰과 같은 시나리오에 적합한 레지스트리 자격 증명을 전달할 수 있습니다.

• 레지스트리에 대한 끌어오기 및 푸시 권한이 있는 Microsoft Entra 서비스 주체(AcrPush 역할)를 사용하여 인증합니다.

  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)
  

• AD 토큰을 사용하여 Helm 차트를 푸시하고 끌어오려면 개별 Microsoft Entra ID로 인증합니다.

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

• 리포지토리 범위 토큰으로 인증합니다(미리 보기).

  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)
  

• 그런 다음 자격 증명을 helm registry login에 제공합니다.

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

OCI 아티팩트로 레지스트리에 차트 푸시

Helm 3 CLI에서 helm push 명령을 실행하여 차트 보관 파일을 정규화된 대상 리포지토리로 푸시합니다. 차트 이름에서 단어를 구분하고 소문자와 숫자만 사용합니다. 다음 예제에서 대상 리포지토리 네임스페이스는 helm/hello-world이고 차트는 0.1.0으로 태그가 지정됩니다.

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

푸시가 성공적으로 완료되면 출력은 다음과 유사합니다.

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

리포지토리의 차트 목록 표시

Azure 컨테이너 레지스트리에 저장된 이미지와 마찬가지로 az acr repository 명령을 사용하여 차트를 호스팅하는 리포지토리와 차트 태그 및 매니페스트를 표시할 수 있습니다.

예를 들어 az acr repository show를 실행하여 이전 단계에서 만든 리포지토리의 속성을 볼 수 있습니다.

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

출력은 다음과 비슷합니다.

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

az acr manifest list-metadata 명령을 실행하여 리포지토리에 저장된 차트의 세부 정보를 확인합니다. 예시:

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

이 예제의 축약된 출력에는 application/vnd.cncf.helm.config.v1+json의 configMediaType이 표시됩니다.

[
  {
    [...]
    "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 차트 설치

helm install을 실행하여 레지스트리에 푸시한 Helm 차트를 설치합니다. 차트 태그는 --version 매개 변수를 사용하여 전달됩니다. myhelmtest와 같은 릴리스 이름을 지정하거나 --generate-name 매개 변수를 전달합니다. 예시:

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

성공적인 차트 설치 후의 출력은 다음과 유사합니다.

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

설치를 확인하려면 helm get manifest 명령을 실행합니다.

helm get manifest myhelmtest

명령은 configmap.yaml 템플릿 파일의 YAML 데이터를 반환합니다.

helm uninstall을 실행하여 클러스터에서 차트 릴리스를 제거합니다.

helm uninstall myhelmtest

로컬 보관 파일로 차트 끌어오기

필요에 따라 helm pull을 사용하여 컨테이너 레지스트리에서 로컬 보관 파일로 차트를 끌어올 수 있습니다. 차트 태그는 --version 매개 변수를 사용하여 전달됩니다. 로컬 보관 파일이 현재 경로에 있는 경우 이 명령은 파일을 덮어씁니다.

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

레지스트리에서 차트 삭제

컨테이너 레지스트리에서 차트를 삭제하려면 az acr repository delete 명령을 사용합니다. 다음 명령을 실행하고 메시지가 표시되면 작업을 확인합니다.

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

Helm OCI 아티팩트를 저장하도록 레지스트리 마이그레이션

이전에 Helm 2 및 az acr helm 명령을 사용하여 Azure Container Registry를 차트 리포지토리로 설정한 경우 Helm 3 클라이언트로 업그레이드하는 것이 좋습니다. 그런 후 다음 단계에 따라 차트를 레지스트리에 OCI 아티팩트로 저장합니다.

Important

• Helm 2 스타일(index.yaml 기반) 차트 리포지토리에서 OCI 아티팩트 리포지토리로 마이그레이션을 완료한 후 Helm CLI 및 az acr repository 명령을 사용하여 차트를 관리합니다. 이 문서의 이전 섹션을 참조하세요.
• Helm OCI 아티팩트 리포지토리는 helm search 및 helm repo list와 같은 Helm 명령을 사용하여 검색할 수 없습니다. 차트를 OCI 아티팩트로 저장하는 데 사용되는 Helm 명령에 대한 자세한 내용은 Helm 문서를 참조하세요.

OCI 지원 사용(Helm v3.8.0에서 기본적으로 사용하도록 설정됨)

Helm 3 클라이언트를 사용 중인지 확인합니다.

helm version

Helm v3.8.0 이상을 사용하는 경우 기본적으로 사용하도록 설정됩니다. 더 낮은 버전을 사용하는 경우 환경 변수를 설정하여 OCI 지원을 사용하도록 설정할 수 있습니다.

export HELM_EXPERIMENTAL_OCI=1

현재 차트 나열

현재 myregistry라는 이름의 레지스트리에 저장된 차트를 나열합니다.

helm search repo myregistry

출력에 차트 및 차트 버전이 표시됩니다.

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

차트 보관 파일을 로컬로 끌어오기

리포지토리의 각 차트에 대해 차트 보관 파일을 로컬로 끌어오고 파일 이름을 기록해 둡니다.

helm pull myregisry/ingress-nginx
ls *.tgz

로컬 차트 보관 파일(예: ingress-nginx-3.20.1.tgz )이 만들어집니다.

레지스트리에 OCI 아티팩트로 차트 푸시

레지스트리에 로그인:

az acr login --name $ACR_NAME

각 차트 보관 파일을 레지스트리에 푸시합니다. 예시:

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

차트를 푸시한 후 레지스트리에 저장되었는지 확인합니다.

az acr repository list --name $ACR_NAME

모든 차트를 푸시한 후 선택적으로 레지스트리에서 Helm 2 스타일 차트 리포지토리를 제거합니다. 이렇게 하면 레지스트리의 스토리지가 줄어듭니다.

helm repo remove $ACR_NAME

다음 단계

• Helm 차트를 만들고 배포하는 방법에 대한 자세한 내용은 Helm 차트 개발을 참조하세요.
• AKS(Azure Kubernetes Service)에서 Helm을 사용하여 애플리케이션을 설치하는 방법에 대해 자세히 알아보세요.
• Helm 차트는 컨테이너 빌드 프로세스의 일부로 사용할 수 있습니다. 자세한 내용은 Azure Container Registry 작업 사용을 참조하세요.