This is a cache of https://docs.okd.io/latest/storage/container_storage_interface/persistent-storage-csi-secrets-store.html. It is a snapshot of the page at 2026-10-20T18:48:17.857+0000.
Secrets Store CSI Driver Operator - Using Container Storage Interface (CSI) | Storage | OKD 5
  1. Documentation
×

Secrets Store Container Storage Interface Driver Operator

Overview of Secrets Store CSI Driver Operator

The Secrets Store CSI Driver Operator mounts secrets from external secret management systems, such as Azure Key Vault, into pods by using a provider plugin. The secrets do not persist on the system after pod termination.

Secret objects are stored with Base64 encoding. etcd provides encryption at rest for these secrets, but when secrets are retrieved, they are decrypted and presented to the user. If role-based access control is not configured properly on your cluster, anyone with API or etcd access can retrieve or modify a secret. Additionally, anyone who is authorized to create a pod in a namespace can use that access to read any secret in that namespace.

The Secrets Store CSI Driver Operator, secrets-store.csi.k8s.io, enables OKD to mount multiple secrets, keys, and certificates stored in enterprise-grade external secrets stores into pods as a volume. The Secrets Store CSI Driver Operator communicates with the provider using gRPC to fetch the mount contents from the specified external secrets store. After the volume is attached, the data in it is mounted into the container’s file system. Secrets store volumes are mounted in-line.

For more information about CSI inline volumes, see "CSI inline ephemeral volumes".

Familiarity with persistent storage and configuring CSI volumes is recommended when working with a CSI driver. For more information, see "Understanding persistent storage" and "Configuring CSI volumes".

Additional resources

Secrets store providers

You can store sensitive application data in an external secret management system and use the Secrets Store CSI Driver Operator to mount the secret content as a pod volume.

The Secrets Store CSI Driver Operator has been tested with the following secrets store providers:

  • AWS Secrets Manager

  • AWS Systems Manager Parameter Store

  • Azure Key Vault

  • Google Secret Manager

  • HashiCorp Vault

IBM Z supports only HashiCorp Vault.

Red Hat does not test all factors associated with third-party secrets store provider functionality. For more information about third-party support, see the "Red Hat third-party support policy".

About CSI

The Container Storage Interface (CSI) enables storage vendors to deliver plugins through a standard interface without modifying Kubernetes core code, replacing traditional embedded storage drivers.

CSI Operators give OKD users storage options, such as volume snapshots, that are not possible with in-tree volume plugins.

Support for disconnected environments

You can use certain secrets store providers in disconnected OKD clusters by configuring VPC endpoints or equivalent connectivity to enable communication between the driver and external secret management systems.

The following secrets store providers support using the Secrets Store CSI driver in disconnected clusters:

  • AWS Secrets Manager

  • Azure Key Vault

  • Google Secret Manager

  • HashiCorp Vault

To enable communication between Secrets Store CSI driver and the secrets store provider, configure Virtual Private Cloud (VPC) endpoints or equivalent connectivity to the corresponding secrets store provider, the OpenID Connect (OIDC) issuer, and the Secure Token Service (STS). The exact configuration depends on the secrets store provider, the authentication method, and the type of disconnected cluster.

For more information about disconnected environments, see "About disconnected environments".
Additional resources

Support for network policies

The Secrets Store CSI Driver Operator uses pre-defined NetworkPolicies to control ingress and egress traffic for enhanced security of the Operator and driver components.

The following table summarizes the default ingress and egress rules:

Component Ingress ports Egress ports Description

Secrets Store CSI Driver Operator

8443

6443

Accesses metrics and communicates with the API server

Secrets Store CSI driver

8095

6443

Accesses metrics and communicates with the API server

Install the Secrets Store CSI driver

To enable OKD to mount secrets from external secret management systems, install the Secrets Store CSI Driver Operator and create a ClusterCSIDriver instance.

Prerequisites

  • Access to the OKD web console.

  • Administrator access to the cluster.

