Cookiecutter Template Formula (Salt)

This cookiecutter template is an opinionated variant of the official template-formula. Note that this is pre-alpha atm and not everything might make sense.

Prerequisites

Cookiecutter

• Cookiecutter currently needs to be modified to find the template files with the alternative syntax, otherwise it will complain about this not being a template. (@TODO pull request)
• Also, since PR #1692, cookiecutter does not support dicts with new keys, which breaks my use case. Hence I removed this breaking change again.

Cruft

Cruft is a wrapper around cookiecutter that takes care of maintaining the boilerplate. It allows you to show the diff between what the template generated and the current state with cruft diff and to apply updates from the template with cruft update (and more).

Cruft currently also needs to be very recent and modified to support cookiecutter v2 and the alternative Jinja syntax. Both changes are found in the my branch of my fork. (@TODO pull request)

Example Installation

Since I use pipx to manage python programs in their own isolated environments, my installation goes as follows:

pipx install git+https://github.com/lkubb/cruft.git@my
pipx runpip cruft uninstall cookiecutter
pipx runpip cruft install git+https://github.com/lkubb/cookiecutter.git@my

Pip might complain about some dependencies, but it works.

Usage

First Creation

Creating a new formula from this template is as easy as:

cookiecutter https://github.com/lkubb/salt-template-formula

For cookiecutter, this is where the journey ends.

The recommended way to use this template goes a little further though, since (a) there are hidden variables with further configuration and (b) updates from the template are cumbersome. This is where cruft steps in.

cruft create https://github.com/lkubb/salt-template-formula

Customization

Having created the formula with cruft, you will find a .cruft.json file in the root directory. This saves your answers and allows you to edit some hidden variables. Those are currently for parameters to the formula, sorted into:

• lookup: Custom lookup variables for data that the user should not have to modify regularly.
• settings: Global settings for this formula.

Once you have modified those, run cruft diff | git apply to recreate the formula. Warning: This command resets the state to the autogenerated one, so take care if you have modified any files manually at this point. In that case, you can pipe the output into a file and manually select the changes: cruft diff > temp.patch, edit and then git apply temp.patch.

Parameters

This is an overview of the available parameters for autogeneration. The most recent version is found in cookiecutter.json though and might be out of sync. In contrast to tool-template-formula, empty strings are considered as false.

name [str]

The name of the managed program. Example: Gitea.

abbr [str]

A slugified version of name. Example: gitea.

abbr_pysafe [str]

A short and pythonic version of abbr. Example: gitea. This will be used in many places, including the formula base dir, the pillar key and the Jinja variable name.

pkg [str]

The name of the package to install. Leave empty to skip. If skipped, will still leave the state files since most formulae will install some program, even if it is not packaged.

needs_repo [bool]

Whether the package installation relies on custom repositories (for Linux). This will add boilerplate for those in the parameters/os_family files as well as sls files to install them.

config [str]

Path to the default config file. Leave empty to skip.

service [str]

The name of the service [on Linux]. Leave empty to skip.

subcomponent [str]

The name of a subcomponent, if applicable. Leave empty to skip.

subcomponent_config [str]

Path to the default config file of a subcomponent. Leave empty to skip.

git_username [str]

Your Github/Gitlab/... username that should be used as the author of the formula.

lookup [map/dict]

An arbitrarily nested mapping/dictionary that describes lookup data that the user should not have to modify. Examples include package dependencies, some paths, package names etc.

settings [map/dict]

An arbitrarily nested mapping/dictionary that describes global parameters for the formula. Examples include package version and system configuration for the managed program.

References

• https://github.com/saltstack-formulas/template-formula