### Install OpenBao Helm Chart using OCI

Source: https://github.com/openbao/openbao-helm/blob/main/README.md

Installs the OpenBao Helm chart using an OCI-based registry. This is an alternative installation method.

```bash
helm install oci://ghcr.io/openbao/charts/openbao
```

--------------------------------

### Install OpenBao with Default Configuration

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/11-installation-operations.md

Installs OpenBao using the default configuration. You can specify the namespace and create it if it doesn't exist, or use a custom release name.

```bash
# Install in default namespace
helm install openbao openbao/openbao

# Install in specific namespace
helm install openbao openbao/openbao \
  --namespace openbao \
  --create-namespace

# Install with custom release name
helm install my-openbao openbao/openbao

# Install specific chart version
helm install openbao openbao/openbao \
  --version 0.28.4
```

--------------------------------

### Install OpenBao Helm Chart

Source: https://github.com/openbao/openbao-helm/blob/main/README.md

Installs the latest version of the OpenBao Helm chart from the added repository. Refer to values.yaml for configuration options.

```bash
helm install openbao openbao/openbao
```

--------------------------------

### Install OpenBao Helm Chart in Development Mode

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/README.md

Adds the OpenBao Helm repository and installs the chart in development mode with a single server instance. Use this for local testing and development.

```bash
helm repo add openbao https://openbao.github.io/openbao-helm
helm repo update

helm install openbao openbao/openbao \
  --set server.dev.enabled=true \
  --set server.ha.enabled=false
```

--------------------------------

### Install Bats Core

Source: https://github.com/openbao/openbao-helm/blob/main/CONTRIBUTING.md

Installs the Bats testing framework using Homebrew. This is a prerequisite for running tests locally.

```bash
brew install bats-core
```

--------------------------------

### Install OpenBao with Custom Values

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/11-installation-operations.md

Installs OpenBao using a custom values file or by overriding specific configuration values directly on the command line.

```bash
# Using values file
helm install openbao openbao/openbao \
  -f values-prod.yaml

# Overriding specific values
helm install openbao openbao/openbao \
  --set server.ha.enabled=true \
  --set server.ha.replicas=5 \
  --set global.tlsDisable=false

# Multiple value overrides
helm install openbao openbao/openbao \
  -f values-ha.yaml \
  -f values-prod.yaml \
  --set server.ha.replicas=5
```

--------------------------------

### MySQL Connection String Examples

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/08-storage-configuration.md

Examples of valid connection strings for MySQL/MariaDB storage. Supports user, password, protocol, host, port, and database name.

```text
openbao:password@tcp(mysql.example.com:3306)/openbao
root:@unix(/var/run/mysqld/mysqld.sock)/openbao
```

--------------------------------

### Development Deployment Example

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/10-values-reference.md

A basic configuration for a development environment, enabling Openbao, disabling TLS, and setting up the server for development mode.

```yaml
global:
  enabled: true
  tlsDisable: true

server:
  dev:
    enabled: true
  ha:
    enabled: false

injector:
  replicas: 1

csi:
  enabled: false

ui:
  enabled: true
```

--------------------------------

### Install OpenBao Helm Chart with External Server (Injector + CSI)

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/README.md

Configures the Helm chart to use an external OpenBao server, enabling the injector and CSI components. This setup is suitable when OpenBao is managed separately.

```bash
helm install openbao openbao/openbao \
  --set global.externalBaoAddr=https://vault.example.com:8200 \
  --set server.enabled=false \
  --set injector.enabled=true \
  --set csi.enabled=true
```

--------------------------------

### Install OpenBao Helm Chart in Production HA Mode

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/README.md

Installs the OpenBao Helm chart with High Availability (HA) enabled, using 3 replicas and disabling TLS for simplicity in this example. A custom values file 'values-prod.yaml' is used for production-specific configurations.

```bash
helm install openbao openbao/openbao \
  --set server.ha.enabled=true \
  --set server.ha.replicas=3 \
  --set global.tlsDisable=false \
  -f values-prod.yaml
```

--------------------------------

### Production HA Deployment Example

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/10-values-reference.md

Configuration for a production-ready High Availability (HA) deployment, including multiple server replicas, resource limits, and snapshot agent setup.

```yaml
global:
  enabled: true
  tlsDisable: false

server:
  ha:
    enabled: true
    replicas: 3
  standalone:
    enabled: false
  
  resources:
    requests:
      memory: "512Mi"
      cpu: "500m"
    limits:
      memory: "1Gi"
      cpu: "1000m"

injector:
  replicas: 3
  leaderElector:
    enabled: true

snapshotAgent:
  enabled: true
  schedule: "0 2 * * *"
  storage:
    s3:
      enabled: true
      bucket: "openbao-backups"

ui:
  enabled: true
```

--------------------------------

### Install OpenBao from OCI Registry

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/11-installation-operations.md

Installs OpenBao directly from an OCI-compliant container registry, specifying the chart version and optionally providing a custom values file.

```bash
# Direct OCI installation
helm install openbao oci://ghcr.io/openbao/charts/openbao \
  --version 0.28.4

# With custom values
helm install openbao oci://ghcr.io/openbao/charts/openbao \
  --version 0.28.4 \
  -f values.yaml
```

--------------------------------

### Database Setup SQL for PostgreSQL

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/08-storage-configuration.md

SQL commands to create the necessary database and user for OpenBao. OpenBao will automatically create the required tables.

```sql
-- Create database
CREATE DATABASE openbao;
CREATE USER openbao WITH PASSWORD 'strong-password';
GRANT ALL PRIVILEGES ON DATABASE openbao TO openbao;

-- OpenBao creates tables automatically
-- openbao_table (default: vault)
-- openbao_ha_table (default: vault_ha_locks)
```

