---
title: "Kubernetes CSI"
description: "How to use Infisical 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), the Infisical CSI provider will allow you to sync Infisical secrets directly to pods as files, removing the need for Kubernetes secret resources.

```mermaid
flowchart LR
    subgraph Secrets Management
        SS(Infisical) --> CSP(Infisical CSI Provider)
        CSP --> CSD(Secrets Store CSI Driver)
    end

    subgraph Application
        CSD --> V(Volume)
        V <--> P(Pod)
    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 will first have to install the [Secrets Store CSI driver](https://secrets-store-csi-driver.sigs.k8s.io/getting-started/installation) to your cluster. It is important that you define
the audience value for token requests as demonstrated below. The Infisical CSI provider will **NOT WORK** if this is not set.

```bash
helm repo add secrets-store-csi-driver https://kubernetes-sigs.github.io/secrets-store-csi-driver/charts
```

```bash
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 (required)
- `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

<Info>
  If you do not 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 will not propagate to the pods unless auto-syncing is enabled
  for the CSI driver.
</Info>

### Install Infisical CSI Provider

You would then have to install the Infisical CSI provider to your cluster.

**Install the latest Infisical Helm repository**

```bash
helm repo add infisical-helm-charts 'https://dl.cloudsmith.io/public/infisical/helm-charts/helm/charts/'

helm repo update
```

**Install the Helm Chart**

```bash
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
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 will have to configure
a machine identity with [Kubernetes authentication](https://infisical.com/docs/documentation/platform/identities/kubernetes-auth) configured with your cluster.
You can refer to the documentation for setting it up [here](https://infisical.com/docs/documentation/platform/identities/kubernetes-auth#guide).

<Warning>
  The allowed audience field of the Kubernetes authentication settings should
  match the audience specified for the Secrets Store CSI driver during
  installation.
</Warning>

### 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.

```yaml
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"
```

<Note>
  The SecretProviderClass should be provisioned in the same namespace as the pod
  you intend to mount secrets to.
</Note>

#### Supported Parameters

<Accordion title="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>

<Accordion title="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>

<Accordion title="authMethod">
  The auth method to use for authenticating the Infisical CSI provider with
  Infisical. For now, the only supported method is `kubernetes`.
</Accordion>

<Accordion title="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>

<Accordion title="projectId">
  The project ID of the Infisical project to pull secrets from.
</Accordion>

<Accordion title="envSlug">
  The slug of the project environment to pull secrets from.
</Accordion>

<Accordion title="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>

<Accordion title="audience">
  The custom audience value configured for the CSI driver. This defaults to
  `infisical`.
</Accordion>

### Using Secret Provider Class

A pod can use the Secret Provider Class by mounting it as a CSI volume:

```yaml
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
# 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
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
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

## 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

<AccordionGroup>
  <Accordion title="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>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Do I have to list out every Infisical single secret that I want to sync?">
    Yes, you will 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.
  </Accordion>
</AccordionGroup>