# kubernetes-sigs/secrets-store-csi-driver architecture

> Architecture diagram of the GitHub repository kubernetes-sigs/secrets-store-csi-driver, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kubernetes-sigs/secrets-store-csi-driver
- Repository: https://github.com/kubernetes-sigs/secrets-store-csi-driver

## Overview

##### Project type and purpose
- This is a Kubernetes extension: the “Secrets Store CSI Driver.” It consists of a set of CRDs, controllers, and a CSI volume‐plugin that lets you mount external secrets stores (e.g. Azure Key Vault, AWS Secrets Manager, Vault) into pods.

##### File structure and map out high‐level components
- apis/v1 & apis/v1alpha1: CRD type definitions for SecretProviderClass and SecretProviderClassPodStatus
- controllers/… : Kubernetes controllers (operator pattern)
- secretproviderclasspodstatus_controller
- syncsecret controller (sync CSI‐mounted secrets back to native K8s Secrets)
- tokenrequest controller (manage token refresh for external stores)
- cmd/secrets-store-csi-driver/main.go: entrypoint for the CSI driver binary
- pkg/secrets-store: CSI sidecar gRPC servers
- identityserver (NodeGetInfo, Probe)
- nodeserver (NodePublishVolume, NodeUnpublishVolume)
- controllerserver (ControllerPublish/Unpublish, CreateVolume, DeleteVolume)
- provider/: gRPC plugin interface (service.proto) and provider implementations
- charts/, deploy/, config/: Helm charts and raw YAML for installing the driver
- pkg/client, pkg/k8s, pkg/util, pkg/metrics, pkg/rotation: shared libraries for client‐go, token management, metrics, secret rotation

