Move the “Providers" docs out of the standalone Elastic Agent docs (#3919)

vishaangelova · web-flow · commit 1200d59c0c2c · 2025-11-24T20:47:11.000Z
This PR moves the “Providers" docs out of the standalone Elastic Agent docs, so they are now at the level of the Elastic Agent processors. It also: - Restructures and updates the `providers.md` with more details to make the content more accurate (e.g., for the context and dynamic providers), and includes information on using providers on Fleet-managed Elastic Agent (vs. standalone). - Adds a page-level `applies_to` tag to all provider docs. - Fixes capitalization in titles and refs. <img width="256" height="624" alt="Screenshot 2025-11-12 at 18 21 11" src="https://github.com/user-attachments/assets/1c17c00f-2edf-4613-8821-729aa82b2f4f" /> Closes #2167 ——— An AI assistant (Cursor) was used in this PR to clarify and improve the content in the `providers.md` doc, by checking against the code base for correct/incorrect statements.
diff --git a/reference/fleet/agent-provider.md b/reference/fleet/agent-provider.md
@@ -1,6 +1,8 @@
 ---
 mapped_pages:
   - https://www.elastic.co/guide/en/fleet/current/agent-provider.html
+applies_to:
+  stack: ga
 products:
   - id: fleet
   - id: elastic-agent
diff --git a/reference/fleet/docker-provider.md b/reference/fleet/docker-provider.md
@@ -1,12 +1,14 @@
 ---
 mapped_pages:
   - https://www.elastic.co/guide/en/fleet/current/docker-provider.html
+applies_to:
+  stack: ga
 products:
   - id: fleet
   - id: elastic-agent
 ---
 
-# Docker Provider [docker-provider]
+# Docker provider [docker-provider]
 
 Provides inventory information from Docker. The available dynamic variables are:
 
diff --git a/reference/fleet/env-provider.md b/reference/fleet/env-provider.md
@@ -1,12 +1,14 @@
 ---
 mapped_pages:
   - https://www.elastic.co/guide/en/fleet/current/env-provider.html
+applies_to:
+  stack: ga
 products:
   - id: fleet
   - id: elastic-agent
 ---
 
-# Env Provider [env-provider]
+# Env provider [env-provider]
 
 Provides access to the environment variables as key-value pairs.
 
diff --git a/reference/fleet/filesource-provider.md b/reference/fleet/filesource-provider.md
@@ -1,3 +1,11 @@
+---
+applies_to:
+  stack: ga
+products:
+  - id: fleet
+  - id: elastic-agent
+---
+
 # Filesource provider [filesource-provider]
 
 Watches for changes of specified files and updates the values of the variables when the content of the files changes.
diff --git a/reference/fleet/host-provider.md b/reference/fleet/host-provider.md
@@ -1,6 +1,8 @@
 ---
 mapped_pages:
   - https://www.elastic.co/guide/en/fleet/current/host-provider.html
+applies_to:
+  stack: ga
 products:
   - id: fleet
   - id: elastic-agent
diff --git a/reference/fleet/kubernetes-provider.md b/reference/fleet/kubernetes-provider.md
@@ -1,12 +1,14 @@
 ---
 mapped_pages:
   - https://www.elastic.co/guide/en/fleet/current/kubernetes-provider.html
+applies_to:
+  stack: ga
 products:
   - id: fleet
   - id: elastic-agent
 ---
 
-# Kubernetes Provider [kubernetes-provider]
+# Kubernetes provider [kubernetes-provider]
 
 Provides inventory information from Kubernetes.
 
diff --git a/reference/fleet/kubernetes_leaderelection-provider.md b/reference/fleet/kubernetes_leaderelection-provider.md
@@ -1,6 +1,8 @@
 ---
 mapped_pages:
   - https://www.elastic.co/guide/en/fleet/current/kubernetes_leaderelection-provider.html
+applies_to:
+  stack: ga
 products:
   - id: fleet
   - id: elastic-agent