--------------------------------

### Complete SecretProviderClass Example for OpenBao

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/07-csi-provider.md

A comprehensive SecretProviderClass example demonstrating the mounting of multiple secrets, including database credentials, TLS certificates, and API keys. This configuration requires specific paths and secret keys to be present in OpenBao.

```yaml
apiVersion: secrets-store.csi.x-k8s.io/v1
kind: SecretProviderClass
metadata:
  name: openbao-secrets
  namespace: default
spec:
  provider: vault
  
  parameters:
    vaultAddress: "http://openbao.default.svc.cluster.local:8200"
    vaultSkipTLSVerify: "false"
    vaultAuthPath: "auth/kubernetes"
    roleName: "backend"
    
    secretPath: |
      - secretKey: "username"
        path: "database/static/pg-users"
        objectName: "db-username"
      
      - secretKey: "password"
        path: "database/static/pg-users"
        objectName: "db-password"
      
      - secretKey: "certificate"
        path: "pki/issue/web"
        objectName: "tls-cert"
      
      - secretKey: "private_key"
        path: "pki/issue/web"
        objectName: "tls-key"
      
      - secretKey: "api_key"
        path: "secret/data/api-keys"
        objectName: "api-key"
```

--------------------------------

### Troubleshoot Pods Not Starting

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/11-installation-operations.md

Diagnose why Openbao pods are not starting by checking their status, logs, and related resources like nodes and PVCs. This includes checking for insufficient resources, image pull errors, and PVC binding issues.

```bash
kubectl describe pod openbao-0
```

```bash
kubectl logs openbao-0 -c openbao
```

```bash
kubectl describe node
```

```bash
kubectl logs openbao-0 -c openbao --previous
```

```bash
kubectl describe pvc openbao-data-openbao-0
```

--------------------------------

### Global Configuration Example

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/02-configuration.md

This snippet shows the structure of the global configuration block. Use these parameters to control the overall deployment of OpenBao components.

```yaml
global:
  enabled: true | false | "-"
  namespace: string
  imagePullSecrets: []
  tlsDisable: true | false
  externalBaoAddr: string
  externalVaultAddr: string (deprecated)
  openshift: true | false
  psp:
    enable: boolean
    annotations: string (multiline YAML)
  serverTelemetry:
    prometheusOperator: boolean
```

--------------------------------

### External Server Deployment Example (CSI + Injector Only)

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/10-values-reference.md

Sets up Openbao for use with an external server, enabling only the injector and CSI components and specifying the external server address.

```yaml
global:
  enabled: false
  externalBaoAddr: "https://vault.example.com:8200"

server:
  enabled: false

injector:
  enabled: true
  replicas: 2
  externalBaoAddr: "https://vault.example.com:8200"

csi:
  enabled: true

ui:
  enabled: false
```

--------------------------------

### Install yq

Source: https://github.com/openbao/openbao-helm/blob/main/CONTRIBUTING.md

Installs the yq command-line YAML processor using Homebrew. This tool is used for parsing and manipulating YAML output from Helm templates.

```bash
brew install python-yq
```

--------------------------------

### Install Helm

Source: https://github.com/openbao/openbao-helm/blob/main/CONTRIBUTING.md

Installs the Helm package manager using Homebrew. Helm is used for templating Kubernetes manifests.

```bash
brew install kubernetes-helm
```

--------------------------------

### PostgreSQL Connection String Formats

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/08-storage-configuration.md

Examples of valid PostgreSQL connection strings. Use these for the `connection_url` parameter.

```text
postgresql://openbao:mypassword@db.example.com:5432/openbao
```

```text
postgresql://openbao@localhost/openbao?sslmode=disable
```

--------------------------------

### Deployment Example for Application Accessing Mounted Secrets

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/07-csi-provider.md

Provides a Kubernetes Deployment example where the application container reads secrets from a mounted volume. Secrets are exported as environment variables after being read from files.

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: backend
spec:
  template:
    metadata:
      labels:
        app: backend
    spec:
      serviceAccountName: backend
      
      containers:
      - name: app
        image: backend:1.0
        
        volumeMounts:
        - name: vault-secrets
          mountPath: /vault/secrets
          readOnly: true
        
        # Read secrets from mounted volume
        command:
        - /bin/sh
        - -c
        - |
          export DB_USER=$(cat /vault/secrets/db-username)
          export DB_PASS=$(cat /vault/secrets/db-password)
          exec /app/start.sh
      
      volumes:
      - name: vault-secrets
        csi:
          driver: secrets-store.csi.k8s.io
          readOnly: true
          volumeAttributes:
            secretProviderClass: "openbao-secrets"
```

--------------------------------

### Get All Openbao Resources

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/11-installation-operations.md

List all Kubernetes resources associated with the Openbao application using a label selector.

```bash
# Get all resources
kubectl get all -l app.kubernetes.io/name=openbao
```

--------------------------------

### Test Multiple Resource Values

Source: https://github.com/openbao/openbao-helm/blob/main/CONTRIBUTING.md

This example shows how to test multiple resource requests and limits for a StatefulSet by using multiple `--set` flags with `helm template`. It then uses `yq` to extract and assert specific resource values.

```bash
@test "server/standalone-StatefulSet: custom resources" {
  cd `chart_dir`
  local actual=$(helm template \
		  --show-only templates/server-statefulset.yaml  \
		  --set 'server.standalone.enabled=true' \
		  --set 'server.resources.requests.memory=256Mi' \
		  --set 'server.resources.requests.cpu=250m' \
		  . | tee /dev/stderr |
		  yq -r '.spec.template.spec.containers[0].resources.requests.memory' | tee /dev/stderr)
  [ "${actual}" = "256Mi" ]

  local actual=$(helm template \
		  --show-only templates/server-statefulset.yaml  \
		  --set 'server.standalone.enabled=true' \
		  --set 'server.resources.limits.memory=256Mi' \
		  --set 'server.resources.limits.cpu=250m' \
		  . | tee /dev/stderr |
		  yq -r '.spec.template.spec.containers[0].resources.limits.memory' | tee /dev/stderr)
  [ "${actual}" = "256Mi" ]
}
```

--------------------------------

### Test Secret Mount with CSI Provider

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/07-csi-provider.md

Apply a SecretProviderClass and a Pod to test mounting secrets using the CSI driver. This example configures Vault as the provider and mounts a secret to a specified path.

```yaml
apiVersion: secrets-store.csi.x-k8s.io/v1
kind: SecretProviderClass
metadata:
  name: test-vault
