Pull CloudRepo Helm charts from Argo CD and Flux

View as Markdown

Argo CD and Flux are GitOps tools for Kubernetes, and both can install a Helm chart from an OCI registry (Argo CD, Flux). CloudRepo keeps a Helm chart as an OCI artifact in a Docker repository (see Helm Charts (OCI)), so each tool can pull your chart from there with a repository token. This page shows, for each tool, the Kubernetes objects that do it. Each tool’s own documentation defines every field, and the page links it.

Before you start

A chart in a CloudRepo Docker repository. Log in, push and pull on the Helm page shows how to package and push one. The blocks below use that page’s example: the chart docs-helm, version 1.0.0, in the repository your-repo.
A repository token that reaches the repository. Use a Read only token: both tools only pull, and each keeps the token in a Kubernetes Secret. Create it under Repository Tokens, as an account that outlives any one person (see The rule every guide follows). Use a Generic token, whose value starts with crp_v1_: an npm-format token is turned away at this registry.
Your account email address, which is the username (you@example.com below).

The token never goes in a manifest you commit, and never on a command line. Each section below says how its Secret gets the token instead.

Argo CD

Argo CD reads a repository’s details from a Secret in its own namespace, argocd unless you installed it elsewhere (Declarative Setup, Repositories). For a Helm chart in an OCI registry, that Secret sets type: helm and enableOCI: "true" (Declarative Setup, Helm).

Describe the repository

apiVersion: v1
kind: Secret
metadata:
  name: cloudrepo-helm
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  name: cloudrepo
  type: helm
  enableOCI: "true"
  url: your-org.mycloudrepo.io/repositories/your-repo
  username: you@example.com

The label argocd.argoproj.io/secret-type: repository marks the Secret as a repository, as in Argo CD’s own examples.
name, type and url are the three fields Argo CD requires of a Helm repository Secret, and enableOCI is set to "true" for charts from an OCI registry.
url is the repository address that helm push takes on the Helm page, without oci://. Argo CD’s example of a public OCI chart says of its address: “the oci:// syntax is not included” (Helm user guide).
username is your account email address.

There is no password line in this manifest, on purpose.

Give the Secret the token

Argo CD takes the password from the password key of this same Secret. The password is the repository token. Put it there by one of these routes, so it is in no manifest you commit and on no command line:

From a file. Save the Secret above with a password line added in a file that stays out of Git, apply it with kubectl apply -f, and delete the file. This is the form of Argo CD’s own example, a Secret with username and password under stringData.
From a sealed secret. Argo CD’s documentation suggests bitnami-labs/sealed-secrets to store an encrypted Secret definition as a Kubernetes manifest. It warns that the labels are removed and have to be added again, as the Sealed Secrets README describes, so the sealed Secret must still end up with the argocd.argoproj.io/secret-type: repository label.
From an external secret. An operator that writes the Secret from your secret store, such as External Secrets Operator. The Secret it writes needs the same label and every key above, and a password key holding the token.

Create the Application

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: docs-helm
  namespace: argocd
spec:
  project: default
  source:
    chart: docs-helm
    repoURL: your-org.mycloudrepo.io/repositories/your-repo
    targetRevision: 1.0.0
  destination:
    name: in-cluster
    namespace: default

chart is the chart’s name and targetRevision its version: the name and the version that helm pull takes on the Helm page. For an application from a Helm repository, Argo CD requires chart where a Git source has path (Declarative Setup, Applications).
repoURL is the same address as the Secret’s url, again without oci://.
The Application’s namespace is the one your Argo CD runs in, typically argocd.
destination is the shape of Argo CD’s own example of a public OCI chart (Helm user guide): the cluster Argo CD runs in, and the namespace the chart installs into.

Flux

Flux reads a registry login from a Secret that a HelmRepository names with secretRef, and a HelmRelease installs a chart from that HelmRepository (HelmRepository, HelmRelease).

Flux’s documentation marks the oci type of HelmRepository as in maintenance mode, and points to its OCIRepository API for improved support for OCI Helm charts (HelmRepository, Type). This page shows the HelmRepository form.

Create the Secret

secretRef names a Secret in the same namespace as the HelmRepository. For an OCI HelmRepository, Flux accepts a Secret of type kubernetes.io/dockerconfigjson (HelmRepository, Secret reference). Make that Secret from a Docker login with the token on standard input, as under Create the image pull secret on the Docker pull page, with two changes. Add --namespace default to its kubectl create secret command (or the namespace you put the HelmRepository in), so the Secret is beside the HelmRepository below. Keep the Secret’s name, cloudrepo: the secretRef below uses it.

Flux’s own command for an OCI login Secret, flux create secret oci, takes the password as a flag (flux create secret oci), which puts the token on the command line. This page does not use it.

Add the repository

apiVersion: source.toolkit.fluxcd.io/v1
kind: HelmRepository
metadata:
  name: cloudrepo
  namespace: default
spec:
  type: "oci"
  interval: 5m0s
  url: oci://your-org.mycloudrepo.io/repositories/your-repo
  secretRef:
    name: cloudrepo

type: "oci" makes it an OCI Helm repository. Flux’s choices for type are default for a Helm HTTP/S repository and oci for an OCI Helm repository.
url starts with oci:// and ends at the repository, the address that helm push takes on the Helm page. Flux expects an OCI url to point to a registry repository (HelmRepository, URL).
secretRef.name is the Secret made above.
interval is set as in Flux’s own OCI example, though Flux’s documentation says an OCI HelmRepository ignores it.

Install the chart

apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: docs-helm
  namespace: default
spec:
  interval: 15m
  chart:
    spec:
      chart: docs-helm
      version: "1.0.0"
      sourceRef:
        kind: HelmRepository
        name: cloudrepo
      interval: 5m

chart is the chart’s name alone, as Flux’s documentation says for a HelmRepository source, and version is the version that helm pull takes on the Helm page (HelmChart, Chart and Version). Left out, version defaults to the latest version of the chart.
sourceRef names the HelmRepository above, in the same namespace.
The two interval values are those of Flux’s own example of a HelmRelease from a HelmRepository (HelmRelease).

If a chart does not sync

Rule out the token and the address with Helm first. Log in and pull the same chart with the same token, as under Log in, push and pull on the Helm page. If Helm cannot, the Troubleshooting section there lists what CloudRepo answers for a refused token, a wrong address and a chart it cannot find.

If Helm pulls the chart and the tool does not, the token and the address work at CloudRepo with Helm’s client, and the difference is in the tool’s setup or in how the tool reaches the registry. Check your objects against the tool’s pages linked above, and email support@cloudrepo.io with the tool, its version, and the error it reports (never the token).