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:

Find the iot hub resource in azure
Click on “Devices” on the sidebar and select the relevant device.
Click on “Set Modules”
Click on the module named “factorytx”
You should now be able to configure “Environment Variables” on this page.

MASE (aka factorytx-cloud)¶

To configure environment variables, follow these steps:

Obtain credentials for the kubernetes cluster in which the MASE is deployed.
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

In a text editor, add the variables to the yaml file in a section called stringData. For example:
stringData: VARIABLE1: FOO VARIABLE2: BAR
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:

Refresh the JSON configuration editor or make any change to the config
Pause and Start the FactoryTX Core service (can be done through the pause/start functionality in the UI)
Navigating to the Secrets link in the main FTX UI
Restart the FactoryTX container

Additionally, the secrets cached on the device will not be cleared, only updated when successfully pulled from KeyVault. They will persist until the container is recreated or the volume is cleared. This is to avoid FTX interruptions due to network issues or Azure KeyVault downtime. This also means that if secrets access is removed from the SP, the secrets will still be available on the device.