spec:
  provider: vault
  parameters:
    vaultAddress: "http://openbao.default.svc:8200"
    vaultSkipTLSVerify: "false"
    roleName: "default"
    secretPath: |
      - secretKey: "value"
        path: "secret/data/test"
        objectName: "test-secret"
---
apiVersion: v1
kind: Pod
metadata:
  name: test-csi
spec:
  serviceAccountName: default
  containers:
  - name: test
    image: alpine
    command: ["sleep", "3600"]
    volumeMounts:
    - name: vault
      mountPath: /vault/secrets
  volumes:
  - name: vault
    csi:
      driver: secrets-store.csi.k8s.io
      volumeAttributes:
        secretProviderClass: "test-vault"
```

```bash
# Check mounted secrets
kubectl exec test-csi -- ls -la /vault/secrets/
kubectl exec test-csi -- cat /vault/secrets/test-secret
```

--------------------------------

### Verify OpenBao Helm Charts with chart-verifier

Source: https://github.com/openbao/openbao-helm/blob/main/test/README.md

Run chart verification tests using the chart-verifier tool. You can use a local installation or the latest Docker container.

```bash
bats test/chart/verifier.bats
```

```bash
USE_DOCKER=true bats test/chart/verifier.bats
```

--------------------------------

### Install Secrets Store CSI Driver using Helm

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/07-csi-provider.md

Install the Kubernetes Secrets Store CSI Driver separately using Helm. This is a prerequisite for the OpenBao CSI Provider.

```bash
# Using Helm
helm repo add secrets-store-csi-driver https://kubernetes-sigs.github.io/secrets-store-csi-driver/charts
helm install csi-secrets-store secrets-store-csi-driver/secrets-store-csi-driver \
  --namespace kube-system
```

--------------------------------

### Standalone Mode Configuration with File Storage

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/05-deployment-modes.md

Configure OpenBao to run in standalone mode using file storage. This example also enables the UI and disables TLS for simplicity.

```yaml
server:
  standalone:
    enabled: true
    config: |
      listener "tcp" {
        address = "0.0.0.0:8200"
        tls_disable = true
      }
      
      storage "file" {
        path = "/openbao/data"
      }
      
      ui = true
```

--------------------------------

### Run Local Unit Tests

Source: https://github.com/openbao/openbao-helm/blob/main/CONTRIBUTING.md

Executes the unit tests locally using the Bats test runner. Ensure Bats is installed and you are in the `openbao-helm` directory.

```bash
bats ./test/unit
```

--------------------------------

### Configure OpenBao Snapshot Backups

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/05-deployment-modes.md

Enable and configure automatic snapshot backups for OpenBao in HA mode. This example shows enabling the snapshot agent, setting a schedule, retention policy, and S3 storage configuration.

```yaml
snapshotAgent:
  enabled: true
  schedule: "0 2 * * *"  # Daily at 2 AM
  preserve: 7  # Keep 7 recent snapshots
  
  storage:
    s3:
      enabled: true
      bucket: "my-openbao-backups"
      region: "us-east-1"
      path: "raft-snapshots"
```

--------------------------------

### Add OpenBao Helm Repository

Source: https://github.com/openbao/openbao-helm/blob/main/README.md

Adds the OpenBao Helm chart repository to your Helm configuration. This is a prerequisite for installing the chart.

```bash
helm repo add openbao https://openbao.github.io/openbao-helm
```

--------------------------------

### Get Openbao Related Resource Details

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/11-installation-operations.md

Retrieve detailed information about core Kubernetes resource types used by Openbao.

```bash
# Get details of main resources
kubectl get statefulsets
kubectl get deployments
kubectl get daemonsets
kubectl get services
```

--------------------------------

### Verify Webhook Registration with kubectl

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/06-agent-injector.md

Commands to check if the mutating webhook configuration is registered and to get detailed information about it.

```bash
kubectl get mutatingwebhookconfigurations
kubectl describe mutatingwebhookconfigurations openbao-agent-injector-cfg
```

--------------------------------

### Create and Copy Manual Snapshot

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/09-ha-and-clustering.md

Manually create a snapshot of the Openbao data and copy it out of the pod. This is useful for ad-hoc backups or migration.

```bash
# Create snapshot manually
kubectl exec openbao-0 -- \
  openbao operator raft snapshot /tmp/snapshot.snap

# Copy snapshot out
kubectl cp openbao/openbao-0:/tmp/snapshot.snap ./snapshot.snap
```

--------------------------------

### List Available OpenBao Chart Versions

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/11-installation-operations.md

Searches the added OpenBao Helm repository to display all available chart versions and their corresponding application versions.

```bash
# See all available chart versions
helm search repo openbao/openbao --versions

