tvl-depot/docs/resource-sets.md

Resource Sets

Resource sets are collections of Kubernetes resources that should be passed to kubectl together.

Technically a resource set is simply a folder with a few YAML and/or JSON templates in it.

Table of Contents

• Resource Sets
• Creating resource sets
  • Default variables
• Including resource sets
  • Fields
    • name
    • path
    • values
    • args
    • include
  • Multiple includes
  • Nesting resource sets
    • Caveats

Creating resource sets

Simply create a folder in your Kontemplate repository and place a YAML or JSON file in it. These files get interpreted as templates during Kontemplate runs and variables (as well as template logic or functions) will be interpolated.

Refer to the template documentation for information on how to write templates.

Default variables

Sometimes it is useful to specify default values for variables that should be interpolated during a run if the cluster configuration does not specify a variable explicitly.

This can be done simply by placing a default.yaml or default.json file in the resource set folder and filling it with key/value pairs of the intended default variables.

Kontemplate will error during interpolation if any variables are left unspecified.

Including resource sets

Under the cluster configuration include key resource sets are included and required variables are specified. For example:

include:
  - name: some-api
    values:
      version: 1.2-SNAPSHOT

This will include a resource set from a folder called some-api and set the specified version variable.

Fields

The available fields when including a resource set are these:

name

The name field contains the name of the resource set. This name can be used to refer to the resource set when specifying explicit includes or excludes during a run.

By default it is assumed that the name is the path to the resource set folder, but this can be overridden.

This field is required.

path

The path field specifies an explicit path to a resource set folder in the case that it should differ from the resource set's name.

This field is optional.

values

The values field specifies key/values pairs of variables that should be available during templating.

This field is optional.

args

The args field specifies a list of arguments that should be passed to kubectl.

This field is optional.

include

The include field specifies additional resource sets that should be included and that should inherit the variables of this resource set.

The fully qualified names of "nested" resource sets are set to ${PARENT_NAME}/${CHILD_NAME} and paths are merged in the same way.

This makes it easy to organise different resource sets as "groups" to include / exclude them collectively during runs.

This field is optional.

Multiple includes

Resource sets can be included multiple times with different configurations. In this case it is recommended to set the path and name fields explicitly. For example:

include:
  - name: forwarder-europe
    path: tools/forwarder
    values:
      source: europe
  - name: forwarder-asia
    path: tools/forwarder
    values:
      source: asia

The two different configurations can be referred to by their set names, but will use the same resource templates with different configurations.

Nesting resource sets

As mentioned above for the include field, resource sets can be nested. This lets users group resource sets in logical ways using simple folder structures.

Assuming a folder structure like:

├── backend
│   ├── auth-api
│   ├── message-api
│   └── order-api
└── frontend
    ├── app-page
    └── login-page

With each of these folders being a resource set, they could be included in a cluster configuration like so:

include:
  - name: backend
    include:
      - name: auth-api
      - name: message-api
      - name: order-api
  - name: frontend:
    include:
      - name: app-page
      - name: login-page

Kontemplate could then be run with, for example, --include backend to only include the resource sets nested in the backend group. Specific resource sets can also be targeted, for example as --include backend/order-api.

Variables specified in the parent resource set are inherited by the children.

Caveats

Two caveats apply that users should be aware of:

1. The parent resource set can not contain any resource templates itself.

2. Only one level of nesting is supported. Specifying include again on a nested resource set will be ignored.