Variable mapping enables you to reuse templates more easily.
Variable mapping follows very specific rules that are easy to understand, and that can be applied in very specific locations within a system configuration template.
The very simplest variable mapping is a string literal that you define in-place where the variable is declared as follows:
Dollar sign character
$ at start of value indicates that a function will be called to fetch the value. There are many included functions as shown below.
You can also optionally add the name of the variable to the end of the line as shown below. If you do not add the name of the variable to the end of the line, then acm will infer that the variable name is the same inside the source as inside the destination.
$keys implies that the variable has the same name inside keys,yaml as in the system template file, while
$keys.variableName explicitly states to look for a variable named
variableName within keys.yaml, even if that name is different than the name that the system config gives to the same variable.
The same concept applies to the other mappings given below.
There are two external sources from which a system template can import values for specific fields in the system template.
These two external sources are
config.yaml. Secrets are generally imported from
keys.yaml, while non-secret values are generally imported from
Within instances and within foundations, top-level fields can have their values sourced from
config.yaml unless the field is named
Obviously, the controller, templateName, and emptyTemplateName fields must have values defined as strings within the system template for security reasons.
Preprocessor and Postprocessor also must be defined using strings in the system template only.
Also, the reason instanceName must be given a string value in the system template is that the variable mapping rules below should provide sufficient ability to customize the names of underlying cloud resources to avoid conflicts, for example appending the organization name to instance names if necessary.
The following table lists all the commands you can use to map values to variables within a system template.
Rules restrict where each of the commands can be used.
Do not assume that you can use these commands anywhere.
The rules for where each command can be used will be given separately later on in this document.
|String||A simple string value.|
|$keys||The value of a variable in keys.yaml with the same name as the variable that is requesting this value in the system template|
|$keys.variableName||The value of a variable in keys.yaml whose name in keys.yaml is
|$config||The value of a variable in config.yaml with the same name as the variable that is requesting this value in the system template|
|$config.variableName||The value of a variable in config.yaml whose name in config.yaml is
|$this.foundaton||The value of a field defined in the foundation block of the system template whose name is the same in the foundation block as in the location that is requesting it.|
|$this.foundation.variableName||The value of a field defined in the foundation block of the system template whose name is
|$this.instance||The value of a field defined in the same instance block of the system template whose name is the same in the instance block as in the location that is requesting it.|
|$this.instance.variableName||The value of a field defined in the same instance block of the system template whose name is
|$this.tags||The value of a field defined in the tags block of the system template whose name is the same in the tags block as in the location that is requesting it.|
|$this.tags.variableName||The value of a field defined in the tags block of the system template whose name is
|$this.foundationMapped||The value of a field in the mappedVariables sub-block of the foundation block whose name is the same in the mappedVariables sub-block of the foundation block as in the location that is requesting it.|
|$this.foundationMapped.variableName||The value of a field in the mappedVariables sub-block of a foundation block whose name is
|$customFunction.foundationOutput||The value of a field in the output variables of the basic building block that gets run when the
|$customFunction.foundstionOutput.variableName||The value of a field in the output variables of the basic building block that gets run when the
|$customFunction.addPath||Prepends the absolute path in front of a relative path string that the template gives as the value of a field named
|$customFunction.imageBuilderId||Assembles an Azure imageBuilderId. This can ONLY be used within the
|$customFunction.currentDateTime||Returns a string that represents the current dateTime.|
|$customFunction.mostRecentImage||Returns the name of the most recently created image with the name given by a field named
|$customFunction.addOrganization.root||Converts the value given by the system template’s organization field to lowercase and then appends that lowercase string to whatever string value was given in place of root in the command.|
|$customFunction.addDateTime.root||Appends the current dateTime to whatever string value was given in place of root in the command, and then converts to lowercase.|
|$customFunction.imageTemplateName||Assembles a suffix that includes “t” plus the current dateTime, and then appends that suffix to the value of the
The locations where variable mapping is allowed include:
organizationfield in the system template
tagsblock in the system template
Only certain of the variable mapping syntax is allowed in each location for reasons that will become obvious as you begin to use system templates.
A discussion of which rules apply to each location is as follows:
The top-level organization field in each system template is intended to be used to help you customize the unique names of cloud resources. The intention is for multiple groups within your enterprise to be able to create uniquely-named cloud resources with the same templates by using the
$customFunction.addOrganization.root function within mappedVariables sections of your system templates.
The organization field itself can receive its value using any of the following 3 syntax options:
<String> $config $config.variableName
Though you are welcome to use a string as the value in an organization field, your template can be more reusable if you pass the value of organization in from the config.yaml file using either
The top-level tags block in each system template is intended to be used to help you pass customized tags into cloud resources. These custom tags can enable your templates to be more reusable and for your underlying infrastructure to become more trackable.
Each of the fields in the tags block can receive its value using any of the following 3 syntax options:
<String> $config $config.variableName
Several of the controllers also allow fields with specific names to receive values mapped from config.yaml. These special mapping rules reflect the unique behavior of specific controllers.
A summary of the controllers that have special mapping rules is given in the following table.
|Controller||Variable Name||Section||Rules Allowed|
|terraform||Any of the variables that are legal within a backendVariables section.||backendVariables||
|arm||resourceGroupName, resourceGroupRegion. Also, the following 3 variables can either be in config.yaml or in keys.yaml depending on your preferences: subscriptionId, tenantId, clientId||foundation, image, serviceInstance||
|cloudformation||stackName, region (region only in foundation)||foundation, image, serviceInstance||
Note that the needs of other controllers can generally be handled within the mappedVariables sections of a template.
One example is that, if you use terraform to create Azure resources, you can customize resourcegroupName and resourceGroupRegion within the mappedVariables section. The only reason these are handled specially for the arm controller is that the arm controller uses these fields before and after running ARM templates.
Another example is that a terraform user can handle stackName and region in the mappedVariables section because the terraform controller does not have the special needs that the cloudformation controller has.
For custom controllers, we assume that you have the freedom to design your custom controllers in a way that would enable the mappedVariables sections to provide sufficient mapping of your variables.
Also, the tfbackendazrm controller requires the following things in order to work properly:
The most extensive variable mapping is allowed within mappedVariables blocks, which can be written to pull values from many locations within the same system template in addition to pulling external values from keys.yaml and config.yaml.
The following table summarizes the 22 types of syntax that you can use in each of the 4 mappedVariables blocks that are allowed in a system template.
|Syntax||foundation mappedVars||images instance mappedVars||serviceType sharedVars||serviceType instance mappedVars|
|$customFunction.imageBuilderId||No||Yes (ARM only)||No||No|