Skip to content

Environment Variables

There are three types of environment variables used by all EdgeX services. They are standard, command-line overrides, and configuration overrides.

Standard Environment Variables

This section describes the standard environment variables common to all EdgeX services. Standard environment variables do not override any command line flag or service configuration. Some services may have additional standard environment variables which are documented in those service specific sections. See Notable Other Standard Environment Variables below for list of these additional standard environment variables.

Note

All standard environment variables have the EDGEX_ prefix

EDGEX_SECURITY_SECRET_STORE

This environment variable indicates whether the service is expected to initialize the secure SecretStore which allows the service to access secrets from Vault. Defaults to true if not set or not set to false. When set to true the EdgeX security services must be running. If running EdgeX in non-secure mode you then want this explicitly set to false.

Example - Using docker-compose to disable secure SecretStore

environment: 
  EDGEX_SECURITY_SECRET_STORE: "false"

EDGEX_DISABLE_JWT_VALIDATION

This environment variable disables, at the microservice-level, validation of the Authorization HTTP header of inbound REST API requests. (Microservice-level authentication was added in EdgeX 3.0.)

Normally, when EDGEX_SECURITY_SECRET_STORE is unset or true, EdgeX microservices authenticate inbound HTTP requests by parsing the Authorization header, extracting a JWT bearer token, and validating it with the EdgeX secret store, returning an HTTP 401 error if token validation fails.

If for some reason it is not possible to pass a valid JWT to an EdgeX microservice -- for example, the eKuiper rule engine making an unauthenticated HTTP API call, or other legacy code -- it may be necessary to disable JWT validation in the receiving microservice.

Example - Using docker-compose environment variable to disable secure JWT validation

environment: 
  EDGEX_DISABLE_JWT_VALIDATION: "true"

Regardless of the setting of this variable, the API gateway (and related security-proxy-auth microservice) will always validate the incoming JWT.

EDGEX_STARTUP_DURATION

This environment variable sets the total duration in seconds allowed for the services to complete the bootstrap start-up. Default is 60 seconds.

Example - Using docker-compose to set start-up duration to 120 seconds

environment: 
  EDGEX_STARTUP_DURATION: "120"

EDGEX_STARTUP_INTERVAL

This environment variable sets the retry interval in seconds for the services retrying a failed action during the bootstrap start-up. Default is 1 second.

Example - Using docker-compose to set start-up interval to 3 seconds

environment: 
  EDGEX_STARTUP_INTERVAL: "3"

Notable Other Standard Environment Variables

This section covers other standard environment variables that are not common to all services.

EDGEX_ADD_SECRETSTORE_TOKENS

This environment variable tells the Secret Store Setup service which add-on services to generate SecretStore tokens for. See Configure Service's Secret Store section for more details.

EDGEX_ADD_KNOWN_SECRETS

This environment variable tells the Secret Store Setup service which add-on services need which known secrets added to their Secret Stores. See Configure Known Secrets section for more details.

EDGEX_ADD_REGISTRY_ACL_ROLES

This environment variable tells the Consul service entry point script which add-on services need ACL roles created. See Configure ACL Role section for more details.

EDGEX_ADD_PROXY_ROUTE

This environment variable tells the Proxy Setup Service which additional routes need to be added for add-on services. See Configure API Gateway Route section for more details.

EDGEX_IKM_HOOK

This environment variable tells the Secret Store Setup service the path to an executable that implements the IKM interface. See IKM HOOK section for more details.

Command-line Overrides

This section describes the command-line overrides that are common to most services. These overrides allow the use of the specific command-line flag to be overridden each time a service starts up.

Note

All command-line overrides also have the EDGEX_ prefix.

EDGEX_CONFIG_DIR

This environment variable overrides the -cd/--configDir command-line option.

Example - Using docker-compose to override the configuration folder name

environment: 
  EDGEX_CONF_DIR: "/my-config"

EdgeX 3.0

The EDGEX_CONF_DIR environment variable is replaced by EDGEX_CONFIG_DIR in EdgeX 3.0.

EDGEX_CONFIG_FILE

This environment variable overrides the -cf/--configFile command-line option.

Example - Using docker-compose to override the configuration file name used

environment: 
  EDGEX_CONFIG_FILE: "my-config.yaml"

EDGEX_CONFIG_PROVIDER

This environment variable overrides the -cp/--configProvider command-line option.

Overriding with a value of none disables the use of the Configuration Provider.

Note

All EdgeX service Docker images have this option set to -cp=consul.http://edgex-core-consul:8500.

Example - Using docker-compose to override with different port number

environment: 
  EDGEX_CONFIG_PROVIDER: "consul.http://edgex-consul:9500"

