Using Environment Variables with Configuration Merge

In the previous sections, Useful Update Parameters in Automated Deployment and Useful Action Parameters in Automated Deployment, the different examples of configuration merge files completely specified the needed parameters for all of the shown update and action parameters. However, instead of specifying the exact values for the parameters in the merge files, you can substitute environment variables into your merge files. You specify the environment variables in an environment variable file, and then specify that file in the merge file. This approach can have added flexibility; for example, a merge file with the same set of update and action parameters can be used on different systems with different environment variable files to perform the same changes during the merge but with system-specific values.

Merge File and Environment Variable File Requirements

When performing a configuration merge using an environment variable file to specify environment variables, the merge file and environment variable file should fulfill the following conditions:

The merge file and environment variable file must be in the same directory.
The merge file and environment variable file should be in the same directory as the configuration parameter file (CPF).
The merge file and environment variable file should have the same file attributes as the CPF.
On UNIX®, the merge file and environment variable file should have the same owner and group permissions as the CPF.

Environment variables are case-sensitive on UNIX® and not case-sensitive on Windows.

Environment Variable File

The environment variable file must contain a series of key-value pairs which specify the environment variables and their values. The environment variable file can also contain comments, starting either with # or //. Here is an example of an environment variable file, merge.env; the following examples refer to this example environment variable file.

//Example merge.env file
Application=SALES
Namespace=SALES
Directory=/USER/SALES
//Set up global buffers
globals=0,0,2048,0,0,0
//Set up routine buffers
routines=routines=100

Specifying an Environment Variable File in a Merge File

A merge file can specify an environment variable file in either the [config] or [Actions] sections of the merge file or in both sections. Moreover, it does not matter which section of the merge file specifies the environment variable file definition; the environment variables apply to the entire merge file. When specifying the environment variable file in the merge file, the syntax is slightly different depending on the section; the following example shows the different syntax with the example environment variable file merge.env.

[config]
ConfigEnv=/iris/merge.env

[Actions]
ConfigEnv:File=/iris/merge.env

If you do not specify a directory for the environment variable file, then it uses the directory where the merge file is located; for example, ConfigEnv=merge.env uses the /iris/merge.env file.

You can also specify multiple different environment variable files in your merge file as follows.

[Actions]
ConfigEnv:File=/iris/merge.env
ConfigEnv:File=/iris/merge1.env

During the merge, InterSystems IRIS® data platform processes the environment variable files in the order they appear in the merge file. If the different environment variable files specify the same environment variable, the value of that environment variable in the merge file comes from the most recently processed environment variable file. For example, if the merge.env file specifies Path=/iris/data and the merge1.env file specifies Path=/iris/data1, then the value of the Path environment variable used in the preceding merge file is /iris/data1.

The previous examples specify the environment variable file directly in the merge file. You can also specify the environment variable file itself as an environment variable defined in the user process. When you use an environment variable defined in the user process, the substitution cannot come from another environment variable file. If a process environment variable defines an environment variable file, such as MergeEnvFile=/iris/merge.env, then you can use it in the merge file to define an environment variable file as follows.

[config]
ConfigEnv=${MergeEnvFile}

Note:

This is the only case where a process-defined environment variable can be used for substitution in the merge file. All other substitutions must come from the environment variable file definitions.

Specifying Environment Variables in a Merge File

After specifying the environment variable file or files in the merge file, you must specify the environment variables you want for substitution. To substitute environment variables in the merge file, use the ${EnvironmentVariable} syntax. For example, to use the merge.env file in the preceding section to specify the global buffer sizes, the merge file looks like the following.

[config]
ConfigEnv=/iris/merge.env
globals=${globals}

The previous merge file using the ${globals} environment variable results in the following merge file.

[config]
globals=0,0,2048,0,0,0

You can also perform a substitution on any value on the line. For example, to use the merge.env file in the preceding section to specify the routine buffer sizes, the merge file looks like the following.

[config]
ConfigEnv=/iris/merge.env
${routines}

This results in the following merge file.

[config]
routines=100

