feat: improve Helm documentation (#22859)

sabre1041 · web-flow · commit 4a15925edc89 · 2025-05-31T14:30:43.000+02:00
Signed-off-by: Andrew Block &lt;andy.block@gmail.com&gt;
diff --git a/docs/assets/repo-type-helm.png b/docs/assets/repo-type-helm.png
diff --git a/docs/operator-manual/declarative-setup.md b/docs/operator-manual/declarative-setup.md
@@ -362,6 +362,10 @@ The following keys are valid to refer to credential secrets:
 * `githubAppEnterpriseBaseUrl` refers to the base api URL for GitHub Enterprise (e.g. `https://ghe.example.com/api/v3`)
 * `tlsClientCertData` and `tlsClientCertKey` refer to secrets where a TLS client certificate (`tlsClientCertData`) and the corresponding private key `tlsClientCertKey` are stored for accessing GitHub Enterprise if custom certificates are used.
 
+#### Helm Chart repositories
+
+See the [Helm](#helm) section for the properties that apply to Helm repositories and charts sourced from OCI registries.
+
 ### Repositories using self-signed TLS certificates (or are signed by custom CA)
 
 You can manage the TLS certificates used to verify the authenticity of your repository servers in a ConfigMap object named `argocd-tls-certs-cm`. The data section should contain a map, with the repository server's hostname part (not the complete URL) as key, and the certificate(s) in PEM format as data. So, if you connect to a repository with the URL `https://server.example.com/repos/my-repo`, you should use `server.example.com` as key. The certificate data should be either the server's certificate (in case of self-signed certificate) or the certificate of the CA that was used to sign the server's certificate. You can configure multiple certificates for each server, e.g. if you are having a certificate roll-over planned.
@@ -1100,27 +1104,54 @@ stringData:
     }
 ```
 
-## Helm Chart Repositories
+## Helm
 
-Non standard Helm Chart repositories have to be registered explicitly.
-Each repository must have `url`, `type` and `name` fields. For private Helm repos you may need to configure access credentials and HTTPS settings using `username`, `password`,
-`tlsClientCertData` and `tlsClientCertKey` fields.
+Helm charts can be sourced from a Helm repository or OCI registry.
 
-Example:
+This is an example of a Helm chart being sourced from a Helm repository. The `releaseName` property is used to customize the name of the Helm _release_.
 
 ```yaml
-apiVersion: v1
-kind: Secret
+apiVersion: argoproj.io/v1alpha1
+kind: Application
 metadata:
-  name: istio
+  name: sealed-secrets
   namespace: argocd
-  labels:
-    argocd.argoproj.io/secret-type: repository
-stringData:
-  name: istio.io
-  url: https://storage.googleapis.com/istio-prerelease/daily-build/master-latest-daily/charts
-  type: helm
----
+spec:
+  project: default
+  source:
+    chart: sealed-secrets
+    repoURL: https://bitnami-labs.github.io/sealed-secrets
+    targetRevision: 1.16.1
+    helm:
+      releaseName: sealed-secrets
+  destination:
+    server: "https://kubernetes.default.svc"
+    namespace: kubeseal
+```
+
+Another example using a public OCI helm chart:
+
+```yaml
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: nginx
+spec:
+  project: default
+  source:
+    chart: nginx
+    repoURL: registry-1.docker.io/bitnamicharts  # note: the oci:// syntax is not included.
+    targetRevision: 15.9.0
+  destination:
+    name: "in-cluster"
+    namespace: nginx
+```
+
+Helm charts located in sources that require additional configuration, such as authentication or TLS connection details, are defined within a _repository_ Secret. Each Secret must specify the `url`, `type` and `name` fields. Additional fields including `username`, `password`, `tlsClientCertData` and `tlsClientCertKey` can be specified as desired.
+
+Helm Chart Repository:
+
+```yaml
 apiVersion: v1
 kind: Secret
 metadata:
@@ -1138,6 +1169,23 @@ stringData:
   tlsClientCertKey: ...
 ```
 
+Helm charts sourced from OCI registries should utilize the fields described previously as well as set the `enableOCI` field as `true`.
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: oci-helm-chart
+  namespace: oci-helm-chart
+  labels:
+    argocd.argoproj.io/secret-type: repository
+stringData:
+  name: oci-helm-chart
+  url: myregistry.example.com
+  type: helm
+  enableOCI: "true"
+```
+
 ## Resource Exclusion/Inclusion
 
 Resources can be excluded from discovery and sync so that Argo CD is unaware of them. For example, the apiGroup/kind `events.k8s.io/*`, `metrics.k8s.io/*` and `coordination.k8s.io/Lease` are always excluded. Use cases:
diff --git a/docs/user-guide/helm.md b/docs/user-guide/helm.md
@@ -45,7 +45,7 @@ spec:
 !!! note "When using Helm there are multiple ways to provide values"
     Order of precedence is `parameters > valuesObject > values > valueFiles > helm repository values.yaml` (see [Here](./helm.md#helm-value-precedence) for a more detailed example)
 
-See [here](../operator-manual/declarative-setup.md#helm-chart-repositories) for more info about how to configure private Helm repositories.
+See [here](../operator-manual/declarative-setup.md#helm) for more info about how to configure private Helm repositories and private OCI registries.
 
 ## Values Files
 
diff --git a/docs/user-guide/private-repositories.md b/docs/user-guide/private-repositories.md
@@ -435,6 +435,51 @@ It is possible to add and remove SSH known hosts entries using the ArgoCD web UI
 
 You can also manage SSH known hosts entries in a declarative, self-managed ArgoCD setup. All SSH public host keys are stored in the ConfigMap object `argocd-ssh-known-hosts-cm`. For more details, please refer to the [Operator Manual](../operator-manual/declarative-setup.md#ssh-known-host-public-keys).
 
+## Helm
+
+Helm charts can be sourced from protected Helm repositories or OCI registries. You can configure access to protected Helm charts by using either the CLI or the UI by speciying `helm` as the _type_ of HTTPS based repository.
+
+Using the CLI:
+
+Specify the `--type` flag of the `argocd repo add` command:
+
+```bash
+argocd repo add https://argoproj.github.io/argo-helm --type=helm <additional-flags>
+```
+
+Using the UI:
+
+1. Navigate to `Settings/Repositories`
+
+    ![connect repo overview](../assets/repo-add-overview.png)
+
+2. Click the `Connect Repo` button
+
+3. Select `VIA HTTPS` as the Connection Method
+
+4. Select `helm` as the Type.
+
+    ![helm repository type](../assets/repo-type-helm.png)
+
+5. Click `Connect` to test the connection and have the repository added
+
+Helm charts stored in protected OCI registries should use the steps described previously as well as explicitly specifying that the source is an Helm chart stored in an OCI registry.
+
+Using CLI:
+
+Specify the `--enable-oci` flag of the `argocd repo add` command:
+
+```bash
+argocd repo add registry-1.docker.io/bitnamicharts --type=helm --enable-oci=true <additional-flags>
+```
+
+!!! note
+    The protocol, such as `oci://` should be omitted when referencing an OCI registry
+
+Using the UI:
+
+Select the _Enable OCI_ checkbox when adding a HTTPS based _helm_ repository.
+
 ## Git Submodules
 
 Submodules are supported and will be picked up automatically. If the submodule repository requires authentication then the credentials will need to match the credentials of the parent repository. Set ARGOCD_GIT_MODULES_ENABLED=false to disable submodule support