# Output:
NAME                CHART VERSION   APP VERSION     DESCRIPTION
openbao/openbao    0.28.4          v2.5.5          Official OpenBao Chart
openbao/openbao    0.28.3          v2.5.4          Official OpenBao Chart
...
```

--------------------------------

### Get Target Kubernetes Namespace

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/03-helm-templates.md

Returns the target Kubernetes namespace for all resource deployments.

```go-html-template
{{- define "openbao.namespace" -}}
{{- default .Release.Namespace .Values.global.namespace -}}
{{- end -}}
```

--------------------------------

### Configure Openbao Readiness Probe

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/09-ha-and-clustering.md

Configure the readiness probe for Openbao pods to detect failures. Ensure the probe path and port are correctly set for health checks.

```yaml
readinessProbe:
  httpGet:
    path: /v1/sys/health?standbyok=true
    port: 8200
  failureThreshold: 2
  periodSeconds: 5
```

--------------------------------

### Configure MySQL Storage

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/08-storage-configuration.md

Use this configuration to set up MySQL or MariaDB as the Openbao storage backend. Ensure the connection URL is correctly formatted.

```yaml
server:
  ha:
    enabled: true
    replicas: 3
    config: |
      storage "mysql" {
        connection_url = "openbao:password@tcp(mysql.example.com:3306)/openbao"
        table = "vault"
      }
```

--------------------------------

### Get Helm Release Manifest

Source: https://github.com/openbao/openbao-helm/blob/main/charts/openbao/templates/NOTES.txt

Use this command to retrieve the Kubernetes manifest for your OpenBao Helm release.

```bash
helm get manifest {{ .Release.Name }}
```

--------------------------------

### Run OpenBao Helm Acceptance Tests in GKE

Source: https://github.com/openbao/openbao-helm/blob/main/test/README.md

Use these Makefile targets to provision a GKE cluster, run acceptance tests, and tear down the cluster. Ensure GOOGLE_CREDENTIALS and CLOUDSDK_CORE_PROJECT are set.

```bash
make test-image
```

```bash
make test-provision
```

```bash
make test-acceptance
```

```bash
ACCEPTANCE_TESTS=true make test-acceptance
```

```bash
make test-destroy
```

--------------------------------

### Run OpenBao Helm Acceptance Tests in Kind

Source: https://github.com/openbao/openbao-helm/blob/main/test/README.md

Execute acceptance tests locally using a kind cluster. You can specify custom cluster names and Kubernetes versions.

```bash
make test-acceptance LOCAL_ACCEPTANCE_TESTS=true
```

```bash
ACCEPTANCE_TESTS=true make test-acceptance LOCAL_ACCEPTANCE_TESTS=true
```

```bash
make delete-kind
```

```bash
KIND_CLUSTER_NAME=my-kind-cluster make test-acceptance LOCAL_ACCEPTANCE_TESTS=true
```

```bash
KIND_K8S_VERSION=v1.25.0 make test-acceptance LOCAL_ACCEPTANCE_TESTS=true
```

--------------------------------

### Check Openbao Readiness and Initialization Status

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/11-installation-operations.md

Execute a command inside an Openbao pod to check its initialization and sealed status.

```bash
# Check readiness
kubectl exec openbao-0 -- \
  curl -s http://localhost:8200/v1/sys/health | jq '.initialized,.sealed'
```

--------------------------------

### Create OpenBao Snapshot Backup

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/11-installation-operations.md

Use this command to create a snapshot of the OpenBao Raft data. Ensure you have sufficient space in the specified path.

```bash
# Create snapshot
kubectl exec openbao-0 -- \
  openbao operator raft snapshot /tmp/snapshot.snap

# Copy snapshot
kubectl cp openbao/openbao-0:/tmp/snapshot.snap ./snapshot-backup.snap

# Store in safe location
aws s3 cp snapshot-backup.snap s3://backups/openbao/
```

--------------------------------

### Get OpenBao Prometheus Metrics

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/09-ha-and-clustering.md

Fetch OpenBao metrics in Prometheus format from the `/v1/sys/metrics` endpoint. These metrics can be used for monitoring various aspects of the OpenBao cluster.

```bash
# Get Prometheus-format metrics
curl http://openbao:8200/v1/sys/metrics
```

--------------------------------

### Build Docker Image for Tests

Source: https://github.com/openbao/openbao-helm/blob/main/CONTRIBUTING.md

Builds the Docker image required for running automated tests. Ensure you are in the `openbao-helm` directory before running.

```shell
docker build -f ${PWD}/test/docker/Test.dockerfile ${PWD}/test/docker/ -t openbao-helm-test
```

--------------------------------

### Initialize OpenBao Cluster

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/11-installation-operations.md

Initialize the OpenBao cluster for non-development deployments. Ensure you securely store the generated unseal keys and root token.

```bash
# Get pod to initialize
kubectl get pods -l app.kubernetes.io/name=openbao

# Initialize the cluster
kubectl exec openbao-0 -- openbao operator init

# Output:
Unseal Key 1: xxxxxxxxxx
Unseal Key 2: xxxxxxxxxx
Unseal Key 3: xxxxxxxxxx
Unseal Key 4: xxxxxxxxxx
Unseal Key 5: xxxxxxxxxx

Initial Root Token: s.xxxxxxxx
```

--------------------------------

### Run Specific Dockerized Bats Tests

Source: https://github.com/openbao/openbao-helm/blob/main/CONTRIBUTING.md

Runs specific Bats tests within the Docker container by filtering with a regular expression. This example filters for tests containing 'injector'.

```shell
docker run -it --rm -v "${PWD}:/test" openbao-helm-test bats /test/test/unit -f "injector"
```

--------------------------------

### Configure Google Cloud Storage (GCS)

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/08-storage-configuration.md

Configure Openbao to use Google Cloud Storage (GCS) for data storage. Specify the bucket name and project ID for your GCS setup.

```yaml
server:
  ha:
    enabled: true
    replicas: 3
    config: |
      storage "gcs" {
        bucket = "my-openbao-storage"
        project_id = "my-gcp-project"
      }
