Using Configuration Variables Templates with Microservices Runtime

Microservices Runtime provides the ability to create a Docker image from an installed and configured instance of Microservices Runtime. The Docker image contains the Microservices Runtime application including packages and Microservices Runtime assets such as ports, JMS connection aliases, keystores, and JDBC pools. Because you can execute multiple Docker containers from a single Docker image, a Docker image for a Microservices Runtime instance might be used across development, testing, and production environments. While the microservices and accompanying artifacts are the same across the running containers and stages, configuration information might be different. For example, user name and password combinations, proxy server host and port, remote server host and port, and global variable values might be different across different instances of running Docker containers. While a Microservices Runtime stores configuration information inside its file system and therefore inside any Docker image created from the Microservices Runtime, some configuration information can be externalized and passed to the Microservices Runtime at startup. With Microservices Runtime you can accomplish this through use of a configuration variables template and environment variables.

A configuration variables template contains configuration properties that map to properties on the Microservices Runtime. The property values can be set externally in the template and then passed to a Microservices Runtime when it starts up. As part of the startup process, Microservices Runtime loads the information from the configuration variables template and replaces the configuration information stored in the file system.

By externalizing configuration information, a single Docker image created for a Microservices Runtime can be used across multiple environments, including different stages of the production cycle. For example, you might use different templates for specific environments such as testing versus production. Or you might use the same template for all environments but use environment variables to vary the configuration in each environment.

While the primary purpose of configuration variables is to extend the usefulness of single Microservices Runtime image by making it possible to reuse a single Docker image across multiple stages in the production cycle, you can also use configuration variables templates in situations where other deployment options are too heavyweight.

A configuration variables template is a properties file that contains configuration data as a series of key-value pairs where the key name reflects the asset and particular asset property for which you can supply a value. For example, jndi.DEFAULT_IS_JNDI_PROVIDER.providerURL=nsp://myHost:9000 indicates that the JNDI provider alias named DEFAULT_IS_JNDI_PROVIDER has a URL of nsp://myHost:9000.

When a configuration variables template is generated from an existing Microservices Runtime, the template is populated with configuration data from the Microservices Runtime instance. The template content reflects the Microservices Runtime configuration at the time Microservices Runtime generated the template. For example, the configuration variables template lists a key-value pair for each defined global variable.

The generated configuration variables template does not contain key-value pairs for all of configuration information for Microservices Runtime.

Below is an excerpt of a configuration variables template:

#Sample Generated Template 
#Wed Jun 20 17:13:40 EDT 2018 
email.WmRoot.myEmailPort.host=exchange 
email.WmRoot.myEmailPort.password={AES}VphDydln9QyvLIGf+FASxw\=\= 
email.WmRoot.myEmailPort.server_port=7891 
email.WmRoot.myEmailPort.user=user123ispasswordexpirationsettings. 
jms.DEFAULT_IS_JMS_CONNECTION.clientID=DEFAULT_IS_JMS_CLIENT 
jndi.DEFAULT_IS_JNDI_PROVIDER.providerURL=nsp\://localhost\:9000 
settings.watt.server.compile=C\:\\IS_10-3\\June6\\jvm\\jvm\\bin\\javac - 
classpath {0} -d {1} {2} 
settings.watt.ssh.jsch.ciphers=aes256-ctr,aes192- 
ctr,arcfour,arcfour128,arcfour256,aes128-ctr,aes128-cbc,3des-ctr,3des- 
cbc,blowfish-cbc,aes192-cbc,aes256-cbc

Only specific values can be supplied via the template for an asset. For example, for a JMS connection alias a configuration variables template lists a key-value pair for the clientID, user, and password properties. The template omits key-value pairs for all other properties.

In the template, each property name follows this pattern: assetType.assetName.propertyName=value where assetType is the type of administrative asset, assetName is the name given to the asset such as an alias name, and propertyName is the asset property for which you can set a value.

For example, following are key-value pairs for a global variable named serverhost, a global variable named serverport, the DEFAULT_IS_JMS_CONNECTION connection alias, and the JDBC pool alias named webMPool:

globalvariable.serverhost.value=server123.example.com 
globalvariable.serverport.value=5555 
jms.DEFAULT_IS_JMS_CONNECTION.clientID=DEFAULT_IS_JMS_CLIENT 
jms.DEFAULT_IS_JMS_CONNECTION.password=encryptedValue 
jms.DEFAULT_IS_JMS_CONNECTION.user= userA 
jdbc.webMPool.dbURL=jdbc:wm:oracle://testserver:1521;serviceName=webm 
jdbc.webMPool.password={AES}CszC/Yl1w1XqEK0B17RFucP0kgMHNt823RUU6ad39tw\= 
jdbc.webMPool.userid=jdbcuserTest

