Warning

Features currently under evaluation may be modified in the next version without prior notice. If you are using these beta features, we welcome your feedback and experience. Your input is crucial to refining and improving these features before their official release. Please share your thoughts and experiences with us, and contribute to the evaluation process.

General usage

Warning

The template feature is an advanced aspect that requires a thorough understanding of its workings. It is strongly advised to read the chapter before using template playbook warnings before using it.

Capabilities

Capability	Support	Comment
Inherit from other file		This feature is called templating and can be viewed there
File render / Items render - Using inventory to declare variable		See supported variable type for the current supported variables types
File render - Generate a single file		See file render
File render - Using inventory to loop over entries		See context gathering for how to include CSV as variable usable by nunjunks
File render - Using a templating language		See nunjunks documentation for templating language details and file-rendering nunjunks
Items render - Generate multiples items / files based on a inventory		See items render
Items render - Create dedicated rules by line		See items render for how to specify advanced rules like include / remove some files from a template.
Items render - Using a templating language		See nunjunks documentation for templating language details items rendering nunjunks usage for dedicated usage.

Purpose

OnSphere configuration might contains a lot of duplicates, when configuring multiple similar devices for example. The goal of template playbook is to provide a way to write configuration once as a template and then automatically generate final configuration based on inventory and variables definition.

Template interpretation and generation are ensured by osp-composer to obtain a final configuration to be as close as possible from a classic osp-configuration. Every file generated are injected inside the root directory. The idea behind the playbook template is to generate large configuration with similar parts, if the configuration has no similar points, there is no meaning about using templates.

Use-case are

1. Generate multiples devices/advanced configuration with only minor change between them

2. Create complex file from configurable data

3. Creating complex script or dashboard based on list

4. Limit configuration efforts to add standard devices

5. Replicated the same configuration multiples times configured by variables (IP/MAC/position)

6. Create complex logic based on inventory (ex: create insertion rules based on variables)

7. Define standard dashboard and personalize some items for different groups.

Before using templates playbook

Security concern

Warning

Nunjucks does not sandbox execution so it is not always safe to use templates. You can be exposed to attack vectors for accessing sensitive data and remote code execution. On the client, you can expose cross-site scripting vulnerabilities. See this issue for more information. In a few words, Nunjucks is a scripting language. Do not use a template that you don’t trust sources (other people who are pushing configuration)

Within the context of OnSphere, the risk is constrained since typically only trusted individuals possess the capability to push configurations. However, when dealing with loading unfamiliar rules, it is essential to carefully review them before execution.

Configuration status

Another crucial point to note is that since the playbooks are generated by osp-composer and not on the osp-configuration-dispatcher side. There is no mechanism to verify whether the generated files have been updated from the template. Consequently, if the configuration is generated through a playbook, it becomes imperative to manually regenerate the templates when Inventory is updated.

Performances

Template playbook is designed to handle large configurations, but the creation process is done on the client side, so it’s advisable to avoid CSV files with more than 1’000’000 entries. It’s even recommended to have less than 100,000 entries to ensure that each computer can handle template generation with ease.

Tip

It’s better to have several Inventories with fewer variables and entries.

Misc

1. Avoid using the dash “-” operator in variable names as in Nunjucks framework, this is reserved for subtraction. Failure to adhere to this rule will result in the variable name being inaccessible in the .nunjucks file.

2. As the playbook generation can be an expensive process for large configuration, it run only on the client-side to avoid to “paid” at every loading of the osp-configuration-dispatcher.

3. Do not use the directory /templates for another purpose than playbook templating files see directories usage for details.

Generic information

The information presented in this chapter applies to all templates generation methods. Refer to each specific chapter for detailed instructions on usage.

• See Items Render

• See File Render

And inventory who can be used by both method :

• See Inventory

Directories

Warning

The directory /templates is not recognized by osp-configuration-dispatcher. Therefore, it is strongly advised to refrain from utilizing this directory for any purpose other than storing templates. Using it otherwise will fail to trigger a configuration update.

Directory name	Usage
/templates/	This folder is used by the osp-composer and is not interpreted by the osp-configuration-dispatcher.
/templates/playbooks/	All the playbooks must be placed on this directory
/templates/inventory/	This folder contains all the csv files used to manage the inventory. The
/templates/sources/	This folder contains all the sources files who are used from both the .nunjunks playbook and csv playbooks

Associated files

Filename	Usage
*.nunjucks	This file is interpreted with nunjucks interpreter
*.csv	Inventory on csv format who can be used a CSV playbook
*.playbook	A playbook description see playbook file
*.items-render-rules	A rule for Items Render targets Evaluation rules

Command list

• A single playbook can be executed by the command template.playbook.execute

• All playbooks can be executed at once by the command template.playbook.execute.all. This command begin with a clean method call.

• The cleanup of all generated files template.playbook.clean

Playbook file

A Playbook (see the schema there) is a sequential list of targets to compute an OnSphere configuration. There are currently two kinds of targets available that both have there own specificities.

FileRender

FileRender target has a file granularity, it means that this target is appropriate for single file templating resolution. A very common usage is to populate a dashboard view by one widget for every single device in a list.

ItemRender

ItemRender targets are meant to generate a configuration item. This allow integrator to write configuration for a specific configuration item once, and then automatically generate a similar serval times. A very common usage of this target in case of serval devices instances each of them at a specific geolocation.

Hint

It’s a really good practice to always run command template.playbook.execute.all before commit a configuration. To avoid every kind of conflict.

Playbook execution order

The schema below is showing how playbooks are generated, this knowledge can be helpful in some edge case situation.

Examples

• Simple CSV example

• Use of rules with CSV files example

• Use of nunjunks file in a CSV generated

• Use of nunjunks file playbook

• Multiples inventory file render