# hashicorp/vault-secrets-operator architecture

> Architecture diagram of the GitHub repository hashicorp/vault-secrets-operator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hashicorp/vault-secrets-operator
- Repository: https://github.com/hashicorp/vault-secrets-operator

## Overview

##### Project Type and Purpose
- This is a Kubernetes operator – the Vault Secrets Operator – whose purpose is to monitor a set of Custom Resource Definitions (CRDs) (defined under the “api/v1beta1” directory and in configuration files under “config/crd” and “chart/crds”) to synchronize secrets from an external Vault secrets engine to Kubernetes Secrets.
- The operator supports various authentication methods, secret types (static and dynamic), credential integrations (AWS, GCP, Azure, HCP), and secret rotation capabilities.

##### Main Components
a. Kubernetes Cluster: Show the overall K8s environment where the operator runs.
b. Operator Pod: The central component that includes the operator’s main business logic. This encapsulates several sub-components:
- CRD Watchers & Controllers – the reconciliation loops implemented in the “controllers” directory (for example, hcpauth_controller, hcpvaultsecretsapp_controller, vaultauth_controller, etc.)
- API Definitions – found in the “api/v1beta1” directory to define the CRDs.
- Vault Client & Vault Integration – the “vault” package and related helper modules manage communication with Vault.
- Credentials Management – sub-modules under “credentials” that provide management and validation for various auth providers (e.g., Kubernetes, HCP, Vault’s AWS, GCP, Azure auth).
- Utilities and Helpers – the “helpers”, “common”, “consts”, and “internal” directories which provide shared functionality (logging, metrics, configuration, etc.).
d. Kubernetes Secrets: Display Kubernetes Secrets as the ultimate destination for the synchronized data.
e. Deployment & Configuration Resources: Show artifacts like Helm charts (in “chart”), Kustomize configurations (in “config”), and manifests that are used for deployment and customization.
f. Monitoring and Logging: Include Prometheus instrumentation (seen in RBAC setup and metrics-related templates) and logging components for tracking the operator’s activity.

##### Relationships and Data Flow
- That when a relevant CRD (for example, VaultStaticSecret, VaultDynamicSecret, VaultAuth, etc.) is created/modified, the operator’s controllers are triggered.
- How controllers use the API definitions to understand the desired state and then interact with the external Vault service via authenticated calls (using credentials patterns detailed under “credentials/vault”).
- Flow where data fetched from Vault is written into Kubernetes Secrets.
- Optionally, illustrate bidirectional feedback: The operator may adjust auxillary resources or update metrics/logs that are then collected by Prometheus and other monitoring tools.

##### Architectural Patterns and Design Principles
- Operator Pattern with a reconciliation loop that periodically checks the state of both Vault and Kubernetes.
- Usage of CRDs to extend Kubernetes’ API and support declarative management.
- Separation of concerns by grouping functionalities into distinct modules (controllers for business logic, credentials management for external auth integrations, and utility packages for common operations).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Kubernetes Cluster
    subgraph "Kubernetes Cluster"
        A["Vault Secrets Operator Pod"]:::operatorPod
        B["Kubernetes Secrets"]:::k8s
    end

    %% Operator internal modules
    A1["Main Logic (main.go)"]:::internal
    A2["CRD Controllers (controllers)"]:::internal
    A3["API Definitions (api/v1beta1)"]:::internal
    A4["Vault Integration (vault & credentials/vault)"]:::internal
    A5["Credentials Management (credentials)"]:::internal
    A6["Utilities & Helpers (helpers, common, consts, internal)"]:::internal

    %% External Service
    E["External Vault Service (Vault)"]:::external

    %% Deployment & Configuration Resources
    subgraph "Deployment & Configuration"
        D1["Helm Charts & Manifests (chart)"]:::config
        D2["Kustomize & Config (config)"]:::config
    end

    %% Monitoring & Logging
    M1["Prometheus & Logging (internal/metrics, prometheus-servicemonitor)"]:::monitoring

    %% Layout inside Kubernetes Cluster: Link Operator Pod to its internal modules
    A --> A1
    A1 --> A2
    A2 --> A3
    A3 --> A4
    A5 --> A4
    A1 --> A6

    %% Operator workflow: From Vault Integration to external Vault and then to Kubernetes Secrets
    A4 -->|"fetch_secrets"| E
    A4 -->|"sync_secrets"| B

    %% Monitoring: Operator sends metrics/logs
    A1 -->|"metrics_update"| M1

    %% Deployment: Operator is managed via deployment resources
    A -->|"deployed_by"| D1
    A -->|"configured_by"| D2

    %% Click Events
    click A1 "https://github.com/hashicorp/vault-secrets-operator/blob/main/main.go"
    click A2 "https://github.com/hashicorp/vault-secrets-operator/blob/main/controllers/hcpauth_controller.go"
    click A3 "https://github.com/hashicorp/vault-secrets-operator/tree/main/api/v1beta1"
    click A4 "https://github.com/hashicorp/vault-secrets-operator/blob/main/vault/client.go"
    click A5 "https://github.com/hashicorp/vault-secrets-operator/tree/main/credentials"
    click A6 "https://github.com/hashicorp/vault-secrets-operator/blob/main/helpers/client.go"
    click D1 "https://github.com/hashicorp/vault-secrets-operator/tree/main/chart"
    click D2 "https://github.com/hashicorp/vault-secrets-operator/tree/main/config"
    click M1 "https://github.com/hashicorp/vault-secrets-operator/blob/main/internal/metrics/metrics.go"

    %% Styles
    classDef operatorPod fill:#D3E4CD,stroke:#4B3832,stroke-width:2px;
    classDef internal fill:#95E1D3,stroke:#4B3832,stroke-width:2px;
    classDef k8s fill:#ACE7EF,stroke:#4B3832,stroke-width:2px;
    classDef external fill:#FFB6C1,stroke:#4B3832,stroke-width:2px;
    classDef config fill:#F0E68C,stroke:#4B3832,stroke-width:2px;
    classDef monitoring fill:#F08080,stroke:#4B3832,stroke-width:2px;
```