Procedure

  1. Install the Secrets Store CSI Driver Operator:

    1. Log in to the web console.

    2. Click Ecosystem → Software Catalog.

    3. Locate the Secrets Store CSI Driver Operator by typing "Secrets Store CSI" in the filter box.

    4. Click the Secrets Store CSI Driver Operator button.

    5. On the Secrets Store CSI Driver Operator page, click Install.

    6. On the Install Operator page, ensure that:

      • All namespaces on the cluster (default) is selected.

      • Installed Namespace is set to openshift-cluster-csi-drivers.

    7. Click Install.

      After the installation finishes, the Secrets Store CSI Driver Operator is listed in the Installed Operators section of the web console.

  2. Create the ClusterCSIDriver instance for the driver (secrets-store.csi.k8s.io):

    1. Click Administration → CustomResourceDefinitions → ClusterCSIDriver.

    2. On the Instances tab, click Create ClusterCSIDriver.

      Use the following YAML file:

      apiVersion: operator.openshift.io/v1
kind: ClusterCSIDriver
metadata:
    name: secrets-store.csi.k8s.io
spec:
  managementState: Managed

    3. Click Create.

Installing the Secrets Store CSI driver by using the CLI

The Secrets Store CSI driver is typically installed in the namespace openshift-cluster-csi-drivers. This namespace is present in the cluster as part of the installation of the Cluster Storage Operator.

Procedure

  1. Create an OperatorGroup object by running the following command:

    $ oc apply -f - <<EOF
apiVersion: operators.coreos.com/v1
kind: OperatorGroup
metadata:
  name: openshift-cluster-csi-drivers
  namespace: openshift-cluster-csi-drivers
spec: {}
EOF

  2. Create a Subscription object by running the following command:

    $ oc apply -f - <<EOF
apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: secrets-store-csi-driver-operator
  namespace: openshift-cluster-csi-drivers
spec:
  channel: stable
  installPlanApproval: Automatic
  name: secrets-store-csi-driver-operator
  source: redhat-operators
  sourceNamespace: openshift-marketplace
EOF

  3. Wait for the Operator to be up and running. You can check the Operator status by running the following command:

    $ oc get csv -n openshift-cluster-csi-drivers
    Example output
    NAME    DISPLAY     VERSION         RELEASE   REPLACES   PHASE
secrets-store-csi-driver-operator.v4.22.0-202607151755   Secrets Store CSI Driver Operator   4.22.0-202607151755                        Succeeded

  4. Create the Cluster CSI driver by running the following command:

    $ oc apply -f - <<EOF
apiVersion: operator.openshift.io/v1
kind: ClusterCSIDriver
metadata:
  name: secrets-store.csi.k8s.io
spec:
  managementState: Managed
EOF
Verification

  • Verify that the Operator is running:

    $ oc get operator -n openshift-cluster-csi-drivers
    Example output
    NAME                                                             AGE
secrets-store-csi-driver-operator.openshift-cluster-csi-drivers   7m55s

  • Verify that the pods are running:

    $ oc get pods -n openshift-cluster-csi-drivers
    Example output
    NAME                                                 READY   STATUS    RESTARTS   AGE
....
....
secrets-store-csi-driver-node-bhp2d                  3/3     Running   0          45s
secrets-store-csi-driver-operator-74696fc7bc-qjrl8   1/1     Running   0          7m40s

Configuring secret rotation for the Secrets Store CSI Driver

You can configure secret rotation intervals to control how often mounted secrets are refreshed from external stores, or disable rotation for static secrets based on your specific security and operational requirements.

By default, secret rotation is enabled. When rotation is enabled, the Secrets Store CSI Driver Operator polls the external secret store at a configurable interval to check for secret updates. This process ensures that updates in the external store are automatically reflected in your pods and secrets. By default, polling interval is 2 minutes.

If you enabled synchronization of mounted content as Kubernetes secrets, the Kubernetes secrets are also rotated when the external secrets are updated.

Applications consuming the secret data must watch for file system changes to detect updated secrets. The Secrets Store CSI Driver Operator updates the content of the mounted volume, and applications should reload the secrets when changes are detected.

Prerequisites

  • The Secrets Store CSI Driver Operator is installed on the cluster.

  • You have access to the cluster with cluster-admin privileges.

