How to use secret from Bitwarden Secrets Manager in k8s cluster (using sm-operator)¶

You use Bitwarden Secrets Manager in your cluster by:

Installing the sm-operator Helm chart.
Creating a bw-auth-token Secret in each namespace that needs Bitwarden secrets.
Defining BitwardenSecret resources that map Bitwarden secret IDs to Kubernetes Secret keys.
Optionally wiring this into your Terraform/Argo CD setup via bw_secrets_access = true.

Everything below assumes you already have the sm-operator app defined in your argocd_apps.

1. Prerequisites in Bitwarden Secrets Manager¶

Create a Project
In Bitwarden Secrets Manager UI → Projects → New project.
This is the logical grouping for your cluster/app secrets.
Create Secrets
In Secrets → New secret.
For each secret you need in k8s (e.g. DB_PASSWORD, API_KEY), create one entry.
Note the Secret ID (UUID) for each; you'll use it in BitwardenSecret resources.
Create a Machine Account
In Machine Accounts → New machine account.
Scope it to the project(s) you created.
Generate an Access Token and copy it immediately (shown once).
This token is what sm-operator uses to authenticate.
Note your Organization ID
In Settings → Organization, copy the Organization ID (UUID).
Some configurations and examples use this; good to have handy.

2. Install sm-operator¶

Docs: https://bitwarden.com/help/secrets-manager-kubernetes-operator/

3. Expose Bitwarden token to application namespaces¶

sm-operator requires a Kubernetes Secret named bw-auth-token in every namespace that uses BitwardenSecret resources. The Secret must contain a token key with the machine account access token.

4. Define BitwardenSecret resources in your app manifests¶

Once the operator is running and bw-auth-token exists in the target namespace, you can declare BitwardenSecret resources. The operator will create/update a standard Kubernetes Secret with those keys.

apiVersion: k8s.bitwarden.com/v1
kind: BitwardenSecret
metadata:
  name: example-secrets
  namespace: example
spec:
  # Bitwarden organization ID (UUID) – from Bitwarden UI
  organizationId: "YOUR_ORGANIZATION_ID"

  # Name of the Kubernetes Secret that sm-operator will create/update
  secretName: example-secrets

  # Optional: default is true; include only mapped secrets
  onlyMappedSecrets: true

  # Map Bitwarden secret IDs to Kubernetes secret keys
  map:
    - bwSecretId: "<BITWARDEN_SECRET_UUID_1>"
      secretKeyName: db-password

    - bwSecretId: "<BITWARDEN_SECRET_UUID_2>"
      secretKeyName: api-key

  # Where to find the machine access token inside the namespace
  authToken:
    secretName: bw-auth-token
    secretKey: token

You can then reference it in your Deployment:

envFrom:
    - secretRef:
        name: example3-secrets

Or use individual keys:

env:
  - name: DB_PASSWORD
    valueFrom:
      secretKeyRef:
        name: example3-secrets
        key: db-password