Environment Variables

This page shows us how to configure environment variables and use them in the FTX configuration.

How to configure

We are able to setup environment variables for the device in Balena and Azure Iot Edge.

Balena

There are two ways of configuring environment variables in balena.

Fleet Level

A fleet can have multiple devices so if you configure environment variables here, they apply to all devices in that fleet.

To configure, go to the fleet page and search for “Variables” on the sidebar.

Device Level

A device with environment variables will override fleet environment variables that share the same name.

To configure, go to the device page and search for “Device Variables” on the sidebar.

Azure Iot Edge

To configure environment variables, follow these steps:

  1. Find the iot hub resource in azure

  2. Click on “Devices” on the sidebar and select the relevant device.

  3. Click on “Set Modules”

  4. Click on the module named “factorytx”

  5. You should now be able to configure “Environment Variables” on this page.

MASE (aka factorytx-cloud)

To configure environment variables, follow these steps:

  1. Obtain credentials for the kubernetes cluster in which the MASE is deployed.

  2. Edit the ‘factorytx-config’ secret in the MASE’s namespace. For example:

kubectl --context aks-multi-tenant-prod-westus2-kube --namespace mase-demo-continuous edit secret factorytx-config

  1. In a text editor, add the variables to the yaml file in a section called stringData. For example:

    stringData:
      VARIABLE1: FOO
      VARIABLE2: BAR
    
  2. After saving your changes, delete the factorytx-0 pod. This will force it to be recreated with the new variables.

How to use environment variables in the config

The configuration supports bash-like environment variables for string values.

  • Values such as ${PASSWORD} or ${PREFIX}-name are allowed.

  • If you want to prevent the environment variables from showing up or being stored in the logs, add FTX_CREDS to the name. For example, something configured with ${FTX_CREDS_PASSWORD} or ${MY_VAR_FTX_CREDS_PW} will be hidden from the logs.

For example, your config can look like this:

{
  "data_receiver": [
    {
      "data_receiver_name": "${FACTORY} sql receiver",
      "protocol": "sql",
      "poll_interval": 10,
      "connections": [
        {
          "host": "${SQL_FACTORY_HOSTNAME}",
          "port": ${SQL_FACTORY_PORT},
          "username": "${SQL_FACTORY_USERNAME}",
          "password": "${SQL_FACTORY_PASSWORD}",
          "database_type": "postgresql",
          "database_name": "p1",
          "ssl": false
        }
      ...
    ]
}

How to use secrets from Azure KeyVault

The following need to be set in azure/balena env vars to facilitate this:

  • AZ_VAULT_URL (Azure KeyVault URL)

  • AZ_VAULT_TENANT_ID (Azure Tenant ID)

  • AZ_VAULT_USERNAME (ServicePrincipal Username)

  • AZ_VAULT_PASSWORD (ServicePrincipal Password)

The secrets will be prefixed with AZ_FTX_CREDS_ to prevent naming collisions, and will be injected into the config as environment variables. A list of the secrets that can be used in the configuration can be found in the Secrets link in the main FTX UI.

Changes to the vault can be refreshed by one of the following methods:

  1. Restart the FactoryTX container

  2. Pause and Start the FactoryTX Core service (can be done through the pause/start functionality in the UI)

  3. Navigating to the Secrets link in the main FTX UI