From 4b55601d1bc7ebdb771e68eca99fbd291ab48346 Mon Sep 17 00:00:00 2001 From: Oleg Kuznetsov <71344093+icmp0x8@users.noreply.github.com> Date: Sun, 12 Jul 2026 20:26:11 +0200 Subject: [PATCH] docs: document native Kubernetes auth for HashiCorp Vault secret store Add a "Kubernetes authentication" section covering the new vaultAuthMethod: kubernetes option (native login via the pod's service account token, no Vault Agent Injector sidecar required), including the one-time Vault-side setup (enable the auth method, configure it, create a policy and role). Also documents the new vaultKubernetesRole, vaultKubernetesMountPath, and vaultServiceAccountTokenPath fields, and corrects vaultToken/vaultTokenMountPath from required to optional in the metadata table, since neither is required under kubernetes auth. Signed-off-by: Oleg Kuznetsov <71344093+icmp0x8@users.noreply.github.com> --- .../hashicorp-vault.md | 74 ++++++++++++++++++- 1 file changed, 70 insertions(+), 4 deletions(-) diff --git a/daprdocs/content/en/reference/components-reference/supported-secret-stores/hashicorp-vault.md b/daprdocs/content/en/reference/components-reference/supported-secret-stores/hashicorp-vault.md index 1d9518d6aad..6bc8b85289b 100644 --- a/daprdocs/content/en/reference/components-reference/supported-secret-stores/hashicorp-vault.md +++ b/daprdocs/content/en/reference/components-reference/supported-secret-stores/hashicorp-vault.md @@ -32,9 +32,11 @@ spec: value : "[skip_tls_verification]" - name: tlsServerName # Optional. value : "[tls_config_server_name]" - - name: vaultTokenMountPath # Required if vaultToken not provided. Path to token file. + - name: vaultAuthMethod # Optional. Default: "token" + value: "token" + - name: vaultTokenMountPath # Required if vaultAuthMethod is "token" and vaultToken not provided. Path to token file. value : "[path_to_file_containing_token]" - - name: vaultToken # Required if vaultTokenMountPath not provided. Token value. + - name: vaultToken # Required if vaultAuthMethod is "token" and vaultTokenMountPath not provided. Token value. value : "[path_to_file_containing_token]" - name: vaultKVPrefix # Optional. Default: "dapr" value : "[vault_prefix]" @@ -49,6 +51,66 @@ spec: The above example uses secrets as plain strings. It is recommended to use a local secret store such as [Kubernetes secret store]({{% ref kubernetes-secret-store.md %}}) or a [local file]({{% ref file-secret-store.md %}}) to bootstrap secure key storage. {{% /alert %}} +## Kubernetes authentication + +When running on Kubernetes, you can set `vaultAuthMethod` to `kubernetes` instead of `token`. In this mode, the component authenticates itself directly against Vault's [Kubernetes Auth Method](https://developer.hashicorp.com/vault/docs/auth/kubernetes) using the pod's own service account token, and keeps the resulting session renewed in the background for as long as the component is running. This means you don't need to run a [Vault Agent Injector](https://developer.hashicorp.com/vault/docs/deploy/kubernetes/injector) sidecar, or manage and rotate a static token yourself. + +```yaml +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: vault +spec: + type: secretstores.hashicorp.vault + version: v1 + metadata: + - name: vaultAddr + value: [vault_address] + - name: vaultAuthMethod + value: "kubernetes" + - name: vaultKubernetesRole # Required when vaultAuthMethod is "kubernetes". + value: "[vault_role_name]" + - name: vaultKubernetesMountPath # Optional. Default: "kubernetes" + value: "kubernetes" + - name: vaultServiceAccountTokenPath # Optional. Default: "/var/run/secrets/kubernetes.io/serviceaccount/token" + value: "/var/run/secrets/kubernetes.io/serviceaccount/token" +``` + +`vaultToken` and `vaultTokenMountPath` must not be set when using `vaultAuthMethod: kubernetes`. + +Before this works, Vault itself needs to know about your cluster and about the role your Dapr app's pod is allowed to use. This is a one-time setup on the Vault side, done with the [Vault CLI](https://developer.hashicorp.com/vault/docs/install), for example: + +```shell +# Enable the Kubernetes auth method (skip if already enabled). +vault auth enable kubernetes + +# Point it at your cluster's API server. Run from within a pod that already +# has a Kubernetes service account token and CA cert mounted (for example, +# the Vault server pod itself) and Vault will pick up the reviewer JWT and +# CA cert from its own environment. +vault write auth/kubernetes/config \ + kubernetes_host="https://kubernetes.default.svc:443" + +# A policy granting access to the secrets your app needs. +vault policy write dapr-app - <