OpenBao chart

You can use the OpenBao chart to install OpenBao, which is required to enable the GitLab secrets manager.

Known limitations

• You can’t upgrade OpenBao without downtime. Zero downtime upgrades are proposed in issue 595721.
• You can’t deploy OpenBao with GitLab Operator. Support is proposed in issue 1933.
• A FIPS variant of the OpenBao image is already being built, but OpenBao is not FIPS validated. FIPS validation is tracked in GitLab issue 574875.
• When failing over to a Geo secondary site that uses a different domain (instead of updating DNS to point the primary domain to the secondary site), OpenBao requires manual re-provisioning of JWT authentication for all projects and groups where GitLab Secrets Manager is enabled. This process can be time-consuming for large deployments. A migration tool is being proposed in GitLab issue 595722. Until then, the recommended approach is to update DNS records so the primary domain points to the promoted secondary site.

Setup GitLab secret manager and OpenBao

1. On an existing GitLab instance, enable OpenBao and configure its database connection. OpenBao requires a separate PostgreSQL database that you must create first. For the database and password secret, see Database configuration.

   # Enable OpenBao integration
   global:
     openbao:
       enabled: true
       # Connect to the separate OpenBao database you created
       psql:
         host: "psql.openbao.example.com"
         password:
           secret: openbao-db-password
           key: password
   # Install bundled OpenBao
   openbao:
     install: true

2. In GitLab, on the top bar, select Search or go to and find your project.

3. Select Settings > General.

4. Expand Visibility, project features, permissions.

5. Turn on the Secrets Manager toggle, and wait for the Secrets Manager to be provisioned.

Rolling back OpenBao upgrades

OpenBao upgrades can make changes to the PostgreSQL data that are not backwards compatible, which can cause compatibility issues if the OpenBao upgrade must be rolled back.

You should always back up before upgrading OpenBao. If you need to roll back an OpenBao upgrade, also restore the database backup matching the OpenBao version.

For more information, see OpenBao upgrade documentation.

Back up OpenBao

A complete OpenBao backup includes the:

• OpenBao unseal key
• OpenBao PostgreSQL database

The Toolbox backs up the OpenBao database as part of the standard GitLab backup, when backup credentials are configured.

Back up the OpenBao database at the same time as the main GitLab PostgreSQL database to avoid data inconsistencies.

Restore OpenBao

The Toolbox restores the OpenBao database as part of the standard GitLab restore. See OpenBao database credentials to configure restore credentials.

Before restoring an OpenBao backup:

1. Note the current replica count so you can restore it afterward.

2. Scale down OpenBao so the running pod does not race the DROP TABLE and CREATE TABLE statements in the dump:

   kubectl get deploy -lapp.kubernetes.io/name=openbao,app.kubernetes.io/instance=<helm release name> -n <namespace>
   kubectl scale deploy -lapp.kubernetes.io/name=openbao,app.kubernetes.io/instance=<helm release name> -n <namespace> --replicas=0

After the restore completes, scale OpenBao back to its previous replica count so it reads from the restored database:

kubectl scale deploy -lapp.kubernetes.io/name=openbao,app.kubernetes.io/instance=<helm release name> -n <namespace> --replicas=<previous count>

OpenBao configuration options

The following tables list all available OpenBao configuration options. Global chart settings, such as Ingress configuration and image tag suffixes, also apply to OpenBao.

Installation command-line options

The table below contains all the possible charts configurations that can be supplied to the helm install command using the --set flags.

Container image options

The OpenBao chart deploys a cloud-native GitLab container image to deploy OpenBao. The OpenBao build includes modifications from the upstream version. As a result, some functionality may differ from the standard OpenBao releases.

Ingress and TLS configuration options

The OpenBao chart defaults to Ingress-terminated TLS encryption.

You should operate OpenBao with end-to-end encrypted TLS. To enable end-to-end TLS configure, OpenBao to expect a TLS connection and pass the TLS connection through NGINX Ingress:

global:
  ingress:
    useNewIngressForCerts: true
config:
  tlsDisable: false
ingress:
  sslPassthroughNginx: true

Gateway API

The OpenBao chart allows to expose traffic via an HTTPRoute. If Gateway API is enabled globally, a listener for OpenBao will be created in the managed Gateway resource.

Monitoring configuration options

OpenBao is preconfigured to expose Prometheus metrics which will be scraped by the bundled Prometheus subchart.

Unsealing and initialization options

The OpenBao chart supports two mutually exclusive auto-unseal methods:

• static auto unsealing (default)
• AWS KMS unsealing

It also uses OpenBao declarative self initialization.

During initialization, OpenBao generates recovery keys for emergency access when JWT authentication is unavailable. To store and use them, see recovery key management.

AWS KMS unsealing

AWS KMS unsealing delegates the unseal key to an AWS KMS key, removing the need to manage a static key secret.

When running on AWS (EKS, EC2), use IRSA or an instance profile so that no explicit AWS credentials are required. Annotate the OpenBao service account with the IAM role ARN:

openbao:
  serviceAccount:
    annotations:
      eks.amazonaws.com/role-arn: "arn:aws:iam::<account-id>:role/<role-name>"
  config:
    unseal:
      static:
        enabled: false
      awskms:
        enabled: true
        kmsKeyId: "alias/my-openbao-key"
        region: "us-east-1"

The IAM role must have kms:Encrypt, kms:Decrypt, and kms:DescribeKey permissions on the KMS key.

Audit event streaming options

The OpenBao chart configures auditing devices to stream events to GitLab.

Change an existing HTTP audit device

OpenBao registers the HTTP audit device declaratively and does not support modifying a registered device in place. To change an audit device, remove the existing audit device and add a new device. Make all changes through the chart values.

The chart supports adding or removing config.audit.http.requestTimeout directly. It switches the audit device path so setting or clearing the timeout is a remove and add operation, not an in-place modification.

To change the timeout from one value to another, use two deploys to force that path switch:

1. First set requestTimeout to empty.
2. Set the new value.

Database configuration

OpenBao uses a separate logical database (openbao by default) for data isolation from the Rails backend.

Configure global.openbao.psql or openbao.config.storage.postgresql.connection with host, database, username, and password. You must create the database manually. Password is required and is not inherited from the main GitLab database.

To configure an external database:

1. Create a PostgreSQL user and database on your database server:

   -- Create the OpenBao user
   CREATE USER openbao WITH PASSWORD '<password>';
   
   -- Create the OpenBao database
   CREATE DATABASE openbao OWNER openbao;

2. Create a Kubernetes secret containing the password:

   kubectl create secret -n bao generic openbao-db-password --from-literal=password="<password>"

3. Configure OpenBao to connect to your external database:

   global:
     openbao:
       psql:
         host: "psql.openbao.example.com"
         port: 5432
         database: openbao
         username: openbao
         password:
           secret: openbao-db-password
           key: password

   This uses global.openbao.psql, which is the preferred location because it is also accessible by Toolbox for backup and restore operations. To set advanced connection options (such as sslMode, connectTimeout, or keepalive tuning), use openbao.config.storage.postgresql.connection alongside the global settings.

4. Deploy or upgrade OpenBao. When starting, OpenBao automatically creates its database schema in the specified database.

PostgreSQL storage options

The following options tune the OpenBao PostgreSQL storage backend. Set them under openbao.config.storage.postgresql, in addition to the connection details in global.openbao.psql.