youtubebeat/vendor/github.com/elastic/beats/libbeat/docs/shared-env-vars.asciidoc

110 lines
4.4 KiB
Text

//////////////////////////////////////////////////////////////////////////
//// This content is shared by all Elastic Beats. Make sure you keep the
//// descriptions here generic enough to work for all Beats that include
//// this file. When using cross references, make sure that the cross
//// references resolve correctly for any files that include this one.
//// Use the appropriate variables defined in the index.asciidoc file to
//// resolve Beat names: beatname_uc and beatname_lc.
//// Use the following include to pull this content into a doc file:
//// :standalone:
//// include::../../libbeat/docs/shared-env-vars.asciidoc[]
//// Specify :standalone: when this file is pulled into and index. When
//// the file is embedded in another file, do no specify :standalone:
//////////////////////////////////////////////////////////////////////////
ifdef::standalone[]
[[using-environ-vars]]
== Use environment variables in the configuration
endif::[]
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
{beatname_uc} to pick up the new value.
[NOTE]
==================================
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}`
==================================
[float]
=== Examples
Here are some examples of configurations that use environment variables
and what each configuration looks like after replacement:
[options="header"]
|==================================
|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`
|==================================
[float]
=== Specify complex objects in environment variables
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:
[source,yaml]
-------------------------------------------------------------------------------
ES_HOSTS="10.45.3.2:9220,10.45.3.1:9230"
-------------------------------------------------------------------------------
You can reference this variable in the config file:
[source,yaml]
-------------------------------------------------------------------------------
output.elasticsearch:
hosts: '${ES_HOSTS}'
-------------------------------------------------------------------------------
When {beatname_uc} loads the config file, it resolves the environment variable and
replaces it with the specified list before reading the `hosts` setting.
NOTE: Do not use double-quotes (`"`) to wrap regular expressions, or the backslash (`\`) will be interpreted as an escape character.