This is a cache of https://docs.okd.io/latest/applications/working_with_helm_charts/configuring-custom-helm-chart-repositories.html. It is a snapshot of the page at 2026-10-24T18:58:57.042+0000.
Configuring custom <strong>helm</strong> chart repositories - Working with <strong>helm</strong> charts | Building applications | OKD 5
  1. Documentation
×

Configuring custom helm chart repositories

You can create helm releases on an OKD cluster by using the following methods:

  • The CLI.

  • The web console.

The Software Catalog displays helm charts available in the cluster. By default, it lists charts from the Red Hat OpenShift helm repository.

As a cluster administrator, you can add cluster-scoped and namespace-scoped helm chart repositories in addition to the default. The Software Catalog displays charts from all of them.

As a project member with the required role-based access control (RBAC) permissions, you can also add namespace-scoped helm chart repositories. The Software Catalog displays the helm charts from these repositories.

On the Ecosystem → helm page, you can:

  • Create helm Releases and Repositories using the Create button.

  • Create, update, or delete a cluster-scoped or namespace-scoped helm chart repository.

  • View the list of the existing helm chart repositories in the Repositories tab, which can also be easily distinguished as either cluster scoped or namespace scoped.

Installing a helm chart on an OKD cluster

Prerequisites

  • You have a running OKD cluster and you have logged into it.

  • You have installed helm.

Procedure

  1. Create a new project:

    $ oc new-project vault

  2. Add a repository of helm charts to your local helm client:

    $ helm repo add openshift-helm-charts https://charts.openshift.io/
    Example output
    "openshift-helm-charts" has been added to your repositories

  3. Update the repository:

    $ helm repo update

  4. Install an example HashiCorp Vault:

    $ helm install example-vault openshift-helm-charts/hashicorp-vault
    Example output
    NAME: example-vault
LAST DEPLOYED: Fri Mar 11 12:02:12 2022
NAMESPACE: vault
STATUS: deployed
REVISION: 1
NOTES:
Thank you for installing HashiCorp Vault!

  5. Verify that the chart has installed successfully:

    $ helm list
    Example output
    NAME         	NAMESPACE	REVISION	UPDATED                                	STATUS  	CHART       	APP VERSION
example-vault	vault    	1       	2022-03-11 12:02:12.296226673 +0530 IST	deployed	vault-0.19.0	1.9.2

Creating helm releases by using the web console

You can use either the web console or the CLI to create a helm release from a chart. The web console lists helm releases on the Ecosystem → helm page.

Prerequisites

  • You have logged in to the web console.

Procedure

  1. Navigate to Ecosystem → Software Catalog.

  2. Under Type, click helm Charts.

  3. Select a chart and read the description, README, and other details about the chart.

  4. Click Create.

  5. In the Create helm Release page:

    1. Enter a unique name for the release in the Release Name field.

    2. Select the required chart version from the Chart Version drop-down list.

    3. Configure your helm chart by using the Form View or the YAML View.

      Where available, you can switch between the YAML View and Form View. The web console keeps your data when you switch between views.

    4. Click Create to create a helm release. The web console displays the new release on the Ecosystem → helm page.

      If a helm chart has release notes, the web console displays them.

      If a helm chart creates workloads, the web console displays them on the helm release details page. The workloads are DaemonSet, CronJob, Pod, Deployment, and DeploymentConfig.

      You can upgrade, roll back, or delete a helm release from the overflow menu in its row on the Ecosystem → helm page.

Using helm in the web terminal

You can run helm CLI commands in the web terminal.

Creating a custom helm chart on OKD

Procedure

  1. Create a new project:

    $ oc new-project nodejs-ex-k

  2. Download an example Node.js chart that contains OKD objects:

    $ git clone https://github.com/redhat-developer/redhat-helm-charts

  3. Go to the directory with the sample chart:

    $ cd redhat-helm-charts/alpha/nodejs-ex-k/

  4. Edit the Chart.yaml file and add a description of your chart:

    apiVersion: v2 (1)
name: nodejs-ex-k (2)
description: A helm chart for OpenShift (3)
icon: https://static.redhat.com/libs/redhat/brand-assets/latest/corp/logo.svg (4)
version: 0.2.1 (5)
    1 The chart API version. It should be v2 for helm charts that require at least helm 3.
    2 The name of your chart.
    3 The description of your chart.
    4 The URL to an image to be used as an icon.
    5 The Version of your chart as per the Semantic Versioning (SemVer) 2.0.0 Specification.

  5. Verify that the chart is formatted properly:

    $ helm lint
    Example output
    [INFO] Chart.yaml: icon is recommended

