Skip to main content
Redhat Developers  Logo
  • Products

    Featured

    • Red Hat Enterprise Linux
      Red Hat Enterprise Linux Icon
    • Red Hat OpenShift AI
      Red Hat OpenShift AI
    • Red Hat Enterprise Linux AI
      Linux icon inside of a brain
    • Image mode for Red Hat Enterprise Linux
      RHEL image mode
    • Red Hat OpenShift
      Openshift icon
    • Red Hat Ansible Automation Platform
      Ansible icon
    • Red Hat Developer Hub
      Developer Hub
    • View All Red Hat Products
    • Linux

      • Red Hat Enterprise Linux
      • Image mode for Red Hat Enterprise Linux
      • Red Hat Universal Base Images (UBI)
    • Java runtimes & frameworks

      • JBoss Enterprise Application Platform
      • Red Hat build of OpenJDK
    • Kubernetes

      • Red Hat OpenShift
      • Microsoft Azure Red Hat OpenShift
      • Red Hat OpenShift Virtualization
      • Red Hat OpenShift Lightspeed
    • Integration & App Connectivity

      • Red Hat Build of Apache Camel
      • Red Hat Service Interconnect
      • Red Hat Connectivity Link
    • AI/ML

      • Red Hat OpenShift AI
      • Red Hat Enterprise Linux AI
    • Automation

      • Red Hat Ansible Automation Platform
      • Red Hat Ansible Lightspeed
    • Developer tools

      • Red Hat Trusted Software Supply Chain
      • Podman Desktop
      • Red Hat OpenShift Dev Spaces
    • Developer Sandbox

      Developer Sandbox
      Try Red Hat products and technologies without setup or configuration fees for 30 days with this shared Openshift and Kubernetes cluster.
    • Try at no cost
  • Technologies

    Featured

    • AI/ML
      AI/ML Icon
    • Linux
      Linux Icon
    • Kubernetes
      Cloud icon
    • Automation
      Automation Icon showing arrows moving in a circle around a gear
    • View All Technologies
    • Programming Languages & Frameworks

      • Java
      • Python
      • JavaScript
    • System Design & Architecture

      • Red Hat architecture and design patterns
      • Microservices
      • Event-Driven Architecture
      • Databases
    • Developer Productivity

      • Developer productivity
      • Developer Tools
      • GitOps
    • Secure Development & Architectures

      • Security
      • Secure coding
    • Platform Engineering

      • DevOps
      • DevSecOps
      • Ansible automation for applications and services
    • Automated Data Processing

      • AI/ML
      • Data Science
      • Apache Kafka on Kubernetes
      • View All Technologies
    • Start exploring in the Developer Sandbox for free

      sandbox graphic
      Try Red Hat's products and technologies without setup or configuration.
    • Try at no cost
  • Learn

    Featured

    • Kubernetes & Cloud Native
      Openshift icon
    • Linux
      Rhel icon
    • Automation
      Ansible cloud icon
    • Java
      Java icon
    • AI/ML
      AI/ML Icon
    • View All Learning Resources

    E-Books

    • GitOps Cookbook
    • Podman in Action
    • Kubernetes Operators
    • The Path to GitOps
    • View All E-books

    Cheat Sheets

    • Linux Commands
    • Bash Commands
    • Git
    • systemd Commands
    • View All Cheat Sheets

    Documentation

    • API Catalog
    • Product Documentation
    • Legacy Documentation
    • Red Hat Learning

      Learning image
      Boost your technical skills to expert-level with the help of interactive lessons offered by various Red Hat Learning programs.
    • Explore Red Hat Learning
  • Developer Sandbox

    Developer Sandbox

    • Access Red Hat’s products and technologies without setup or configuration, and start developing quicker than ever before with our new, no-cost sandbox environments.
    • Explore Developer Sandbox

    Featured Developer Sandbox activities

    • Get started with your Developer Sandbox
    • OpenShift virtualization and application modernization using the Developer Sandbox
    • Explore all Developer Sandbox activities

    Ready to start developing apps?

    • Try at no cost
  • Blog
  • Events
  • Videos

3 ways to install a database with Helm charts

April 7, 2022
Wanja Pernath
Related topics:
Kubernetes
Related products:
Red Hat OpenShift