```

--------------------------------

### Standalone Mode Integrated Storage (Raft) Backend

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/05-deployment-modes.md

Configure OpenBao to use integrated storage with the Raft consensus protocol. This is suitable for HA setups but can also be used in standalone mode.

```hcl
storage "raft" {
  path = "/openbao/data"
  node_id = "openbao-0"
}
```

--------------------------------

### Run Helm Test for OpenBao Release

Source: https://github.com/openbao/openbao-helm/blob/main/test/README.md

Execute a simple Helm test against an existing OpenBao Helm release. Replace `<RELEASE_NAME>` with your actual release name.

```bash
helm test <RELEASE_NAME>
```

--------------------------------

### Openbao Server Configuration

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/10-values-reference.md

Configure the Openbao server deployment, including image details, update strategies, logging, resource limits, and ingress settings. Use '-' to inherit from global settings.

```yaml
server:
  enabled: "-" # "-" inherits from global.enabled
  
  # Images
  image:
    registry: "quay.io"
    repository: "openbao/openbao"
    tag: "" # Defaults to chart appVersion
    pullPolicy: "IfNotPresent"
  
  # Update strategy
  updateStrategyType: "OnDelete"
  podManagementPolicy: "OrderedReady"
  
  # Logging
  logLevel: ""
  logFormat: ""
  
  # Resources
  resources: {}
  
  # Ingress
  ingress:
    enabled: false
    labels: {}
    annotations: {}
    ingressClassName: ""
    pathType: "Prefix"
    activeService: true
    hosts:
      - host: chart-example.local
        paths: []
    extraPaths: []
    tls: []
  
  # Gateway API (K8s 1.20+)
  gateway:
    tlsRoute:
      enabled: false
      labels: {}
      annotations: {}
      hosts: []
      apiVersion: gateway.networking.k8s.io/v1alpha3
      activeService: true
      parentRefs: []
    
    httpRoute:
      enabled: false
      labels: {}
      annotations: {}
      hosts: []
      apiVersion: gateway.networking.k8s.io/v1
      activeService: true
      parentRefs: []
      matches:
        path:
          type: PathPrefix
          value: '/'
        timeouts: {}
      filters: []
    
    tlsPolicy:
      enabled: false
      labels: {}
      annotations: {}
      apiVersion: gateway.networking.k8s.io/v1
      activeService: true
      targetRefs: []
      validation: {}
  
  # OpenShift Route
  route:
    enabled: false
    activeService: true
    labels: {}
    annotations: {}
    host: chart-example.local
    tls:
      termination: passthrough
  
  # Probes
  readinessProbe:
    enabled: true
    port: 8200
    path: ""
    failureThreshold: 2
    initialDelaySeconds: 5
    periodSeconds: 5
    successThreshold: 1
    timeoutSeconds: 3
  
  livenessProbe:
    enabled: false
    execCommand: []
    path: "/v1/sys/health?standbyok=true"
    port: 8200
    failureThreshold: 2
    initialDelaySeconds: 60
    periodSeconds: 5
    successThreshold: 1
    timeoutSeconds: 3
  
  # Lifecycle
  terminationGracePeriodSeconds: 10
  preStopSleepSeconds: 5
  postStart: []
  
  # Volumes
  extraInitContainers: []
  extraContainers: null
  shareProcessNamespace: false
  extraArgs: ""
  extraPorts: []
  extraEnvironmentVars: {}
  extraSecretEnvironmentVars: []
  volumes: null
  volumeMounts: null
  
  # Pod configuration
  affinity: ""
  topologySpreadConstraints: []
  tolerations: []
  nodeSelector: {}
  priorityClassName: ""
  annotations: {}
  extraLabels: {}
  configAnnotation: false
  
  # Security
  securityContext:
    pod: {}
    container: {}
  
  networkPolicy:
    enabled: false
    egress: []
    ingress:
      - from:
          - namespaceSelector: {}
        ports:
          - port: 8200
            protocol: TCP
          - port: 8201
            protocol: TCP
  
  # Service
  service:
    enabled: true
    active:
      enabled: true
      annotations: {}
      extraLabels: {}
    standby:
      enabled: true
      annotations: {}
      extraLabels: {}
    annotations: {}
    extraLabels: {}
  
  # Service Account
  serviceAccount:
    create: true
    name: ""
    annotations: {}
    createSecret: false
  
  # Auth Delegator
  authDelegator:
    enabled: true
  
  # Pod Disruption Budget
  podDisruptionBudget: {}
  
  # Standalone mode
  standalone:
    enabled: "-"
    config: ""
  
  # Dev mode
  dev:
    enabled: false
    devRoot: "/openbao/data"
  
  # HA mode
  ha:
    enabled: true
    replicas: 3
    raft:
      enabled: true
      setNodeId: true
      config: ""
    disruptionBudget:
      maxUnavailable: null

```

--------------------------------

### OpenBao Agent Injector Health Probes

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/04-kubernetes-resources.md

Configures liveness and readiness probes for the OpenBao agent injector Deployment. These probes use HTTP GET requests to the /health/ready endpoint on port 8080 with HTTPS.

```yaml
livenessProbe:
  httpGet:
    path: /health/ready
    port: 8080
    scheme: HTTPS
  failureThreshold: 2
  initialDelaySeconds: 5
  periodSeconds: 2
  timeoutSeconds: 5

readinessProbe:
  httpGet:
    path: /health/ready
    port: 8080
    scheme: HTTPS
