doc: add mention of default audience support for CSI

This commit is contained in:
Sheen Capadngan
2025-06-30 23:51:50 +08:00
parent c6074dd69a
commit 14d6f6c048

View File

@@ -44,8 +44,11 @@ Currently, the Infisical CSI provider only supports static secrets.
### Install Secrets Store CSI Driver ### 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 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.
the audience value for token requests as demonstrated below. The Infisical CSI provider will **NOT WORK** if this is not set.
#### Standard Installation
For most Kubernetes clusters, use the following installation:
```bash ```bash
helm repo add secrets-store-csi-driver https://kubernetes-sigs.github.io/secrets-store-csi-driver/charts helm repo add secrets-store-csi-driver https://kubernetes-sigs.github.io/secrets-store-csi-driver/charts
@@ -62,7 +65,7 @@ helm install csi secrets-store-csi-driver/secrets-store-csi-driver \
The flags configure the following: The flags configure the following:
- `tokenRequests[0].audience=infisical`: Sets the audience value for service account token authentication (required) - `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 - `enableSecretRotation=true`: Enables automatic secret updates from Infisical
- `rotationPollInterval=2m`: Checks for secret updates every 2 minutes - `rotationPollInterval=2m`: Checks for secret updates every 2 minutes
- `syncSecret.enabled=true`: Enables syncing secrets to Kubernetes secrets - `syncSecret.enabled=true`: Enables syncing secrets to Kubernetes secrets
@@ -76,6 +79,25 @@ The flags configure the following:
for the CSI driver. for the CSI driver.
</Info> </Info>
#### 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
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**: Do not 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.
</Warning>
### Install Infisical CSI Provider ### Install Infisical CSI Provider
You would then have to install the Infisical CSI provider to your cluster. You would then have to install the Infisical CSI provider to your cluster.
@@ -107,9 +129,12 @@ a machine identity with [Kubernetes authentication](https://infisical.com/docs/d
You can refer to the documentation for setting it up [here](https://infisical.com/docs/documentation/platform/identities/kubernetes-auth#guide). You can refer to the documentation for setting it up [here](https://infisical.com/docs/documentation/platform/identities/kubernetes-auth#guide).
<Warning> <Warning>
The allowed audience field of the Kubernetes authentication settings should **Important**: The "Allowed Audience" field in your machine identity's
match the audience specified for the Secrets Store CSI driver during Kubernetes authentication settings must match your CSI driver installation. If
installation. 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.
</Warning> </Warning>
### Creating Secret Provider Class ### Creating Secret Provider Class
@@ -117,6 +142,8 @@ You can refer to the documentation for setting it up [here](https://infisical.co
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 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. 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 ```yaml
apiVersion: secrets-store.csi.x-k8s.io/v1 apiVersion: secrets-store.csi.x-k8s.io/v1
kind: SecretProviderClass kind: SecretProviderClass
@@ -139,6 +166,41 @@ spec:
secretKey: "APP_SECRET" 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
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>
<Note> <Note>
The SecretProviderClass should be provisioned in the same namespace as the pod The SecretProviderClass should be provisioned in the same namespace as the pod
you intend to mount secrets to. you intend to mount secrets to.
@@ -189,6 +251,19 @@ spec:
`infisical`. `infisical`.
</Accordion> </Accordion>
<Accordion title="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, do not 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.
</Note>
</Accordion>
### Using Secret Provider Class ### Using Secret Provider Class
A pod can use the Secret Provider Class by mounting it as a CSI volume: A pod can use the Secret Provider Class by mounting it as a CSI volume:
@@ -252,6 +327,11 @@ kubectl logs csi-secrets-store-csi-driver-7h4jp -n=kube-system
- Invalid machine identity configuration - Invalid machine identity configuration
- Incorrect secret paths or keys - 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 ## 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). 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).