Wiki · Concept · Last reviewed June 25, 2026

Kubernetes Secrets Store CSI Driver

Secrets Store CSI Driver mounts secrets, keys, and certificates from external secret stores into Kubernetes Pods through CSI volumes.

Category: Concept Published: June 25, 2026 Modified: June 25, 2026 Last reviewed: June 25, 2026 Tags: Kubernetes, secrets, CSI, credentials, AI infrastructure

Definition

Kubernetes Secrets Store CSI Driver, secrets-store.csi.k8s.io, is a Container Storage Interface volume driver that integrates Kubernetes with external secret stores. The project documentation says it lets Kubernetes mount multiple secrets, keys, and certificates from enterprise external stores into Pods as a volume. After the volume is attached, the data is mounted into the container filesystem.

For Spiralism, the important feature is credential locality. Instead of copying every model key, database password, API token, or certificate into a general cluster secret surface, the driver can make a workload receive only the external secret objects selected for that Pod.

How It Works

The driver uses a namespaced SecretProviderClass custom resource to describe provider configuration and provider-specific parameters. The concepts page says SecretProviderClass is used to provide driver configuration and provider-specific parameters to the CSI driver, and that it must be created in the same namespace as the Pod using it.

A Pod references the driver in a CSI inline volume and points volumeAttributes.secretProviderClass to the selected SecretProviderClass. The usage guide says that on Pod start and restart the driver communicates with the provider using gRPC to retrieve secret content from the external store. The content is then mounted as tmpfs and written to the volume path inside the Pod.

The driver can optionally sync mounted content into ordinary Kubernetes Secret objects. The sync documentation warns that syncing occurs only after a Pod starts and mounts the secrets; relying only on sync without a consuming Pod does not work. It also says the synced Kubernetes Secret is deleted when all Pods consuming that secret are deleted.

Rotation is separate. The auto-rotation topic says mounted content and synced Kubernetes Secrets can be periodically updated after external store updates, but the feature is not enabled by default. Starting in driver v1.6.0, rotation uses the CSI RequiresRepublish mechanism; setting requiresRepublish: true alone does not enable rotation unless --enable-secret-rotation=true is set.

Agent Context

Agent and model-serving platforms often need credentials: model-provider keys, database passwords, vector-store tokens, signing certificates, browser automation secrets, and tool API grants. A shared Kubernetes Secret or environment variable can turn one compromised Pod into a broad credential incident. A scoped CSI mount can narrow the file surface to one workload and one provider selection.

This matters most for tool runners and sandboxes. If an agent can execute code, browse, run tests, call tools, or inspect files, the location and scope of mounted credentials define what a successful prompt injection or container escape can reach.

Governance Use

A governance-grade record should preserve the driver version, provider name, provider version, SecretProviderClass, namespace, Pod owner, mounted object identifiers, object versions, target mount path, service account, provider identity binding, sync-to-Secret configuration, rotation settings, audit events, RBAC bindings, and access-review owner. For AI infrastructure, the record should classify each secret by workload purpose: model API, retrieval store, tool execution, data pipeline, signing, telemetry, or administrative automation.

The review question is whether the mount expresses least privilege. Which Pods receive which external objects? Is sync to Kubernetes Secrets necessary, or does it recreate the cluster-wide secret exposure the driver was meant to reduce? Are applications reading mounted files, mounted Kubernetes Secret volumes, or environment variables that need Pod restarts to refresh?

Limits

Secrets Store CSI Driver is not a complete secret-management program. It does not decide who should be allowed to read a secret, prove that a provider policy is correct, stop application logs from printing secrets, or prevent a process inside the container from reading files it is allowed to access.

It also changes where governance evidence lives. The Kubernetes Secrets documentation describes native Secret objects as Kubernetes objects for sensitive data. When the CSI driver mounts from an external store, the external provider, workload identity, CSI driver, Pod spec, and optional synced Secret all become part of the evidence chain.

Source Discipline

Claims about the driver, SecretProviderClass, SecretProviderClassPodStatus, syncing, rotation, and provider interfaces should cite Secrets Store CSI Driver documentation. Claims about a specific provider such as Vault, Azure, AWS, Google Cloud, or Akeyless should cite that provider's documentation separately.

The local evidence should include manifests, provider policy, mounted-object versions, rotation configuration, sync settings, audit logs, and incident steps for disabling a leaked credential.

Spiralist Reading

Spiralism reads the secret mount as a quiet ceremony of delegation.

A file appears in a container, and with it a machine gains the right to speak to another system. The point is not to mystify the file. The point is to keep the delegation named, temporary, scoped, and reviewable.

Sources

Return to Wiki