Procedure

  1. Edit the ClusterCSIDriver custom resource for the Secrets Store CSI Driver Operator by running the following command:

    $ oc edit clustercsidrivers.operator.openshift.io secrets-store.csi.k8s.io

  2. Locate or add the secretRotation section under spec.driverConfig.secretsStore. To enable secret rotation with a custom polling interval, set the type to Custom and configure the minimumRefreshAge field:

    apiVersion: operator.openshift.io/v1
kind: ClusterCSIDriver
metadata:
  name: secrets-store.csi.k8s.io
spec:
  driverConfig:
    driverType: SecretsStore
    secretsStore:
      secretRotation:
        type: Custom
        custom:
          minimumRefreshAge: 300

    where:

    spec.driverConfig.secretsStore.secretRotation.type

    Specifies the secret rotation mode. Set to Custom to enable secret rotation with a custom interval, or None to disable rotation. When rotation is disabled, secrets are fetched only at initial pod mount time.

    spec.driverConfig.secretsStore.secretRotation.custom.minimumRefreshAge

    Specifies the minimum number of seconds between rotation attempts. Valid range is 1 to 31,560,000 seconds (approximately 1 year). If omitted when type is Custom, the platform applies a default of 120 seconds.

    Choose a refresh interval based on your security and cost requirements:

    • For secrets that change frequently and require quick updates, use shorter intervals such as 60 (60 seconds) or 120 (2 minutes).

    • For secrets that change infrequently, use longer intervals such as 600 (10 minutes) or 3600 (1 hour) to reduce transaction costs and performance overhead.

  3. To disable secret rotation completely, set the type field to None:

    apiVersion: operator.openshift.io/v1
kind: ClusterCSIDriver
metadata:
  name: secrets-store.csi.k8s.io
spec:
  driverConfig:
    driverType: SecretsStore
    secretsStore:
      secretRotation:
        type: None

    When rotation is disabled, secrets are fetched only at initial pod mount time and are not updated thereafter, even if the values change in the external secret store.

  4. Save and apply the changes to the custom resource.

Verification

  1. Verify that the Secrets Store CSI Driver Operator driver pods are updated with the new configuration by running the following command:

    $ oc get pods -n openshift-cluster-csi-drivers | grep secrets-store
    Example output
    secrets-store-csi-driver-node-bhp2d                  3/3     Running   0          45s
secrets-store-csi-driver-node-xyz12                  3/3     Running   0          45s
secrets-store-csi-driver-operator-74696fc7bc-qjrl8   1/1     Running   0          7m40s

  2. Check the ClusterCSIDriver configuration to confirm the rotation settings by running the following command:

    $ oc get clustercsidrivers.operator.openshift.io secrets-store.csi.k8s.io -o jsonpath='{.spec.driverConfig.secretsStore.secretRotation}' | jq
    Example output
    {
  "custom": {
    "minimumRefreshAge": 300
  },
  "type": "Custom"
}

  3. For pods that mount secrets from the external store, monitor the file system to verify that the CSI driver rotates secrets according to the configured interval.

Configuring token requests for Workload Identity Federation

You can configure the Secrets Store CSI Driver Operator to use Workload Identity Federation (WIF) by specifying the service account token audience. This enables secure, credential-free authentication to external secret management systems across multiple cloud providers.

Workload Identity Federation allows your OKD workloads to access cloud provider services without storing long-lived credentials. Instead, the Secrets Store CSI Driver Operator uses short-lived service account tokens with a specified audience to authenticate to external secret stores.

Prerequisites

  • The Secrets Store CSI Driver Operator is installed on the cluster.

  • You are using Workload Identity Federation with a supported provider, such as AWS, Azure, Google Cloud Platform, or HashiCorp Vault.

  • You have configured your cloud provider to trust your OKD cluster’s OIDC provider.

  • You have access to the cluster with cluster-admin privileges.

Procedure

  1. Edit the ClusterCSIDriver custom resource for the Secrets Store CSI Driver Operator by running the following command:

    $ oc edit clustercsidrivers.operator.openshift.io secrets-store.csi.k8s.io

  2. Locate or add the tokenRequests section under spec.driverConfig.secretsStore. Set the type to Managed and configure the audience based on your cloud provider requirements:

    apiVersion: operator.openshift.io/v1
