Flogo Enterprise allows you to externalize app configuration using app properties, so that you can run the same app binary in different environments without making changes to your app. It integrates with configuration management systems such as Consul and AWS Systems Manager Parameter Store to get the values of app properties at runtime.
You can switch between configuration management systems without making changes to your app. You can do this by running the command to set the configuration-management-system-specific environment variable from the command line. Since the environment variables are set for the specific configuration management system, at runtime the app connects to that specific configuration management system to pull the values for the app properties.
Consul
The Consul provides a key/value store for managing app configuration externally. Flogo Enterprise allows you to fetch values for app properties from Consul and override them at runtime.
This document assumes that you have set up Consul and know how Consul is used to store service configuration. Refer to the Consul documentation for Consul specific information.
A Flogo app connects to the Consul server as its client by setting the environment variable,
FLOG_APPS_PROPS_CONSUL. At runtime, you must provide the Consul server endpoint in order for your app to connect to a Consul server. You have the option to enter the values for the Consul connection parameters either by typing in their values as JSON strings, or creating a file that contains the values and using the file as input.
Consul can be started with or without acl_token. If using ACL token, make sure to have ACL configured in Consul.
Using Consul with Flogo Enterprise
Below is a high-level workflow for using Consul with your Flogo app.
Prerequisites
You must have access to Consul before following this procedure. This document assumes that you have set up Consul and know how Consul is used to store service configuration. For information on Consul, refer to the Consul documentation.
At a high level, to use Consul to override app properties in your app (properties that were set in Flogo Enterprise), do the following:
Procedure
1. Export your app binary from Flogo Enterprise. Refer to Exporting and Importing an App for details on how to export the app.
2. Configure key/value pairs in Consul for the app properties whose values you want to override. At runtime, the app fetches these values from the Consul and uses them to replace their default values that were set in the app.
When setting up the Key in Consul, make sure that the Key name matches exactly with the corresponding app property name in the Application Properties dialog in Flogo Enterprise. If the property name does not match exactly, you will receive a warning message and the app will use the default value for the property that you configured in Flogo Enterprise.
3. Set the FLOGO_APP_PROPS_CONSUL environment variable to set the Consul server connection parameters.
See Setting the Consul Connection Parameters for details.
Consul Connection Parameters
Provide the following configuration information during runtime to connect to the Consul server.
Property Name Required Description
server_address Yes Address of the Consul server which could be run locally or elsewhere in the cloud.
key_prefix No Prefix to be prepended to the lookup key. This is
essentially the hierarchy that your app follows to get to the Key location in the Consul. This is helpful in case key hierarchy is not fixed and may change based on the environment during runtime. It is also helpful in case you want to switch to a different configuration service such as AWS param store.
Although it is a good idea to include the app name in the key_prefix, it is not required. key_prefix
can be any hierarchy that is meaningful to you.
As an example of a key_prefix, if you have an app property (for example, Message) which has two different values depending on the environment from which it is being accessed (for example, dev or test
environment), your <key_prefix> for the two values can be /dev/<APPNAME>/ and /test/
<APPNAME>/. At run time, the right value for
Message will be picked up depending on which
<key_prefix> you specify in the
FLOGO_APP_PROPS_CONSUL environment variable.
Hence, setting a <key_prefix> allows you to change the values of the app properties at runtime without modifying your app.
Property Name Required Description
acl_token No Use this parameter if you have key access protected
by ACL. Tokens specify which keys can be accessed from the Consul. You create the token on the ACL tab in Consul.
During runtime, if you use the acl_token
parameter, Key access to your app will be based on the token you specify.
To protect the token, encrypt the token for the
key_prefix where your Key resides and provide the encrypted value of that token by prefixing the
acl_token parameter with SECRET. For example,
"acl_token":
"SECRET:QZLOrtN3gOEpXgUuud6jprgo/WzLR7j +Twv28/4KCp7573snZWo+hGuQauuR2o/7TJ+ZLQ==". Note that the encrypted value follows the
key_prefix format.
Provide the encrypted value of the token as the SECRET. SECRETS get decrypted at runtime. To encrypt the token, you obtain the token from the Consul and encrypt it using the app binary by running the following command from the directory in which your app binary is located:
./<app_binary> --encryptsecret
<token_copied_from_Consul>
The command outputs the encrypted token which you can use as the SECRET.
Since special characters (such as `! | < > &
`) are shell command directives, if they appear in the token string, when
encrypting the token, you must use a back slash (\) to escape such characters.
insecure_connection No By default, set to False. Set to True if you want to connect to a secure Consul server without specifying client certificates. This should only be used in test environments.
Setting the Consul Connection Parameters
You set the values for app properties that you want to override by creating a Key/Value pair for each property in Consul. You can create a standalone property or a hierarchy that groups multiple related properties.
Prerequisites
This document assumes that you have access to Consul and are familiar with its use.
To create a standalone property (without hierarchy), you simply enter the property name as the name of the Key when creating the Key in Consul. To create a property within a hierarchy enter the hierarchy in the following format in the Create Key field in Consul: <key_prefix>/<key_name> where <key_prefix> is a meaningful string or hierarchy that serves as a path to the key in Consul and <key_name> is the name of the
app property whose value you want to override. For example, in dev/Timer/Message and test/Timer/
Message, dev/Timer and test/Timer are the <key_prefix> which could stand for the dev and test environments and Message is the key name. During runtime, you provide the <key_prefix> value which tells your app the location in Consul from where to access the property values.
The Key name in Consule must be identical to its counterpart in the Application Properties dialog in Flogo Enterprise. If the key name does not match exactly, you will receive a warning message and the app will use the default value that you configured for the property in Flogo Enterprise.
A single app property, for example Message, will be looked up by your app as either Message or
<key_prefix>/Message in Consul. An app property within a hierarchy such as x.y.z will be looked up as
x/y/z or <key_prefix>/x/y/z in Consul. Note that the dot in the hierarchy is represented by a forward slash (/) in Consul.
After you have configured the app properties in Consul, you need to set the environment variable,
FLOGO_APP_PROPS_CONSUL, with the Consul connection parameters in order for your app to connect to the Consul. When you set the environment variable, it triggers the app to run, which connects to the Consul using the Consul connection parameters you provided and pulls the app property values from the
key_prefix location you set by matching the app property name with the key_name. Hence, it is mandatory for the Key names to be identical to the app property names defined in the Application Properties dialog in Flogo Enterprise.
You can set the FLOGO_APP_PROPS_CONSUL environment variable either by directly entering the values as a JSON string on the command line or placing the properties in a file and using the file as input to the
FLOGO_APP_PROPS_CONSUL environment variable.
Entering the Consul Parameter Values as a JSON String
To enter the Consul parameters as a JSON string, enter the parameters as key/value pairs using the comma delimiter. The following examples illustrate how to set the values as JSON strings. You would run the following from the location where your app resides:
An example when not using security without tokens enabled:
FLOGO_APP_PROPS_CONSUL="{\"server_address\":\"http:\/\/127.0.0.1:8500\"}" ./Timer-darwin-amd64
where Timer-darwin-amd64 is the name of the app binary.
An example when tokens are enabled and app properties are within a hierarchy:
FLOGO_APP_PROPS_CONSUL="{"server_address":"http://127.0.0.1:8500","key_prefix":"/dev/
Timer","acl_token":"SECRET:b0UaK3bTyD9wN+ZJkmlKRmojhAv+"}"
where /dev/Timer is the path and SECRET is the encrypted value of the token obtained from the Consul.
This command directs your app to connect to the Consul at the server_address and pull the values for the properties from the Consul and run your app with those values.
Refer to Consul Connection Parameters section for a description of the parameters. Refer to Encrypting Password Values for details on how to encrypt a value.
Setting the Consul Parameter Values Using a File
To set the parameter values in a file, create a .json file, for example, consul_config.json containing the parameter values in key/value pairs. Here's an example:
{
"server_address": "http://127.0.0.1:32819", "key_prefix": "/dev/<APPNAME>/",
"acl_token": "SECRET:b0UaK3bTyD9wN+ZJkmlKRmojhAv+"
}
You would then run the following from the location where your app binary resides to set the
FLOGO_APP_PROPS_CONSUL environment variable. For example, to use the consul_config.json file from the example above, you would run:
FLOGO_APP_PROPS_CONSUL=consul_config.json ./<app_binary_name>
The command extracts the Consul server connection parameters from the file and connects to the Consul to pull the app properties values from the Consul and run your app with those values.
Consul properties can also be run using docker by passing the same arguments for the docker image of a binary app.