To change the assigned values in a configuration variables template, use a text editor to open the template and make changes. Any value you specify for a property must adhere to the requirements for that property. For example, the global variable value cannot exceed 255 characters. For passwords or other types of values that should be encrypted, Microservices Runtime Administrator provides a utility to encrypt a value. Microservices Runtime Administrator uses password handles and the Password-Based Encryption technology installed with Microservices Runtime for encryption.

You can also add an asset by editing the configuration variables template. Not all assets for which you can edit configuration in a configuration variables template can be created via a template.

As an alternative to “hard coding” a value for a property in a template, you can specify an environment variable (ENV variable) as the value of a property in the configuration variables template. The following line specifies that the JDBC pool URL for the alias webMPool should be set to the value of the environment variable named JDBC_URL: jdbc.webMPool.dbURL=$env{JDBC_URL}

If you opt to use an ENV variable as a value for configuration variables, make sure that you specify the values for ENV variables defined in the configuration variables template. Refer to the Docker documentation or the documentation for your container orchestration tool for more information about how to specify the ENV variables for Docker containers.

Microservices Runtime applies a configuration variables template at startup. When Microservices Runtime starts, either in a Docker container or on-premises, Microservices Runtime looks for a configuration variables template in the following locations in the specified order.

1. The location identified by the SAG_IS_CONFIG_PROPERTIES environment variable.
2. Integration Server_directory /instances/instanceName/application.properties
3. Integration Server_directory /application.properties

Once Microservices Runtime locates a template, Microservices Runtime does not look for a template in any remaining locations.

Microservices Runtime processes the template, updating the configuration information in Microservices Runtime with the information in the template. While processing the template, Microservices Runtime writes log messages to the logs/configurationvariables.log to reflect the progress of the variable substitution. When updating is complete, Microservices Runtime proceeds with startup.

Because a configuration variables template can be used with a Microservices Runtime running in a Docker container or an on-premises Microservices Runtime, there are multiple approaches to using the template. The approach you select determines the template file name, the template file location, whether the template file is part of a Docker image, and how to start the Microservices Runtime so that Microservices Runtime applies the template.

To help determine which approach to use, decide the following:

• Will the Microservices Runtime with which you want to use the template run in a Docker container or on-premises (outside of a Docker contaier)?
• If Microservices Runtime runs in a Docker container, do you want to include the template as part of the Docker image or external to the image?
• Do you want to hard code values for variables in the template or use environment (ENV) variables to specify some or all values?

The answers to the above questions help determine which approach to use, which in turn, determines the files that you need to create, where you place the configuration variables template, the name of the file, and how to start the Microservices Runtime so that Microservices Runtime applies the template values.

The following table describes the possible approaches for using a configuration variables template with Microservices Runtime

Preparing a configuration variables template for use with Microservices Runtime consists of a series of general tasks. The order in which you complete these tasks may be affected by whether you intend to use the template with a Microservices Runtime in a Docker container or an on-premises Microservices Runtime.

The following table identifies the general tasks that you complete for preparing a configuration variables template for use with Microservices Runtime.

For some asset types, you can add assets to Microservices Runtime by adding key-value pairs to the configuration variables template that is applied at start up. Any asset that you create must meet the naming requirements for the asset. An incorrectly configured asset can cause Microservices Runtime start up fail or result in failure during later server operations.

To add an asset to a configuration variables template, follow the procedure and guidelines in Editing a Configuration Variables Template.

The following list identifies the asset types for which you can create an asset through application of a configuration variables template:

• Consul
• Email port
• File polling port
• Global variable
• JDBC pool alias
• JMS connection alias
• JNDI provider alias
• Keystore alias
• LDAP configuration
• Proxy server alias
• Remote server alias
• SFTP server alias
• SFTP user alias
• Truststore alias
• Universal Messaging connection alias (webMethods messaging)
• User account

When the configuration variables template is ready for use with a Microservices Runtime, you need to save the template to a place accessible to Microservices Runtime upon startup. Where you place the configuration variables template file and any accompanying environment variables list depends on whether you are using the template with Microservices Runtime running in a Docker container or on-premises.

You can place the template file in one of the following locations.

• The location to be identified by the SAG_IS_CONFIG_PROPERTIES environment variable.
• Integration Server_directory /instances/instanceName

  For this option, the configuration variables template must be a file named application.properties. If you use this location with Microservices Runtime running in a Docker container, create the Docker image after completing the template and placing it here.

