Developer Portal

Container / Software Gateway Installation Guide

The UG-CLOUD Software Gateway is typically installed using containers, via container platforms like Docker or Kubernetes (K8s). This guide walks you through the steps to install on either of those platforms, though in both cases engagement with Mapped support (reachable via [email protected] or support.mapped.com) will be necessary to complete the installation.

If you do not have a container platform, but do want to use the software gateway, alternate options may be available. Contact support to discuss further.

System Requirements

The Mapped UG-CLOUD software was designed to be very lightweight. However, every deployment environment is different. In order to avoid surprises, it is recommended that you have the following minimum system resources available before installing:

1Gi of Memory
1 CPU Core / VCore
A Persistent Volume of 500MB

These should only be considered the minimum requirements, we do not recommend setting these as the maximum limits.

Network Access

Please also confirm with your network team that port 443 to the following FQDNs is accessible from the host machine before running the Mapped UG container:

Legacy FQDNs for existing gateway installations

datadog-api.mapped.com
datadog-process.mapped.com
datadog-logs.mapped.com
hosted.mender.io
hosted-mender-artifacts.s3.amazonaws.com
mapped-iot-prod.azure-devices.net
global.azure-devices-provisioning.net
*.balena-cloud.com

Current FQDNs for new gateway installations

api.mgmt.edge.mapped.com
api.telemetry.edge.mapped.com
cloudlink.mgmt.edge.mapped.com
d2c.edge.mapped.com
logs.mgmt.edge.mapped.com
logs.telemetry.edge.mapped.com
api.mapped.com
c2d.edge.mapped.com
process.telemetry.edge.mapped.com
registry.mgmt.edge.mapped.com
s3.mgmt.edge.mapped.com
delta.mgmt.edge.mapped.com
mapped-iot-prod.azure-devices.net
global.azure-devices-provisioning.net

Docker Deployment

The following instructions will walk through the process to install the Mapped UG-CLOUD Gateway on the Docker platform. Prior to starting the steps, please ensure you've been in contact with Mapped support and received the Docker token for your organization. If you do not have this token yet, you'll only be able to proceed through the first couple steps before getting stuck.

Installation Procedure

Create and Register a Mapped Personal Access Token

The first step to get the gateway installed on Docker is the creation of a Mapped Personal Access Token (PAT) via the Mapped Developer Portal.

Select the following permissions and click Generate Access Token at the bottom:

CONNECTOR_READWRITE_ALL
GATEWAY_READWRITE_ALL

Make sure to copy the PAT somewhere safe. It will only be displayed once!

Open your preferred text editor on the designated system where Docker will run and and input the following text as the content:

Copy1
MAPPED_API_KEY=<YOUR_PAT>

Replacing <YOUR_PAT> with the Mapped PAT generated in the previous step. Save the file as mapped-ug.env in the same directory where Docker will run.

Login to Docker Hub

The Mapped UG container image is hosted on a private Docker Hub repository. In order for your local Docker instance to access the software, you must first login to Docker Hub with a unique token generated for your organization. This is the token mentioned at the very first step of these instructions, and needs to be provided to you by Mapped support. Once you have the token, go to the command line / terminal and enter:

Copy1
docker login -u mappedops

You'll receive an immediate authorization prompt - enter the token provided via a Mapped support here and hit Enter / Return.

Next, confirm that the login was successful by running the following command:

Copy1
docker pull mapped/ugagent:latest

The first time the command is executed, you should see output similar to this:

Copy1
2
3
4
5
6
latest: Pulling from mapped/ugagent
4f4fb700ef54: Pull complete
b7f2631f226a: Pull complete
ed3520b491aa: Pull complete
c109b122292c: Pull complete
...

Create Data Volumes

Mapped UG-CLOUD requires two read/write data volumes:

