Groups

Advanced Configuration

In general, Group configuration through the User Console is sufficient for most use cases. However, in some cases you may want to configure groups programmatically using the Soracom API, or with the Soracom CLI in order to store configuration parameters in separate files.

As Group configuration options on the User Console are separated by namespace (Air, Beam, Funnel, Funk, Harvest, etc.), advanced configuration through the API or CLI is also separated into corresponding namespaces. When configuring multiple namespaces, each configuration must be made separately.

Configuration Structure

When a Group is created, it receives a configuration that looks something like this:

{
  "operatorId": "OP0012345678",
  "groupId": "abcdef00-0000-0000-0000-000012345678",
  "tags": {
    "name": "my-group"
  },
  "configuration": {
    "SoracomAir": {
      "binaryParserEnabled": false,
      "dnsServers": [],
      "useCustomDns": false,
      "useVpg": false,
      // ... additional Soracom Air configuration
    },
    "SoracomHarvest": {
      "enabled": false
    },
    // ... additional namespaces
  }
}

Each namespace (in this example, SoracomAir and SoracomHarvest) is an object that contains several key-value pairs which define the configuration settings of that namespace for the group.

Available Namespaces

Details of each namespace and possible values are described in the Advanced Configuration page of their respective corresponding service:

Programmatic Usage

Advanced configuration allows you to modify those key-value pairs using the Soracom API or Soracom CLI. However, rather than specifying the entire object, each key-value pair is passed in separately in an array, and in turn updated individually, so as not to affect other key-value pairs.

For example, in the sample above, to set and enable Custom DNS, we only need to modify the dnsServers and useCustomDns keys within the SoracomAir namespace. We can serialize the relevant keys and values into an array of objects, like so:

[
  {
    "key": "dnsServers",
    "value": [
      "8.8.8.8",
      "8.8.4.4"
    ]
  },
  {
    "key": "useCustomDns",
    "value": true
  }
]

Then we just pass this data into the SoracomAir namespace using the Soracom API or Soracom CLI, and our group configuration will be updated accordingly.

Soracom API

To access the Soracom API, first use the auth API to obtain an API Key and Token. Refer to the API Reference Guide for instructions on how to use the API Key and Token in API requests.

Then, use the putConfigurationParameters API with the SoracomAir namespace to update the group configuration:

curl -X PUT \
>  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
>  -H 'X-Soracom-Token: <MY-TOKEN>' \
>  -H 'Content-Type: application/json' \
>  -d '[
>        {
>          "key": "useCustomDns",
>          "value": true
>        },
>        {
>          "key": "dnsServers",
>          "value": [
>            "8.8.8.8",
>            "8.8.4.4"
>          ]
>        }
>      ]' \
>  https://g.api.soracom.io/v1/groups/<GROUP-ID>/configuration/SoracomAir

Soracom CLI

To use the Soracom CLI, you must first configure it to authenticate with your account information, authorization key, or SAM user credentials.

Then, run the following command while specifying the SoracomAir namespace to update the group configuration:

soracom groups put-config --group-id '<GROUP-ID>' --namespace 'SoracomAir' \
>  --body '[ {"key":"dnsServers","value":["8.8.8.8","8.8.4.4"]}, {"key":"useCustomDns","value":true} ]' --coverage-type g