• Integration Server_directory

  For this option, the configuration variables template must be a file named application.properties. If you use this location with Microservices Runtime running in a Docker container, create the Docker image after completing the template and placing it here.

For more details about where to place the configuration variables template and an environment variables list, if you are using one, see Approaches for Using a Configuration Variables Template with Microservices Runtime.

When running a Microservices Runtime image in a Docker container, you can specify the configuration variables template and/or environment (ENV) variables in the docker run command.

docker run -d --name IS_Default -p 5555 -p 9999 
-v /opt/softwareag/customApplication.properties:/opt/softwareag/customApplication.properties 
-e SAG_IS_CONFIG_PROPERTIES=/opt/softwareag/customApplication.properties 
is:microPkg

docker run -d --name IS_Default -p 5555 -p 9999 
-e SAG_IS_CONFIG_PROPERTIES=/opt/softwareag/customApplication.properties 
-v /opt/softwareag/customApplication.properties:/opt/softwareag/customApplication.properties 
--env-file env.list is:microPkg

When Microservices Runtime applies the configuration variables template at startup, Microservices Runtime has not yet initialized the journal logger which is used for the server log. For this reason, Microservices Runtime uses a separate logging capability for logging Microservices Runtime messages related to processing a configuration variables template. The configuration variables log contains messages about the operations, warnings, and errors that occur while Microservices Runtime applies the template.

Below is an excerpt from the configuration variables log:

2018-06-18 15:34:10 EDT [ISS.0028.0016I] Configuration variables template file 
found at C:\SoftwareAG\IntegrationServer\application.properties will be used for 
processing. 
2018-06-18 15:34:12 EDT [ISS.0028.0007I] Changed property in 
C:\SoftwareAG\IntegrationServer\instances\default\config\server.cnf. Old value: 
localhost. New value: localhost,127.0.0.1. Configuration variable key: 
watt.net.proxySkipList. 
2018-06-18 15:34:12 EDT [ISS.0028.0017W] Encryptor is creating password handle 
because the given password handle 
wm.is.admin.WSEndpoint.message.CONSUMER.HTTPS.ws_cons_https does not exist in 
the password store. 
2018-06-18 15:34:12 EDT [ISS.0028.0008I] Set password in secure password store. 
Password handle: wm.is.admin.WSEndpoint.message.CONSUMER.HTTPS.ws_cons_https 
2018-06-18 15:34:12 EDT [ISS.0028.0017W] Encryptor is creating password handle 
because the given password handle 
wm.is.admin.WSEndpoint.transport.CONSUMER.HTTPS.ws_cons_https does not exist in the password store. 
2018-06-18 15:34:12 EDT [ISS.0028.0008I] Set password in secure password store. 
Password handle: wm.is.admin.WSEndpoint.transport.CONSUMER.HTTPS.ws_cons_https 
2018-06-18 15:34:12 EDT [ISS.0028.0008I] Set password in secure password store. 
Password handle: wm.is.admin.WSEndpoint.message.CONSUMER.HTTPS.ws_cons_https 
2018-06-18 15:34:12 EDT [ISS.0028.0007I] Changed property in 
C:\SoftwareAG\IntegrationServer\instances\default\config\kerberos.cnf. Old 
value: . New value:

Each log message is prefixed with the time stamp and a message ID that includes the logging facility (0028), message code, and the severity level. The severity levels are described in the following table:

Microservices Runtime does not support filtering the contents of the configuration variables log based on logging level. By default, the configuration variables log includes all messages with a severity of Information or higher. To include debug messages in the log, you must set the SAG_IS_CONFIG_VARIABLES_DEBUG environment variable to true at startup.

Microservices Runtime writes the configuration variables log messages to the console (STDOUT) and/or to the location: Integration Server_directory /instances/instanceName/logs/configurationvariables.log. A Microservices Runtime running in a Docker container always writes the configuration variables log messages to both locations.

When starting an on-premises Microservices Runtime from the command line, you can specify the destination for the configuration variables log using the -log switch.

The following table identifies the command line options for specifying the destination of the configuration variables log file.

Starting Microservices Runtime from the command line is the same as starting Integration Server from the command line.

For information about starting Integration Server from the command line, see webMethods Integration Server Administrator’s Guide.

For information about starting Integration Server from the command line, see Starting a Server Instance from the Command Prompt .

Microservices Runtime does not preserve the contents of the configurations variable log across restarts. When running on-premises Microservices Runtime overwrites the existing configurations variable log upon startup.