Config & Registry

Introduction

The Edge Xpert registry and configuration service provides other Edge Xpert with information about associated services within Edge Xpert (e.g., location and status) and configuration properties (i.e. - a repository of initialization and operational values). Today, Edge Xpert uses Core Keeper as a reference implementation for configuration and registry providers by default. However, abstractions are available so that these functions can also be provided by an alternative implementation. In fact, registry and configuration could be provided by different services under the hood. For more information, see the Configuration Provider and Registry Provider sections on this page.

Configuration

Common Configuration

The tables on each tab below document configuration properties that apply to all Edge Xpert platform services. Service-specific properties can be found on the respective documentation page for each service.

Configuration Properties

Writable vs Readable Settings

Within a given service's configuration, there are keys whose values can be edited and change the behavior of the service while it is running versus those that are effectively read-only. These writable settings are grouped under a given service key. For example, the top-level groupings for Core Data are:

• /edgex/core/2.0/core-data/Writable
• /edgex/core/2.0/core-data/Service
• /edgex/core/2.0/core-data/Clients
• /edgex/core/2.0/core-data/Databases
• /edgex/core/2.0/core-data/MessageQueue
• /edgex/core/2.0/core-data/Registry
• /edgex/core/2.0/core-data/SecretStore

Any configuration settings found in a service's Writable section may be changed and affect a service's behavior without a restart. Any modifications to the other settings (read-only configuration) would require a restart.

Local Configuration

Because Edge Xpert may be deployed and run in several different ways, it is important to understand how configuration is loaded and from where it is sourced. Inside each service container there is a res directory (short for "resource"). There you will find the configuration files in TOML format that defines each service's configuration. A service may support several different configuration profiles, for example, an App Service Configurable has multiple configuration profiles. In this case, the configuration file located directly in the res directory should be considered the default configuration profile. Sub-directories will contain configurations appropriate to the respective profile.

As of the v1.8 release, Edge Xpert recommends using environment variable overrides instead of creating profiles to override some subset of config values. Application Service Configurable is an exception to this as this is how it defined unique instances using the same executable.

If you choose to use profiles as described above, the config profile can be indicated using one of the following command line flags:

--profile / -p

Taking the Core Data and App Service Configurable services as an examples:

• ./core-data starts the service using the default profile found locally
• ./app-service-configurable --profile=rules-engine starts the service using the rules-engine profile found locally

Seeding Configuration

When utilizing the centralized configuration management for the Edge Xpert micro services, it is necessary to seed the required configuration before starting the services. Each service has the built-in capability to perform this seeding operation. A service will use its local configuration file to initialize the structure and relevant values, and then overlay any environment variable override values as specified. The end result will be seeded into the configuration provider if such is being used.

In order for a service to seed/load the configuration to/from the configuration provider, use one of the following flags:

--configProvider / -cp

Again, taking the core-data service as an example:

./core-data -cp=keeper.http://localhost:59890 will start the service using configuration values found in the provider or seed them if they do not exist.

Configuration Structure

Configuration information is organized into a hierarchical structure allowing for a logical grouping of services, as well as versioning, beneath an "edgex" namespace at root level of the configuration tree. The root namespace separates Edge Xpert-related configuration information from other applications that may be using the same configuration provider. Below the root, sub-nodes facilitate grouping of device services, core/support/security services, app services, etc. As an example, the top-level nodes shown when one views the configuration registry might be as follows:

• edgex (root namespace)
  • core (core/support/security services)
  • devices (device services)
  • appservices (application services)

Versioning

Incorporating versioning into the configuration hierarchy looks like this.

• edgex (root namespace)
  • core (core/support/security services)
    • 2.0
      • core-command
      • core-data
      • core-metadata
      • support-notifications
      • support-scheduler
      • sys-mgmt-agent
    • 3.0
  • devices (device services)
    • 2.0
      • device-mqtt
      • device-virtual
      • device-modbus
    • 3.0
  • appservices (application services)
    • 2.0
      • app-rules-engine
    • 3.0

The versions shown correspond to major versions of the given services. For all minor/patch versions associated with a major version, the respective service keys live under the major version in configuration (such as 2.0). Changes to the configuration structure that may be required during the associated minor version development cycles can only be additive. That is, key names will not be removed or changed once set in a major version. Furthermore, sections of the configuration tree cannot be moved from one place to another. In this way, backward compatibility for the lifetime of the major version is maintained.

An advantage of grouping all minor/patch versions under a major version involves end-user configuration changes that need to be persisted during an upgrade. A service on startup will not overwrite existing configuration when it runs unless explicitly told to do so via the --overwrite / -o command line flag. Therefore if a user leaves their configuration provider running during an Edge Xpert upgrade any customization will be left in place. Environment variable overrides such as those supplied in the docker-compose for a given release will always override existing content in the configuration provider.

Configuration Provider

You can supply and manage configuration in a centralized manner by utilizing the -cp/--configProvider flag when starting a service. If the flag is provided and points to an application such as Core Keeper or HashiCorp's Consul, the service will bootstrap its configuration into the provider, if it doesn't exist. If configuration does already exist, it will load the content from the given location applying any environment variables overrides of which the service is aware.

Registry Provider

The registry refers to any platform you may use for service discovery. For the Edge Xpert reference implementation, the default provider for this responsibility is Core Keeper.

Introduction to Registry

The objective of the registry is to enable micro services to find and to communicate with each other. When each micro service starts up, it registers itself with the registry, and the registry continues checking its availability periodically via a specified health check endpoint. When one micro service needs to connect to another one, it connects to the registry to retrieve the available host name and port number of the target micro service and then invokes the target micro service. The following figure shows the basic flow.

Core Keeper is the default registry implementation and provides native features for service registration, service discovery, and health checking.

Physically, the "registry" and "configuration" management services are running on the same Core Keeper service node.

Edge Xpert Manager UI

In the future Edge Xpert 2.3.1 release, users can manage the configuration settings and examine the health status of each Edge Xpert service through the Service Control page of Edge Xpert Manager UI.