Use the sections that follow to provision and add Edge Nodes (formerly Edge iNodes) and Cloud Connectors (formerly Virtual iNodes).

Get node profile IDs for your organization

Start out by getting the node profile IDs for your organization. The node profile ID is a required parameter for the API call to provision a node. To get the list of node profile IDs available for your organization, make the following GET request:

curl -X GET \
  -H 'X-API-KEY:<your_api_key>' \
  -H "Content-type:application/json" \
  'https://<your_company>.manage.iotium.io/api/v2/profile' \
  | jq '.results | .[]' | jq '{profile_id: .id, name: .name}'

The response includes the IDs and names of all the node profiles available for your organization:

{
  "profile_id": "<your_edge_ra_profile_id>",
  "name": "Edge Remote Access"
}
{
  "profile_id": "<your_virtual_edge_profile_id>",
  "name": "Virtual Edge"
}
{
  "profile_id": "<your_virtual_profile_id>",
  "name": "Virtual"
}
{
  "profile_id": "<your_edge_profile_id>",
  "name": "Edge"
}

Add a public key to the Secure Edge Portal

Before provisioning an Edge Node or Virtual Edge Node, make sure you have an SSH public key for accessing the node console. If you don't have an SSH key pair, see Managing SSH key authentication for a node.

To add your SSH public key to the Secure Edge Portal, make the following POST request with the request body parameters:

Name	Type	Required or Optional	Description
name	string	Required	Name for your SSH key.
public_key	string	Required	Content of your SSH public key file.

curl -X POST \
  -H 'X-API-KEY:<your_api_key>' \
  -H "Content-type:application/json" \
  -d '{"name":"<your_ssh_key_name>", \
       "public_key":"<your_ssh_public_keyfile_content>"}' \
  'https://<your_company>.manage.iotium.io/api/v1/sshkey' \
  | jq '{ssh_key_id: .id, name: .name}'

The response includes the name and ID of the SSH key added to the Secure Edge Portal:

{
  "ssh_key_id": "<your_ssh_key_id>",
  "name": "<your_ssh_key_name>"
}

Get all public keys added for your organization

To get the list of all SSH keys added to the Secure Edge Portal for your organization, make the following GET request:

curl -X GET \
  -H 'X-API-KEY:<your_api_key>' \
  -H "Content-type:application/json"\
  'https://<your_company>.manage.iotium.io/api/v2/sshkey' \
  | jq '.results | .[]' | jq '{name: .name, ssh_key_id: .id}'

The response includes the names and IDs of all the SSH keys available for your organization:

{
  "name": "<your_ssh_key_1_name>",
  "ssh_key_id": "<your_ssh_key_1_id>"
}
{
  "name": "<your_ssh_key_2_name>"
  "ssh_key_id": "<your_ssh_key_2_id>"
}

Provision an Edge Node

Use information these sections to provision Edge Nodes.

Get available hardware serial numbers for your organization

Before provisioning an Edge Node, make sure the hardware serial number that matches the serial number label on your Edge Node is available in your Secure Edge Portal account. We've pre-populated the hardware serial numbers in the Secure Edge Portal for the hardware devices that we shipped to you.

To get the list of available hardware serial numbers for your organization, make the following GET request with the query string parameters:

Name	Type	Required or Optional	Description
assigned	boolean	Optional	Specify false to only get serial numbers that are available (i.e., not already provisioned).

curl -X GET \
  -H 'X-API-KEY:<your_api_key>' \
  -H "Content-type:application/json" \
  'https://<your_company>.manage.iotium.io/api/v2/pki?assigned=false' \
  |  jq '.results | .[]' | jq '{hardware_serial_number: .id}'

The response includes all the available (not already provisioned) hardware serial numbers for your organization:

{
  "hardware_serial_number": "<your_serial_number_1>"
}
{
  "hardware_serial_number": "<your_serial_number_2>"
}

Add an Edge Node

To add an Edge Node to the Secure Edge Portal, make the following POST request with the request body parameters:

Name	Type	Required or Optional	Description
name	string	Required	Name for your Edge Node.
profile_id	string	Required	Your Edge Node profile ID.
hardware_serial_number	string	Required	Serial Number that matches the serial number label on your hardware device.
ssh_keys	array	Required	IDs of SSH keys you want to associate with the node.
metadata	object	Optional	Custom attributes to specify as Label.
max_headless_time	integer	Optional	Standalone mode expiry time. Specify 0 (default) to disable the Standalone mode; any non-zero value to enable. Maximum is 365 days. See Using standalone mode in our Getting Started Guide.
stat_mode	string	Optional	By default, system and container resource utilization metrics are sent by the node to the Secure Edge Portal every minute. This is the FAST setting (default). Can set it to SLOW (five minutes) or OFF. See Using data saving mode in our Getting Started Guide.

curl -X POST \
  -H 'X-API-KEY:<your_api_key>' \
  -H "Content-type:application/json" \
  -d '{"name":"<your_edge_inode_name>", \
       "profile_id":"<your_edge_profile_id>", \
       "hardware_serial_number":"<your_serial_number_1>", \
       "ssh_keys":["<your_ssh_key_id>"]}' \
  'https://<your_company>.manage.iotium.io/api/v1/node' \
  | jq '{node_id: .id, name: .name}'

The response includes the name and ID of the Edge Node added to the Secure Edge Portal:

{
  "node_id": "<your_edge_inode_id>",
  "name": "<your_edge_inode_name>"
}

Add the local network to be protected by the Edge Node

To add the local network to be protected by this Edge Node, make the following POST request with the request body parameters:

Name	Type	Required or Optional	Description
name	string	Required	Name for your local network.
cidr	string	Required	This local network’s IP address range in the form of a CIDR block. In this example, the local network CIDR is set to 192.168.0.0/28.
reserved	object	Required	Internal reserved IP address range - range of IP addresses (at least one) reserved for node internal use. These addresses should be part of the same IP subnet as the network CIDR. In this example, the internal reserved IP address range is set to 192.168.0.1 - 192.168.0.14.
interface	string	Required	Interface connected to this local network; is set to eth1.
network_type	string	Required	Networking addressing for this network; is set to STATIC. The hosts in this network must be manually configured with static IP addresses.
node_id	string	Required	ID of the Edge Node that protects this local network.
metadata	object	Optional	Custom attributes to specify as Label.
gateway	string	Optional	IP address of the default gateway in your local network. If you don't specify a default gateway, the start IP address in the internal IP reserved address range is assumed to be the default gateway. In this example, the default gateway is not set; hence 192.168.0.1 (the start IP address in internal reserved address range) is implicitly set as the default gateway.
service_addressing	string	Optional	By default, the Edge Node assigns IP addresses to services on the network dynamically from the internal reserved IP address range. This is the AUTO setting (default). You can set it to MANUAL if you plan to configure the services manually with static IP addresses.

curl -X POST \
  -H 'X-API-KEY:<your_api_key>' \
  -H "Content-type:application/json" \
  -d '{"name":"<your_edge_inode_network_name>", \
       "cidr":"192.168.0.0/28", \
       "reserved":{"start":"192.168.0.1", "end":"192.168.0.14"}, \
       "interface":"eth1", \
       "network_type":"STATIC", \
       "node_id":"<your_edge_inode_id>"}' \
  'https://<your_company>.manage.iotium.io/api/v1/network' \
  | jq '{id:.id, config:.config}'

The response includes the ID and the configured settings of the local network:

{
  "id": "<your_edge_inode_network_id>",
  "config": {
    "network": {
      "cidr": "192.168.0.0/28",
      "netmask": "255.255.255.240",
      "gateway": "192.168.0.1",
      "reserved": [
        {
          "start": "192.168.0.1",
          "end": "192.168.0.14"
        }
      ],
      "vlan_id": 0,
      "service_addressing": "AUTO"
    }
  }
}

Set the default destination for local network to Edge Node's WAN network

Any traffic from the local network with a destination outside the local network (for example,
traffic going to the internet or LAN) is sent to the default destination. The default destination is not set by default, which results in dropping the traffic. You can set the default destination to the IP address of a gateway in the local network, or the Edge iNode's WAN network, which sends the traffic through the node uplink.

