Agile Cloud Institute

Variable Mapping Syntax for the Agile Cloud Manager Domain Specific Language DSL

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.

Basic Variable Mapping

The very simplest variable mapping is a string literal that you define in-place where the variable is declared as follows:

<variable-name>: any-string-can-be-a-value  

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.

For example, $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.

External Configuration Sources

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 keys.yaml and config.yaml. Secrets are generally imported from keys.yaml, while non-secret values are generally imported from config.yaml.

Within instances and within foundations, top-level fields can have their values sourced from config.yaml unless the field is named instanceName, controller, templateName, or emptyTemplateName.

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, instanceName must be given a string value in the system template. The reason 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.

Summary of Variable Mapping Syntax Rules

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.

Locations For Variable Mapping

The locations where variable mapping is allowed include:

• The mappedVariables sections that are allowed in specific places in foundation blocks, image instance blocks, service type sharedVariables blocks, and service instance blocks.
• backendVariables sections where the terraform controller is used, and where you are specifying a remote backend for terraform.
• The top-level organization field in the system template
• The top-level tags block in the system template
• Controller-specific locations that will be summarized in a separate section below

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:

Top-Level organization Field Mapping

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 $config or $config.variableName.

Top-Level tags Block Mapping

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  

Controller-Specific Field Mapping

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.

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:

• a field named “type” with the value “azurerm”
• the “controller” field having the value “arm”
• the serviceType must be named “tfBackend”
• the templateName must point to a compatible ARM template like the one included in our working demo

mappedVariables Section Mapping Rules

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.

back to Site Home

back to Engineering section Home