Skip to content

vaultwarden

Metadata

Field Value
Service vaultwarden
Purpose Self-hosted password manager compatible with Bitwarden clients
Criticality Tier 1
Owner Platform / Security owner
Clusters local
Namespace vaultwarden
Exposure internet
Stateful yes
Backup class snapshot
RPO / RTO Daily backup target, 2 to 4 hours to restore
Last reviewed 2026-06-29

1. Service Overview

Vaultwarden provides credential storage and password-management features and is therefore one of the more security-sensitive internet-facing applications in the estate. It also stores TOTP secrets and generates authenticator codes through the standard Bitwarden "authenticator key" item field; this is normal vault usage and requires no integration or API changes.

Summary

If it fails, users lose access to stored credentials and secure item synchronization until the service and data volume are restored.

Dependencies

Dependency Type Why it matters
Traefik ingress External HTTPS and websocket path
SMTP notification Needed for mail-based account flows where enabled
Persistent storage storage Preserves the credential database and attachments

2. Architecture Diagram

[Browser / Bitwarden client]
  -> [Traefik]
  -> [Vaultwarden]
  -> [PVC-backed application data]

3. Deployment Specifications

Item Value
Source path vaultwarden/base and vaultwarden/overlays/local
Deployment model Kustomize plus Fleet bundle
Namespace vaultwarden
Workload kind StatefulSet
Image vaultwarden/server:1.36.0 (pinned in base)
Scheduling edge node (node.io/ingress=true, tolerates node.io/role=edge)
Probes readiness + liveness on GET /alive:8080
Pod security non-root (UID 33), read-only root FS, dropped capabilities, no privilege escalation
RBAC ServiceAccount only (no Role/RoleBinding)
Config files base/kustomization.yaml, overlays/local/kustomization.yaml, fleet.yaml

Cluster mapping

Cluster Overlay path Notes
local vaultwarden/overlays/local Current local deployment

4. Configuration Guide

Environment variables

Runtime configuration is split into a committed ConfigMap and a gitignored Secret, both loaded by the StatefulSet through envFrom.

Variable Source Purpose Secret?
DOMAIN, SMTP_HOST, SMTP_PORT, SMTP_SECURITY, SMTP_FROM, SMTP_FROM_NAME ConfigMap vaultwarden-config (vault-config.env, committed) Domain and SMTP transport config no
ROCKET_PORT, ROCKET_WORKERS, WEBSOCKET_ENABLED, DATA_FOLDER ConfigMap vaultwarden-config App runtime tuning no
SIGNUPS_ALLOWED, INVITATIONS_ALLOWED, SHOW_PASSWORD_HINT, WEB_VAULT_ENABLED ConfigMap vaultwarden-config Account and vault policy no
SMTP_USERNAME, SMTP_PASSWORD Secret vaultwarden-secrets (vault-secrets.env, gitignored) SMTP authentication yes
ADMIN_TOKEN Secret vaultwarden-secrets Admin panel access yes

ConfigMaps

Resource Path Purpose
vaultwarden-config vaultwarden/overlays/local/vault-config.env Non-secret runtime configuration

Secrets management

  • Secret name: vaultwarden-secrets (namespace vaultwarden), generated from overlays/local/vault-secrets.env.
  • Required keys: SMTP_USERNAME, SMTP_PASSWORD, ADMIN_TOKEN. See overlays/local/vault-secrets.env.example.
  • Source of truth: overlays/local/vault-secrets.env is gitignored and supplied out of band. Do not commit real values.
  • Rotation trigger: admin changes, SMTP rotation, or incident response.
  • Recovery note: restore vault-secrets.env (or recreate the Secret) before redeploying the StatefulSet.
  • Audit note: real SMTP_PASSWORD and ADMIN_TOKEN values were previously committed in vault-config.env and remain in git history. History purge and rotation are tracked separately in context/progress-tracker.md.

5. Access Protocols

Path URL or endpoint Audience Auth TLS terminates at
Internal Vaultwarden service in the namespace Cluster workloads namespace RBAC Traefik / Vaultwarden
External https://vault.mutana.fr End users Vaultwarden auth Traefik

6. Operations and Observability

  • Primary health indicators: readiness/liveness probes on GET /alive:8080, StatefulSet healthy, PVC mounted.
  • Dashboards or alerts: shared cluster monitoring and ingress health.
  • Log locations: Vaultwarden pod logs.
  • Known failure modes: PVC attach failure, SMTP issues, websocket routing errors, stale or missing vaultwarden-secrets.

7. Backup and Recovery Notes

  • Backup method: application data snapshot plus secret backup.
  • Restore prerequisites: restored PVC and runtime secrets.
  • Related runbook: ../runbooks/vaultwarden.md

8. Release and Change Notes

  • Current deployed app version: vaultwarden/server:1.36.0 (security release: SSO Login CSRF, user enumeration, SSRF fixes).
  • Current chart version: N/A.
  • Last significant change: hardened pod security, added probes, split runtime config into ConfigMap + gitignored Secret, removed unused Role/RoleBinding, pinned image in base.
  • Rollback reference: previous overlay revision in Git; snapshot the PVC before a version downgrade because vaultwarden data-format changes can make downgrades unsafe.