mapped-identity-volume Used to store the public/private key pair generated during the first boot. Your Mapped PAT is used to securely upload the public key to the Mapped Cloud, while the private key never leaves the edge and is used to encrypt observations before they are sent over MQTT.

mapped-data-volume Used to store system logs, state store and other operational runtime data.

To create these volumes, please execute these commands on the Docker host:

Copy1
2
docker volume create mapped-identity-volume
docker volume create mapped-data-volume

Start Mapped UG-CLOUD

The following command will instruct Docker to download and start the Mapped UG software:

Copy1
docker run --restart always --network host --name mappedug --cpus 1 --memory-reservation 524288000 --env-file mapped-ug.env --volume mapped-identity-volume:/identity --volume mapped-data-volume:/data --pull=always mapped/ugagent

Here's a breakdown of the Docker options used above:

Option	Description
--restart	Automatically start the container when Docker initializes and restart on any failure
--network	Use the host's networking directly. This is required to avoid NAT issues
--name	Provides a friendly name for the container, making it easier to identify and target with commands
--cpus	Allocate 1 CPU to this container
--memory-reservation	Ensures that the system has at least 500mb of RAM available
--env-file	Load the mapped-ug.env file that was created above into the container's environment
--volume	Mounts volumes into the container
--pull=always	Check for a newer container image on every start

The command above starts Mapped UG in "attached mode". This should only be used for initial validation. Once you confirm that the container started successfully, press Control-C to quit the container and instead start Mapped UG as a service like so (you may need to remove a previous container first, if you get a message stating the container already exists):

Copy1
docker run --restart always --network host --name mappedug --cpus 1 --memory-reservation 524288000 --env-file mapped-ug.env --volume mapped-identity-volume:/identity --volume mapped-data-volume:/data --pull=always --detach mapped/ugagent

Kubernetes Deployment

The following instructions will walk through the process to install the Mapped UG-CLOUD Gateway on the Kubernetes platform. Prior to starting the steps, please ensure you've been in contact with Mapped support and received the following two files:

Name	Description
mapped-regcred.json	Contains a token used to pull Mapped UG container image
manifest.yaml	The Kubernetes manifest file that will be used to deploy Mapped UG

These files will need to be on the same system you're using to deploy (same host as kubectl). If you do not have these files yet, you won't be able to progress very far in the installation. Note that the provided manifest assumes the default storage class - feel free to replace/adjust to meet your specific needs.

Installation Procedure

Create Namespace

This step is optional but is a good practice in a multi-vendor environment. If you would like to deploy the Mapped container in a different namespace, please replace the value in each kubectl command using the -n command line switch.

Copy1
kubectl create namespace mapped

Create Image Pull Secret

Mount the credentials to the Mapped container registry. The mapped-regcred.json file received from Mapped support should look something like this:

Copy1
2
3
4
5
6
7
{
  "auths": {
    "https://index.docker.io/v1/": {
      "auth": "xxxxxxxxxxxxxxxxx"
    }
  }
}

Use the following command to create a secret containing the credentials:

Copy1
2
3
4
kubectl create secret generic mapped-regcred \
    --from-file=.dockerconfigjson=mapped-regcred.json \
    --type=kubernetes.io/dockerconfigjson \
    -n mapped

Create and Register a Mapped Personal Access Token

Next you will create a Mapped Personal Access Token (PAT) via the Mapped Developer Portal.

Select the following permissions and click Generate Access Token at the bottom:

CONNECTOR_READWRITE_ALL
GATEWAY_READWRITE_ALL

Make sure to copy the PAT somewhere safe. It will only be displayed once!

Last, mount the PAT as a Kubernetes secret:

Copy1
2
3
kubectl create secret generic mapped-gateway-pat \
  --from-literal=MAPPED_API_KEY='THE_PERSONAL_ACCESS_TOKEN' \
  -n mapped

Start Mapped UG-CLOUD

Deploy the Mapped UG-CLOUD software gateway using the following command:

Copy1
kubectl apply -f ./manifest.yaml

Example Manifest

Copy1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: mapped-data-volume-claim
  namespace: mapped
spec:
  accessModes:ReadWriteOnce
  storageClassName: default
  resources:
    requests:
      storage: 30Gi
apiVersion: apps/v1
kind: Deployment
metadata:
  name: mapped-ug
  namespace: mapped
spec:
  replicas: 1
  selector:
    matchLabels:
      app: mapped-ug
  revisionHistoryLimit: 0
  template:
    metadata:
      labels:
        app: mapped-ug
    spec:
      hostNetwork: true
      imagePullSecrets:
	name: mapped-regcred
      containers: 
	name: mapped-ug
        	imagePullPolicy: Always
        	image: mapped/ugagent:latest
        resources:
          requests:
            memory: "1Gi"
            cpu: "100m"
          limits:
            memory: "4Gi"
            cpu: "400m"
        env:
	name: UG_REDIS_ENABLE
            value: "true"
	name: REDIS_ADDR
            value: "localhost:6379"
        envFrom:
	secretRef:
            name: mapped-gateway-pat
        volumeMounts:
	name: mapped-identity-volume
            mountPath: /identity/
	name: mapped-data-volume
            mountPath: /data/
      volumes:
	name: mapped-identity-volume
        secret:
          	secretName: mapped-identity
	name: mapped-data-volume
        persistentVolumeClaim:
          claimName: mapped-data-volume-claim

View Secure Edge Deployment

View Secure Edge is a third party product that enables the deployment of various IoT solutions in a plug-and-play fashion. Mapped is one of the solution providers available, which means if you have Secure Edge setup for your building, installing Mapped is very simple.

Installation Procedure

Create and Register a Mapped Personal Access Token

The first step is the creation of a Mapped Personal Access Token (PAT) via the Mapped Developer Portal.

Select the following permissions and click Generate Access Token at the bottom:

CONNECTOR_READWRITE_ALL
GATEWAY_READWRITE_ALL

Make sure to copy the PAT somewhere safe. It will only be displayed once!

Create a Pull Secret in Secure Edge

Next step is to create a Pull Secret inside of Secure Edge - you'll need some prebuilt JSON for this step which will be provided by Mapped Support; it will contain an encoded Docker token needed for the deployment. That JSON will look similar to this:

Copy1
2
3
4
5
6
7
{
  "auths": {
    "https://index.docker.io/v1/": {
      "auth": "12345GVkb3BzOjM1OTIzNzQ3LWEyMDgtNGRmYi1hYmQzLTUyOTQ1MTMxMABCDE== "
    }
  }
}

Once you have that JSON, log in to Secure Edge, expand Services on the left hand menu and click "Service Secrets". From that window, you should see a plus sign icon (+) near the top right; click that icon, and you'll be in the "Add Pull Secret" window.

Give the secret a name, like "Mapped Secret", and then put the JSON with the encoded token in the field for Docker Config. Click Create and this step is complete.

Create the Mapped Service in Secure Edge

While still in Secure Edge, click iNodes on the left hand menu then select "All iNodes". Select the iNode where you want Mapped to run by clicking its name. This will open a new window with several panels - the one we're concerned with is the one at the bottom right with several sub tabs like "Network", "Services", "Images" and so on.

Click "Services" and then click the plus

iNodes -> all iNodes, click services, then plus sign icon (+) to the right. This will open a list of possible services you can install, including Mapped. Click the icon for Mapped and you'll be brought to a setup screen.

Provide a name, which could just be "Mapped", then pick the network - the available options are predefined by your network team, and one of them should be the BMS network. Click Next at the bottom right to move on to the screen for credentials.

The "Pull Secret" field should have a listing for the one we set up earlier, so select that here, and then add the Mapped PAT generated in the very first install step in the following field. When you click Submit, you're all done! Gateway will be running and scanning for devices and points.