backport of commit e796005 (#20735)

Co-authored-by: Tom Proctor <tomhjp@users.noreply.github.com>

website/content/docs/platform/k8s/csi/configurations.mdx

@@ -16,19 +16,31 @@ Most settings support being set by, in ascending order of precedence:
 If installing via the helm chart, they can be set using e.g.
 `--set "csi.extraArgs={-debug=true}"`.
 
+- `-cache-size` `(int: 1000)` - Set the maximum number of Vault tokens that will
+  be cached in-memory. One Vault token will be stored for each pod on the same
+  node that mounts secrets. Setting to 0 will disable the cache and force each
+  volume mount request to reauthenticate to Vault.
+
 - `-debug` `(bool: false)` - Set to true to enable debug level logging.
 
 - `-endpoint` `(string: "/tmp/vault.sock")` - Path to unix socket on which the
   provider will listen for gRPC calls from the driver.
 
-- `-health-addr` `(string: ":8080")` - (v0.3.0+) The address of the HTTP listener
+- `-health-addr` `(string: ":8080")` - The address of the HTTP listener
   for reporting health.
 
-- `-vault-addr` `(string: "https://127.0.0.1:8200")` - (v0.3.0+) Default address
+- `-hmac-secret-name` `(string: "vault-csi-provider-hmac-key")` - Configure the
+  Kubernetes secret name that the provider creates to store an HMAC key for
+  generating secret version hashes.
+
+- `-vault-addr` `(string: "https://127.0.0.1:8200")` - Default address
   for connecting to Vault. Can also be specified via the `VAULT_ADDR` environment
-  variable.
+  variable. **Note:** It is highly recommended to only set the Vault address when
+  installing the helm chart. The helm chart will install Vault Agent as a sidecar
+  to the Vault CSI Provider for caching and renewals, but setting `-vault-addr`
+  here will cause the Vault CSI Provider to bypass the Agent's cache.
 
-- `-vault-mount` `(string: "kubernetes")` - (v0.3.0+) Default Vault mount path
+- `-vault-mount` `(string: "kubernetes")` - Default Vault mount path
   for Kubernetes authentication. Can be overridden per Secret Provider Class
   object.
 
@@ -73,7 +85,11 @@ structure is illustrated in the [examples](/vault/docs/platform/k8s/csi/examples
 
 - `roleName` `(string: "")` - Name of the role to be used during login with Vault.
 
-- `vaultAddress` `(string: "")` - The address of the Vault server.
+- `vaultAddress` `(string: "")` - The address of the Vault server. **Note:** It is
+  highly recommended to only set the Vault address when installing the helm chart.
+  The helm chart will install Vault Agent as a sidecar to the Vault CSI Provider
+  for caching and renewals, but setting `vaultAddress` here will cause the Vault
+  CSI Provider to bypass the Agent's cache.
 
 - `vaultNamespace` `(string: "")` - The Vault [namespace](/vault/docs/enterprise/namespaces) to use.
 
@@ -94,8 +110,11 @@ structure is illustrated in the [examples](/vault/docs/platform/k8s/csi/examples
 
 - `vaultTLSServerName` `(string: "")` - The name to use as the SNI host when connecting via TLS.
 
+- `vaultAuthMountPath` `(string: "kubernetes")` - The name of the auth mount used for login.
+  Can be a Kubernetes or JWT auth mount. Mutually exclusive with `vaultKubernetesMountPath`.
+
 - `vaultKubernetesMountPath` `(string: "kubernetes")` - The name of the auth mount used for login.
-  At this time only the Kubernetes auth method is supported.
+  Can be a Kubernetes or JWT auth mount. Mutually exclusive with `vaultAuthMountPath`.
 
 - `audience` `(string: "")` - Specifies a custom audience for the requesting pod's service account token,
   generated using the

website/content/docs/platform/k8s/csi/examples.mdx

@@ -26,8 +26,6 @@ spec:
   provider: vault
   parameters:
     roleName: 'app'
-    vaultAddress: 'https://vault.vault:8200'
-    vaultCACertPath: '/vault/tls/ca.crt'
     objects: |
       - objectName: "dbUsername"
         secretPath: "database/creds/db-app"
@@ -105,8 +103,6 @@ spec:
           key: password
   parameters:
     roleName: 'app'
-    vaultAddress: 'https://vault.vault:8200'
-    vaultCACertPath: '/vault/tls/ca.crt'
     objects: |
       - objectName: "dbUsername"
         secretPath: "database/creds/db-app"

website/content/docs/platform/k8s/csi/index.mdx

@@ -19,7 +19,7 @@ At a high level, the CSI Secrets Store driver allows users to create `SecretProv
 This object defines which secret provider to use and what secrets to retrieve. When pods requesting CSI volumes
 are created, the CSI Secrets Store driver will send the request to the Vault CSI Provider if the provider
 is `vault`. The Vault CSI Provider will then use Secret Provider Class specified and the pod's service account to retrieve
-the secrets from Vault, and <span class="x x-first x-last">mount</span> them <span class="x x-first x-last">into</span> the pod<span class="x x-first x-last">'s CSI</span> volume.
+the secrets from Vault, and mount them into the pod's CSI volume.
 
 The secret is retrieved from Vault and populated to the CSI secrets store volume during the `ContainerCreation` phase.
 This means that pods will be blocked from starting until the secrets have been read from Vault and written to the volume.
@@ -32,46 +32,21 @@ The following features are supported by the Vault CSI Provider:
 - Authentication using the requesting pod's service account.
 - TLS/mTLS communications with Vault.
 - Rendering Vault secrets to files.
+- Dynamic lease caching and renewal performed by Agent.
 - Syncing secrets to Kubernetes secrets to be used as environment variables.
 - Installation via [Vault Helm](/vault/docs/platform/k8s/helm)
 
 @include 'kubernetes-supported-versions.mdx'
 
 ## Authenticating with Vault
 
-The primary method of authentication with Vault when using the Vault CSI Provider
-is the service account attached to the pod. At this time no other authentication methods
-are supported.
+The Vault CSI Provider will authenticate with Vault as the service account of the
+pod that mounts the CSI volume. [Kubernetes](/vault/docs/auth/kubernetes) and
+[JWT](/vault/docs/auth/jwt) auth methods are supported. The pod's service account
+must be bound to a Vault role and a policy granting access to the secrets desired.
 
-For [Kubernetes authentication](/vault/docs/auth/kubernetes), the service account must be bound to a Vault role and a
-policy granting access to the secrets desired.
-
-A service account must be present to use the Vault CSI Provider with the Kubernetes
-authentication method. It is _not_ recommended to bind Vault roles to the default service
-account provided to pods if no service account is defined.
-
-### Setting `issuer` for Kubernetes authentication
-
--> **Deprecated:** The `issuer` parameter has been deprecated as of Vault 1.9 and will be removed in a future release.
-
-If running Vault prior to version 1.9, you will likely need to set [`issuer`](/vault/api-docs/auth/kubernetes#issuer) when
-configuring Kubernetes authentication for the Vault CSI Provider.
-Vault CSI Provider does not use the default token associated with service accounts.
-Instead, it creates a token with a short TTL whose lifetime is also bound to the
-lifetime of the requesting pod. A key difference between default tokens and
-ephemeral tokens is the JWT issuer. Default tokens use `kubernetes/serviceaccount`,
-which is the default value that Kubernetes auth will try to validate. However,
-ephemeral tokens use the value of `kube-apiserver`'s `--service-account-issuer`
-flag as the issuer, which is normally a URL instead. See the [Kubernetes auth
-docs](/vault/docs/auth/kubernetes#discovering-the-service-account-issuer) for
-ways to check the issuer using the Kubernetes API.
-
-Importantly, this means most common configurations of Vault Agent Injector and
-Vault CSI Provider **cannot share the same Kubernetes auth mount**. Vault
-Agent sidecars will most commonly be configured to authenticate using a
-long-lived default service account token, with an issuer different to the tokens
-Vault CSI Provider will create. But one Kubernetes auth mount can only be
-configured to validate a single issuer value.
+It is highly recommended to run pods with dedicated Kubernetes service accounts to
+ensure applications cannot access more secrets than they require.
 
 ## Secret Provider Class Example
 
@@ -89,10 +64,12 @@ spec:
   parameters:
     # Vault role name to use during login
     roleName: 'app'
+    # Vault address and TLS connection config is normally best configured by the
+    # helm chart, but can be overridden per SecretProviderClass:
     # Vault's hostname
-    vaultAddress: 'https://vault:8200'
+    #vaultAddress: 'https://vault:8200'
     # TLS CA certification for validation
-    vaultCACertPath: '/vault/tls/ca.crt'
+    #vaultCACertPath: '/vault/tls/ca.crt'
     objects: |
       - objectName: "dbUsername"
         secretPath: "database/creds/db-app"