WARNING: Version 5.6 of Metricbeat has passed its EOL date.

This documentation is no longer being maintained and may be removed. If you are running this version, we strongly advise you to upgrade. For the latest information, see the current release documentation.

« Configuring Metricbeat to Use Logstash YAML Tips and Gotchas »
Elastic Docs ›Metricbeat Reference [5.6] ›Configuring Metricbeat

Using Environment Variables in the Configuration

edit

Using Environment Variables in the Configuration

edit

You can use environment variable references in the config file to set values that need to be configurable during deployment. To do this, use:

${VAR}

Where VAR is the name of the environment variable.

Each variable reference is replaced at startup by the value of the environment variable. The replacement is case-sensitive and occurs before the YAML file is parsed. References to undefined variables are replaced by empty strings unless you specify a default value or custom error text.

To specify a default value, use:

${VAR:default_value}

Where default_value is the value to use if the environment variable is undefined.

To specify custom error text, use:

${VAR:?error_text}

Where error_text is custom text that will be prepended to the error message if the environment variable cannot be expanded.

If you need to use a literal ${ in your configuration file then you can write $${ to escape the expansion.

After changing the value of an environment variable, you need to restart the Beat to pick up the new value.

You can also specify environment variables when you override a config setting from the command line by using the -E option. For example:

-E name=${NAME}

Examples

edit

Here are some examples of configurations that use environment variables and what each configuration looks like after replacement:

Config source Environment setting Config after replacement

name: ${NAME}

export NAME=elastic

name: elastic

name: ${NAME}

no setting

name:

name: ${NAME:beats}

no setting

name: beats

name: ${NAME:beats}

export NAME=elastic

name: elastic

name: ${NAME:?You need to set the NAME environment variable}

no setting

None. Returns an error message that’s prepended with the custom text.

name: ${NAME:?You need to set the NAME environment variable}

export NAME=elastic

name: elastic

Specifying Complex Objects in Environment Variables

edit

You can specify complex objects, such as lists or dictionaries, in environment variables by using a JSON-like syntax.

As with JSON, dictionaries and lists are constructed using {} and []. But unlike JSON, the syntax allows for trailing commas and slightly different string quotation rules. Strings can be unquoted, single-quoted, or double-quoted, as a convenience for simple settings and to make it easier for you to mix quotation usage in the shell. Arrays at the top-level do not require brackets ([]).

For example, the following environment variable is set to a list:

ES_HOSTS="10.45.3.2:9220,10.45.3.1:9230"

You can reference this variable in the config file:

output.elasticsearch:
  hosts: '${ES_HOSTS}'

When the Beat loads the config file, it resolves the environment variable and replaces it with the specified list before reading the hosts setting.

Do not use double-quotes (") to wrap regular expressions, or the backslash (\) will be interpreted as an escape character.

« Configuring Metricbeat to Use Logstash YAML Tips and Gotchas »