template-1.7.0

KOSI Plugin Template Version 1.7.0

Summary

The KOSI Template Plugin allows users to process and generate configuration files based on predefined templates. By specifying a template file (tmpl) and a target file (target), the plugin dynamically replaces placeholders with actual values retrieved from various sources, such as the KOSI package itself or user-defined values.

This plugin is particularly useful when you need to create configuration files dynamically by integrating predefined values into a structured template. It enables flexibility and automation in generating configuration files for different environments.

How It Works

The template file (tmpl) consists of placeholders enclosed in double curly braces ({{ }}). These placeholders reference values from configuration files such as the KOSI package itself or user-defined .yaml files. When the plugin processes the template, it replaces these placeholders with the actual values and saves the result in the specified target file.

The plugin utilizes the Scriban templating engine to replace placeholders. Try Scriban Online.

You can use dot notation to navigate through the YAML structure:

• The root keyword for the KOSI package itself is package.
• The root keyword for user-defined YAML files is values.

Keys

Examples

Example 1 - Basic Usage

This example demonstrates how to use the template plugin to generate a configuration file from a template.

languageversion = "1.0.0";
apiversion = "kubernative/kubeops/sina/user/v4";
name = "kosi-example-package";
description = "kosi-example-package";
version = "0.1.0";
docs = "docs.tgz";
logo = "logo.png";

files =
{
    input = "template.yaml";
}

install
{
    template
    (
        tmpl = "template.yaml";
        target = "result.yaml";
    );
}

Example 2 - Using the Template Engine

Consider the following template.yaml file:

api: {{package.apiversion}}
package:
  name: {{package.name}}
  version: {{package.version}}
  input_file: {{package.includes.files.input}}
  container_registry: {{package.includes.containers.example.registry}}
values:
  primary_ip: {{values.ipNormal}}
  first_listed_ip: {{values.IPList[0]}}

Corresponding package.kosi Example:

languageversion = "1.0.0";
apiversion = "kubernative/kubeops/sina/user/v4";
name = "kosi-example-packagev3";
description = "kosi-example-package";
version = "0.1.0";
docs = "docs.tgz";
logo = "logo.png";

files =
{
    input = "template.yaml";
}

containers =
{
    example = ["docker.io", "nginx", "latest"];
}

install
{
    template
    (
        tmpl = "template.yaml";
        target = "/user/output/result.yaml";
    );
}

Corresponding values.yaml Example:

IPList:
  - "127.0.0.1"
  - "192.128.16.1"
  - "192.128.18.14"
ipNormal: "12.10.45.23"

After we have built the KOSI package with kosi build, we install the created package and include the values.yaml by executing kosi install -p package.tgz -f values.yaml.

Expected Output in result.yaml

After executing the KOSI install command, result.yaml would contain:

api: kubernative/kubeops/sina/user/v4
package:
  name: kosi-example-packagev3
  version: 0.1.0
  input_file: template.yaml
  container_registry: docker.io
values:
  primary_ip: 12.10.45.23
  first_listed_ip: 127.0.0.1

Example 3 - YAML Path Navigation

As already explained in the summary, you can use dot notation to navigate through the YAML structure.

To access values from the KOSI package itself (package.kosi):

name: {{package.name}}

To reference a deeply nested value, use dot notation:

input_file: {{package.includes.files.input}}

The input-element in the KOSI package is accessible with package.includes.files.input, because the input element is nested inside the files tree, which itself is part of the includes hierarchy.