Using Apache Velocity in your Nimbus scripts.
Nimbus uses Apache’s VTL to bind the UI variables to your script.
That kindof says it all. When Nimbus was created, it was important to find a flexible solution to “bind” the variables you configure in the UI with your Terraform / Cloud formation… etc. scripts. To do this, we pre-processes your script using Apache’s Velocity template language (VTL). If you don’t know VTL, it’s basically like JSP programming, or handlebars. Nimbus provides an object tree that can be referenced to replace strings, or iterate and perform logical conditions on your variable data, and replace stuff in your script. Its incredibly powerful, and assures that you have a consistent layer of logical processing that can be repeated across different platforms and clouds.
You can learn more about VTL at the link below:
https://velocity.apache.org/engine/1.7/user-guide.html
Nimbus provides an object model that you can use to add complex logic to your scripts.
You can reference Nimbus objects in a VTL script by using the ${context.<variable path>} notation. This will only work if you specify that your script supports Nimbus scripting when you define it. Each script can access the following data:
| Path | Object Type | Description | Optional? |
|---|---|---|---|
| ${context.cloud} | Cloud | The cloud configuration being used in this script | |
| ${context.orchestrator} | Orchestrator | The IaC platform configuration being used in this script | |
| ${context.application} | Application | The application this build is for | |
| ${context.organization} | Organization | The organization this build is for | |
| ${context.environment} | Template | The root template (environment template) that this script lies within | |
| ${context.template} | Template | The environment, zone, or service template that this script is for. | |
| ${context.parent} | Template | The parent (if applicable). This is the environment if this is a zone script, or the zone if this is a service script. For the environment script, this will be NULL. | Optional |
Each of these paths references an object that has fields. You can use the below reference to the fields available for each object type, and what they provide:
| Object | Property | Description | Format | Optional |
|---|---|---|---|---|
| Cloud | type | The unique identifier of the type of cloud. Currently one of: aws, azure, gcp | String | |
| Cloud | name | The name of the cloud account as you configured it | String | |
| Cloud | description | The description you provided of the cloud account | String | Optional |
| Cloud | vars | Cloud specific variables, excluding sensitive information. For AWS this may specify the region. | Map(String,String|Number) | Optional |
| Orchestrator | type | The unique identifier of the type of IaC platform such as "terraform" | String | |
| Orchestrator | name | The name of the account as you configured it | String | |
| Orchestrator | description | The description you provided of the IaC platform account | String | Optional |
| Orchestrator | vars | IaC platform specific variables, excluding sensitive information | Map(String,String|Number) | Optional |
| Template | uniqueID | A globally unique ID of the template. This idnetifier will be best practice in the format of | String | |
| Template | type | The type of template this is, currently one of : environment, zone, or object | String | |
| Template | container | True if this template has children | Boolean | |
| Template | service | The unique identifier of the service this template deploys | String | |
| Template | identifier | The unique identifier of this configuration within the specific environment that is specified as the identifier when you configured it. | String | |
| Template | name | the user-friendly name of this template instance | String | |
| Template | description | the description you provided of this template instance | String | Optional |
| Template | parent | the parent of this template which will be the zone if this is an object, or the environment if this is a zone. The environment template will have a null value for the parent. | Template | Optional |
| Template | children | An array of children template instances. This is applicable if container is TRUE. | Template[] | Optional |
| Template | ports | An array of ports configured for this template. | Port[] | Optional |
| Template | connections | An array of other peer templates that this template has a connection with. These are used to identify how to filter traffic between zones. This list will be the other zones that this template should allow traffic inbound from | Template[] | Optional |
| Template | vars | The variables that are configured for this template, with their specified values. | Map(String,String|Number) | Optional |
| Template | props | The output properties expected for this template. This will be a Map, with the key being the identifier of the property, and the value being a uniquely generated name that should be used as the value of key to the property in the script. Nimbus will look for that unique ID and map it to the correct template's properties. | Map(String,String) | Optional |
| Port | protocol | TCP or UDP | String | |
| Port | address | the Inet address to set for the port filters. This will be an address that the cloud filters inbound traffic to. | String | |
| Port | port | The allowed port number. Only a single number is allowed. | Number | |
| Application | identifier | The unique identifier of the application | String | |
| Application | name | The user friendly name of the application | String | |
| Application | description | The description you provided of the application | String | Optional |
| Application | fields | Any custom fields configured for this application along with their configured value. | Map(String,String|Number) | Optional |
| Organization | path | The path to this organization in the organization hierarchy | String | |
| Organization | name | the user friendly name of this organization | String | |
| Organization | description | The optional description of this organization that you provided. | String | Optional |
| Organization | fields | Any custom fields configured for this organization along with their configured value. | Map(String,String|Number) | Optional |
Watch outs, and best practices
If you are combining VTL with the IaC platform’s scripting language, you may need to escape any statement that you don’t want Nimbus to process. For example, in Terraform - if you use the ${} notation, you will need to escape it with a ‘\’ character: \${}.
NULL values are rendered as empty strings in VTL.
You should run a compile test on any VTL script that has complex VTL in it. this will help assure your scripts work correctly.
If you want to handle all your logic in the IaC platform’s scripting language. You can make a separate “variable” file to bind all your Nimbus UI elements, then you can reference those variables locally. in your other scripts. (just make sure to flip the flag telling Nimbus to pre-process the script)