> ## Documentation Index > Fetch the complete documentation index at: https://infisical.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Kubernetes CSI > How to use the Infisical Kubernetes CSI provider to inject secrets directly into Kubernetes pods. ## Overview The Infisical CSI provider allows you to use Infisical with the [Secrets Store CSI driver](https://secrets-store-csi-driver.sigs.k8s.io) to inject secrets directly into your Kubernetes pods through a volume mount. In contrast to the [Infisical Kubernetes Operator](https://infisical.com/docs/integrations/platforms/kubernetes/overview), the Infisical CSI provider will allow you to sync Infisical secrets directly to pods as files, removing the need for Kubernetes secret resources. > [!TIP] > > For a complete Helm chart reference including all configurable values, see the [CSI Provider Helm chart documentation](https://infisical.com/docs/self-hosting/helm-charts/csi-provider.md). ```mermaid theme={"dark"} flowchart LR subgraph Secrets Management SS(Infisical) --> CSP(Infisical CSI Provider) CSP --> CSD(Secrets Store CSI Driver) end subgraph Pod CSD --> V(Volume) V <--> P(Application) end ``` ## Features The following features are supported by the Infisical CSI Provider: * Integration with Secrets Store CSI Driver for direct pod mounting * Authentication using Kubernetes service accounts via machine identities * Auto-syncing secrets when enabled via CSI Driver * Configurable secret paths and file mounting locations * Installation via Helm ## Prerequisites The Infisical CSI provider is only supported for Kubernetes clusters with version >= 1.20. ## Limitations Currently, the Infisical CSI provider only supports static secrets. ## Deploy to Kubernetes cluster ### Install Secrets Store CSI Driver In order to use the Infisical CSI provider, you'll first have to install the [Secrets Store CSI driver](https://secrets-store-csi-driver.sigs.k8s.io/getting-started/installation) to your cluster. #### Standard installation For most Kubernetes clusters, use the following installation: ```bash theme={"dark"} helm repo add secrets-store-csi-driver https://kubernetes-sigs.github.io/secrets-store-csi-driver/charts ``` ```bash theme={"dark"} helm install csi secrets-store-csi-driver/secrets-store-csi-driver \ --namespace=kube-system \ --set "tokenRequests[0].audience=infisical" \ --set enableSecretRotation=true \ --set rotationPollInterval=2m \ --set "syncSecret.enabled=true" \ ``` The flags configure the following: * `tokenRequests[0].audience=infisical`: Sets the audience value for service account token authentication (recommended for environments that support custom audiences) * `enableSecretRotation=true`: Enables automatic secret updates from Infisical * `rotationPollInterval=2m`: Checks for secret updates every 2 minutes * `syncSecret.enabled=true`: Enables syncing secrets to Kubernetes secrets > [!NOTE] > > If you don't wish to use the auto-syncing feature of the secrets store CSI > driver, you can omit the `enableSecretRotation` and the `rotationPollInterval` > flags. Do note that by default, secrets from Infisical are only fetched and > mounted during pod creation. If there are any changes made to the secrets in > Infisical, they won't propagate to the pods unless auto-syncing is enabled > for the CSI driver. #### Installation for environments without custom audience support Some Kubernetes environments (such as AWS EKS) don't support custom audiences and will reject tokens with non-default audiences. For these environments, use this installation instead: ```bash theme={"dark"} helm install csi secrets-store-csi-driver/secrets-store-csi-driver \ --namespace=kube-system \ --set enableSecretRotation=true \ --set rotationPollInterval=2m \ --set "syncSecret.enabled=true" \ ``` > [!WARNING] > > **Environments without custom audience support**: Don't set a custom audience > when installing the CSI driver in environments that reject custom audiences. > Instead, use the installation above and set `useDefaultAudience: "true"` in > your SecretProviderClass configuration. ### Install Infisical CSI Provider You would then have to install the Infisical CSI provider to your cluster. **Install the latest Infisical Helm repository** ```bash theme={"dark"} helm repo add infisical-helm-charts 'https://dl.cloudsmith.io/public/infisical/helm-charts/helm/charts/' helm repo update ``` **Install the Helm Chart** ```bash theme={"dark"} helm install infisical-csi-provider infisical-helm-charts/infisical-csi-provider ``` For a list of all supported arguments for the helm installation, you can run the following: ```bash theme={"dark"} helm show values infisical-helm-charts/infisical-csi-provider ``` ### Authentication In order for the Infisical CSI provider to pull secrets from your Infisical project, you'll have to configure a machine identity with [Kubernetes authentication](https://infisical.com/docs/documentation/platform/identities/kubernetes-auth.md) configured with your cluster. You can refer to the documentation for setting it up [here](https://infisical.com/docs/documentation/platform/identities/kubernetes-auth.md#guide). > [!WARNING] > > **Important**: The "Allowed Audience" field in your machine identity's > Kubernetes authentication settings must match your CSI driver installation. If > you used the standard installation with `tokenRequests[0].audience=infisical`, > set the "Allowed Audience" field to `infisical`. If you used the installation > for environments without custom audience support, leave the "Allowed Audience" > field empty. ### Creating secret provider class With the Secrets Store CSI driver and the Infisical CSI provider installed, create a Kubernetes [SecretProviderClass](https://secrets-store-csi-driver.sigs.k8s.io/concepts.html#secretproviderclass) resource to establish the connection between the CSI driver and the Infisical CSI provider for secret retrieval. You can create as many Secret Provider Classes as needed for your cluster. #### Standard configuration ```yaml theme={"dark"} apiVersion: secrets-store.csi.x-k8s.io/v1 kind: SecretProviderClass metadata: name: my-infisical-app-csi-provider spec: provider: infisical parameters: infisicalUrl: "https://app.infisical.com" authMethod: "kubernetes" identityId: "ad2f8c67-cbe2-417a-b5eb-1339776ec0b3" projectId: "09eda1f8-85a3-47a9-8a6f-e27f133b2a36" envSlug: "prod" secrets: | - secretPath: "/" fileName: "dbPassword" secretKey: "DB_PASSWORD" - secretPath: "/app" fileName: "appSecret" secretKey: "APP_SECRET" ``` #### Configuration for environments without custom audience support For environments that don't support custom audiences (such as AWS EKS), use this configuration instead: ```yaml theme={"dark"} apiVersion: secrets-store.csi.x-k8s.io/v1 kind: SecretProviderClass metadata: name: my-infisical-app-csi-provider spec: provider: infisical parameters: infisicalUrl: "https://app.infisical.com" authMethod: "kubernetes" useDefaultAudience: "true" identityId: "ad2f8c67-cbe2-417a-b5eb-1339776ec0b3" projectId: "09eda1f8-85a3-47a9-8a6f-e27f133b2a36" envSlug: "prod" secrets: | - secretPath: "/" fileName: "dbPassword" secretKey: "DB_PASSWORD" - secretPath: "/app" fileName: "appSecret" secretKey: "APP_SECRET" ``` > [!NOTE] > > **Key difference**: The only change from the standard configuration is the > addition of `useDefaultAudience: "true"`. This parameter tells the CSI > provider to use the default Kubernetes audience instead of a custom > "infisical" audience, which is required for environments that reject custom > audiences. > [!NOTE] > > The SecretProviderClass should be provisioned in the same namespace as the pod > you intend to mount secrets to. #### Supported parameters > [accordion] infisicalUrl > > The base URL of your Infisical instance. If you're using Infisical Cloud US, > this should be set to `https://app.infisical.com`. If you're using Infisical > Cloud EU, then this should be set to `https://eu.infisical.com`. > [accordion] caCertificate > > The CA certificate of the Infisical instance in order to establish SSL/TLS > when the instance uses a private or self-signed certificate. Unless necessary, > this should be omitted. > [accordion] authMethod > > The auth method to use for authenticating the Infisical CSI provider with > Infisical. For now, the only supported method is `kubernetes`. > [accordion] identityId > > The ID of the machine identity to use for authenticating the Infisical CSI > provider with your Infisical organization. This should be the machine identity > configured with Kubernetes authentication. > [accordion] projectId > > The project ID of the Infisical project to pull secrets from. > [accordion] envSlug > > The slug of the project environment to pull secrets from. > [accordion] secrets > > An array that defines which secrets to retrieve and how to mount them. Each > entry requires three properties: `secretPath` and `secretKey` work together to > identify the source secret to fetch, while `fileName` specifies the path where > the secret's value will be mounted within the pod's filesystem. > [accordion] audience > > The custom audience value configured for the CSI driver. This defaults to > `infisical`. > [accordion] useDefaultAudience > > When set to `"true"`, the Infisical CSI provider will use the default > Kubernetes audience instead of a custom audience. This is required for > environments that don't support custom audiences (such as AWS EKS), which > reject tokens with non-default audiences. When using this option, don't set a > custom audience in the CSI driver installation. This defaults to `false`. > > > [!NOTE] > > > > When enabled, the CSI provider will dynamically create service account > > tokens on-demand using the default Kubernetes audience, rather than using > > pre-existing tokens from the CSI driver. ### Using secret provider class A pod can use the Secret Provider Class by mounting it as a CSI volume: ```yaml theme={"dark"} apiVersion: v1 kind: Pod metadata: name: nginx-secrets-store labels: app: nginx spec: containers: - name: nginx image: nginx volumeMounts: - name: secrets-store-inline mountPath: "/mnt/secrets-store" readOnly: true volumes: - name: secrets-store-inline csi: driver: secrets-store.csi.k8s.io readOnly: true volumeAttributes: secretProviderClass: "my-infisical-app-csi-provider" ``` When the pod is created, the secrets are mounted as individual files in the /mnt/secrets-store directory. ### Verifying secret mounts To verify your secrets are mounted correctly: ```bash theme={"dark"} # Check pod status kubectl get pod nginx-secrets-store # View mounted secrets kubectl exec -it nginx-secrets-store -- ls -l /mnt/secrets-store ``` ### Troubleshooting To troubleshoot issues with the Infisical CSI provider, refer to the logs of the Infisical CSI provider running on the same node as your pod. ```bash theme={"dark"} kubectl logs infisical-csi-provider-7x44t ``` You can also refer to the logs of the secrets store CSI driver. Modify the command below with the appropriate pod and namespace of your secrets store CSI driver installation. ```bash theme={"dark"} kubectl logs csi-secrets-store-csi-driver-7h4jp -n=kube-system ``` **Common issues include:** * Mismatch in the audience value of the CSI driver with the machine identity's Kubernetes auth configuration * SecretProviderClass in the wrong namespace * Invalid machine identity configuration * Incorrect secret paths or keys **Issues in environments without custom audience support:** * **Token authentication failed with custom audience**: If you're seeing authentication errors in environments that don't support custom audiences (such as AWS EKS), ensure you're using the installation without custom audience and have set `useDefaultAudience: "true"` in your SecretProviderClass * **Audience not allowed errors**: Make sure the "Allowed Audience" field is left empty in your machine identity's Kubernetes authentication configuration when using environments that don't support custom audiences ## Best practices For additional guidance on setting this up for your production cluster, you can refer to the Secrets Store CSI driver documentation [here](https://secrets-store-csi-driver.sigs.k8s.io/topics/best-practices). ## Frequently asked questions > [accordion] Is it possible to sync Infisical secrets as environment variables? > > Yes, but it requires an indirect approach: > > 1. First enable syncing to Kubernetes secrets by setting `syncSecret.enabled=true` in the CSI driver installation > 2. Configure the Secret Provider Class to sync specific secrets to Kubernetes secrets > 3. Use the resulting Kubernetes secrets in your pod's environment variables > > This means secrets are first synced to Kubernetes secrets before they can be used as environment variables. You can find detailed examples in the [Secrets Store CSI driver documentation](https://secrets-store-csi-driver.sigs.k8s.io/topics/set-as-env-var). > [accordion] Do I have to list out every Infisical single secret that I want to sync? > > Yes, you'll need to explicitly list each secret you want to sync in the > Secret Provider Class configuration. This is a common requirement across all > CSI providers as the Secrets Store CSI Driver architecture requires specific > mapping of secrets to their mounted file locations. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.