Skip to content

Adapter Hub Services

Adapter Hub Services can be deployed on an Adapter Hub to run pre-configured services on the hub. These services are deployed and managed using the UIP system.

Service Templates

A service template defines configuration and deployment parameters for Adapter Hub services. To deploy a service you must configure a template on the Adapter Hub Services page by adding a service with the Add Adapter Hub Service button. A working Adapter Hub should be configured before creating an Adapter Hub Service.

Service templates created and maintained by NEC can be selected from the Adapter Hub Service Templates dropdown. You can also create your own custom service template.

Each service template is a JSON representation of the service to be run combined with the configuration needed by the service.

Prior to updating or installing a new Adapter Hub Service, it is recommended to apply the latest security updates to Ubuntu for the Adapter Hub machine. On the Adapter Hub machine, run apt update and then apt upgrade to get the latest package versions including kernel updates.

Template Structure

The following adapter hub service template sections are supported. Each section is optional.

Properties

The properties section is a JSON object that defines name/value pairs. The name can be referenced in other sections of the template to set a value. This is useful to put commonly changed values in one place. The name and value must both be a string.

In the example provided below the properties section defines a "mongoServerPort" to be "27017". In the "mongodb" service's "ports" section the "hostPort" value is set using "${mongoServerPort}" so the effective value will be "27017" when the template is deployed.

"properties": {
  "mongoImage": "mongo:latest",
  "mongoServer": "exampleMongoServer",
  "mongoServerPort": 27017,
  "mongoDbUser": "mongoUser",
  "mongoDbPassword": "mongoPass"
}

If a service needs to know the client access URL of UIP it can be input using the system property ${nec.uipServerUrl}.

Network

The network section - used to configure settings for the adapter hub service's overlay network.

  • Each Adapter Hub Service has a Docker overlay network created for it.
  • By default Docker will assign a subnet to the overlay network (e.g. 10.0.2.0/24).
  • This section can override Docker to set the subnet to use (e.g. 10.200.15.0/24).
"network": {
  "subnet": "10.1.7.0/24"
}

Secrets

The secrets section allow configuring a Docker secret with data that can be accessed by one or more of the Docker services provisioned by the Adapter Hub Service.

Each secret has a name and content. The name is limited to 16 characters. The first character must be a-z or A-Z. The remaining characters must be a-z, A-Z, 0-9, or a dash. Secrets are referenced in the "services" section using their name.

The content can be specified one of these ways:

  • External - This is used if the secret is manually created on Adapter Hub system. Adapter Hub assumes the secret already exists and uses it with the name provided.
  • JSON - The JSON object provided in the template is saved UTF-8 encoded.
  • Text - The text provided in the template is saved UTF-8 encoded.
  • Base64 - The base64 string is base64 decoded and saved.

This example shows all four ways but only the first one defined is used. The order they are checked is the order given above.

"secrets": {
  "secret1": {
    "external": true,
    "json": {
      "prop1": 7,
      "prop2": "name",
      "thing": {
        "prop3": 18,
        "prop4": "something"
      }
    },
    "text": "This text is saved as the secret content",
    "base64": "IlRoaXMgdGV4dCBpcyBzYXZlZCBhcyB0aGUgc2VjcmV0IGNvbnRlbnQiIA0K"
  }
}

Volumes

The volumes section can be used to map a file or folder of the Adapter Hub host machine into services to persist data.

Each volume has a name. The name is limited to 16 characters. The first character must be a-z or A-Z. The remaining characters must be a-z, A-Z, 0-9, or a dash.

Each service can specify to use:

  • "volume": Map to a Docker volume folder. For "volume" types the volume must be specified in the "volumes" section.
  • "bind": Map directly to a file or folder on the host system.

In the following example:

  • "db-mongodb" is a Docker volume created when the Adapter Hub Service is deployed. It is deleted when the Adapter Hub Service is removed (undeployed).

  • "manual" is an external Docker volume that was manually created on the Adapter Hub host (docker volume create manual). Adapter Hub does not manage this volume.

"volumes": {
  "db-mongodata": {}
  "manual": {
    "external": true
  }
}

Services

The services section defines the Docker services that are created for an adapter hub service. Each Docker service runs from a Docker image and can use the secrets and volumes defined in the other sections.

  • Each service is defined as a name and a configuration object. The name is limited to 16 characters. The first character must be a-z or A-Z. The remaining characters must be a-z, A-Z, 0-9, or a dash.
  • When multiple Docker services are defined in one Adapter Hub service they can use the name to connect to each other if needed.
  • Each Docker service runs with a single replica.
  • The "image" is the only required field. All others are optional.