1 chart(s) linted, 0 chart(s) failed

  6. Navigate to the previous directory level:

    $ cd ..

  7. Install the chart:

    $ helm install nodejs-chart nodejs-ex-k

  8. Verify that the chart has installed successfully:

    $ helm list
    Example output
    NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION
nodejs-chart nodejs-ex-k 1 2019-12-05 15:06:51.379134163 -0500 EST deployed nodejs-0.1.0  1.16.0

Adding custom helm chart repositories

As a cluster administrator, you can add custom helm chart repositories to your cluster. The Software Catalog then displays the helm charts from these repositories.

Procedure

  1. To add a new helm Chart Repository, you must add the helm Chart Repository custom resource (CR) to your cluster.

    Sample helm Chart Repository CR
    apiVersion: helm.openshift.io/v1beta1
kind: helmChartRepository
metadata:
  name: <name>
spec:
 # optional name that might be used by console
 # name: <chart-display-name>
  connectionConfig:
    url: <helm-chart-repository-url>

    For example, to add an Azure sample chart repository, run:

    $ cat <<EOF | oc apply -f -
apiVersion: helm.openshift.io/v1beta1
kind: helmChartRepository
metadata:
  name: azure-sample-repo
spec:
  name: azure-sample-repo
  connectionConfig:
    url: https://raw.githubusercontent.com/Azure-Samples/helm-charts/master/docs
EOF

  2. Navigate to Ecosystem → Software Catalog and verify that it displays the helm charts from the chart repository.

    For example, use the Chart repositories filter to search for a helm chart from the repository.

    You can also verify by running the following command:

    $ oc get helmchartrepositories
    Example output
    NAME                     AGE
azure-sample-repo        1m

Adding namespace-scoped custom helm chart repositories

The cluster-scoped helmChartRepository custom resource definition (CRD) for helm repository provides the ability for administrators to add helm repositories as custom resources. The namespace-scoped ProjecthelmChartRepository CRD allows project members with the appropriate role-based access control (RBAC) permissions to create helm repository resources of their choice but scoped to their namespace. Such project members can see charts from both cluster-scoped and namespace-scoped helm repository resources.

  • Administrators can limit users from creating namespace-scoped helm repository resources. By limiting users, administrators have the flexibility to control the RBAC through a namespace role instead of a cluster role. This avoids unnecessary permission elevation for the user and prevents access to unauthorized services or applications.

  • The addition of the namespace-scoped helm repository does not impact the behavior of the existing cluster-scoped helm repository.

As a project member with the required RBAC permissions, you can add custom namespace-scoped helm chart repositories to your cluster. The Software Catalog then displays the helm charts from these repositories.

Procedure

  1. To add a new namespace-scoped helm Chart Repository, you must add the helm Chart Repository custom resource (CR) to your namespace.

    Sample Namespace-scoped helm Chart Repository CR
    apiVersion: helm.openshift.io/v1beta1
kind: ProjecthelmChartRepository
metadata:
  name: <name>
spec:
  url: https://my.chart-repo.org/stable

  # optional name that might be used by console
  name: <chart-repo-display-name>

  # optional and only needed for UI purposes
  description: <My private chart repo>

  # required: chart repository URL
  connectionConfig:
    url: <helm-chart-repository-url>

    For example, to add an Azure sample chart repository scoped to your my-namespace namespace, run:

    $ cat <<EOF | oc apply --namespace my-namespace -f -
apiVersion: helm.openshift.io/v1beta1
kind: ProjecthelmChartRepository
metadata:
  name: azure-sample-repo
spec:
  name: azure-sample-repo
  connectionConfig:
    url: https://raw.githubusercontent.com/Azure-Samples/helm-charts/master/docs
EOF

    The output confirms that you created the namespace-scoped helm Chart Repository CR:

    Example output
    projecthelmchartrepository.helm.openshift.io/azure-sample-repo created

  2. Navigate to Ecosystem → Software Catalog and verify that it displays the helm charts from the chart repository in your my-namespace namespace.

    For example, use the Chart repositories filter to search for a helm chart from the repository.

    You can also verify by running the following command:

    $ oc get projecthelmchartrepositories --namespace my-namespace
    Example output
    NAME                     AGE
