Skip to content

Provision

Overview

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

The Provision Microservice aims to support following use cases:

  • Add device profiles into core metadata service
  • Add devices into core metadata service
  • Add flows into Node-RED
  • Add data sources into Grafana
  • Add dashboard into Grafana

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

Feed Provision Data into the Provision Microservice

To provision other services through the Provision Microservice, 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 Microservice will look for provision data from the following folders:

Provision Target Default Folder
device profiles /provision-data/profiles
devices /provision-data/devices
Node-RED flow /provision-data/nodered
Grafana data sources /provision-data/grafana/datasources
Grafana dashboard /provision-data/grafana/dashboards

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

Default Configuration

By default, the Provision Microservice 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"

Just like other EdgeX microservices, the Provision Microservice uses the same common configuration. Provisions is the only unique configuration used by the Provision Microservice.

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

Property Description
PayloadFolderPath Specify the location of payload files to add devices. The Provision Microservice will examine each *.json file under this folder, then attempt to add devices through device client library.
Property Description
PayloadFolderPath Specify the location of payload files to add device profiles. The Provision Microservice will examine each *.json file under this folder, then attempt to add device profiles through device profile client library.
Property Description
Endpoint Specify the Rest endpoint to invoke
PayloadFolderPath Specify the location of payload files to send as request body when invoking the Rest endpoint. The Provision Microservice will examine each *.json file under this folder, then attempt to issue an HTTP request with payload to the designated endpoint.

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.

Note

The Provision Microservice will provision Rest targets in increasing order of <Target_Name>. For example, Provisions.Rest.POST.1_NodeRED_Flow will be executed prior to Provisions.Rest.POST.2_GRAFANA_DataSource.

Override Default Configuration

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

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 Microservice 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 Microservice will override the default configuration with /provision-data/configuration.toml.

Run the Provision Microservice through Edge Xpert CLI

As the Provision Microservice is designed to be a one-off service, it is recommended to run the Provision Microservice 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 Microservice:

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 Microservice:

  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 Microservice through edgexpert CLI:
    edgexpert run support-provision
    
Back to top