Architecture: OpenBao Supervisor Operator

This document provides a comprehensive overview of the OpenBao Operator's architecture.

• Overview

  ---

  High-level design and supervisor pattern.

  Jump to Overview

• Components

  ---

  Controller manager, interacting controllers, and state.

  Jump to Components

• Security

  ---

  Least-privilege RBAC and zero-trust model.

  Security Docs

• API Spec

  ---

  CRD specification and status fields.

  Jump to API

1. Architecture Overview

The OpenBao Operator adopts a Supervisor Pattern. It delegates data consistency to the OpenBao binary while managing the external ecosystem: PKI lifecycle, Infrastructure state, and Safe Version Upgrades.

1.1 Tenancy Models

The operator supports two architectural modes:

1. Multi-Tenant (Default): Uses a Provisioner controller to manage RBAC and namespaces dynamically. Adopts a Zero-Trust model where the Controller has limited permissions.
2. Single-Tenant: Designed for direct embedding. The Provisioner is disabled, and the Controller manages the target namespace directly with full permissions.

1.2 System Components

graph TD
    User([User]) -->|CRD| API[Kubernetes API]

    subgraph "Operator Controller Manager"
        Workload[Workload Ctrl]
        AdminOps[AdminOps Ctrl]
        Status[Status Ctrl]
        Provisioner[Provisioner Ctrl]
    end

    API -->|Watch| Operator[Operator Manager]
    Operator --> Workload & AdminOps & Status & Provisioner

    Workload -->|Reconcile| STS[StatefulSet]
    Workload -->|Reconcile| Svc[Services]
    AdminOps -->|Backup| ObjStore[Object Storage]

    STS -->|Run| Pods[OpenBao Pods]
    Pods -->|Data| PVC[Persistent Volumes]

1.3 Component Interaction

sequenceDiagram
    autonumber
    actor User
    participant API as K8s API
    participant Workload as Workload Ctrl
    participant AdminOps as AdminOps Ctrl
    participant Pods as OpenBao Pods

    User->>API: Apply OpenBaoCluster
    API->>Workload: Reconcile Event
    Workload->>API: Create ConfigMaps & Secrets
    Workload->>API: Create StatefulSet
    API->>Pods: Schedule Pods
    Pods->>Pods: Peer Discovery & Join

    loop Monitoring
        AdminOps->>API: Check Status
        opt Backup Scheduled
            AdminOps->>Pods: Trigger Snapshot
        end
    end

1.4 Assumptions

Core Assumptions

• Storage: Default StorageClass available.
• Network: Working DNS for StatefulSet identity.
• Version: OpenBao v2.4.0+ (required for static auto-unseal).

Cross-Cutting Concerns

Observability

Metric	Description
openbao_cluster_ready_replicas	Number of Ready replicas
openbao_reconcile_duration_seconds	Reconciliation duration
openbao_upgrade_status	Upgrade status (0=Idle, 1=Upgrading)

API Specification

The OpenBaoCluster CRD defines the desired state.

Spec (Desired State)

apiVersion: openbao.org/v1alpha1
kind: OpenBaoCluster
spec:
  version: "2.4.4"       # (1)!
  image: "openbao:2.4.4" # (2)!
  replicas: 3            # (3)!
  tls:
    enabled: true        # (4)!
  unseal:
    type: awskms         # (5)!
  profile: Hardened      # (6)!

1. Semantic OpenBao version.
2. Container image reference.
3. Number of replicas (default: 3).
4. Enable Operator-managed TLS.
5. Auto-unseal mechanism (static or external).
6. Security posture (Hardened or Development).

Status (Observability)

status:
  phase: Running  # (1)!
  activeLeader: pod-0  # (2)!
  readyReplicas: 3  # (3)!
  conditions:  # (4)!
    - Type: Available
      Status: True

1. High-level lifecycle phase.
2. Current Raft leader.
3. Number of ready pods.
4. Standard Kubernetes conditions.