"services": {
  "myservice1": {
    "image": "docker.io/example/databaseimg:1.2.3",
    "imageCredentials": {
      "server": "https://index.docker.io/v1/",
      "username": "myusername",
      "password": "mypassword"
    },
    "command": [ "/bin/program", "--arg1", "arg2" ],
    "arguments": [ "--arg1", "arg2" ],
    "cpuLimit": "1.25",
    "memoryLimit": "1gb",
    "hostname": "myhostname",
    "user": "u1",
    "groups": [ "g1", "g2" ],
    "extraHosts": [
      "dnsname1:10.22.33.44",
      "dnsname2:10.22.33.55"
    ],
    "secrets": [
      {
          "source": "secret",
          "target": "/folder1/folder2/file.json"
      }
    ],
    "volumes": [
      {
        "type": "volume",
        "source": "dbdata",
        "target": "/data/db",
        "readonly": false
      },
      {
        "type": "bind",
        "source": "/host/path/to/use",
        "target": "/container/path/to/use",
        "readonly": true
      }
    ],
    "env": [
      {
        "name": "ENVNAME1",
        "value": "Value for env1"
      },
      {
        "name": "ENVNAME2",
        "value": "Value for env2"
      }
    ],
    "ports": [
      {
        "protocol": "tcp",
        "hostPort": 7000,
        "containerPort": 60091
      }
    ]
  }
}
  • "image": This is the Docker image to start the Docker service with.
  • "command": Used to override the command specified in the Docker image. If specified, this must be an array of strings.
  • "arguments": Used to specify arguments to the executed program. If specified, this must be an array of strings.
  • "cpuLimit": Limit how much CPU the service can use.
    • "1.00" specifies a single core
    • "0.25" specifies one quarter of a single core.
    • "3.00" specifies three cores.
  • "memoryLimit": Limits how much memory the service has access to. The value is in bytes but can use suffixes for megabytes ("m" or "mb") or gigabytes ("g" or "gb"). The suffix is case insensitive.
    • "1g" or "1GB" for one gigabyte of memory.
    • "512M" or "512mb" for 512 megabytes of memory.
  • "hostname": Set the hostname used in the the Docker container. By default the hostname is the Docker container id. Some programs may require a different hostname.
  • "user": Specify the user id the Docker service runs as. Overrides the value in the Docker image.
  • "groups": Specify groups the Docker service runs as. Overrides the value in the Docker image.
  • "extraHosts": Add extra host addresses in the Docker service. This is an array of strings of "name:address".
  • "secrets": Map secrets into the Docker service.
    • This is an array of objects. Each object has:
      • "source": The name of the secret defined in the secrets section of the template.
      • "target": The filename to use in the container. The file will have readonly access for all users (0444).
  • "volumes": Map volumes into the Docker service.
    • This is an array of objects. Each item has a "type":
      • "volume" - map a Docker volume to a folder in the Docker service.
        • "source": The name of the volume defined in the volumes section of the template.
        • "target": The folder to map the volume to in the Docker service.
        • "readonly": true = readonly access, false = readwrite access.
      • "bind" - map a file or folder on the host system to a file or folder in the Docker service.
        • "source": The file or folder on the host system to map from
        • "target": The file or folder in the Docker service to map to.
        • "readonly": true = readonly access, false = readwrite access.
  • "env" Sets environment variables for the Docker service.
    • This is an array of objects. Each object as:
      • "name": The name of the environment variable.
      • "value": The value of the environment variable.
  • "network": Specify the name of an pre-existing Docker network to connect to. In this example it is connected to the host network.
    • By default each Docker service is connected to a Docker network that is created for each adapter hub service. All Docker containers for the Docker services are attached to that Docker network which allows them to communicate with each other.
    • If a Docker service needs to be on a different Docker network it can be specified in the "network" setting. This is most useful for connecting to the host network. ("network": "host")
    • When a Docker network is specified the Docker service it not connected to the Docker network for the adapter hub service.
  • "ports": Specifies port mappings to allow external access to the Docker service.
    • This is an array of objects. Each object has:
      • "protocol": "tcp" or "udp"
      • "hostPort": The port number on the host to receive on (1 - 65535).
      • "containerPort": The port number in the Docker service to receive on (1 - 65535).
    • The hostPort and containerPort can contain a range of ports using a dash. The ranges must include the same number of ports and the range must be from low to high.

Example Adapter Hub Service Template for MongoDB

The following is an example of a MongoDB service template. The configuration "properties" at the top of the template can be modified as needed for the service's use case.

{
  "name": "MongoDB",
  "version": "0.1",
  "description": "MongoDB Service Example",
  "properties": {
      "mongoImage": "docker.io/mongo:latest",
      "mongoServer": "exampleMongoServer",
      "mongoServerPort": 27017,
      "mongoDbUser": "mongoUser",
      "mongoDbPassword": "mongoPass"
  },
  "volumes": {
    "db-mongodb": {}
  },
  "services": {
    "mongodb": {
      "image": "${mongoImage}",
      "hostname": "${mongoServer}",
      "env": [
        {
          "name": "MONGO_INITDB_ROOT_USERNAME",
          "value": "${mongoDbUser}"
        },
        {
          "name": "MONGO_INITDB_ROOT_PASSWORD",
          "value": "${mongoDbPassword}"
        }
      ],
      "ports": [
        {
          "protocol": "tcp",
          "hostPort": "${mongoServerPort}",
          "containerPort": 27017
        }
      ],
      "volumes": [
        {
          "type": "volume",
          "source": "db-mongodb",
          "target": "/data/db",
          "readonly": false
        }
      ]
    }
  }
}

Deploy Actions

The Deploy Actions control can be used to Deploy a service after its configuration has been saved. A service can also be Undeployed from an adapter hub when it is not needed anymore.

Deploy Status

The current deployment status of each adapter hub service is shown on the Adapter Hub Services page. This does not represent the state of the service - just the deployment.

  • Unknown - the adapter hub has not sent a deploy status.
  • Not Deployed - the service is not deployed to an adapter hub.
  • Success - the service was successfully deployed to an adapter hub.
  • Faulted - the service had an error while deploying the service on the adapter hub.

Service Status

The Adapter Hub Services page also displays the status of the individual services within an adapter hub service.

  • Unknown - the adapter hub has not sent a service status.
  • Stopped - The Docker services are not running.
  • Starting - Docker services for the Adapter Hub Service are running but some are still starting up (such as waiting for health checks to complete)
  • Started - All Docker services for the Adapter Hub Service are in running mode.
  • Faulted - At least one of the Docker services is not in running mode.