Applications Configuration¶

You can learn more about App Configurations in the Overview ⟶ Concepts page.

Creating App Configurations¶

The configuration variable names and values are defined in the Application's app.yaml file as configuration.

Configurations can also be optionally defined in the ui_schemas that provides a link to a JSON file containing all the information about how to display Configurations in the Kelvin UI.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

ui_schemas:
  configuration: "ui_schemas/configuration.json"

defaults:
  configuration:
    broker-ip: edge-mqtt-broker
    broker-port: 1883
    nest-example:
      nest1: 25
      next2: 30

For the configuration.json file you can define all the information for the Kelvin UI — the display label, helper text, input type, value constraints, and UI behaviour for each configuration field.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

{
  "type": "object",
  "properties": {
    "broker-ip": {
      "type": "string",
      "title": "Broker IP Address",
      "description": "Hostname or IP of the MQTT broker"
    },
    "broker-port": {
      "type": "number",
      "title": "Broker Port Number",
      "description": "Port number the MQTT broker listens on",
      "minimum": 0,
      "maximum": 65535
    },
    "api-key": {
      "type": "string",
      "title": "API Key",
      "description": "API key for authentication"
    }
  },
  "required": ["broker-ip", "broker-port"],
  "x-kelvin-ui": {
    "api-key": {
      "ui:widget": "password"
    },
    "ui:order": ["broker-ip", "broker-port", "api-key"]
  }
}

UI Components¶

Each configuration field is defined inside properties with a set of keys that control how it appears and behaves in the Kelvin UI:

"broker-port": {
  "type": "number",
  "title": "Broker Port Number",
  "description": "Port number the MQTT broker listens on",
  "minimum": 0,
  "maximum": 65535
}

Mandatory Fields¶

You can define which UI components must have a value before the user can save and apply the configuration. Any field listed in required will block saving if left empty.

"required": ["broker-ip", "broker-port"]

UI Features¶

Advanced Widgets¶

By default each component uses the standard input for its type — a text box for strings and numbers, a toggle for booleans, and so on. Advanced widgets let you override this with a more appropriate control.

To use an advanced widget, define the component under properties as normal, then add an entry for it under the x-kelvin-ui key specifying the widget to use. For example, to mask an API key as a password input:

"x-kelvin-ui": {
  "api-key": {
    "ui:widget": "password"
  }
}

Component Order¶

By default, components are displayed in the Kelvin UI in the order they are defined in configuration.json. You can override this by specifying a custom order under x-kelvin-ui:

"x-kelvin-ui": {
  "ui:order": ["broker-ip", "broker-port", "api-key"]
}

Any fields not included in ui:order are displayed after the listed fields in their original definition order.

Get Configuration Values¶

This is how to access the global configuration variables in a Application:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

import asyncio

from kelvin.application import KelvinApp


async def main() -> None:
    app = KelvinApp()
    await app.connect()

    (...)

    # Get IP
    ip = app.app_configuration["broker-ip"]

You can also get nested App Configuration values;

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

import asyncio

from kelvin.application import KelvinApp


async def main() -> None:
    app = KelvinApp()
    await app.connect()

    (...)

    # Get IP
    ip = app.app_configuration["nest-example"]["nest1"]

Updating Configuration Values¶

Developers and Administrators can update these values through the Kelvin API without needing to re-upload the complete Application or Kelvin UI.

To update the configuration values dynamically, you use the Kelvin API endpoint /workloads/{workload_name}/configurations/update.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

  curl -X 'POST' \
  "https://<url.kelvin.ai>/api/v4{workloads/<workload_name}/configurations/update" \
  -H "Authorization: Bearer <Your Current Token>" \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "configuration": {
    "recommendations": [
      {
        "description": "Water level increasing, higher pump speed will lead water level to return to optimal.",
        "setpoint": {
          "name": "speed_sp",
          "variation_factor": 0.1
        },
        "type": "increase_speed"
      },
      {
        "description": "Production gain possible after step test, with higher pump speed",
        "setpoint": {
          "name": "speed_sp",
          "variation_factor": 0.1
        },
        "type": "increase_speed"
      },
      {
        "description": "Erratic Torque detected at this speed previously, lower pump speed will reduce vibrations",
        "setpoint": {
          "name": "speed_sp",
          "variation_factor": -0.1
        },
        "type": "decrease_speed"
      },
      {
        "description": "Reducing Speed will save energy and keep production levels constant",
        "setpoint": {
          "name": "speed_sp",
          "variation_factor": -0.1
        },
        "type": "decrease_speed"
      },
      {
        "description": "Above max Drawdown, parameters stable",
        "setpoint": null,
        "type": "no_action"
      },
      {
        "description": "Casing Pressure Event Detected, no changes allowed",
        "setpoint": null,
        "type": "no_action"
      },
      {
        "description": "No action - monitoring",
        "setpoint": null,
        "type": "no_action"
      }
    ]
  }
}'

Upgrading Applications¶

When a Application is upgraded, Kelvin automatically propagates all matching App Configuration values from the previous version to the new version.

For any new App Configurations introduced in the upgraded Application version, the default values will initially applied to the Workload.