kind: ClusterCSIDriver
metadata:
  name: secrets-store.csi.k8s.io
spec:
  driverConfig:
    driverType: SecretsStore
    secretsStore:
      tokenRequests:
        type: Managed
        managed:
          audiences:
            - audience: "api://AzureADTokenExchange"
              expirationSeconds: 3600

    where:

    spec.driverConfig.secretsStore.tokenRequests.managed.audiences[].audience

    Specifies the audience value required by your cloud provider or secret management system. The audience must match the value configured in the trust policy of your cloud provider. For more information regarding audience value associated with different cloud providers, see corresponding cloud provider documentation.

    spec.driverConfig.secretsStore.tokenRequests.managed.audiences[].expirationSeconds

    Specifies the token validity duration in seconds. This parameter is optional. Valid range is 600 to 315,360,000 seconds. If omitted, the platform applies a default value.

  3. For environments that require multiple audiences, you can specify multiple audience entries:

    apiVersion: operator.openshift.io/v1
kind: ClusterCSIDriver
metadata:
  name: secrets-store.csi.k8s.io
spec:
  driverConfig:
    driverType: SecretsStore
    secretsStore:
      tokenRequests:
        type: Managed
        managed:
          audiences:
            - audience: "sts.amazonaws.com"
              expirationSeconds: 3600
            - audience: "api://AzureADTokenExchange"
              expirationSeconds: 3600

  4. Save and apply the changes to the custom resource.

Verification

  1. Verify that the Secrets Store CSI Driver Operator driver pods have been updated with the token request configuration by running the following command:

    $ oc get pods -n openshift-cluster-csi-drivers | grep secrets-store
    Example output
    secrets-store-csi-driver-node-bhp2d                  3/3     Running   0          45s
secrets-store-csi-driver-node-xyz12                  3/3     Running   0          45s
secrets-store-csi-driver-operator-74696fc7bc-qjrl8   1/1     Running   0          7m40s

  2. Check the ClusterCSIDriver configuration to confirm the token request settings by running the following command:

    $ oc get clustercsidrivers.operator.openshift.io secrets-store.csi.k8s.io -o jsonpath='{.spec.driverConfig.secretsStore.tokenRequests}' | jq
    Example output
    {
  "managed": {
    "audiences": [
      {
        "audience": "api://AzureADTokenExchange",
        "expirationSeconds": 3600
      }
    ]
  },
  "type": "Managed"
}

  3. Create a test pod that mounts secrets from your external secret store to verify that Workload Identity Federation authentication works correctly by running the following command:

    $ oc apply -f <test_pod_yaml>

  4. Check the pod logs to confirm successful authentication and secret mounting by running the following command:

    $ oc logs <test_pod_name>

    Successful authentication indicates that the service account token with the specified audience is being accepted by your cloud provider’s identity federation system.

Token request configuration parameters

You can configure Workload Identity Federation for the Secrets Store CSI Driver Operator by setting parameters in the tokenRequests section under spec.driverConfig.secretsStore of the ClusterCSIDriver custom resource. It enables credential-free authentication to cloud provider secret stores.

The following table describes the parameters available for configuring service account token requests:

Table 1. Token request configuration parameters
Parameter Type Description

type

String

Specifies the token request management mode. Set to Managed to enable Workload Identity Federation with operator-managed token configuration. When omitted, the Operator preserves any existing token request configuration on the CSIDriver object.

managed.audiences

Array of objects

Configures the service account token projection for Workload Identity Federation. Each entry specifies an audience and optional expiration. The Secrets Store CSI Driver Operator uses these tokens to authenticate to external secret management systems without storing long-lived credentials. This field is required when type is set to Managed.

managed.audiences[].audience

String

Specifies the intended audience claim (aud) for the projected service account token. The audience must match the value expected by the cloud provider’s identity federation system. Different cloud providers require different audience values. This field is required for each audience entry.

managed.audiences[].expirationSeconds

Integer

Specifies the token validity duration in seconds. Valid range is 600 to 315,360,000 seconds. If omitted, the platform applies a default value.