diff --git a/reference/fleet/kubernetes_secrets-provider.md b/reference/fleet/kubernetes_secrets-provider.md
@@ -1,12 +1,14 @@
 ---
 mapped_pages:
   - https://www.elastic.co/guide/en/fleet/current/kubernetes_secrets-provider.html
+applies_to:
+  stack: ga
 products:
   - id: fleet
   - id: elastic-agent
 ---
 
-# Kubernetes Secrets Provider [kubernetes_secrets-provider]
+# Kubernetes Secrets provider [kubernetes_secrets-provider]
 
 Provides access to the Kubernetes Secrets API.
 
diff --git a/reference/fleet/local-dynamic-provider.md b/reference/fleet/local-dynamic-provider.md
@@ -1,6 +1,8 @@
 ---
 mapped_pages:
   - https://www.elastic.co/guide/en/fleet/current/local-dynamic-provider.html
+applies_to:
+  stack: ga
 products:
   - id: fleet
   - id: elastic-agent
diff --git a/reference/fleet/local-provider.md b/reference/fleet/local-provider.md
@@ -1,12 +1,14 @@
 ---
 mapped_pages:
   - https://www.elastic.co/guide/en/fleet/current/local-provider.html
+applies_to:
+  stack: ga
 products:
   - id: fleet
   - id: elastic-agent
 ---
 
-# Local [local-provider]
+# Local provider [local-provider]
 
 Provides custom keys to use as variables. For example:
 
diff --git a/reference/fleet/providers.md b/reference/fleet/providers.md
@@ -1,25 +1,65 @@
 ---
-navigation_title: Providers
+navigation_title: Agent providers
 mapped_pages:
   - https://www.elastic.co/guide/en/fleet/current/providers.html
+applies_to:
+  stack: ga
 products:
   - id: fleet
   - id: elastic-agent
 ---
 
-# Configure providers for standalone {{agent}}s [providers]
+# {{agent}} providers [providers]
 
+Providers supply key-value pairs for variable substitution and conditional logic. They define dynamic values that {{agent}} uses when building configurations.
 