Share:

    Helm is a package manager for Kubernetes. Helm uses a packaging format called charts, which include all of the Kubernetes resources that are required to deploy an application, such as deployments, services, ingress, and so on. Helm charts are very useful for installing applications and performing upgrades on a Kubernetes cluster.

    In chapter 3 of my e-book Getting GitOps: A Practical Platform with OpenShift, Argo CD, and Tekton, I discuss the basics of creating and using Helm charts. I also dig into the the use case of creating a post-install and post-upgrade job.

    However, that chapter provided a very basic example that focused only on what's necessary to create and deploy a Helm chart. This article will demonstrate some more advanced techniques to create a chart that could be installed more than once in the same namespace. It also shows how you could easily install a dependent database with your chart.

    The source code for this example can be found in the GitHub repository that accompanies my book.

    The use case: How to install a dependent database with a Helm chart

    Chapter 1 of my book outlines the Quarkus-based person-service, a simple REST API service that reads and writes personal data from and into a PostgreSQL database. A Helm chart packages this service, and needs to provide all the dependencies necessary to successfully install it. As discussed in that chapter, you have three options to achieve that goal:

    • Use the corresponding OpenShift template to install the necessary PostgreSQL database
    • Use the CrunchyData Postgres Operator (or any other Operator-defined PostgreSQL database extension) for the database
    • Install a dependent Helm chart, such as the PostgreSQL chart by Bitnami, with your chart

    No matter which route you take, however, you also need to ensure that your chart can be installed multiple times on each namespace. So let's tackle that task first.

    Make the chart installable multiple times in the same namespace

    The most crucial step for making your chart installable multiple times in the same namespace is to use generated names for all the manifest files. Therefore, you need an object called Release with the following properties:

    Name: The name of the release
    Namespace: Where you are going to install the chart
    Revision: The revision number of this release (starts at 1 on install, and each update increments it by one)
    IsInstall: true if it's an installation process
    IsUpgrade: true if it's an upgrade process

    If you want to make sure that your chart installation won't conflict with any other installations in the same namespace, do the following:

    apiVersion: v1
    kind: ConfigMap
    metadata:
      name: {{ .Release.Name }}-config
      labels:
        app.kubernetes.io/part-of: {{ .Release.Name }}-chart
    data:
      APP_GREETING: |- 
        {{ .Values.config.greeting | default "Yeah, it's openshift time" }}

    This creates a ConfigMap with the name of the release, followed by a dash, followed by config. Of course, you now need to make sure that the ConfigMap is being read by the deployment accordingly:

    - image: "{{ .Values.deployment.image }}:{{ .Values.deployment.version }}"
              envFrom:
                - configMapRef:
                    name: {{ .Release.Name }}-config
    
    [...]

    If you are updating all the other manifest files in your Helm's templates folder, you can install your chart multiple times.

    $ helm install person-service1 <path to chart>
    $ helm install person-service2 <path to chart>

    With that task out of the way, we can now consider each of the three potential approaches outlined above in turn.

    Install the database via an existing OpenShift template

    By far easiest way to install a PostgreSQL database in an OpenShift namespace is by using an OpenShift template. We did it several times in my book. The call is simple:

    $ oc new-app postgresql-persistent \
        -p POSTGRESQL_USER=wanja \
        -p POSTGRESQL_PASSWORD=wanja \
        -p POSTGRESQL_DATABASE=wanjadb \
        -p DATABASE_SERVICE_NAME=wanjaserver

    But how could you automate this process? There is no way to execute this call from within a Helm chart installation. (Well, you could do it by using a pre-install hook, but that would be quite ugly.)

    Fortunately, the OpenShift client has a function called process that processes a template. The result of this call is a list of YAML objects that can then be installed into OpenShift.

    $ oc process postgresql-persistent -n openshift -o yaml

    If you're piping the result into a new file, you would get something like this:

    apiVersion: v1
    kind: List
    items:
    - apiVersion: v1
      kind: Secret
      metadata:
        labels:
          template: postgresql-persistent-template
        name: postgresql
      stringData:
        database-name: sampledb
        database-password: KSurRUMyFI2fiVpx
        database-user: user0U4
    - apiVersion: v1
      kind: Service
    [...]

    If you're not happy with the default parameters for username, password, and database name, call the process function with the -p PARAM=VALUE option:

    $ oc process postgresql-persistent -n openshift -o yaml \
        -p POSTGRESQL_USER=wanja \
        -p POSTGRESQL_PASSWORD=wanja \
        -p POSTGRESQL_DATABASE=wanjadb \
        -p DATABASE_SERVICE_NAME=wanjaserver

    Place the resulting file into your chart's templates folder, and it will be used to install the database. If you have a closer look at the file, you can see that it's using DATABASE_SERVICE_NAME as manifest names for its Service, Secret, and DeploymentConfig objects, which would make it impossible to install your resulting chart more than once into any namespace.

    If you're providing the string -p DATABASE_SERVICE_NAME='pg-{{ .Release.Name }}' instead of the fixed string wanjaserver, then this will be used as the object name for these manifest files. However, if you try to install your Helm chart now, you'll get some verification error messages. This is because oc process generates some top-level status fields that the Helm parser does not understand, so you need to remove them.

    The only thing you now need to do is to connect your person-service deployment with the corresponding database instance. Simply add the following entries to the env section of your Deployment.yaml file:

    [...]
              env:
                - name: DB_host
                  value: pg-{{ .Release.Name }}.{{ .Release.Namespace }}.svc
                - name: DB_dbname
                  valueFrom:
                    secretKeyRef:
                      name: pg-{{ .Release.Name }}
                      key: database-name
                - name: DB_user
                  valueFrom:
                    secretKeyRef:
                      name: pg-{{ .Release.Name }}
                      key: database-user
                - name: DB_password
                  valueFrom:
                    secretKeyRef:
                      name: pg-{{ .Release.Name }}
                      key: database-password
    [...]

    Your Helm chart is now ready to be packaged and installed:

    $ helm package better-helm/with-templ
    $ helm upgrade --install ps1 person-service-templ-0.0.10.tgz

    Unfortunately, one of the resulting manifest files is a DeploymentConfig, which would only work on Red Hat OpenShift. As a result, this chart can't be installed on any other Kubernetes distribution. So let's discuss other options.

    Install a Kubernetes Operator with your chart

    Another way to install a dependent database with your Helm chart is to look for a Kubernetes Operator on OperatorHub. If your cluster already has an Operator Lifecycle Manager (OLM) installed (as all OpenShift clusters do), then the only thing you need to do is create a Subscription that describes your desire to install an Operator.

    For example, to install the community operator by CrunchyData into OpenShift, you would need to create the following file:

    apiVersion: operators.coreos.com/v1alpha1
    kind: Subscription
    metadata:
      name: postgresql-operator
      namespace: openshift-operators
    spec:
      channel: v5 
      name: postgresql
      source: community-operators 
      sourceNamespace: openshift-marketplace

    If you put this file into the crds folder of your Helm chart, Helm takes care of installing the Operator before it processes the template files of the chart. Please note, however, that Helm will never uninstall the custom resource definitions, so the Operator will stay on the Kubernetes cluster.

    If you place the following file into the templates folder of the chart, your PostgreSQL database instance will be ready to use:

    apiVersion: postgres-operator.crunchydata.com/v1beta1
    kind: PostgresCluster
    metadata:
      name: {{ .Release.Name }}-db
      labels:
        app.kubernetes.io/part-of: {{ .Release.Name }}-chart
    spec:
      image: registry.developers.crunchydata.com/crunchydata/crunchy-postgres:centos8-13.5-0
      postgresVersion: 13
      instances:
        - name: instance1
          dataVolumeClaimSpec:
            accessModes:
            - "ReadWriteOnce"
            resources:
              requests:
                storage: 1Gi
      backups:
        pgbackrest:
          image: registry.developers.crunchydata.com/crunchydata/crunchy-pgbackrest:centos8-2.36-0
          repos:
          - name: repo1
            volume:
              volumeClaimSpec:
                accessModes:
                - "ReadWriteOnce"
                resources:
                  requests:
                    storage: 1Gi

    Of course, you now need to make sure that your person-service is able to connect to this PostgreSQL instance. Simply add a secretRef to the deployment file with the following content:

    [...]
              envFrom:
                - secretRef:
                    name: {{ .Release.Name }}-db-pguser-{{ .Release.Name }}-db
                  prefix: DB_
    [...]

    This will map all values of the PostgresCluster secret to your deployment with a prefix of DB_, which is exactly what you need.

    Now your chart is ready to be packaged and can be installed in any OpenShift namespace:

    $ helm package with-crds
    $ helm install ps1 person-service-crd-0.0.10.tgz
    $ helm uninstall ps1

    Install the database by adding a subchart dependency

    The last option is to use a subchart within your chart. For this scenario, Helm has a dependency management system that makes it easier for you as a chart developer to use third-party charts. The example that follows makes use of the Bitnami PostgreSQL chart, which you can find on ArtifactHub.

    To start, you have to change the Chart.yaml file to add the external dependency. With the following lines, you can add the dependency to the Bitnami PostgreSQL database with the version 11.1.3.

    dependencies:
        - name: postgresql
          repository: https://charts.bitnami.com/bitnami
          version: 11.1.3

    If you want to define properties from within your values.yaml file, you simply need to use the name of the chart as the first parameter in the tree; in this case, it is postgresql. You can then add all necessary parameters below that key:

    postgresql:
      auth:
        username: wanja
    [...]

    Next, you need to have a look at the documentation of the Bitnami chart to understand how to use it in your target environment (OpenShift, in this case). Unfortunately, as of the time of this writing, the current documentation is a bit outdated, so you would not be able to install your chart without digging further into the values.yaml file Bitnami supplies to see which security settings you have to set in order to use it with OpenShift's strong enterprise security.

    To save you the trouble, I've put together this minimum list of settings you would need to use:

    postgresql:
        auth:
            username: wanja
            password: wanja
            database: wanjadb
        primary:
            podSecurityContext:
                enabled: false
                fsGroup: ""
            containerSecurityContext:
                enabled: false
                runAsUser: "auto"
    
        readReplicas:
            podSecurityContext:
                enabled: false
                fsGroup: ""
            containerSecurityContext:
                enabled: false
                runAsUser: "auto"
    
        volumePermissions:
            enabled: false
            securityContext:
                runAsUser: "auto"

    The final step is to make sure that your deployment is able to connect to this database.

    [...]
              env:
                - name: DB_user
                  value: wanja
                - name: DB_password
                  valueFrom:
                    secretKeyRef:
                      name: {{ .Release.Name }}-postgresql
                      key: password
                - name: DB_dbname
                  value: wanjadb
                - name: DB_host            
                  value: {{ .Release.Name }}-postgresql.{{ .Release.Namespace }}.svc
    [...]

    Now you need to package your chart. Because you're depending on a third-party chart, you need to use the -u option, which downloads the dependencies into the charts folder of your Helm chart.

    $ helm package -u better-helm/with-subchart
    $ helm install ps1 person-service-sub.0.0.11.tgz

    Conclusion

    Using Helm charts for your own projects is quite easy, even if you need to make sure certain dependencies are being installed as well. Thanks to Helm's dependency management, you can easily use subcharts with your charts. And thanks to the flexibility of Helm, you can also either use a (processed) template or quickly install a Kubernetes Operator before proceeding.

    Check out these articles to learn more about Helm:

    • Deploy Helm charts with Jenkins CI/CD in Red Hat OpenShift 4
    • Deploy a Java application using Helm

    And for a more in-depth look at the example explored here, check out my e-book, Getting GitOps: A Practical Platform with OpenShift, Argo CD and Tekton.

    Last updated: September 20, 2023

    Recent Posts

    • GuideLLM: Evaluate LLM deployments for real-world inference

    • Unleashing multimodal magic with RamaLama

    • Integrate Red Hat AI Inference Server & LangChain in agentic workflows

    • Streamline multi-cloud operations with Ansible and ServiceNow

    • Automate dynamic application security testing with RapiDAST

    What’s up next?

    Getting GitOps e-book card

    Learn how to navigate the complex world of modern container-based software development and distribution with Getting GitOps: A Practical Platform with OpenShift, Argo CD, and Tekton.

    Download the e-book
    Red Hat Developers logo LinkedIn YouTube Twitter Facebook

    Products

    • Red Hat Enterprise Linux
    • Red Hat OpenShift
    • Red Hat Ansible Automation Platform

    Build

    • Developer Sandbox
    • Developer Tools
    • Interactive Tutorials
    • API Catalog

    Quicklinks

    • Learning Resources
    • E-books
    • Cheat Sheets
    • Blog
    • Events
    • Newsletter

    Communicate

    • About us
    • Contact sales
    • Find a partner
    • Report a website issue
    • Site Status Dashboard
    • Report a security problem

    RED HAT DEVELOPER

    Build here. Go anywhere.

    We serve the builders. The problem solvers who create careers with code.

    Join us if you’re a developer, software engineer, web designer, front-end designer, UX designer, computer scientist, architect, tester, product manager, project manager or team lead.

    Sign me up

    Red Hat legal and privacy links

    • About Red Hat
    • Jobs
    • Events
    • Locations
    • Contact Red Hat
    • Red Hat Blog
    • Inclusion at Red Hat
    • Cool Stuff Store
    • Red Hat Summit

    Red Hat legal and privacy links

    • Privacy statement
    • Terms of use
    • All policies and guidelines
    • Digital accessibility

    Report a website issue