diff --git a/reference/fleet/agent-provider.md b/reference/fleet/agent-provider.md index 0407ad4ff1..40be749991 100644 --- 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 index 7edca62677..28e0655181 100644 --- 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 index c050b36098..a7c67f6b0e 100644 --- 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 index 34bd268a0b..be197f506e 100644 --- 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 index a16240a2a6..5d60269596 100644 --- 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 index c5737b0fed..43a9318615 100644 --- 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 index b55731c718..4ac3a9ab49 100644 --- 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 index ec3b9ff65d..dfba13b6b7 100644 --- 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 index 32e1d0997a..78593c6c7b 100644 --- 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 index 2f4ecf8d56..a057703036 100644 --- 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 index 1703243110..f88074ce09 100644 --- 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,7 +76,12 @@ 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: @@ -44,45 +89,9 @@ providers: 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). \ No newline at end of file diff --git a/reference/fleet/toc.yml b/reference/fleet/toc.yml index 662133a11a..1e7cb62606 100644 --- 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