DS Service Registry Admin Guide

Configuration

Service Registry is configured using a JSON configuration file, path to which is provided to the SC via -conf flag. By default, the service looks for a configuration file at: conf/service-catalog.json

All configuration fields (except for arrays of objects) can be overridden using environment variables. Below are few examples:

  • SC_STORAGE_TYPE=leveldb
  • SC_MQTT_CLIENT_BROKERURI=tcp://iot.linksmart.eu:1883
  • SC_MQTT_CLIENT_REGTOPICS="a/b,a/c"
  • ❌ SC_MQTT_ADDITIONALCLIENTS setting array of objects is not supported with environment variables

Configuration File

A sample configuration file is available at service-catalog.json.

{
  "description": "string",
  "dnssdEnabled": "boolean",
  "storage": {
    "type": "string",
    "dsn": "string"
  },
  "http" : {
    "bindAddr": "string",
    "bindPort": "int"
  }, 
  "mqtt":{
    "client": {
        "disabled": "bool",
        "brokerID": "string",
        "brokerURI":"string",
        "regTopics": ["string"],
        "willTopics": ["string"],
        "qos": "int",
        "username": "",
        "password": ""
    },
    "additionalClients": [],
    "commonRegTopics":  ["string"],
    "commonWillTopics": ["string"],
    "topicPrefix": "string"
  },
  "auth": {
        "enabled": "bool",
        "provider": "string",
        "providerURL": "string",
        "serviceID": "string",
        "basicEnabled": "bool",
        "authorization": {}
    }
}

where

  • description is a human-readable description for the SC
  • dnssdEnabled is a flag enabling DNS-SD advertisement of the catalog on the network
  • storage is the configuration of the storage backend
    • type is the type of the backend (supported backends are memory and leveldb)
    • dsn is the Data Source Name for storage backend (ignored for memory, “ file:///path/to/ldb” for leveldb)
  • http is the configuration of HTTP API
    • bindAddr is the bind address which the server listens on
    • bindPort is the bind port
  • mqtt is the configuration of MQTT API
    • client is the configuration for the main MQTT client
      • disabled is a boolean flag disabling/enabling the mqtt client
      • brokerID is the service ID of the broker (Optional)
      • brokerURI is the URL of the broker
      • regTopics is an array of topics that the client should subscribe to for addition/update of services
        • Example: "regTopics": ["topic/reg/+"]
        • While publishing a service registration message over this topic, ‘+’ should be replaced by id of the service to be added/updated. id passed in message payload takes precedence over id in the topic
          • E.g., mosquitto_pub -h localhost -p 1883 -t 'topic/reg/custom_id1' -f ./service_object.json
      • willTopics is an array of will topics that the client should subscribe to for removal of services (Optional in case TTL is used for registration)
        • Example: "willTopics": ["topic/dereg/+"]
        • While publishing a service deregistration message over this topic, ‘+’ should be replaced by id of the service to be removed
          • E.g., mosquitto_pub -h localhost -p 1883 -t 'topic/dereg/custom_id1' -m 'something'
      • qos is the MQTT Quality of Service (QoS) for all reg and will topics
      • username is username for MQTT client
      • password is the password for MQTT client
    • additionalClients is an array of additional brokers objects.
    • commonRegTopics is an array of topics that all clients should subscribe to for addition/update of services (Optional)
      • Example: same as the example for ‘regTopics’ above
    • commonWillTopics is an array of will topic that the client should subscribe to for removal of services (Optional in case commonRegTopics not used or TTL is used for registration)
      • Example: same as the example for ‘willTopics’ above
    • **topicPrefix** is the string describing the prefix of service announcement topics
  • auth is the Authentication configuration
    • enabled is a boolean flag enabling/disabling the authentication
    • provider is the name of a supported auth provider
    • providerURL is the URL of the auth provider endpoint
    • serviceID is the ID of the service in the authentication provider (used for validating auth tokens provided by the clients)
    • basicEnabled is a boolean flag enabling/disabling the Basic Authentication
    • authorization - optional, see authorization configuation

Deployment

Docker

docker run -p 8082:8082 linksmart/sc

The index of the REST API should now be accessible at: http://localhost:8082

Custom configuration

For a configuration file located on host at $(pwd)/conf/service-catalog.json

docker run -p 8082:8082 --name serviceregistry -d -v $(pwd)/conf:/conf -v $(pwd)/data:/data --restart=unless-stopped  linksmart/sc:latest -conf /conf/service-catalog.json

Binary Distributions

Available for released versions and for multiple platforms: https://github.com/linksmart/service-catalog/releases

Download and run:

./service-catalog-<os-arch> --help

On Linux and macOS, it needs to have execution permission. E.g. chmod +x service-catalog-<os-arch>

Program Profiling

The program profiling can be enabled by setting --profile argument. Once enabled, an HTTP runtime profiling server will bind to the given port.

The profile can be analysed with go pprof tool. E.g:

go tool pprof <service-catalog-executable-path> http://<host>:<profile-port>/debug/pprof/<profile_type>

Add --http localhost:<port> to get an interactive web UI locally at the given port.

The list of profile types are available here: https://golang.org/pkg/runtime/pprof/#Profile

For example, to get the CPU profile for 60 seconds:

go tool pprof --http localhost:8888 --seconds 60 ./service-catalog-linux-amd64 http://example.com:6060/debug/pprof/profile

For more information regarding pprof, visit: https://blog.golang.org/profiling-go-programs

Next

Last updated on 05.08.2020