From 14d6f6c04862078f29a07ba1119a9df5a468d774 Mon Sep 17 00:00:00 2001 From: Sheen Capadngan Date: Mon, 30 Jun 2025 23:51:50 +0800 Subject: [PATCH] doc: add mention of default audience support for CSI --- .../integrations/platforms/kubernetes-csi.mdx | 92 +++++++++++++++++-- 1 file changed, 86 insertions(+), 6 deletions(-) diff --git a/docs/integrations/platforms/kubernetes-csi.mdx b/docs/integrations/platforms/kubernetes-csi.mdx index da1d4d019..2dfcb448a 100644 --- a/docs/integrations/platforms/kubernetes-csi.mdx +++ b/docs/integrations/platforms/kubernetes-csi.mdx @@ -44,8 +44,11 @@ Currently, the Infisical CSI provider only supports static secrets. ### 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. +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. + +#### Standard Installation + +For most Kubernetes clusters, use the following installation: ```bash 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: -- `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 - `rotationPollInterval=2m`: Checks for secret updates every 2 minutes - `syncSecret.enabled=true`: Enables syncing secrets to Kubernetes secrets @@ -76,6 +79,25 @@ The flags configure the following: 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 +helm install csi secrets-store-csi-driver/secrets-store-csi-driver \ +--namespace=kube-system \ +--set enableSecretRotation=true \ +--set rotationPollInterval=2m \ +--set "syncSecret.enabled=true" \ +``` + + + **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. + + ### Install Infisical CSI Provider 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). - The allowed audience field of the Kubernetes authentication settings should - match the audience specified for the Secrets Store CSI driver during - installation. + **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 @@ -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 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 apiVersion: secrets-store.csi.x-k8s.io/v1 kind: SecretProviderClass @@ -139,6 +166,41 @@ spec: 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" +``` + + + **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. + + The SecretProviderClass should be provisioned in the same namespace as the pod you intend to mount secrets to. @@ -189,6 +251,19 @@ spec: `infisical`. + + 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`. + + 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: @@ -252,6 +327,11 @@ kubectl logs csi-secrets-store-csi-driver-7h4jp -n=kube-system - 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).