Skip to content

Migrating the existing Helm charts in Azure Container Registry to OCI Protocol and reconfigure ArgoCD to use the OCI protocol

Disclaimer: This guide is for educational purposes only. The author is not responsible for any damage and costs caused by following this guide.

Explanation: All commands are written separately from their output, so the reader can do simply copy/paste.

Prerequisites

  • Azure CLI installed
  • Enough permissions to update push and pull images/charts from Azure Container Registry
  • Helm in a version 3.8 or newer installed
  • skopeo installed
  • jq installed
  • ArgoCD installed and configured
  • Azure Container Registry (ACR) set up

Steps

1. Install required tools

Since I'm running on a Mac, I'll use Homebrew to install the required tools. If you're running on a different OS, you can install the tools using the instructions provided on their respective websites.

Command:

brew install azure-cli helm skopeo argocd jq

Output:

Very long and depends on the tools and their version you have already installed.

Verify the installation and versions by running the following commands:

Command:

az --version

Output:

azure-cli                         2.65.0

core                              2.65.0
telemetry                          1.1.0

Extensions:
account                            0.2.5
aks-preview                      0.5.154
storage-preview                  1.0.0b1

Dependencies:
msal                              1.31.0
azure-mgmt-resource               23.1.1

Python location '/usr/local/Cellar/azure-cli/2.65.0/libexec/bin/python'
Extensions directory '/Users/tbosnjak/.azure/cliextensions'

Python (Darwin) 3.11.10 (main, Sep  7 2024, 01:03:31) [Clang 15.0.0 (clang-1500.3.9.4)]

Legal docs and information: aka.ms/AzureCliLegal


Your CLI is up-to-date.

Command:

helm version

Output:

version.BuildInfo{Version:"v3.16.2", GitCommit:"13654a52f7c70a143b1dd51416d633e1071faffb", GitTreeState:"dirty", GoVersion:"go1.23.2"}

Command:

skopeo --version

Output:

skopeo version 1.16.1

Command:

argocd version

Output:

argocd: v2.12.4+27d1e64
  BuildDate: 2024-09-26T09:35:58Z
  GitCommit: 27d1e641b6ea99d9f4bf788c032aeaeefd782910
  GitTreeState: clean
  GoVersion: go1.23.1
  Compiler: gc
  Platform: darwin/amd64
argocd-server: v2.11.2+25f7504

Command:

jq --version

Output:

jq-1.7.1

2. Login to Azure and set the respective subscription

Since I work on a terminal on remote server and there is no browser, I'll use the device code login method to login to Azure.

az login --use-device-code

Setting the subscription can be done using a subscription ID or the subscription name. I'll use the subscription id, because I set myself a multiple aliases in the form.

alias set_az_sub_name="az account set --subscription <subscription-id>"

Having such aliases makes it easier to switch between subscriptions.

Setting the subscription can be done using the alias.

set_az_sub_name

3. Add the exiting Azure Container Registry to helm

Command:

az acr helm repo add --name <acr-name>

Output:

This command has been deprecated and will be removed in future release. Use 'Helm v3 commands' instead. Learn more about storing Helm charts at https://aka.ms/acr/helm
This command is implicitly deprecated because command group 'acr helm' is deprecated and will be removed in a future release. Use 'Helm v3 commands' instead.
"<acr-name>" has been added to your repositories

4. List all the charts in the Azure Container Registry

Command:

helm repo update

Output:

Hang tight while we grab the latest from your chart repositories...
...Successfully got an update from the "actions-runner-controller" chart repository
...Successfully got an update from the "<acr-name>" chart repository
Update Complete. ⎈Happy Helming!⎈

Command:

