From 126ebdbfb562d532cea8d9f73b85b38a22290f5d Mon Sep 17 00:00:00 2001 From: Anton Troshin Date: Thu, 10 Oct 2024 14:32:00 -0500 Subject: [PATCH 1/2] Add support for injecting environment variables from a Secret into the Dapr sidecar Signed-off-by: Anton Troshin --- .../environment-variables-secrets.md | 114 ++++++++++++++++++ .../arguments-annotations-overview.md | 1 + 2 files changed, 115 insertions(+) create mode 100644 daprdocs/content/en/operations/configuration/environment-variables-secrets.md diff --git a/daprdocs/content/en/operations/configuration/environment-variables-secrets.md b/daprdocs/content/en/operations/configuration/environment-variables-secrets.md new file mode 100644 index 000000000..b822fb2de --- /dev/null +++ b/daprdocs/content/en/operations/configuration/environment-variables-secrets.md @@ -0,0 +1,114 @@ +--- +type: docs +title: "How-To: Configure Environment Variables from Secrets for Dapr sidecar" +linkTitle: "Environment Variables from Secrets" +weight: 7500 +description: "Inject Environment Variables from Kubernetes Secrets into Dapr sidecar" +--- +In special cases, Dapr sidecar needs an environment variable injected into it. This use case may be required by a Component, a 3rd party library, or a module that uses environment variables to configure the said Component or customize its behavior. This can be useful for both production and non-production environments. + +## Overview +In Dapr 1.15 the new annotation was introduced, `dapr.io/env-from-secret`, similarly to `dapr.io/env`, see [here]({{}}). +This annotation allows users to inject an environment variable with a value from a Secret, into the Dapr sidecar. + +### Annotation format +The values of this annotation are formatted like so: + +- Single key secret: `=` +- Multi key-value secret: `=:` + +`` is required to follow the `C_IDENTIFIER` format and captured by the following regex: `[A-Za-z_][A-Za-z0-9_]*`
+- Must start with a letter or underscore +- The rest of the identifier to contain letters, digits, or underscores + +Due to the restriction of the `secretKeyRef`, `name` field is required, so both `name` and `key` must be set (read more [here](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#environment-variables), in section "env.valueFrom.secretKeyRef.name")
+In this case, Dapr will set both to the same value. + +## Configuring single key secret environment variable +Example:
+Add the `dapr.io/env-from-secret` annotation to Deployment +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: nodeapp +spec: + template: + metadata: + annotations: + dapr.io/enabled: "true" + dapr.io/app-id: "nodeapp" + dapr.io/app-port: "3000" + dapr.io/env-from-secret: "AUTH_TOKEN=auth-headers-secret" + spec: + containers: + - name: node + image: dapriosamples/hello-k8s-node:latest + ports: + - containerPort: 3000 + imagePullPolicy: Always +``` +Annotation: `dapr.io/env-from-secret: "AUTH_TOKEN=auth-headers-secret"` will be injected as: +```yaml +env: +- name: AUTH_TOKEN + valueFrom: + secretKeyRef: + name: auth-headers-secret + key: auth-headers-secret +``` +This will require the Secret to have both `name` and `key` fields with the same value, "auth-headers-secret".
+Example secret (for demo purposes only, don't store secrets in plain text) +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: auth-headers-secret +type: Opaque +stringData: + auth-headers-secret: "AUTH=mykey" +``` + +## Configuring multi-key secret environment variable + +Add the `dapr.io/env-from-secret` annotation to Deployment +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: nodeapp +spec: + template: + metadata: + annotations: + dapr.io/enabled: "true" + dapr.io/app-id: "nodeapp" + dapr.io/app-port: "3000" + dapr.io/env-from-secret: "AUTH_TOKEN=auth-headers-secret:auth-header-value" + spec: + containers: + - name: node + image: dapriosamples/hello-k8s-node:latest + ports: + - containerPort: 3000 + imagePullPolicy: Always +``` +Annotation: `dapr.io/env-from-secret: "AUTH_TOKEN=auth-headers-secret:auth-header-value"` will be injected as: +```yaml +env: +- name: AUTH_TOKEN + valueFrom: + secretKeyRef: + name: auth-headers-secret + key: auth-header-value +``` +Example secret (for demo purposes only, don't store secrets in plain text) +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: auth-headers-secret +type: Opaque +stringData: + auth-header-value: "AUTH=mykey" +``` \ No newline at end of file diff --git a/daprdocs/content/en/reference/arguments-annotations-overview.md b/daprdocs/content/en/reference/arguments-annotations-overview.md index 6a0c2f60b..a0f7324f0 100644 --- a/daprdocs/content/en/reference/arguments-annotations-overview.md +++ b/daprdocs/content/en/reference/arguments-annotations-overview.md @@ -67,6 +67,7 @@ This table is meant to help users understand the equivalent options for running | not supported | not supported | | `dapr.io/sidecar-readiness-probe-period-seconds` | How often (in seconds) to perform the sidecar readiness probe. Read more [here](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#configure-probes). Default is `6`| | not supported | not supported | | `dapr.io/sidecar-readiness-probe-threshold` | When the sidecar readiness probe fails, Kubernetes will try N times before giving up. In this case, the Pod will be marked Unready. Read more about `failureThreshold` [here](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#configure-probes). Default is `3`| | not supported | not supported | | `dapr.io/env` | List of environment variable to be injected into the sidecar. Strings consisting of key=value pairs separated by a comma.| +| not supported | not supported | | `dapr.io/env-from-secret` | List of environment variable to be injected into the sidecar from Secret. Strings consisting of "key=secret-name:secret-key" pairs separated by a comma.| | not supported | not supported | | `dapr.io/volume-mounts` | List of [pod volumes to be mounted to the sidecar container]({{< ref "kubernetes-volume-mounts" >}}) in read-only mode. Strings consisting of `volume:path` pairs separated by a comma. Example, `"volume-1:/tmp/mount1,volume-2:/home/root/mount2"`. | | not supported | not supported | | `dapr.io/volume-mounts-rw` | List of [pod volumes to be mounted to the sidecar container]({{< ref "kubernetes-volume-mounts" >}}) in read-write mode. Strings consisting of `volume:path` pairs separated by a comma. Example, `"volume-1:/tmp/mount1,volume-2:/home/root/mount2"`. | | `--disable-builtin-k8s-secret-store` | not supported | | `dapr.io/disable-builtin-k8s-secret-store` | Disables BuiltIn Kubernetes secret store. Default value is false. See [Kubernetes secret store component]({{< ref "kubernetes-secret-store.md" >}}) for details. | From c269439ec6b5c2d136bb829cde4978f7fd3ea2e6 Mon Sep 17 00:00:00 2001 From: Anton Troshin Date: Mon, 28 Oct 2024 12:59:51 -0500 Subject: [PATCH 2/2] CR suggestions Signed-off-by: Anton Troshin --- .../environment-variables-secrets.md | 40 +++++++++++-------- .../arguments-annotations-overview.md | 2 +- 2 files changed, 25 insertions(+), 17 deletions(-) diff --git a/daprdocs/content/en/operations/configuration/environment-variables-secrets.md b/daprdocs/content/en/operations/configuration/environment-variables-secrets.md index b822fb2de..960ee4771 100644 --- a/daprdocs/content/en/operations/configuration/environment-variables-secrets.md +++ b/daprdocs/content/en/operations/configuration/environment-variables-secrets.md @@ -5,28 +5,27 @@ linkTitle: "Environment Variables from Secrets" weight: 7500 description: "Inject Environment Variables from Kubernetes Secrets into Dapr sidecar" --- -In special cases, Dapr sidecar needs an environment variable injected into it. This use case may be required by a Component, a 3rd party library, or a module that uses environment variables to configure the said Component or customize its behavior. This can be useful for both production and non-production environments. +In special cases, the Dapr sidecar needs an environment variable injected into it. This use case may be required by a component, a 3rd party library, or a module that uses environment variables to configure the said component or customize its behavior. This can be useful for both production and non-production environments. ## Overview -In Dapr 1.15 the new annotation was introduced, `dapr.io/env-from-secret`, similarly to `dapr.io/env`, see [here]({{}}). -This annotation allows users to inject an environment variable with a value from a Secret, into the Dapr sidecar. +In Dapr 1.15, the new `dapr.io/env-from-secret` annotation was introduced, [similar to `dapr.io/env`]({{< ref arguments-annotations-overview >}}). +With this annotation, you can inject an environment variable into the Dapr sidecar, with a value from a secret. ### Annotation format The values of this annotation are formatted like so: - Single key secret: `=` -- Multi key-value secret: `=:` +- Multi key/value secret: `=:` -`` is required to follow the `C_IDENTIFIER` format and captured by the following regex: `[A-Za-z_][A-Za-z0-9_]*`
+`` is required to follow the `C_IDENTIFIER` format and captured by the `[A-Za-z_][A-Za-z0-9_]*` regex: - Must start with a letter or underscore -- The rest of the identifier to contain letters, digits, or underscores +- The rest of the identifier contains letters, digits, or underscores -Due to the restriction of the `secretKeyRef`, `name` field is required, so both `name` and `key` must be set (read more [here](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#environment-variables), in section "env.valueFrom.secretKeyRef.name")
-In this case, Dapr will set both to the same value. +The `name` field is required due to the restriction of the `secretKeyRef`, so both `name` and `key` must be set. [Learn more from the "env.valueFrom.secretKeyRef.name" section in this Kubernetes documentation.](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#environment-variables) +In this case, Dapr sets both to the same value. ## Configuring single key secret environment variable -Example:
-Add the `dapr.io/env-from-secret` annotation to Deployment +In the following example, the `dapr.io/env-from-secret` annotation is added to the Deployment. ```yaml apiVersion: apps/v1 kind: Deployment @@ -48,7 +47,9 @@ spec: - containerPort: 3000 imagePullPolicy: Always ``` -Annotation: `dapr.io/env-from-secret: "AUTH_TOKEN=auth-headers-secret"` will be injected as: + +The `dapr.io/env-from-secret` annotation with a value of `"AUTH_TOKEN=auth-headers-secret"` is injected as: + ```yaml env: - name: AUTH_TOKEN @@ -57,8 +58,12 @@ env: name: auth-headers-secret key: auth-headers-secret ``` -This will require the Secret to have both `name` and `key` fields with the same value, "auth-headers-secret".
-Example secret (for demo purposes only, don't store secrets in plain text) +This requires the secret to have both `name` and `key` fields with the same value, "auth-headers-secret". + +**Example secret** + +> **Note:** The following example is for demo purposes only. It's not recommended to store secrets in plain text. + ```yaml apiVersion: v1 kind: Secret @@ -71,7 +76,7 @@ stringData: ## Configuring multi-key secret environment variable -Add the `dapr.io/env-from-secret` annotation to Deployment +In the following example, the `dapr.io/env-from-secret` annotation is added to the Deployment. ```yaml apiVersion: apps/v1 kind: Deployment @@ -93,7 +98,7 @@ spec: - containerPort: 3000 imagePullPolicy: Always ``` -Annotation: `dapr.io/env-from-secret: "AUTH_TOKEN=auth-headers-secret:auth-header-value"` will be injected as: +The `dapr.io/env-from-secret` annotation with a value of `"AUTH_TOKEN=auth-headers-secret:auth-header-value"` is injected as: ```yaml env: - name: AUTH_TOKEN @@ -102,7 +107,10 @@ env: name: auth-headers-secret key: auth-header-value ``` -Example secret (for demo purposes only, don't store secrets in plain text) + +**Example secret** + + > **Note:** The following example is for demo purposes only. It's not recommended to store secrets in plain text. ```yaml apiVersion: v1 kind: Secret diff --git a/daprdocs/content/en/reference/arguments-annotations-overview.md b/daprdocs/content/en/reference/arguments-annotations-overview.md index a0f7324f0..2ae41c3b5 100644 --- a/daprdocs/content/en/reference/arguments-annotations-overview.md +++ b/daprdocs/content/en/reference/arguments-annotations-overview.md @@ -67,7 +67,7 @@ This table is meant to help users understand the equivalent options for running | not supported | not supported | | `dapr.io/sidecar-readiness-probe-period-seconds` | How often (in seconds) to perform the sidecar readiness probe. Read more [here](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#configure-probes). Default is `6`| | not supported | not supported | | `dapr.io/sidecar-readiness-probe-threshold` | When the sidecar readiness probe fails, Kubernetes will try N times before giving up. In this case, the Pod will be marked Unready. Read more about `failureThreshold` [here](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#configure-probes). Default is `3`| | not supported | not supported | | `dapr.io/env` | List of environment variable to be injected into the sidecar. Strings consisting of key=value pairs separated by a comma.| -| not supported | not supported | | `dapr.io/env-from-secret` | List of environment variable to be injected into the sidecar from Secret. Strings consisting of "key=secret-name:secret-key" pairs separated by a comma.| +| not supported | not supported | | `dapr.io/env-from-secret` | List of environment variables to be injected into the sidecar from secret. Strings consisting of `"key=secret-name:secret-key"` pairs are separated by a comma. | | not supported | not supported | | `dapr.io/volume-mounts` | List of [pod volumes to be mounted to the sidecar container]({{< ref "kubernetes-volume-mounts" >}}) in read-only mode. Strings consisting of `volume:path` pairs separated by a comma. Example, `"volume-1:/tmp/mount1,volume-2:/home/root/mount2"`. | | not supported | not supported | | `dapr.io/volume-mounts-rw` | List of [pod volumes to be mounted to the sidecar container]({{< ref "kubernetes-volume-mounts" >}}) in read-write mode. Strings consisting of `volume:path` pairs separated by a comma. Example, `"volume-1:/tmp/mount1,volume-2:/home/root/mount2"`. | | `--disable-builtin-k8s-secret-store` | not supported | | `dapr.io/disable-builtin-k8s-secret-store` | Disables BuiltIn Kubernetes secret store. Default value is false. See [Kubernetes secret store component]({{< ref "kubernetes-secret-store.md" >}}) for details. |