Before setting the default destination to the Edge Node's WAN network, you have to get the ID of the WAN network. To get the list of all networks in the Edge Node, make the following GET request with the query string parameters:

Name	Type	Required or Optional	Description
node_id	string	Optional	Your Edge Node ID.

curl -X GET \
  -H 'X-API-KEY:<your_api_key>' \
  -H "Content-type:application/json" \
  'https://<your_company>.manage.iotium.io/api/v2/network?node_id=<your_edge_inode_id>' \
  | jq '.results | .[]' | jq '{net_id:.id, name: .name}'

The response includes the name and ID of all networks in the Edge Node:

{
  "net_id": "<your_edge_inode_network_id>",
  "name": "<your_edge_inode_network_name>"
}
{
  "net_id": "<your_edge_wan_network_id>",
  "name": "WAN Network"
}

To set the default destination to the Edge Node's WAN network, make the following PUT request with the request body parameters:

Name	Type	Required or Optional	Description
routes	array	Required	Specify a route with destination 0.0.0.0/0 via your Edge iNode WAN network ID.

curl -X PUT \
  -H 'X-API-KEY:<your_api_key>' \
  -H "Content-type:application/json" \
  -d '{"routes":[{"destination":"0.0.0.0/0","via":"<your_edge_wan_network_id>"}]}' \
  'https://<your_company>.manage.iotium.io/api/v1/network/<your_edge_inode_network_id>' \
  | jq '{default_destination: .routes}'

The response includes the route setting for the default destination:

{
  "default_destination": [
    {
      "dest": "0.0.0.0/0",
      "via": "<your_edge_wan_network_id>"
    }
  ]
}

Provision a Cloud Connector

Use this section to provision and add a Cloud Connector (formerly Virtual iNode).

Adding a Cloud Connector

To add a Cloud Connector to the Secure Edge Portal, make the following POST request with the request body parameters:

Name	Type	Required or Optional	Description
name	string	Required	Name for your Cloud Connector .
profile_id	string	Required	Your Cloud Connector profile ID.
metadata	object	Optional	Custom attributes to specify as Label.
stat_mode	string	Optional	By default, system and container resource utilization metrics are sent by the Cloud Connector to the portal every minute. This is the FAST setting (default). Can set it to SLOW (five minutes) or OFF.

curl -X POST \
  -H 'X-API-KEY:<your_api_key>' \
  -H "Content-type:application/json" \
  -d '{"name":"<your_virtual_inode_name>", \
       "profile_id":"<your_virtual_profile_id>"}' \
  'https://<your_company>.manage.iotium.io/api/v1/node' \
  | jq '{node_id: .id, name: .name, networks: .networks}'

The response includes the name and ID of the Cloud Connector, and name and ID of all the networks in the Cloud Connector:

{
  "node_id": "<your_virtual_inode_id>",
  "name": "<your_virtual_inode_name>",
  "networks": [
    {
      "id": "<your_virtual_wan_network_id>",
      "name": "WAN Network"
    },
    {
      "id": "<your_virtual_default_network_id>",
      "name": "default"
    }
  ]
}

Download Cloud Connector security credentials

To complete provisioning the Cloud Connector, download its security credentials, which you’ll need when you launch the Cloud Connector. To download the security credentials, make the following GET request with the query string parameters:

Name	Type	Required or Optional	Description
download_type	string	Optional	Format of the Cloud Connector security credentials file to download. The default is yaml, used by AWS and Azure. For VMware, set it to iso.

curl -X GET \
  -H 'X-API-KEY:<your_api_key>' \
  -H "Content-type:application/json" \
  'https://<your_company>.manage.iotium.io/api/v1/node/<your_virtual_inode_id>/download' \
  -o "<your_virtual_inode_security_credentials_file>"

The response is the security credentials, written to the specified credentials file.

The credential file is downloadable only once and contains secure credentials to be used by the Cloud Connector. Save it in a safe place and don't share it with anyone. After creation of the Cloud Connector, you should destroy this credential file.