docs: administration: yaml: document extended env list form

administration/configuring-fluent-bit/yaml/environment-variables-section.md

@@ -1,8 +1,12 @@
 # Environment variables
 
-The `env` section of YAML configuration files lets you define environment variables. These variables can then be used to dynamically replace values throughout your configuration using the `${VARIABLE_NAME}` syntax.
+The `env` section of YAML configuration files lets you define environment variables. These variables can then be used to dynamically replace values throughout your configuration using the `${VARIABLE_NAME}` syntax. The `env` section supports two forms: a map form for static key-value pairs and an extended list form for advanced use cases like file-backed secrets with automatic refresh.
 
-Values set in the `env` section are case-sensitive. However, as a best practice, Fluent Bit recommends using uppercase names for environment variables. The following example defines two variables, `FLUSH_INTERVAL` and `STDOUT_FMT`, which can be accessed in the configuration using `${FLUSH_INTERVAL}` and `${STDOUT_FMT}`:
+Values set in the `env` section are case-sensitive. However, as a best practice, Fluent Bit recommends using uppercase names for environment variables.
+
+## Map form
+
+The map form defines variables as key-value pairs. The following example defines two variables, `FLUSH_INTERVAL` and `STDOUT_FMT`, which can be accessed in the configuration using `${FLUSH_INTERVAL}` and `${STDOUT_FMT}`:
 
 ```yaml
 env:
@@ -23,6 +27,44 @@
       format: ${STDOUT_FMT}
 ```
 
+## Extended list form
+
+The `env` section also accepts a YAML list of entries. Each entry is a mapping with the following properties:
+
+| Property | Required | Description |
+| :------- | :------- | :---------- |
+| `name` | Yes | The name of the environment variable. |
+| `value` | No | An explicit value for the variable. Mutually exclusive with `uri`. |
+| `uri` | No | A URI pointing to the variable's value source. Currently supports `file://` URIs (for example, `file:///run/secrets/my_secret`). The file contents are read and used as the variable's value. |
+| `refresh_interval` | No | How often (in seconds) to re-read the value from the `uri` source. Only meaningful when `uri` is set. Default is `0` (read once at startup). |
+
+Either `value` or `uri` must be provided for each entry.
+
+When `uri` and `refresh_interval` are both set, Fluent Bit re-reads the file at the specified interval. This enables dynamic configuration values, such as rotating secrets, without restarting Fluent Bit. If `refresh_interval` is `0` or omitted, the file is read only once at startup.
+
+```yaml
+env:
+  - name: DB_PASSWORD
+    uri: file:///run/secrets/db_password
+    refresh_interval: 60
+  - name: REGION
+    value: us-east-1
+
+service:
+  flush: 1
+  log_level: info
+
+pipeline:
+  inputs:
+    - name: random
+
+  outputs:
+    - name: stdout
+      match: '*'
+```
+
+In this example, `${DB_PASSWORD}` is read from the file `/run/secrets/db_password` and refreshed every 60 seconds. `${REGION}` is set to the static value `us-east-1`.
+
 ## Predefined variables
 
 Fluent Bit supports the following predefined environment variables. You can reference these variables in configuration files without defining them in the `env` section.