or

environment: 
  EDGEX_CONFIG_PROVIDER: "none"

EdgeX 3.0

The EDGEX_CONFIGURATION_PROVIDER environment variable is replaced by EDGEX_CONFIG_PROVIDER in EdgeX 3.0.

EDGEX_COMMON_CONFIG

This environment variable overrides the -cc/--commonConfig command-line option.

Note

The Common Config can only be specified when not using the Configuration Provider.

Example - Override with a common configuration file at the command line

$ export EDGEX_COMMON_CONFIG=./my-common-configuration.yaml
$ ./core-data

EdgeX 3.0

The EDGEX_COMMON_CONFIG variable is new to EdgeX 3.0.

EDGEX_PROFILE

This environment variable overrides the -p/--profile command-line option. When non-empty, the value is used in the path to the configuration file. i.e. /res/my-profile/configuation.yaml. This is useful when running multiple instances of a service such as App Service Configurable.

Example - Using docker-compose to override the profile to use

app-service-rules:
    image: edgexfoundry/docker-app-service-configurable:2.0.0
    environment: 
      EDGEX_PROFILE: "rules-engine"
    ...

This sets the profile so that the App Service Configurable uses the rules-engine configuration profile which resides at /res/rules-engine/configuration.yaml

EDGEX_USE_REGISTRY

This environment variable overrides the -r/--registry command-line option.

Note

All EdgeX service Docker images have this option set to --registry.

Example - Using docker-compose to override use of the Registry

environment: 
  EDGEX_USE_REGISTRY: "false"

EDGEX_REMOTE_SERVICE_HOSTS

This environment variable overrides the -rsh/--remoteServiceHosts command-line option.

Example - Using docker-compose to override Remote Service Hosts

environment: 
  EDGEX_REMOTE_SERVICE_HOSTS: "172.26.113.174,172.26.113.150,localhost"

Configuration Overrides

EdgeX 3.0

New in EdgeX 3.0. When used, the Configuration Provider is the System of Record for all configuration. The environment variables for configuration overrides no longer have the highest precedence. However, environment variables for standard and command-line overrides still maintain their role and higher precedence.

Configuration Provider is the System of Record for all configurations

When using the Configuration Provider, it is the System of Record for all configurations. Environment variables are only applied when the configuration is first read from file. These overridden values are used to seed the services' configuration into the Configuration Provider. Once the Configuration Provider has been seeded, services always get their configuration from the Configuration Provider on start up. Any subsequent changes to configuration must be done via the Configuration Provider. Changing an environment variable override for configuration and restating the service will not impact the service's configuration. The services configuration must first be removed from the Configuration Provider for any new/updated environment variable override(s) to impact the service's configuration.

Service Configuration Overrides

Any configuration setting from a service's configuration.yaml file can be overridden by environment variables. The environment variable names have the following format:

<SECTION-NAME>_<KEY-NAME>
<SECTION-NAME>_<SUB-SECTION-NAME>_<KEY-NAME>

Example - Environment Variable Overrides of Configuration

Service configuration YAML Environment variable
Writable:
  LogLevel: "INFO"
WRITABLE_LOGLEVEL=DEBUG
Service:
  Host: "localhost"
SERVICE_HOST=edgex-core-data

Important

Private configuration overrides are only applied to configuration settings that exist in the service's private configuration file.

SecretStore Configuration Overrides

The environment variables overrides for SecretStore configuration follow the same rules as the regular configuration overrides. The following are the SecretStore fields that are commonly overridden.

  • SECRETSTORE_HOST
  • SECRETSTORE_RUNTIMETOKENPROVIDER_ENABLED
  • SECRETSTORE_RUNTIMETOKENPROVIDER_HOST

Example SecretStore Configuration Override

Configuration Setting: SecretStore.Host
Environment Variable Override: SECRETSTORE_HOST=edgex-vault

The complete list of SecretStore fields and defaults can be found in the file here. The defaults for the remaining fields typically do not need to be overridden, but may be overridden if needed using that same naming scheme as above.

Notable Configuration Overrides

This section describes configuration overrides that have special utility, such as enabling a debug capability or facilitating code development.

TOKENFILEPROVIDER_DEFAULTTOKENTTL (security-secretstore-setup service)

This configuration override variable controls the TTL of the default SecretStore tokens that are created for EdgeX microservices by the Secret Store Setup service. This variable defaults to 1h (one hour) if unspecified. It is often useful when developing a new microservice to set this value to a higher value, such as 12h. This higher value will allow the secret store token to remain valid long enough for a developer to get a new microservice working and into a state where it can renew its own token. (All secret store tokens in EdgeX expire if not renewed periodically.)