Configuration Templates

History

ReleaseModification
4.5.0This feature was introduced into 128T-4.5.0

Configuration templates allow administrators to automate the configuration of top level resources (e.g. Routers, Tenants, Services, etc). There are two modes of templating configuration: Basic and Advanced. Basic mode is intended for simple templates that don't require complex logic. Advanced mode, on the other hand, exposes the full power of the underlying templating language to the administrator.

Creating a Template

To create a template, begin by navigating to the Configuration page of the 128T Networking Platform. Next, click on the Templates button in the top right action area of the page: navigate_to_templates

On the templates page you will see a list of your current templates, or a button to create a new one if none exist. Click the Create A Template button to create a new template: templates_hero

Next fill out the information for your template and click Save: templates_new

You will now be returned to the list of templates and see your newly created template. If you click into it, you will see the message "Template is empty, copy configuration into the template to populate it.". Follow the steps in Copying Configuration into Template to learn how to populate it with configuration.

Copying Configuration into a Template

Instead of starting a template from scratch, it is often useful to copy existing or new configuration objects into the template body. The following button on top-level configuration object's pages can be used to copy the object into an existing template: templates_copy

Basic Mode

Basic mode consists of two panes, the template body pane and the instances pane. The template body pane shows an annotated tree view of the configuration contained in the template. This represents the base configuration that will get generated for each instance of the template. Within the body you can mark fields as templated to make them a variable field for each instance (see Marking a Field as Templated). The instances pane allows you to add, remove, search, and generate instances of the template. You can picture the instances as the input to a for-loop, where you iterate through each instance, substitute its values into the template body, and generate a chunk of configuration. When generating configuration from instances, the administrator can select individual or all instances to run the generation step on.

Marking a Field as Templated

To mark a field in the template body as a variable field, hover over the value and click on it: templates_mark

The field should turn green and indicate that it is now templated: templates_marked

Adding Instances

To add an instance, click the Create an Instance button in the right pane: templates_add_instance

A new instance should have been created for you, click on it to expand it and fill it out with some info and then click Save: templates_instance_wizard

note

The name of the instance does not have to match the name of the router, it can be any name of your choosing.

Create another instance and save it as well. Now you should have two instances.

Generating Configuration

To generate configuration for instances, first select the instances you want to generate, or use the check box beside the Add Instance button to select them all: templates_select_all_instances

Now click the magic wand icon in the instances pane: templates_generate_btn

A wizard will appear to walk you through the generation steps and display any errors encountered along the way. When generation is finished you will see a success modal with a link to navigate to see your new configuration: templates_generate_success

On the Configuration page you will see your generated configuration: templates_show_generated

Advanced Mode

Advanced mode consists of two text based panes, the template body pane and the variables pane. The template body pane contents are written in the Liquid templating language. The variables pane contents are written in JSON. When you generate output from an advanced mode template, the template body is evaluated using the variables you define, and it must produce a valid configuration in JSON format. If the output of the generation is either not valid JSON or not valid configuration, you will be presented with information on where the failure occurred.

important

Any changes made to the template body pane or variables pane must be saved by clicking the Save button in the upper right portion of the page: templates_advanced_mode_save

Templating Language

The body of a configuration template is written in the Liquid templating language. Please refer to the Liquid documentation for the specifics of the language.

note

The 128T Networking Platform supports several custom tags in Liquid (e.g. {% editGroup $}) that would not be parsable by other Liquid evaluators.

The {% editGroup $} Tag

Unlike in basic mode, advanced mode runs configuration generation in one step and makes one, possibly large, edit. In some cases it is desirable to break this large edit up into a set of smaller edits, this is the functionality of the {% editGroup $} tag. This tag can be conceptually thought of as a separator that the generated output is split upon.

For example, lets say you had the following template body and variables:

{% for instance in instances %}
{% editgroup %}
{
"authority": {
"router": [
{
"name": "{{instance.variables['name_IAPFNIn']}}",
"location": "Boston, MA"
}
]
}
}
{% endfor %}
{
"instances": [
{
"name": "Router1",
"variables": {
"name_IAPFNIn": "Router1"
}
},
{
"name": "Router2",
"variables": {
"name_IAPFNIn": "Router2"
}
}
]
}

After running the loop you would end up with:

{% editgroup %}
{
"authority": {
"router": [
{
"name": "Router1",
"location": "Boston, MA"
}
]
}
}
{% editgroup %}
{
"authority": {
"router": [
{
"name": "Router2",
"location": "Boston, MA"
}
]
}
}

After splitting on the {% editgroup %} tag you would end up with the following chunks of config:

{
"authority": {
"router": [
{
"name": "Router1",
"location": "Boston, MA"
}
]
}
}
{
"authority": {
"router": [
{
"name": "Router2",
"location": "Boston, MA"
}
]
}
}

This feature is also useful for initiating many top level edits that need to overlay on existing configuration.

Tag Naming Conventions

While not enforced, the administrator is encouraged to follow the following naming convention for tag names that correspond to configuration: field-name_{7 Random Characters from [A-Za-a0-9]}. For example, a tag name for a router could look like: name_bZ2h9e0.

Operations

Up until this point, all of the examples in this document have covered generated configurations that are merged into the existing configuration. In some deployments, the administrator may want to have a template that, for example, deletes configuration. The following syntax can be used to accomplish this in advanced mode:

{% for instance in instances %}
{% editgroup %}
{
"authority": {
"router": [
{
"_value": { "name": "{{instance.variables['name_aEayzmy']}}" },
"_operation": "delete"
}
]
}
}
{% endfor %}

Given the following variables:

{
"instances": [
{
"name": "Test1",
"variables": {
"name_aEayzmy": "Test1"
}
}
]
}

In the above example, router Test1 would be deleted from the candidate configuration upon running the generation step.

The following values are supported for the _operation field: merge, create, replace, delete, and remove.

List Positioning

In addition to the _operation property above, there is another property named _position. If, for example, you wanted to create a list item after another list item (e.g. if order matters) you could do the following:

{% for instance in instances %}
{% editgroup %}
{
"authority": {
"router": [
{
"_value": { "name": "{{instance.variables['name_aEayzmy']}}" },
"_operation": "create",
"_position": { "insert": "after", "keys": [{ "key": "name", "value": "Test2" }] }
}
]
}
}
{% endfor %}

Given the following variables:

{
"instances": [
{
"name": "Test1",
"variables": {
"name_aEayzmy": "Test1"
}
}
]
}

The above would insert router Test1 after router Test2.

The insert property can have any of the following values: first, last, before, and after. If the list is of complex objects, like routers in the above example, the keys property must be specified for before and after. If instead the list was of simple strings like ["a", "b"], instead of keys you would specify a property called value which is a string to reference the item in the list that you want to target (e.g. "value": "a").

Conversion Between Modes

When transitioning from basic to advanced mode or vice versa, data is retained and converted to the new mode. Basic mode can always be transitioned to advanced mode, but advanced mode cannot always be transitioned back to basic mode. The following conditions must be met for a template to be transitioned from advanced mode to basic mode:

  • The template body must start with:
{% for instance in instances %}
{% editgroup %}
  • The template body must end with:
{% endfor %}
  • The JSON between the start and end segments of the body must be valid JSON.
  • The JSON between the start and end segments of the body must be structurally valid configuration. We will trim any unrecognized fields, but for example if a field is supposed to be an array and it is a string, the conversion will fail.
  • The variables pane of the template must contain valid JSON.
  • There must be an array of instances in the variables JSON.
  • Each instance must have a name and an optional variables object that maps tag names to the values that will be substituted in for them. For example:
{
"instances": [
{
"name": "Router1",
"variables": {
"name_IAPFNIn": "Router1"
}
},
{
"name": "Router2",
"variables": {
"name_IAPFNIn": "Router2"
}
}
]
}
tip

The easiest way to quickly make modifications to the structure of a template body in basic mode is to switch to advanced mode, make the edits, and then switch back to basic mode.

Import / Export

Templates support import and export functionality, both in basic and advanced mode. The Import / Export wizard can be opened by clicking the following button in the upper right corner of the page: templates_import_export_btn

Backing Up Templates / Storage Mechanism

Templates are stored on disk as JSON in the following location: /etc/128technology/sync/templates.json. This file can be backed up, restored, or edited. While the 128T Networking Platform does watch this file for changes and updates it's state, it is not recommended to edit this file directly as a means to configure templates.

Last updated on