```

--------------------------------

### Kubernetes Service Account, Role, and RoleBinding

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/06-agent-injector.md

Define the necessary Kubernetes Service Account, Role, and RoleBinding for the application to interact with OpenBao. The Role grants permissions to 'get' secrets, which is required for the agent injector.

```yaml
---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: my-app
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: my-app
rules:
- apiGroups: [""]
  resources: ["secrets"]
  verbs: ["get"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: my-app
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: my-app
subjects:
- kind: ServiceAccount
  name: my-app

```

--------------------------------

### Configure and Deploy Standalone Mode

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/05-deployment-modes.md

Set up OpenBao Helm chart for standalone mode, disabling development mode. This is part of the migration from dev to standalone.

```yaml
server:
  dev:
    enabled: false
  standalone:
    enabled: true
```

--------------------------------

### Configure DynamoDB for HA Locking with S3 Storage

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/08-storage-configuration.md

Configure Openbao to use S3 for primary storage and DynamoDB for High Availability (HA) locking. This setup ensures data durability and reliable failover.

```yaml
server:
  ha:
    enabled: true
    replicas: 3
    config: |
      storage "s3" {
        bucket = "openbao-data"
        region = "us-east-1"
      }
      
      ha_storage "dynamodb" {
        ha_table = "openbao-ha-locks"
        region = "us-east-1"
      }
```

--------------------------------

### UI Configuration Parameters

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/02-configuration.md

Defines the settings for the OpenBao web UI, including enablement, replicas, image details, and service configuration. Use '-' to inherit from global settings.

```yaml
ui:
  enabled: true | false | "-"
  replicas: integer
  activeService: boolean
  
  image:
    registry: string
    repository: string
    tag: string
    pullPolicy: string
  
  service:
    enabled: boolean
    port: integer
    targetPort: integer
    nodePort: integer (optional)
    annotations: {}
    extraLabels: {}
  
  externalPort: integer
  resourcesSnapshot: {}
```

--------------------------------

### CSI Provider Network Policy

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/07-csi-provider.md

Define a Kubernetes NetworkPolicy to control network traffic for the OpenBao CSI provider. This example allows egress traffic to the OpenBao API port (8200) and DNS ports (53).

```yaml
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: openbao-csi
spec:
  podSelector:
    matchLabels:
      app.kubernetes.io/name: openbao-csi-provider
  
  policyTypes:
  - Egress
  
  egress:
  - to:
    - namespaceSelector: {}
    ports:
    - protocol: TCP
      port: 8200  # OpenBao API
  
  - to:
    - podSelector: {}
    ports:
    - protocol: TCP
      port: 53    # DNS
    - protocol: UDP
      port: 53
```

--------------------------------

### Test Specific Value Rendering

Source: https://github.com/openbao/openbao-helm/blob/main/CONTRIBUTING.md

Verifies that a template value can be overridden using the `--set` flag in `helm template`. The example demonstrates setting `ui.serviceType` and asserting the rendered output matches the specified value.

```bash
@test "ui/Service: specified type" {
  cd `chart_dir`
  local actual=$(helm template \
      --show-only templates/ui-service.yaml  \
      --set 'ui.serviceType=LoadBalancer' \
      . | tee /dev/stderr |
      yq -r '.spec.type' | tee /dev/stderr)
  [ "${actual}" = "LoadBalancer" ]
}
```

--------------------------------

### Reinitialize and Restore Data

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/05-deployment-modes.md

Initialize a new OpenBao instance and import the previously exported data when migrating from dev to standalone mode. This restores the backed-up secrets.

```bash
vault operator init
vault secrets import kv /tmp/dev-data-backup.json
```

--------------------------------

### Test Agent Injection with a Pod

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/06-agent-injector.md

Applies a sample pod definition to test the agent injection functionality and then describes the pod to verify the injected containers.

```bash
kubectl apply -f - <<EOF
apiVersion: v1
kind: Pod
metadata:
  name: test-inject
  annotations:
    vault.hashicorp.com/agent-inject: "true"
    vault.hashicorp.com/role: "default"
spec:
  serviceAccountName: default
  containers:
  - name: test
    image: alpine
    command: ["sleep", "3600"]
EOF

kubectl describe pod test-inject
# Check for openbao-agent-init and openbao-agent containers
```

--------------------------------

### Automatic Node ID Assignment for Raft

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/08-storage-configuration.md

When `server.ha.raft.setNodeId` is true in the Helm chart values, node IDs are automatically assigned based on the pod index. This simplifies HA setup by eliminating manual ID configuration.

```text
openbao-0 → node_id = openbao-0
openbao-1 → node_id = openbao-1
openbao-2 → node_id = openbao-2
```

--------------------------------

### Troubleshoot Injector Not Injecting

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/11-installation-operations.md

Verify that the Openbao agent injector is functioning correctly by checking the webhook configuration, injector deployment status, and logs. Also, inspect pod annotations to confirm agent injection.

```bash
kubectl get mutatingwebhookconfigurations
```

```bash
kubectl get deploy openbao-agent-injector
```

```bash
kubectl logs -f deploy/openbao-agent-injector
```

```bash
kubectl describe pod test-inject
```

--------------------------------

### DaemonSet Configuration for CSI Provider

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/07-csi-provider.md

Configure the CSI provider's DaemonSet, including image details, kubelet root directory, security contexts, and probe settings. This snippet shows the default structure for deploying the CSI provider as a DaemonSet.

```yaml
csi:
  debug: false  # Enable debug logging
  
  image:
    registry: "quay.io"
    repository: "openbao/openbao-csi-provider"
    tag: ""
    pullPolicy: "IfNotPresent"
  
  daemonSet:
    kubeletRootDir: "/var/lib/kubelet"
    providersDir: "/etc/kubernetes/secrets-store-csi-providers"
    
    updateStrategy:
      type: "RollingUpdate"
      maxUnavailable: "1"
    
    securityContext:
      pod:
        runAsNonRoot: true
        runAsUser: 100
        fsGroup: 1000
      
      container:
        allowPrivilegeEscalation: false
        capabilities:
          drop:
            - ALL
  
  livenessProbe:
    failureThreshold: 2
    initialDelaySeconds: 5
    periodSeconds: 10
    successThreshold: 1
    timeoutSeconds: 3
  
  readinessProbe:
    failureThreshold: 2
    initialDelaySeconds: 5
    periodSeconds: 10
    successThreshold: 1
    timeoutSeconds: 3
  
  resources: {}
  # resources:
  #   limits:
  #     memory: 256Mi
  #     cpu: 100m
  #   requests:
  #     memory: 128Mi
  #     cpu: 50m

```

--------------------------------

### Test Openbao Agent Injection

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/11-installation-operations.md

Create a test pod with annotations to trigger Openbao agent injection and verify its presence and injected secrets.

```bash
# Create test pod with injection
kubectl apply -f - <<EOF
apiVersion: v1
kind: Pod
metadata:
  name: test-inject
  annotations:
    vault.hashicorp.com/agent-inject: "true"
    vault.hashicorp.com/role: "my-app"
    vault.hashicorp.com/agent-inject-secret-db: "secret/data/myapp/db"
spec:
  serviceAccountName: my-app
  containers:
  - name: test
    image: alpine
    command: ["sleep", "3600"]
EOF

# Check if agent was injected
kubectl describe pod test-inject
# Should show openbao-agent-init and openbao-agent containers

# Check injected secrets
kubectl exec test-inject -- ls -la /vault/secrets/
kubectl exec test-inject -- cat /vault/secrets/db
```

--------------------------------

### Basic Injector Configuration

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/06-agent-injector.md

Configure the OpenBao Agent Injector deployment, including replicas, port, image details, and logging settings.

```yaml
injector:
  enabled: true
  replicas: 2
  port: 8080
  
  image:
    registry: "docker.io"
    repository: "hashicorp/vault-k8s"
    tag: "1.7.2"
    pullPolicy: "IfNotPresent"
  
  authPath: "auth/kubernetes"
  logLevel: "info"
  logFormat: "standard"
```

--------------------------------

### View Helm Release Values

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/11-installation-operations.md

Inspect the current configuration values applied to a Helm release.

```bash
# View current values
helm values openbao
```

--------------------------------

### Verify CSI DaemonSet Deployment

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/07-csi-provider.md

Use kubectl commands to verify the deployment status of the CSI provider's DaemonSet. This includes checking the DaemonSet, describing it for details, and viewing its logs.

```bash
kubectl get daemonsets -n default
kubectl describe daemonset openbao-csi-provider
kubectl logs -n default -l app.kubernetes.io/name=openbao-csi-provider
```

--------------------------------

### Configure OpenBao Server Development Mode

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/02-configuration.md

Enable development mode for testing with in-memory storage. This disables persistence.

```yaml
server:
  dev:
    enabled: boolean
    devRoot: string
```

--------------------------------

### CSI Provider Configuration

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/02-configuration.md

Configure the CSI driver deployment and its associated settings. Use `csi.enabled` to control deployment, `csi.image` for image details, and `csi.agent` for the sidecar configuration. Probe settings like `livenessProbe` and `readinessProbe` can be tuned for health checks.

```yaml
csi:
  enabled: true | false | "-"
  debug: boolean
  extraArgs: []
  
  image:
    registry: string
    repository: string
    tag: string
    pullPolicy: string
  
  livenessProbe:
    failureThreshold: integer
    initialDelaySeconds: integer
    periodSeconds: integer
    successThreshold: integer
    timeoutSeconds: integer
  
  readinessProbe:
    failureThreshold: integer
    initialDelaySeconds: integer
    periodSeconds: integer
    successThreshold: integer
    timeoutSeconds: integer
  
  agent:
    enabled: boolean
    image:
      pullPolicy: string
      repository: string
      tag: string
    logFormat: string
    logLevel: string
    resources: {}
    extraArgs: []
  
  daemonSet:
    annotations: {} | string
    extraLabels: {}
    kubeletRootDir: string
    providersDir: string
    updateStrategy:
      maxUnavailable: string
      type: string
    securityContext:
      container: {} | string
      pod: {} | string
  
  pod:
    affinity: null | {} | string
    annotations: {} | string
    extraLabels: {}
    nodeSelector: null | {} | string
    tolerations: null | [] | string
  
  priorityClassName: string
  resources: {}
  serviceAccount:
    annotations: {}
```

--------------------------------

### Determine OpenBao Server Deployment Mode

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/03-helm-templates.md

Sets the `.mode` variable based on various configuration values, prioritizing external and development modes.

```go-html-template
{{- define "openbao.mode" -}}
  {{- template "openbao.serverEnabled" . -}}
  {{- if or (.Values.global.externalVaultAddr) (.Values.global.externalBaoAddr) -}}
    {{- $_ := set . "mode" "external" -}}
  {{- else if not .serverEnabled -}}
    {{- $_ := set . "mode" "external" -}}
  {{- else if eq (.Values.server.dev.enabled | toString) "true" -}}
    {{- $_ := set . "mode" "dev" -}}
  {{- else if eq (.Values.server.ha.enabled | toString) "true" -}}
    {{- $_ := set . "mode" "ha" -}}
  {{- else if or (eq (.Values.server.standalone.enabled | toString) "true") (eq (.Values.server.standalone.enabled | toString) "-") -}}
    {{- $_ := set . "mode" "standalone" -}}
  {{- else -}}
    {{- $_ := set . "mode" "" -}}
  {{- end -}}
{{- end -}}

```

--------------------------------

### Configure Standalone File Storage

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/08-storage-configuration.md

Use this configuration for standalone or development OpenBao deployments. Ensure the path exists and is writable by the OpenBao process.

```yaml
server:
  standalone:
    enabled: true
    config: |
      storage "file" {
        path = "/openbao/data"
      }
      
      listener "tcp" {
        address = "0.0.0.0:8200"
        tls_disable = true
      }
      
      ui = true
```

--------------------------------

### Configure OpenBao Server Standalone

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/02-configuration.md

Enables standalone mode for single-instance deployments. Use HCL configuration for backend selection and parameters. Defaults to using standalone if HA and Dev are both disabled.

```yaml
server:
  standalone:
    enabled: boolean | "-"
    config: string (HCL)
```

--------------------------------

### OpenBao Server Liveness Probe

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/04-kubernetes-resources.md

Configures the liveness probe for the OpenBao server container, using a custom script to check the health of the server.

```yaml
livenessProbe:
  exec:
    command:
      - /bin/sh
      - -c
      - /openbao/userconfig/mylivenessscript/run.sh
  failureThreshold: 2
  initialDelaySeconds: 60
  periodSeconds: 5
  timeoutSeconds: 3
```

--------------------------------

### Check Server Service Account Enabled

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/03-helm-templates.md

Determines if the server service account should be created. It checks if server service account creation is enabled and if either the server or global components are enabled.

```go
{{- define "openbao.serverServiceAccountEnabled" -}}
{{- $_ := set . "serverServiceAccountEnabled"
  (and
    (eq (.Values.server.serviceAccount.create | toString) "true" )
    (or
      (eq (.Values.server.enabled | toString) "true")
      (eq (.Values.global.enabled | toString) "true"))) -}}
{{- end -}}

```

--------------------------------

### OpenBao Server Configuration

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/02-configuration.md

Defines the core settings for an OpenBao server deployment, including image details, update strategies, logging, networking (ingress and service), pod configurations, security contexts, and lifecycle probes.

```yaml
server:
  enabled: true | false | "-"
  image:
    registry: string
    repository: string
    tag: string
    pullPolicy: string
  updateStrategyType: string
  podManagementPolicy: string
  logLevel: string
  logFormat: string
  resources: {}
  
  # Networking & Access
  ingress:
    enabled: boolean
    labels: {}
    annotations: {}
    ingressClassName: string
    pathType: string
    activeService: boolean
    hosts: []
    extraPaths: []
    tls: []
  
  service:
    enabled: boolean
    active:
      enabled: boolean
      annotations: {}
      extraLabels: {}
    standby:
      enabled: boolean
      annotations: {}
      extraLabels: {}
    annotations: {}
    extraLabels: {}
  
  # Pod Configuration
  podDisruptionBudget: {}
  affinity: string (multiline YAML)
  topologySpreadConstraints: []
  tolerations: []
  nodeSelector: {}
  priorityClassName: string
  annotations: {}
  extraLabels: {}
  
  # Security
  securityContext:
    pod: {} | string
    container: {} | string
  
  networkPolicy:
    enabled: boolean
    egress: []
    ingress: []
  
  # Lifecycle
  readinessProbe:
    enabled: boolean
    port: integer
    path: string
    failureThreshold: integer
    initialDelaySeconds: integer
    periodSeconds: integer
    successThreshold: integer
    timeoutSeconds: integer
  
  livenessProbe:
    enabled: boolean
    execCommand: []
    path: string
    port: integer
    failureThreshold: integer
    initialDelaySeconds: integer
    periodSeconds: integer
    successThreshold: integer
    timeoutSeconds: integer
  
  terminationGracePeriodSeconds: integer
  preStopSleepSeconds: integer
  postStart: []
  
  # Extensions
  extraInitContainers: []
  extraContainers: null
  shareProcessNamespace: boolean
  extraArgs: string
  extraPorts: []
  extraEnvironmentVars: {}
  extraSecretEnvironmentVars: []
  volumes: null
  volumeMounts: null

```

--------------------------------

### OpenBao Server Readiness Probe

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/04-kubernetes-resources.md

Configures the readiness probe for the OpenBao server container, checking the `/v1/sys/health` endpoint to ensure the server is ready to serve traffic.

```yaml
readinessProbe:
  httpGet:
    path: /v1/sys/health?standbyok=true
    port: 8200
    scheme: HTTP
  failureThreshold: 2
  initialDelaySeconds: 5
  periodSeconds: 5
  successThreshold: 1
  timeoutSeconds: 3
```

--------------------------------

### Configure OpenBao Kubernetes Auth Method

Source: https://github.com/openbao/openbao-helm/blob/main/_autodocs/07-csi-provider.md

Steps to enable and configure the Kubernetes authentication method on an OpenBao server, including setting up host, CA cert, issuer, and roles.

```hcl
# On OpenBao server
auth enable kubernetes

write auth/kubernetes/config \
  kubernetes_host="$KUBERNETES_SERVICE_HOST:443" \
  kubernetes_ca_cert=@/var/run/secrets/kubernetes.io/serviceaccount/ca.crt \
  issuer="https://kubernetes.default.svc.cluster.local"

write auth/kubernetes/role/backend \
  bound_service_account_names=backend \
  bound_service_account_namespaces=default \
  policies=backend-policy

# Create policy
write sys/policies/acl/backend-policy \
  policy=@- <<EOF
path "database/static/pg-users" {
  capabilities = ["read"]
}

path "pki/issue/web" {
  capabilities = ["create", "update"]
}

path "secret/data/api-keys" {
  capabilities = ["read"]
}
EOF
```