azure-sample-repo        1m

Creating credentials and CA certificates to add helm chart repositories

Some helm chart repositories need credentials and custom certificate authority (CA) certificates to connect to it. You can use the web console as well as the CLI to add credentials and certificates.

Procedure

To configure the credentials and certificates, and then add a helm chart repository using the CLI:

  1. In the openshift-config namespace, create a ConfigMap object with a custom CA certificate in PEM encoded format, and store it under the ca-bundle.crt key within the config map:

    $ oc create configmap helm-ca-cert \
--from-file=ca-bundle.crt=/path/to/certs/ca.crt \
-n openshift-config

  2. In the openshift-config namespace, create a Secret object to add the client TLS configurations:

    $ oc create secret tls helm-tls-configs \
--cert=/path/to/certs/client.crt \
--key=/path/to/certs/client.key \
-n openshift-config

    Note that the client certificate and key must be in PEM encoded format and stored under the keys tls.crt and tls.key, respectively.

  3. Add the helm repository as follows:

    $ cat <<EOF | oc apply -f -
apiVersion: helm.openshift.io/v1beta1
kind: helmChartRepository
metadata:
  name: <helm-repository>
spec:
  name: <helm-repository>
  connectionConfig:
    url: <URL for the helm repository>
    tlsConfig:
        name: helm-tls-configs
    ca:
	name: helm-ca-cert
EOF

    The ConfigMap and Secret are consumed in the helmChartRepository CR using the tlsConfig and ca fields. These certificates are used to connect to the helm repository URL.

  4. By default, all authenticated users have access to all configured charts. However, for chart repositories where certificates are needed, you must provide users with read access to the helm-ca-cert config map and helm-tls-configs secret in the openshift-config namespace, as follows:

    $ cat <<EOF | kubectl apply -f -
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  namespace: openshift-config
  name: helm-chartrepos-tls-conf-viewer
rules:
- apiGroups: [""]
  resources: ["configmaps"]
  resourceNames: ["helm-ca-cert"]
  verbs: ["get"]
- apiGroups: [""]
  resources: ["secrets"]
  resourceNames: ["helm-tls-configs"]
  verbs: ["get"]
---
kind: RoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  namespace: openshift-config
  name: helm-chartrepos-tls-conf-viewer
subjects:
  - kind: Group
    apiGroup: rbac.authorization.k8s.io
    name: 'system:authenticated'
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: helm-chartrepos-tls-conf-viewer
EOF

Filtering helm Charts by their certification level

You can filter helm charts based on their certification level in the Developer Catalog.

Procedure

  1. In the Developer perspective, navigate to the +Add view and select a project.

  2. From the Developer Catalog tile, select the helm Chart option to see all the helm charts in the Developer Catalog.

  3. Use the filters to the left of the list of helm charts to filter the required charts:

    • Use the Chart Repositories filter to filter charts provided by Red Hat Certification Charts or OpenShift helm Charts.

    • Use the Source filter to filter charts sourced from Partners, Community, or Red Hat. Certified charts are indicated with the (odc verified icon) icon.

The Source filter will not be visible when there is only one provider type.

You can now select the required chart and install it.

Disabling helm Chart repositories

You can disable helm Charts from a particular helm Chart Repository in the catalog by setting the disabled property in the helmChartRepository custom resource to true.

Procedure

  • To disable a helm Chart repository by using CLI, add the disabled: true flag to the custom resource. For example, to remove an Azure sample chart repository, run:

    $ cat <<EOF | oc apply -f -
apiVersion: helm.openshift.io/v1beta1
kind: helmChartRepository
metadata:
  name: azure-sample-repo
spec:
  connectionConfig:
   url:https://raw.githubusercontent.com/Azure-Samples/helm-charts/master/docs
  disabled: true
EOF

  • To disable a recently added helm Chart repository by using Web Console:

    1. Go to Custom Resource Definitions and search for the helmChartRepository custom resource.

    2. Go to Instances, find the repository you want to disable, and click its name.

    3. Go to the YAML tab, add the disabled: true flag in the spec section, and click Save.

      Example
      spec:
  connectionConfig:
    url: <url-of-the-repositoru-to-be-disabled>
  disabled: true

      The repository is now disabled and will not appear in the catalog.

Additional resources