In addition to performing a substitution on any value on the line, an environment variable itself may reference another environment variable, for example.

Path=/USER/${dir}
dir=SALES

To illustrate the flexibility using environment variables with configuration merge, suppose you wanted to:

Configure your global buffers and Write Image Journal directory.
Configure your primary and alternate Journal directories.
Create two databases with resources, roles, and a namespace using those databases as its default databases.
Create a resource and role for an application.

The following example shows how you could do this using two environment variable files, config.env and actions.env, and a single merge file merge.cpf. This example assumes that the process executing the merge command has the following process environment variable already set ConfigEnv=/iris/config.env.

//config.env file
Customer=CustomerABC
InstallDir=/install
AppDir=/appdir
JournalDir=/journal
WijDir=/wij
Globals8K=4096
Globals64K=1024
JournalDirectory=${JournalDir}/primary/
AltJournalDirectory=${JournalDir}/alternate/

//actions.env file
Application=sales
ApplicationDirectory=${AppDir}/${Application}

//merge.cpf file with [config], [Journal] and [Actions] sections
[config]
ConfigEnv=${ConfigEnv}
//Configure the global buffers
globals=0,0,${Globals8K},0,0,${Globals64K}

[Journal]
//Configure the Journal directories
AlternateDirectory=${AltJournalDirectory}
CurrentDirectory=${JournalDirectory}

[Actions]
ConfigEnv:File=actions.env
//Create resources for the databases and application
CreateResource:Name=%DB_${Application}-RTN,Description=The ${Application}-RTN database
CreateResource:Name=%DB_${Application}-GBL,Description=The ${Application}-GBL database
CreateResource:Name=%DB_${Application},Description=${Application} application

//Create corresponding roles for each resource
CreateRole:Name=%DB_${Application}-RTN,Resources=%DB_${Application}-RTN:RW
CreateRole:Name=%DB_${Application}-GBL,Resources=%DB_${Application}-GBL:RW
CreateRole:Name=%DB_${Application},Resources=%DB_${Application}:RW

// Define global and routine databases for the application
CreateDatabase:Name=${Application}-GBL,Directory=${AppDir}/${Application}-gbl,Resource=%DB_${Application}-GBL
CreateDatabase:Name=${Application}-RTN,Directory=${AppDir}/${Application}-rtn,Resource=%DB_${Application}-RTN
// Create the namespace
CreateNamespace:Name=${Customer}-${Application},Globals=${Application}-GBL,Routines=${Application}-RTN

Environment Variable Substitution and Auditing

When InterSystems IRIS executes a configuration merge, InterSystems IRIS writes the contents of the merge file to the audit database. Merge commands are associated with the %System/%System/ConfigurationChange system audit event, see About System Audit Events for more information. When you use environment variables in the merge file, the audit entry associated with the merge command displays both the original line of the merge file with no environment variables substituted (as a comment) and the resulting line with the substitution. It also displays the contents of the environment variables.

Caution:

Because the audit entry displays the contents of the environment variables, do not specify secrets as the values for environment variables.

The following shows an example of what the audit entry’s event data could look like for performing a merge with the merge file actions.txt containing both a [config] and [Actions] section, where a process environment variable specifies the environment variable file and config.env defines the environment variables.

Merge file /iris/actions.txt into /iris/iris.cpf

Environment Variables
ABC=TestResource
DEF=TestResource1
GHI=CreateResource
JKL=${MNO}
MNO=7
PERMS=RW

[config]
//ConfigEnv=${ConfigEnv}
ConfigEnv=/iris/config.env
//MaxServers=${JKL}
MaxServers=7

[Actions]
//ModifyResource:Name=${ABC},PublicPermission=${PERMS}
ModifyResource:Name=TestResource,PublicPermission=RW
//CreateResource:Name=${DEF},PublicPermission=R
CreateResource:Name=TestResource1,PublicPermission=R
//${GHI}:Name=TestResource3,PublicPermission=${PERMS}
CreateResource:Name=TestResource3,PublicPermission=RW