-Providers supply the key-value pairs that are used for variable substitution and conditionals. Each provider’s keys are automatically prefixed with the name of the provider in the context of the {{agent}}.
+{{agent}} uses two kinds of providers: [context providers](#context-providers) and [dynamic providers](#dynamic-providers). Each provider’s keys are automatically grouped under the provider name in the {{agent}} context. For example, if the `foo` provider supplies `{"key1": "value1", "key2": "value2"}`, {{agent}} stores these key-value pairs as `{"foo": {"key1": "value1", "key2": "value2"}}`. You can then reference the values using the `${foo.key1}` and `${foo.key2}` variables.
 
-For example, a provider named `foo` provides `{"key1": "value1", "key2": "value2"}`, the key-value pairs are placed in `{"foo" : {"key1": "value1", "key2": "value2"}}`. To reference the keys, use `{{foo.key1}}` and `{{foo.key2}}`.
+How you can configure and use {{agent}} providers depends on whether you're running a standalone or a {{fleet}}-managed {{agent}}. For more information, refer to:
 
+* [Configure providers on standalone {{agent}}](#configure-providers-standalone-agent)
+* [Using providers on {{fleet}}-managed {{agent}}](#using-providers-fleet-managed-agent)
 
-## Provider configuration [_provider_configuration]
 
-The provider configuration is specified under the top-level `providers` key in the `elastic-agent.yml` configuration. All registered providers are enabled by default. If a provider cannot connect, no mappings are produced.
+## Provider types
 
-The following example shows two providers (`local` and `local_dynamic`) that supply custom keys:
+{{agent}} supports two types of providers: [context providers](#context-providers) and [dynamic providers](#dynamic-providers).
+
+
+### Context providers [context-providers]
+
+Context providers supply a single key-value mapping that describes the current environment where {{agent}} is running, such as agent information (ID, version), host information (hostname, IP addresses), and environment information (environment variables). When the underlying context changes, {{agent}} updates this mapping and re-evaluates the configuration.
+
+To ensure consistency and clarity across documentation and projects, context providers use the {{product.ecs}} naming conventions.
+
+{{agent}} supports the following context providers:
+
+* [Local provider](/reference/fleet/local-provider.md) - Provides custom keys to use as variables.
+* [Agent provider](/reference/fleet/agent-provider.md) - Provides information about the {{agent}} such as ID, version, and build details.
+* [Host provider](/reference/fleet/host-provider.md) - Provides information about the current host such as hostname, IP addresses, platform, and architecture.
+* [Env provider](/reference/fleet/env-provider.md) - Provides access to environment variables as key-value pairs.
+* [{{k8s}} Secrets provider](/reference/fleet/kubernetes_secrets-provider.md) - Provides access to the {{k8s}} Secrets API.
+* [{{k8s}} LeaderElection provider](/reference/fleet/kubernetes_leaderelection-provider.md) - Enables leader election between {{agent}} instances running on {{k8s}} to ensure only one agent holds the leader lock.
+
+
+### Dynamic providers [dynamic-providers]
+
+Dynamic providers supply multiple key-value mappings where each mapping represents a separate item or resource (such as a container or pod). When rendering configurations, {{agent}} combines each mapping with the values from context providers, and for every mapping that matches a configuration template or condition, it creates a separate configuration instance and substitutes any dynamic variables (for example, `${docker.container.id}` or `${kubernetes.pod.ip}`) with values from that mapping. This allows {{agent}} to automatically add, update, or remove inputs as your environment changes.
+
+{{agent}} supports the following dynamic providers:
+
+* [Local dynamic provider](/reference/fleet/local-dynamic-provider.md) - Defines multiple key-value pairs to generate multiple configurations.
+* [Docker provider](/reference/fleet/docker-provider.md) - Provides Docker container metadata such as ID, name, image, and labels.
+* [{{k8s}} provider](/reference/fleet/kubernetes-provider.md) - Provides metadata from {{k8s}} resources such as pods, nodes, and services.
+
+
+## Configure providers on standalone {{agent}} [configure-providers-standalone-agent]
+
+On standalone {{agent}}, providers can be configured through the top-level `providers` key in the `elastic-agent.yml` configuration file. All registered providers are enabled by default, but {{agent}} runs them only if they are referenced in the configuration file or in an {{agent}} policy. Disabled providers are not run even if they are referenced. If a provider cannot connect, no mappings are produced.
+
+You can enable, disable, and configure provider settings as needed. All providers are prefixed without name collisions. In the configuration, the name of the provider is in the key.
+
+The following example shows two providers (`local` and `local_dynamic`) that supply custom keys on a standalone {{agent}}:
 
 ```yaml
 providers:
@@ -36,53 +76,22 @@ providers:
           item: key3
 ```
 
-Providers are enabled automatically if a provider is referenced in an {{agent}} policy. All providers are prefixed without name collisions. The name of the provider is in the key in the configuration.
+If a provider is referenced in an {{agent}} policy, it is turned on automatically unless it's explicitly disabled in the `elastic-agent.yml` configuration file.
+
+
+### Disable providers [disable-providers-by-default]
+
+On standalone {{agent}}, you can disable a specific provider, so it cannot be run even if it is referenced. For example, to disable the Docker provider on a standalone {{agent}}, set:
 
 ```yaml
 providers:
   docker:
     enabled: false
 ```
 
-{{agent}} supports two broad types of providers: [context](#context-providers) and [dynamic](#dynamic-providers).
-
-
-### Context providers [context-providers]
-
-Context providers give the current context of the running {{agent}}, for example, agent information (ID, version), host information (hostname, IP addresses), and environment information (environment variables).
-
-They can only provide a single key-value mapping. Think of them as singletons; an update of a key-value mapping results in a re-evaluation of the entire configuration. These providers are normally very static, but not required. A value can change which results in re-evaluation.
-
-Context providers use the Elastic Common Schema (ECS) naming to ensure consistency and understanding throughout documentation and projects.
-
-{{agent}} supports the following context providers:
-
-* [Local](/reference/fleet/local-provider.md)
-* [Agent Provider](/reference/fleet/agent-provider.md)
-* [Host Provider](/reference/fleet/host-provider.md)
-* [Env Provider](/reference/fleet/env-provider.md)
-* [Kubernetes Secrets Provider](/reference/fleet/kubernetes_secrets-provider.md)
-* [Kubernetes Leader Election Provider](/reference/fleet/kubernetes_leaderelection-provider.md)
-
-
-### Dynamic Providers [dynamic-providers]
-
-Dynamic providers give an array of multiple key-value mappings. Each key-value mapping is combined with the previous context provider’s key and value mapping which provides a new unique mapping that is used to generate a configuration.
-
-{{agent}} supports the following context providers:
+With this setting, {{agent}} will not run the Docker provider even if it's referenced in an {{agent}} policy.
 
-* [Local Dynamic Provider](/reference/fleet/local-dynamic-provider.md)
-* [Docker Provider](/reference/fleet/docker-provider.md)
-* [Kubernetes Provider](/reference/fleet/kubernetes-provider.md)
-
-
-### Disabling Providers By Default [disable-providers-by-default]
-
-All registered providers are disabled by default until they are referenced in a policy.
-
-You can disable all providers even if they are referenced in a policy by setting `agent.providers.initial_default: false`.
-
-The following configuration disables all providers from running except for the docker provider, if it becomes referenced in the policy:
+You can also disable all providers by setting `agent.providers.initial_default: false`. The following configuration disables all providers with the exception of the Docker provider, which is run when it's referenced in the policy:
 
 ```yaml
 agent.providers.initial_default: false
@@ -92,11 +101,8 @@ providers:
 ```
 
 
+## Using providers on {{fleet}}-managed {{agent}} [using-providers-fleet-managed-agent]
 
+On {{fleet}}-managed {{agent}}, you can use provider variables in integration policy settings (for example, `${host.name}`, `${env.foo}`, `${agent.id}`), but you cannot add a `providers` configuration block directly through the {{fleet}} UI.
 
-
-
-
-
-
-
+Some providers can be configured on {{k8s}} deployments using ConfigMaps. For more details, refer to [Advanced {{agent}} configuration managed by {{fleet}}](/reference/fleet/advanced-kubernetes-managed-by-fleet.md).
diff --git a/reference/fleet/toc.yml b/reference/fleet/toc.yml
@@ -102,18 +102,6 @@ toc:
           - file: elastic-agent-simplified-input-configuration.md
           - file: elastic-agent-inputs-list.md
           - file: dynamic-input-configuration.md
-      - file: providers.md
-        children:
-          - file: local-provider.md
-          - file: agent-provider.md
-          - file: host-provider.md
-          - file: env-provider.md
-          - file: filesource-provider.md
-          - file: kubernetes_secrets-provider.md
-          - file: kubernetes_leaderelection-provider.md
-          - file: local-dynamic-provider.md
-          - file: docker-provider.md
-          - file: kubernetes-provider.md
       - file: elastic-agent-output-configuration.md
         children:
           - file: elasticsearch-output.md
@@ -163,6 +151,18 @@ toc:
           - file: data-streams-advanced-features.md
       - file: alert-templates.md
   - file: agent-command-reference.md
+  - file: providers.md
+    children:
+      - file: local-provider.md
+      - file: agent-provider.md
+      - file: host-provider.md
+      - file: env-provider.md
+      - file: filesource-provider.md
+      - file: kubernetes_secrets-provider.md
+      - file: kubernetes_leaderelection-provider.md
+      - file: local-dynamic-provider.md
+      - file: docker-provider.md
+      - file: kubernetes-provider.md
   - file: agent-processors.md
     children:
       - file: processor-syntax.md
