Provision

Overview

The Provision Microservice is a one-off service to provision other Edge Xpert services, such as Core Metadata, Node-RED, and Grafana.

It aims to support following use cases:

• Add device profiles into Core Metadata
• Add devices into Core Metadata
• Add flows into Node-RED
• Add data sources into Grafana
• Add dashboard into Grafana

In addition to above typical use cases, the Provision can be configured to invoke REST APIs of other services.

Feed Provision Data into the Provision

To provision other services through the Provision, users have to prepare provision data, such as payload files for new device profiles creation or new devices creation. Provision data must be in the correct format, otherwise error will occur during the provisioning process. By default, the Provision will look for provision data from the following folders:

Users will have to bind mount provision data to these default folders when running the Provision.

Default Configuration

By default, the Provision uses the following configuration:

[Writable]
LogLevel = "INFO"

[Service]
HealthCheckInterval = "10s"
Host = "localhost"
Port = 59866
ServerBindAddr = "" # Leave blank so default to Host value unless different value is needed.
StartupMsg = "This is the EdgeX Provision Microservice"
MaxResultCount = 50000
MaxRequestSize = 0 # Not curently used. Defines the maximum size of http request body in bytes
RequestTimeout = "5s"

[Registry]
Host = "localhost"
Port = 8500
Type = "consul"

[Clients]
[Clients.core-metadata]
  Protocol = "http"
  Host = "localhost"
  Port = 59881
[Clients.support-scheduler]
  Protocol = "http"
  Host = "localhost"
  Port = 59861
[Clients.support-notifications]
  Protocol = "http"
  Host = "localhost"
  Port = 59860

[Provisions]
[Provisions.Clients.ADD]
  [Provisions.Clients.ADD.Device]
  PayloadFolderPath = "/provision-data/devices"
  [Provisions.Clients.ADD.DeviceProfile]
  PayloadFolderPath = "/provision-data/profiles"
[Provisions.Rest]
  [Provisions.Rest.POST.1_NodeRED_Flow]
  Endpoint = "http://nodered:1880/flows"
  PayloadFolderPath = "/provision-data/nodered"
  [Provisions.Rest.POST.2_GRAFANA_DataSource]
  Endpoint = "http://admin:admin@grafana:3000/api/datasources"
  PayloadFolderPath = "/provision-data/grafana/datasources"
  [Provisions.Rest.POST.3_GRAFANA_Dashboard]
  Endpoint = "http://admin:admin@grafana:3000/api/dashboards/db"
  PayloadFolderPath = "/provision-data/grafana/dashboards"

Similar to other EdgeX microservices, the Provision uses the same common configuration. Provisions is the only unique configuration used by the Provision.

The Provision will look for provision targets from Provisions configuration, and there are two types of provision targets: Clients and Rest. And it also supports two Clients provision targets: Add.Device for device creation and Add.DeviceProfile for device profile creation.

A Rest provision target is defined in following format: Provisions.Rest.<HTTP_Operation>.<Target_Name>, where <HTTP_Operation> can be valid HTTP operations, such as GET, POST, or PATCH, and <Target_Name> is the unique name to identify the target.

Override Default Configuration

There are two ways to override the default configuration of the Provision.

Override Specific Configuration with Environment Variables

To override specific configuration settings, you can specify environment variables inside compose files to do the configuration overrides. For example, if the Provision should look for the payload files to add devices from /devices, users can update support-provision service of /etc/edgexpert/docker-compose.yml as shown below:

support-provision:
    image: iotechsys/${EDGEXPERT_IMAGE_REPO}-support-provision:${EDGEXPERT_IMAGE_VERSION}
    container_name: support-provision
    read_only: true
    security_opt:
      - no-new-privileges:true
    networks:
      edgex-network:
        aliases:
          - edgex-support-provision
    user: 2002:2001
    environment:
      <<: *common-variables
      SERVICE_HOST: support-provision
      EDGEX_STARTUP_DURATION: 60
      PROVISIONS_CLIENTS_ADD_DEVICE_PAYLOADFOLDERPATH: /devices
    logging: *default-logging

Override with a configuration.toml

You can use your preferred configuration and override the default file. To do so, copy the default configuration file as the template and then revise the template per your needs. For example, if you only want to POST a serviceA's REST API at http://serviceA/api/resourceA, you can revise the provision target inside the configuration as shown below:

[Writable]
LogLevel = "INFO"

[Service]
HealthCheckInterval = "10s"
Host = "localhost"
Port = 59866
ServerBindAddr = "" # Leave blank so default to Host value unless different value is needed.
StartupMsg = "This is the EdgeX Provision Microservice"
MaxResultCount = 50000
MaxRequestSize = 0 # Not curently used. Defines the maximum size of http request body in bytes
RequestTimeout = "5s"

[Registry]
Host = "localhost"
Port = 8500
Type = "consul"

[Clients]
  [Clients.core-metadata]
  Protocol = "http"
  Host = "localhost"
  Port = 59881

[Provisions]
  [Provisions.Rest]
    [Provisions.Rest.POST.ResourceA]
    Endpoint = "http://serviceA/api/resourceA"
    PayloadFolderPath = "/provision-data/resourceA"

Once the configuration is ready and saved as configuration.toml, users have to bind mount the toml file to /provision-data/confgiuration.toml, and the Provision will override the default configuration with /provision-data/configuration.toml.

Run the Provision through Edge Xpert CLI

As the Provision is designed to be a one-off service, it is recommended to run the it through the edgexpert run utility.

The below example assumes you have prepared provision data in the following folder structure on your host machine:

• /home/tester/provision-data/devices - host *.json payload files for devices creation
• /home/tester/provision-data/profiles - host *.json payload files for device profiles creation
• /home/tester/provision-data/nodered - host *.json payload files for importing Node-RED flows
• /home/tester/provision-data/grafana/datasources - host *.json payload files for Grafana datasource creation
• /home/tester/provision-data/grafana/dashboard - host *.json payload files for Grafana dashboard creation

Run the following command to launch the Provision:

edgexpert run --volume=/home/tester/provision-data/devices:/provision-data/devices --volume=/home/tester/provision-data/profiles:/provision-data/profiles --volume=/home/tester/provision-data/nodered:/provision-data/nodered --volume=/home/tester/provision-data/grafana/datasources:/provision-data/grafana/datasources --volume=/home/tester/provision-data/grafana/dashboard:/provision-data/grafana/dashboard support-provision 

If you have several provision targets, to eliminate the usage of --volume options, you can follow the instructions below to run the Provision:

1. Prepare your provision data in the same folder structure as the PayloadFolderPath of each provision target defined in the configuration.
2. Revise /etc/edgexpert/docker-compose.yml by uncommenting volume section under support-provision service:

   #uncomment following volume binding and specify environment variable PROVISION_DATA to the directory hosting
   #provision-data on the host, e.g. export PROVISION_DATA=/provision/data/on/your/host/
   volumes:
     - ${PROVISION_DATA}:/provision-data
   

3. Specify an environment variable PROVISION_DATA to the parent folder of your provision data, e.g. /home/tester/provision-data

   export PROVISION_DATA=/home/tester/provision-data
   

4. Run the Provision through edgexpert CLI:

   edgexpert run support-provision