Network Connector by Tenant Configuration

During deployment of a tenant, the tenant operator may opt in to create a network connector. This Network Connector that is created and added to the tenant while spinning up the tenant itself is termed Pre-provisioned Network Connector. This functions as the default network connector for a specific tenant.

Features of Pre-provisioned Network Connector

The pre-provisioned network connector can be configured through the tenant configuration yaml file.
Only one pre-provisioned network connector can be deployed at one time.
Pre-provisioned network connector cannot be edited or deleted from the UI.
Pre-provisioned network connector will have the field "Created By" set to "Configuration"
Pre-provisioned network connector always has the auto-activation set to false.
Any error in the pre-provisioned network connector creation will cause the engine service to crash. The details of the error can be found in the logs of the engine service.

Pre-requisites

As a pre-requisite of setting up a Pre-provisioned Network Connector, the type of the network connector needs to be selected (Loriot and Chirpstack configuration are officially supported). Based on the type of network connector, it needs to be setup and its configuration needs to be . To setup the network connector refer to the IoT network connectors page.

Create a Pre-provisioned Network Connector
Step 1) Setup a Network Connector and get the configurations for it. Refer to the Iot Network Connectors page to setup the network connector based on its type. Do not create the network connector through thingshub UI.

Step 2) Get the network connector configurations and create the engine block for tenant configuration file.

A single network connector can be configured through the tenant’s configuration file. The following block defines the network connector:

YAML

engine:
  network_connector:
    name: {{ Network Connector's Name }}
    type: {{ One of supported type. Officially supported types: loriot, chirpstack }}
    config:
      // Config Specific to the network connector

Example Configurations

Loriot

YAML

engine:
  network_connector:
    name: Thingshub Configured Loriot NC
    type: loriot
    config:
      server: https://eu4pro.loriot.io
      app_id: BEX422
      api_key: ApiKeyThatIsConfiguredInLoriot

Chirpstack

YAML

engine:
  network_connector:
    name: Thingshub Configured Chirpstack NC
    type: chirpstack
    config:
      host: https://chirpstack.example.com:443
      app_id: BEX422
      api_key: ApiKeyThatIsConfiguredInChirpstack
      accept_insecure_tls: true

The configuration option is officially supported for loriot and chirpstack only.

Step 3) Add this block to the tennat configuration file.

YAML

global:
  domain: thingshub.iot.yourdomain.com
  name: example
  tenant_mode: thingshub
  
  whitelabeling:
    enabled: true
    ...
    
  log:
    level: debug
    
  metrics:
    enabled: true
    stackdriver_project_id: sample-metrics-project
    
  tracing:
    enabled: true
    sampler: probabilistic
    service_rate: 0.01
    api_rate: 0.01
    exporter: stackdriver
    
  stackdriver:
    project_id: sample-project
    google_application_credentials: |
      {
        "type": "service_account",
        ...
      }
    
  smtp:
    enabled: true
    address: smtp.example.com:1234
    user: notifications@example.com
    password: abcd1234
    host: smtp.example.com
    from: notifications@example.com

  image:
    enabled: true
    registry: eu.gcr.io
    repository: repo.example.com
    tag: develop
    credentials:
      username: john
      password: abcd1234

  security:
    service_key: <randomly-generated service key>
    admin_password: <randomly generated password>
	password_policy_regex: <user defined regular expression>
    password_help_text: <user defined help text to show on user form>

  sql:
    host: hostname.domain:port
    database: example
    user: example
    password: <the example role's passsword on the sql server>

  tls:
    enabled: true
    cert: |
      -----BEGIN CERTIFICATE-----
      ...
      -----END CERTIFICATE-----
      -----BEGIN CERTIFICATE-----
      ...
      -----END CERTIFICATE-----
      -----BEGIN CERTIFICATE-----
      ...
      -----END CERTIFICATE-----
    key: |
      ----BEGIN RSA PRIVATE KEY-----
      ...
      -----END RSA PRIVATE KEY-----
      
  backup:
    sql: enabled
    influx: enabled
    sftp:
      host: sftp.example.com
      port: 1234
      user: john
      password: abcd1234
      remote_dir: /incoming/private

  nats:
    nats_url: nats://nats.example.com:4222
    is_cluster_wide: true
    user: john
    password: abcd1234

registry:
  master:
    url: https://drivers.example.com
    api_key: abcd1234

iam:
  rules:
    permissions: |
      rules:
        - policy: privilege
          pattern: devices:create
        - policy: deny
          pattern: devices:update

visualizer:
  image_renderer:
    enabled: true

  smtp:
    enabled: true
    host: smtp.example.com:587
    user: notifications@example.com
    password: abcd1234
    skip_verify: true
    from:
      address: notifications@example.com
      name: thingsHub

nats:
  enabled: false

influxdb:
  enabled: true

postgresql:
  enabled: true
  fullnameOverride: postgresql
  postgresqlUsername: jane
  postgresqlPassword: abcd1234
  postgresqlDatabase: thingshub
  persistence:
    enabled: true

backup-cron:
  enabled: true
  
engine:
  network_connector:
    name: Thingshub Configured Loriot NC
    type: loriot
    config:
      server: https://eu4pro.loriot.io
      app_id: BEX422
      api_key: ApiKeyThatIsConfiguredInLoriot

Step 4) Deploy the tenant and check the if engine service is up and running. If thingshub can not connect to the pre-provisioned network connector, it will shutdown, proving the logs in the service logs.

Results

After the successful creation of a pre-provisioned network connector, it will be listed in the network connectors list of the tenant settings page in the tenant UI. It will have the value Configuration in the Created by column.

Testing and Next steps

You can now see your pre-provisioned network connector functioning by connecting your devices via this network connection with the thingsHub. You can either add a new device now and connect it during this process, or connect an existing device on the device’s Network tab.

Runtime Behavior

When a network connector is configured through the tenant’s configuration file:

If the network connector of the provided type already exists:
- It is updated with the provided configuration
  - If it can’t be updated:
    - The engine service crashes with an appropriate error message
If the network connector of the provided type does not exist:
- If the network connector of a different type is configured previously
  - It is deleted
    - If it can’t be deleted:
      - The engine service crashes with an appropriate error message
  - The new network connector is then created
    - If it can’t be created:
      - The engine service crashes with an appropriate error message
- If no network connector is configured previously:
  - The new network connector is created
    - If it can’t be created:
      - The engine service crashes with an appropriate error message

Please check the error details on the logs to identify which of the above scenarios is causing the engine service to crash, and resolve it accordingly.