##### README for additional architectural insights
- CSI Inline volume integration
- SecretProviderClass CRD → instructs the CSI driver which provider and objects to fetch
- Sidecar & driver run in the same pod on each node
- Controllers run in a Deployment in the control plane

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Control Plane Components
    subgraph "Control Plane" 
        direction TB
        APIServer["API Server"]:::controlPlane
        ETCD["etcd (CRD Store)"]:::controlPlane
        subgraph "Controllers Deployment"
            direction TB
            SPCPSController["SecretProviderClassPodStatus Controller"]:::controlPlane
            SyncSecretController["SyncSecret Controller"]:::controlPlane
            TokenRequestController["TokenRequest Controller"]:::controlPlane
        end
    end

    %% Kubernetes Resources
    subgraph "Kubernetes Resources"
        direction TB
        SPClassCRD["SecretProviderClass CRD"]:::k8sRes
        SPClassPSCRD["SecretProviderClassPodStatus CRD"]:::k8sRes
        K8sSecret["Kubernetes Secret (optional)"]:::k8sRes
    end

    %% Node Plane Components
    subgraph "Node Plane"
        direction TB
        Kubelet["Kubelet"]:::nodePlane
        subgraph "CSI Driver DaemonSet Pod"
            direction TB
            CSIIdentity["CSI Identity Server"]:::nodePlane
            CSINode["CSI Node Server"]:::nodePlane
            CSIController["CSI Controller Server"]:::nodePlane
            GRPCServer["CSI Sidecar gRPC Server"]:::nodePlane
            subgraph "Provider Plugin"
                direction TB
                ProtoSvc["service.proto & gRPC Stubs"]:::provider
                FakeProvider["Fake Provider Implementation"]:::provider
            end
        end
    end

    %% External Systems
    subgraph "External Secret Stores"
        direction TB
        AzureKV["Azure Key Vault"]:::external
        AWSSecrets["AWS Secrets Manager"]:::external
        HashiVault["HashiCorp Vault"]:::external
        CustomProvider["Custom gRPC Provider"]:::external
    end

    %% Data Flows
    UserPod["User Pod Spec\n(refers to SPClass)"]:::external -->|applies| APIServer
    APIServer -->|stores CRD| ETCD
    APIServer -->|triggers| SPCPSController
    SPCPSController -->|watches| SPClassCRD
    SPCPSController -->|updates| SPClassPSCRD
    SyncSecretController -->|reads| SPClassPSCRD
    SyncSecretController -->|creates| K8sSecret
    TokenRequestController -->|manages| SPClassCRD

    Kubelet -->|CSI Inline Volume Request| CSINode
    CSINode -->|calls| CSIIdentity
    CSINode -->|calls| CSIController
    CSINode -->|uses| GRPCServer
    GRPCServer -->|invokes| ProtoSvc
    ProtoSvc -->|implements| FakeProvider
    FakeProvider -->|fetches| AzureKV
    FakeProvider -->|fetches| AWSSecrets
    FakeProvider -->|fetches| HashiVault
    FakeProvider -->|fetches| CustomProvider

    %% Click Events
    click SPClassCRD "https://github.com/kubernetes-sigs/secrets-store-csi-driver/blob/main/apis/v1/secretproviderclass_types.go"
    click SPClassCRD "https://github.com/kubernetes-sigs/secrets-store-csi-driver/blob/main/apis/v1alpha1/secretproviderclass_types.go"
    click SPClassPSCRD "https://github.com/kubernetes-sigs/secrets-store-csi-driver/blob/main/apis/v1/secretproviderclasspodstatus_types.go"
    click SPClassPSCRD "https://github.com/kubernetes-sigs/secrets-store-csi-driver/blob/main/apis/v1alpha1/secretproviderclasspodstatus_types.go"
    click SPCPSController "https://github.com/kubernetes-sigs/secrets-store-csi-driver/blob/main/controllers/secretproviderclasspodstatus_controller.go"
    click SyncSecretController "https://github.com/kubernetes-sigs/secrets-store-csi-driver/blob/main/controllers/syncsecret/syncsecret.go"
    click TokenRequestController "https://github.com/kubernetes-sigs/secrets-store-csi-driver/blob/main/controllers/tokenrequest/tokenrequest.go"
    click GRPCServer "https://github.com/kubernetes-sigs/secrets-store-csi-driver/blob/main/pkg/secrets-store/server.go"
    click CSIIdentity "https://github.com/kubernetes-sigs/secrets-store-csi-driver/blob/main/pkg/secrets-store/identityserver.go"
    click CSINode "https://github.com/kubernetes-sigs/secrets-store-csi-driver/blob/main/pkg/secrets-store/nodeserver.go"
    click CSIController "https://github.com/kubernetes-sigs/secrets-store-csi-driver/blob/main/pkg/secrets-store/controllerserver.go"
    click ProtoSvc "https://github.com/kubernetes-sigs/secrets-store-csi-driver/blob/main/provider/v1alpha1/service.proto"
    click ProtoSvc "https://github.com/kubernetes-sigs/secrets-store-csi-driver/blob/main/provider/v1alpha1/service.pb.go"
    click ProtoSvc "https://github.com/kubernetes-sigs/secrets-store-csi-driver/blob/main/provider/v1alpha1/service_grpc.pb.go"
    click FakeProvider "https://github.com/kubernetes-sigs/secrets-store-csi-driver/blob/main/provider/fake/fake_server.go"
    click CSIIdentity "https://github.com/kubernetes-sigs/secrets-store-csi-driver/blob/main/cmd/secrets-store-csi-driver/main.go"
    click AzureKV "https://github.com/kubernetes-sigs/secrets-store-csi-driver/tree/main/charts/secrets-store-csi-driver/"
    click ETCD "https://github.com/kubernetes-sigs/secrets-store-csi-driver/blob/main/deploy/secrets-store-csi-driver.yaml"
    click ETCD "https://github.com/kubernetes-sigs/secrets-store-csi-driver/blob/main/deploy/rbac.yaml"
    click SPClassCRD "https://github.com/kubernetes-sigs/secrets-store-csi-driver/blob/main/config/crd/bases/secrets-store.csi.x-k8s.io_secretproviderclasses.yaml"
    click SPClassPSCRD "https://github.com/kubernetes-sigs/secrets-store-csi-driver/blob/main/config/crd/bases/secrets-store.csi.x-k8s.io_secretproviderclasspodstatuses.yaml"
    click APIServer "https://github.com/kubernetes-sigs/secrets-store-csi-driver/tree/main/pkg/client/"
    click APIServer "https://github.com/kubernetes-sigs/secrets-store-csi-driver/tree/main/pkg/k8s/"
    click APIServer "https://github.com/kubernetes-sigs/secrets-store-csi-driver/tree/main/pkg/metrics/"
    click APIServer "https://github.com/kubernetes-sigs/secrets-store-csi-driver/tree/main/pkg/rotation/"
    click APIServer "https://github.com/kubernetes-sigs/secrets-store-csi-driver/tree/main/pkg/util/"

    %% Styles
    classDef controlPlane fill:#bbdefb,stroke:#1e88e5,color:#0d47a1;
    classDef nodePlane fill:#c8e6c9,stroke:#43a047,color:#1b5e20;
    classDef external fill:#ffe0b2,stroke:#fb8c00,color:#e65100;
    classDef k8sRes fill:#e1bee7,stroke:#8e24aa,color:#4a148c;
    classDef provider fill:#fff3e0,stroke:#ffb74d,color:#e65100;
```