```sh
helm search repo <acr-name> --versions --output json | jq '.[] | {name: .name, version: .version}'

Output:

{
  "name": "chart1",
  "version": "0.1.0"
}
{
  "name": "chart2",
  "version": "0.1.0"
}
{
  "name": "chart3",
  "version": "0.1.0"
}

5. Pull the charts from the Azure Container Registry

Now here a very long command that will pull the charts from the Azure Container Registry. The command will pull the charts and save them in the current directory. To keep your filesystem clean, you can create a new temp directory and save the charts there. Just be sure that you have enough space on your disk.

I know the command is long, but it's a one-liner and (trust me, I'm an engineer :)) it works.

Commands:

mkdir -p /tmp/charts
cd /tmp/charts
helm search repo <acr-name> --versions --output json | jq -r '.[] | ["helm pull \(.name) --version \(.version)"] | @tsv' | tr '\n' '\0' | xargs -0 -n1 -P5 sh -c

Command:

ls -1

Output:

chart1-0.1.0.tgz
chart2-0.1.0.tgz
chart2-0.1.1.tgz
...

6. Login helm to the ACR

To be able to push the charts to the Azure Container Registry, you need to login helm to the ACR.

First set the environment variables for the ACR name, user name and password.

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

Now login to the ACR:

Command:

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

Output:

WARNING: Using --password via the CLI is insecure. Use --password-stdin.
Login Succeeded

The warning from above can be ignored.

7. Push the Helm charts to OCI artifact repository

Since all our charts are already in the helm v3 format, we can push them to the OCI artifact repository.

Command:

for chart in $(ls -1); do
    helm push $chart oci://$ACR_NAME.azurecr.io
done

The command from above should produce the following output:

Pushed: <acr-name>.azurecr.io/chart1:0.1.0
Digest: sha256:8d2a27f179318eb03a5daeb2bfb085d2dcaf90bc1999365a5d066b215c9c6d95
Pushed: <acr-name>.azurecr.io/chart1:0.1.0
Digest: sha256:88fbb7f75734805418475ecbb78803f7ee5c0cd8a4704d99f8986b850fdcd735

8. Configure ArgoCD to Use ACR

Update your ArgoCD repository configuration to use the ACR:

apiVersion: v1
data:
  accounts.admin: login
  admin.enabled: "true"
  application.instanceLabelKey: argocd.argoproj.io/instance
  exec.enabled: "true"
  oidc.config: |
    name: AzureAD
    issuer:  https://login.microsoftonline.com/<CENSORED>/v2.0
    clientID: $oidc.azure.clientID
    clientSecret: $oidc.azure.clientSecret
    requestedIDTokenClaims:
      groups:
        essential: true
    requestedScopes:
      - openid
      - profile
      - email
  repositories: |
    - enableOCI: true
      name: org-helm
      passwordSecret:
        key: password
        name: acr-central-secret
      type: helm
      url: <acr-name>.azurecr.io/helm
      usernameSecret:
        key: username
        name: acr-central-secret
    - enableOCI: true
      name: org-cust-helm
      passwordSecret:
        key: password
        name: customer-acr-central-secret
      type: helm
      url: <acr-name-2>.azurecr.io/helm
      usernameSecret:
        key: username
        name: customer-acr-central-secret
    - url: https://github.com/<your-organization>/<your-reponame>.git
  repository.credentials: |
    - passwordSecret:
        key: password
        name: ghe-central-secret
      url: https://github.com/
      usernameSecret:
        key: username
        name: ghe-central-secret

5. Create an Application in ArgoCD

Define your application to use the OCI repository:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
    name: my-app
    namespace: argocd
spec:
    source:
        repoURL: oci://<your-acr-name>.azurecr.io/helm/<your-repo>
        targetRevision: <tag>
    destination:
        server: https://kubernetes.default.svc
        namespace: <your-namespace>
    project: default

6. Sync the Application

Sync your application in ArgoCD:

sh argocd app sync my-app

Your can verify that the all applications are in sync by running the following command:

Command:

argocd app list

Output:

NAME                                                       CLUSTER                         NAMESPACE        PROJECT                 STATUS   HEALTH   SYNCPOLICY  CONDITIONS       REPO                                                                                     PATH                        TARGET
org-gitops/02-customer-repo                                https://kubernetes.default.svc  org-gitops       org-customer-repo-sync  Synced   Healthy  Auto-Prune  <none>           https://github.com/<organization>/customer-org-infra.git                                 services-gitops/cl1         master
org-gitops/argocd                                          https://kubernetes.default.svc  org-gitops       org-infra-apps-prj      Synced   Healthy  Auto-Prune  <none>           <acr-name>.azurecr.io/helm                                                                                            6.1.0
org-gitops/azure-aks-pod-identity                          https://kubernetes.default.svc  kube-system      org-infra-apps-prj      Synced   Healthy  Auto-Prune  <none>           <acr-name>.azurecr.io/helm                                                                                            4.1.8
...

Conclusion

You have successfully migrated your Azure Container Registry to be used with ArgoCD using the OCI protocol.