Defining Configurable Variables
Ballerina supports configurability through the configurable, module-level variables.
Initialising Configurable Variables
configurable keyword is used to declare a configurable variable. The initialization of configurable variables can be done in the ways below.
A configurable variable that is defined with
?as the initializer expression mandates a value to be specified through the configuration.
configurable string host = ?;
If a configurable variable is defined with any other initializer expression, the configuration of that variable is optional. The value provided in the initializer can be overridden by a value specified through the configuration.
configurable string host = “0.0.0.0”;
The values of configurable variables would always be a subtype of
anydata. A configurable variable is implicitly
final and cannot be assigned outside the declaration. The static type of the configurable variable is implicitly
readonly. Therefore, it can always be referenced within an isolated function.
Providing Values to Configurable Variables
Ballerina supports providing the values for configurable variables through configuration files, command-line arguments, and environment variables. The precedence order for retrieving configurable values is as follows.
Tip: For more information on the methods below, see Providing Values to Configurable Variables.
Using Command-Line Arguments
The module information of the configurable variable can be provided with command-line argument. For more information, see Providing Configurable Values Through Command-Line Arguments.
Using Configuration Files
The values can be provided through configuration files in the TOML(v0.4) format. The file location can be set through an environment variable with the name
BAL_CONFIG_FILES. It is possible to specify multiple configuration files using the OS-specific separator. The file precedence order will be as specified in the environment variable. If an environment variable is not specified, it is located in the current working directory with the file name
Using Environment Variables
The values can be provided through an environment variable with the name
BAL_CONFIG_DATA in which the content is expected to be in the TOML(v0.4) format.
Securing Sensitive Data Using Configurable Variables
Configuration values containing passwords or secrets should not be passed with the normal configuration.
Such sensitive data can be passed to runtime using a different TOML file, and you can prioritize it higher than the normal configuration by prefixing the file path in the
BAL_CONFIG_FILES environment variable.
The configuration of sensitive data can be handled at the deployment of the Ballerina program.
For example, in a Kubernetes environment, a Kubernetes secret can be used with a pod as files in a volume mounted on one or more of its containers or as container environment variables. The TOML file, which contains the sensitive data can be stored as a secret resource in Kubernetes and can be placed in a volume mount when running a pod. The file path can be specified via an environment variable.
Trying it Out
For example on defining configurable variables in a Ballerina program, see Trying it Out.