Skip to content

Commit

Permalink
[documentation] Secrets management in Operator 1.11+ (#1555) (#1566)
Browse files Browse the repository at this point in the history 
Co-authored-by: Celene <celene@datadoghq.com>
  • Loading branch information
@tbavelier @celenechang
tbavelier and celenechang authored Dec 16, 2024
1 parent c6380c0 commit 13cf4a4
Showing 1 changed file with 56 additions and 97 deletions.
153 changes: 56 additions & 97 deletions docs/secret_management.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,9 +23,9 @@ spec:

The credentials provided here will be stored in a Secret created by the Operator. By properly setting the `RBAC` on the `DatadogAgent` CRD, one can limit who is able to see those credentials.

## 2. Use secret(s) references
## 2. Use Secret(s) references

Another solution is to provide the name of the secret(s) that contains the credentials:
Another solution is to provide the name of the Secret(s) that contains the credentials:

```yaml
apiVersion: datadoghq.com/v2alpha1
Expand All @@ -44,7 +44,7 @@ spec:
# ...
```

Create the secret(s) before applying the DatadogAgent manifest, or the deployment will fail.
Create the Secret(s) before applying the DatadogAgent manifest, or the deployment will fail.

```yaml
apiVersion: v1
Expand All @@ -65,7 +65,7 @@ data:
**Note:**
It is possible to use the same secret to store both credentials:
It is possible to use the same Secret to store both credentials:
```yaml
---
Expand Down Expand Up @@ -110,15 +110,15 @@ success

#### Using the secret helper

Kubernetes supports exposing secrets as files inside a pod, and we provide a helper script in the Datadog Operator image to read the secrets from files.
Kubernetes supports exposing Secrets as files inside a pod, and we provide a helper script in the Datadog Operator image to read the Secrets from files.

First, mount the secret in the Operator container, for instance at `/etc/secret-volume`. Then install or update the Datadog Operator deployment with the `.Values.secretBackend.command` parameter set to `/readsecret.sh` and the `.Values.secretBackend.arguments` parameter set to `/etc/secret-volume`.
First, mount the Secret in the Operator container, for instance at `/etc/secret-volume`. Then install or update the Datadog Operator deployment with the `.Values.secretBackend.command` parameter set to `/readsecret.sh` and the `.Values.secretBackend.arguments` parameter set to `/etc/secret-volume`.

**Note:** This secret helper requires Datadog Operator v0.5.0+

### How to deploy the agent components using the secret backend feature with DatadogAgent
### How to deploy Agent components using the secret backend feature with the DatadogAgent (Operator 1.11+)

If using a custom script, create a Datadog Agent (or Cluster Agent) image following the example for the Datadog Operator above. Then, to activate the secret backend feature in the `DatadogAgent` configuration, the `spec.credentials.useSecretBackend` parameter should be set to `true`.
If using a custom script, create a Datadog Agent (or Cluster Agent) image following the example for the Datadog Operator above, and specify credentials using `ENC[<placeholder>]`.

```yaml
apiVersion: datadoghq.com/v2alpha1
Expand All @@ -133,53 +133,25 @@ spec:
# ...
```

Then inside the `spec.agent` configuration, the secret backend command can be specified by adding a new environment variable: "DD_SECRET_BACKEND_COMMAND".
The secret backend command can be specified in the `spec.global.secretBackend.command`:

```yaml
apiVersion: datadoghq.com/v2alpha1
kind: DatadogAgent
metadata:
name: datadog
spec:
global:
secretBackend:
command: "/my-secret-backend.sh"
# ...
override:
nodeAgent:
containers:
agent:
env:
- name: DD_SECRET_BACKEND_COMMAND
value: "/my-secret-backend.sh"
```

If the "Cluster Agent" and the "Cluster Check Runner" are also deployed, the environment variable needs to be added also in the other environment variables configuration.

```yaml
apiVersion: datadoghq.com/v2alpha1
kind: DatadogAgent
metadata:
name: datadog
spec:
# ...
override:
clusterAgent:
# ...
containers:
cluster-agent:
env:
- name: DD_SECRET_BACKEND_COMMAND
value: "/my-secret-backend.sh"
clusterChecksRunner:
# ...
containers:
agent:
env:
- name: DD_SECRET_BACKEND_COMMAND
value: "/my-secret-backend.sh"
```
The environment variable `DD_SECRET_BACKEND_COMMAND` from this configuration is automatically applied to all the deployed components: node Agent, Cluster Agent, and Cluster Checks Runners. Ensure the image you are using for all the components includes your command.

As in the Datadog Operator, the Datadog Agent image includes a helper function `readsecret.sh` that can be used to read mounted secrets. After creating the secret and setting the volume mount (in any container that requires it), set the `DD_SECRET_BACKEND_COMMAND` and `DD_SECRET_BACKEND_ARGUMENTS` environmental variables.
For convenience, the Datadog Agent and its sibling Cluster Agent images already include a `readsecret_multiple_providers.sh` [helper function][2] that can be used to read from both files as well as Kubernetes Secrets. After creating the Secret, set `spec.global.secretBackend.command` to `"/readsecret_multiple_providers.sh"`.

For instance, to use the secret backend for the Agent and Cluster Agent, create a secret called "test-secret":
For instance, to use the secret backend for the Agent and Cluster Agent, create a Secret called "test-secret":

`kubectl create secret generic test-secret --from-literal=api_key='<api-key>' --from-literal=app_key='<app-key>'`

Expand All @@ -192,68 +164,55 @@ metadata:
name: datadog
spec:
global:
credentials:
apiKey: ENC[api_key]
appKey: ENC[app_key]
override:
nodeAgent:
env:
- name: DD_SECRET_BACKEND_COMMAND
value: "/readsecret.sh"
- name: DD_SECRET_BACKEND_ARGUMENTS
value: "/etc/secret-volume"
containers:
agent:
volumeMounts:
- name: secret-volume
mountPath: "/etc/secret-volume"
volumes:
- name: secret-volume
secret:
secretName: test-secret
clusterAgent:
containers:
cluster-agent:
env:
- name: DD_SECRET_BACKEND_COMMAND
value: "/readsecret.sh"
- name: DD_SECRET_BACKEND_ARGUMENTS
value: "/etc/secret-volume"
volumeMounts:
- name: secret-volume
mountPath: "/etc/secret-volume"
volumes:
- name: secret-volume
secret:
secretName: test-secret
```

The Datadog Agent also includes a script that can be used to read secrets from files mounted from Kubernetes secrets, or directly from Kubernetes secrets. This script can be used by setting `DD_SECRET_BACKEND_COMMAND` to `/readsecret_multiple_providers.sh`. An example of how to configure the DatadogAgent spec is provided below. For more details, see [Secrets Management][2].

```yaml
apiVersion: datadoghq.com/v2alpha1
kind: DatadogAgent
metadata:
name: datadog
spec:
global:
secretBackend:
command: "/readsecret_multiple_providers.sh"
credentials:
apiKey: ENC[k8s_secret@default/test-secret/api_key]
appKey: ENC[k8s_secret@default/test-secret/app_key]
override:
nodeAgent:
env:
- name: DD_SECRET_BACKEND_COMMAND
value: "/readsecret_multiple_providers.sh"
```

**Remarks:**

* For the "Agent" and "Cluster Agent", others options exist to configure secret backend command:
* The `"/readsecret_multiple_providers.sh"` helper enables the Agent to directly read Kubernetes Secrets across both its own and other namespaces. Ensure that the associated ServiceAccount has the necessary permissions by assigning the appropriate Roles and RoleBindings, which can be set manually or using the following options:
* `global.secretBackend.enableGlobalPermissions`: Determines if a ClusterRole is created that enables the Agents to read **all** Kubernetes Secrets.
```yaml
apiVersion: datadoghq.com/v2alpha1
kind: DatadogAgent
metadata:
name: datadog
spec:
global:
secretBackend:
command: "/readsecret_multiple_providers.sh"
enableGlobalPermissions: true
# ...
```
* `global.secretBackend.roles`: Replaces `enableGlobalPermissions`, detailing the list of namespace/secrets to which the Agents should have access.
```yaml
apiVersion: datadoghq.com/v2alpha1
kind: DatadogAgent
metadata:
name: datadog
spec:
global:
secretBackend:
command: "/readsecret_multiple_providers.sh"
roles:
- namespace: rabbitmq-system
secrets:
- "rabbitmqcluster-sample-default-user"
# ...
```
In this example, a Role is created granting read access to the Secret `rabbitmqcluster-sample-default-user` in the `rabbitmq-system` namespace.

**Note**: Each namespace in the `roles` list must also be configured in the `WATCH_NAMESPACE` or `DD_AGENT_WATCH_NAMESPACE` environment variable on the **Datadog Operator** deployment.


* **DD_SECRET_BACKEND_ARGUMENTS**: those arguments will be specified to the command when the agent executes the secret backend command.
* **DD_SECRET_BACKEND_OUTPUT_MAX_SIZE**: maximum output size of the secret backend command. The default value is 1048576 (1Mb).
* **DD_SECRET_BACKEND_TIMEOUT**: secret backend execution timeout in second. The default value is 5 seconds.
* For the Agent and Cluster Agent, there are other configuration options for the secret backend command:
* `global.secretBackend.args`: these arguments are supplied to the command when the Agent executes the secret backend command.
* `global.secretBackend.timeout`: secret backend execution timeout in seconds. The default value is 30 seconds.
* For versions prior to Operator 1.11, `spec.global.secretBackend` is unavailable. You should follow [these instructions][3] instead.

[1]: https://docs.datadoghq.com/agent/guide/secrets-management
[2]: https://docs.datadoghq.com/agent/guide/secrets-management/?tab=linux#script-for-reading-from-multiple-secret-providers
[3]: https://github.com/DataDog/datadog-operator/blob/2bbda7adace27de3d397b3d76d87fbd49fa304e3/docs/secret_management.md#how-to-deploy-the-agent-components-using-the-secret-backend-feature-with-datadogagent

0 comments on commit 13cf4a4

Please sign in to comment.