Different cloud providers and secret management systems require specific audience values. For more information on audience values, see corresponding cloud provider documentation.

The following examples demonstrate different token request configurations for various cloud providers:

Example 1: Azure Key Vault with Workload Identity
apiVersion: operator.openshift.io/v1
kind: ClusterCSIDriver
metadata:
  name: secrets-store.csi.k8s.io
spec:
  driverConfig:
    driverType: SecretsStore
    secretsStore:
      tokenRequests:
        type: Managed
        managed:
          audiences:
            - audience: "api://AzureADTokenExchange"
              expirationSeconds: 3600
Example 2: AWS Secrets Manager with IAM Roles for Service Accounts
apiVersion: operator.openshift.io/v1
kind: ClusterCSIDriver
metadata:
  name: secrets-store.csi.k8s.io
spec:
  driverConfig:
    driverType: SecretsStore
    secretsStore:
      tokenRequests:
        type: Managed
        managed:
          audiences:
            - audience: "sts.amazonaws.com"
              expirationSeconds: 3600
Example 3: HashiCorp Vault with Kubernetes authentication
apiVersion: operator.openshift.io/v1
kind: ClusterCSIDriver
metadata:
  name: secrets-store.csi.k8s.io
spec:
  driverConfig:
    driverType: SecretsStore
    secretsStore:
      tokenRequests:
        type: Managed
        managed:
          audiences:
            - audience: "vault.example.com"
Example 4: Multiple token audiences for multi-cloud deployments
apiVersion: operator.openshift.io/v1
kind: ClusterCSIDriver
metadata:
  name: secrets-store.csi.k8s.io
spec:
  driverConfig:
    driverType: SecretsStore
    secretsStore:
      tokenRequests:
        type: Managed
        managed:
          audiences:
            - audience: "sts.amazonaws.com"
              expirationSeconds: 3600
            - audience: "api://AzureADTokenExchange"
              expirationSeconds: 3600

When configuring token request parameters, consider the following:

  • The audience value must exactly match the value configured in your cloud provider’s trust policy or identity federation configuration.

  • Token requests enable the Secrets Store CSI Driver Operator to obtain projected service account tokens with the specified audience claim.

  • Different workloads can use different service accounts, allowing fine-grained access control through cloud provider IAM policies.

  • Workload Identity Federation eliminates the need to store cloud provider credentials in OKD, improving security.

  • You must configure your cloud provider to trust your OKD cluster’s OIDC provider before using Workload Identity Federation.

  • Multiple audience values can be specified to support multi-cloud or hybrid deployments where different external secret stores require different audiences.

Next steps

Uninstall the Secrets Store CSI Driver Operator

To remove the Secrets Store CSI Driver Operator and free cluster resources, uninstall the Operator after stopping applications and removing the CSI driver.

Prerequisites

  • Access to the OKD web console.

  • Administrator access to the cluster.

Procedure

  1. Stop all application pods that use the secrets-store.csi.k8s.io provider.

  2. Remove any third-party provider plug-in for your chosen secret store.

  3. Remove the Container Storage Interface (CSI) driver and associated manifests:

    1. Click Administration → CustomResourceDefinitions → ClusterCSIDriver.

    2. On the Instances tab, for secrets-store.csi.k8s.io, on the far left side, click the drop-down menu, and then click Delete ClusterCSIDriver.

    3. When prompted, click Delete.

  4. Verify that the CSI driver pods are no longer running.

  5. Uninstall the Secrets Store CSI Driver Operator:

    Before you can uninstall the Operator, you must remove the CSI driver first.

    1. Click Ecosystem → Installed Operators.

    2. On the Installed Operators page, scroll or type "Secrets Store CSI" into the Search by name box to find the Operator, and then click it.

    3. On the upper, right of the Installed Operators > Operator details page, click Actions → Uninstall Operator.

    4. When prompted on the Uninstall Operator window, click the Uninstall button to remove the Operator from the namespace. Any applications deployed by the Operator on the cluster need to be cleaned up manually.

      After uninstalling, the Secrets Store CSI Driver Operator is no longer listed in the Installed Operators section of the web console.

Additional resources