[TEEP-5473] Document multi_secret_backends for multiple native secret backends

content/en/agent/configuration/secrets-management.md

@@ -35,9 +35,13 @@ Instead of hardcoding sensitive values like API keys or passwords in plaintext w
 
 **Note**: As of Agent version `7.76` and onwards, native secrets management is available for FIPS-enabled Agents.
 
-Starting in Agent version `7.70`, the Datadog Agent natively supports several secret management solutions. Two new settings have been introduced to `datadog.yaml`: `secret_backend_type` and `secret_backend_config`.
+Starting in Agent version `7.70`, the Datadog Agent natively supports several secret management solutions.
 
-`secret_backend_type` is used to specify which secret management solution to use, and `secret_backend_config` holds additional configuration relevant to that solution.
+**Note**: If you are running Datadog in a containerized environment, the [Cluster Agent](/containers/cluster_agent/) requires Agent 7.77 or later to support native secrets fetching. For earlier versions, use [Option 2](#option-2-using-the-built-in-script-for-kubernetes-and-docker) or [Option 3](#option-3-creating-a-custom-executable) instead.
+
+#### Single backend
+
+Use `secret_backend_type` and `secret_backend_config` in `datadog.yaml` to configure a single secret backend:
 
 ```yaml
 # datadog.yaml
@@ -47,8 +51,6 @@ secret_backend_config:
   <KEY_1>: <VALUE_1>
 ```
 
-**Note**: If you are running Datadog in a containerized environment, the [Cluster Agent](/containers/cluster_agent/) requires Agent 7.77 or later to support native secrets fetching. For earlier versions, use [Option 2](#option-2-using-the-built-in-script-for-kubernetes-and-docker) or [Option 3](#option-3-creating-a-custom-executable) instead.
-
 More specific setup instructions depend on the backend type used. See the appropriate section below for further information:
 
 
@@ -426,7 +428,7 @@ secret_backend_type: azure.keyvault
 secret_backend_config:
   keyvaulturl: {keyVaultURL}
   azure_session:
-    azure_client_id: {clientID}  # User-assigned managed identity client ID; omit this field for system-assigned
+    azure_client_id: {clientID}  # User-assigned managed identity client ID; omit this field for system-assigned
 ```
 
 When using environment variables, convert the configuration to JSON:
@@ -1007,7 +1009,7 @@ secret_backend_config:
 | `client_cert` | Path to a PEM-encoded client certificate file for mTLS. |
 | `client_key` | Path to the private key file for the client certificate. |
 | `tls_server` | Expected server name for TLS SNI verification. |
-| `insecure` | Set to `true` to disable TLS certificate verification. Do not use in production. |
+| `insecure` | Set to `true` to disable TLS certificate verification. Do not use in production. |
 
 {{% /collapse-content %}}
 
@@ -1453,6 +1455,93 @@ secret_backend_config:
 
 {{% /collapse-content %}}
 
+#### Multiple backends
+
+**Available in Agent version 7.80+**
+
+Instead of a single `secret_backend_type`, you can declare multiple named backends under `multi_secret_backends`. Each backend has its own `type` and `config`, and secrets are routed to a specific backend using a `backendName;` prefix in the `ENC[]` handle.
+
+If more than one of the following is set, the highest-priority setting takes effect and the others are ignored with a warning:
+
+1. `secret_backend_command`
+2. `secret_backend_type`
+3. `multi_secret_backends`
+
+##### Configuration
+
+```yaml
+# datadog.yaml
+
+multi_secret_backends:
+  <backend_name>:
+    type: <backend_type>
+    config:
+      <KEY_1>: <VALUE_1>
+```
+
+Each `<backend_name>` is an arbitrary identifier you choose. It cannot contain a semicolon, because `;` is the delimiter used in `ENC[]` handles. The `type` and `config` fields follow the same schema as `secret_backend_type` and `secret_backend_config` for the corresponding backend.
+
+##### `ENC[]` notation
+
+When `multi_secret_backends` is active, prefix `ENC[]` handles with the backend name followed by a semicolon:
+
+```
+ENC[<backend_name>;<secret_key>]
+```
+
+Only the **first** semicolon is treated as the backend delimiter. Secret keys that themselves contain semicolons (for example, Kubernetes-style `namespace/secret-name;key`) continue to work.
+
+##### Example
+
+The following configuration reads secrets from two file backends simultaneously:
+
+```yaml
+# datadog.yaml
+multi_secret_backends:
+  yaml_secrets:
+    type: file.yaml
+    config:
+      file_path: /etc/datadog-agent/secrets.yaml
+  aws_secrets:
+    type: aws.secrets
+    config:
+      aws_session:
+        aws_region: us-east-1
+```
+
+Reference secrets by prefixing with the backend name:
+
+```yaml
+# datadog.yaml
+api_key: ENC[yaml_secrets;api_key]
+app_key: ENC[aws_secrets;My-Secrets;appKey]
+```
+
+##### Migrating from `secret_backend_type`
+
+To switch from a single `secret_backend_type` to `multi_secret_backends`:
+
+1. Move `secret_backend_type` and `secret_backend_config` into a named entry under `multi_secret_backends`.
+2. Remove `secret_backend_type` and `secret_backend_config` from the top level.
+3. Update all `ENC[secretKey]` handles to `ENC[backendName;secretKey]`.
+
+```yaml
+# Before
+secret_backend_type: file.yaml
+secret_backend_config:
+  file_path: /etc/datadog-agent/secrets.yaml
+
+api_key: ENC[api_key]
+
+# After
+multi_secret_backends:
+  my_yaml:
+    type: file.yaml
+    config:
+      file_path: /etc/datadog-agent/secrets.yaml
+
+api_key: ENC[my_yaml;api_key]
+```
 
 ### Option 2: Using the built-in Script for Kubernetes and Docker