salt-template

This repository provides salt template files and module functions to serialize data and text into configuration files.

Examples

/etc/default/application:
  file.managed:
    - template: py
    - source: salt://_templates/env.py
    - context:
        # Default config data to merge with pillar data
        default:
          LOG_LEVEL: debug

        # Load data from one or multiple pillar keys and merge
        source:
          - env:default
          - env:application

/etc/systemd/system/application.service:
  file.managed:
    - template: py
    - source: salt://_templates/systemd.py
    - context:
        default:
          Unit:
            Description: My Demo Application
          Service:
            EnvironmentFile: -/etc/default/application
            ExecStart: /usr/local/bin/application -l $LOG_LEVEL

/rails/config/database.yaml:
  file.managed:
    - template: py
    - source: salt://_templates/yaml2.py
    - context:
        source: myapp:rails:database
        root: production

Installation

The recommended installation uses salt GitFS to include this repository into your state tree:

gitfs_remotes:
  - https://github.com/jgraichen/salt-template.git:
      - base: v1.2.0

It is recommended to checkout a specific revision to avoid getting unexpected updates or changes.

Templates

The repository ships a set of Python templates to serialize different kind of files. The can be used via e.g. file.managed. Templates accept configuration via the context option.

All templates accept a source and a default option. Some templates have more options to tweak things specific to them. They all use template.managed to render the final output, see here for details and more options.

source (str, list, optional)

A comma-separated string or a list of pillar keys to load data from. The pillar values will be recursively merged, lists will be concatenated.

/etc/salt/minion.d/minion.conf:
  file.managed:
    - template: py
    - source: salt://_templates/yaml2.py
    - context:
        source:
          - salt:common
          - salt:minion

default (optional)

Some default data to use with the template. If an additional source is specified, it will be merged into the default data.

/etc/salt/minion.d/minion.conf:
  file.managed:
    - template: py
    - source: salt://_templates/yaml2.py
    - context:
        default:
          log_level: INFO
        source: salt:minion

Using default without source only renders the given default data.

Environment

Renders a single-level dictionary into an environment file.

/etc/default/application:
  file.managed:
    - template: py
    - source: salt://_templates/env.py
    - context:
        default:
          KEY: 1
          LONG_VALUE: |
            Long string
            on multiple lines

# This file is managed by salt. Changes will be overwritten.

KEY=1
LONG_VALUE='Long string
on multiple lines'

Sysctl

Renders a sysctl-like configuration with additional list suppport.

/etc/rabbitmq/rabbitmq.conf:
  file.managed:
    - template: py
    - source: salt://_templates/sysctl.py
    - context:
        default:
            cluster_formation.peer_discovery_backend: classic_config
            cluster_formation.classic_config.nodes:
              - rabbit@hostname1.example.org
              - rabbit@hostname2.example.org

# This file is managed by salt. Changes will be overwritten.

cluster_formation.peer_discovery_backend = classic_config
cluster_formation.classic_config.nodes.1 = rabbit@hostname1.example.org
cluster_formation.classic_config.nodes.2 = rabbit@hostname2.example.org

Note: List index starts with 1.

Systemd

Renders a file using an systemd.syntax approximation.

/etc/systemd/system/application.service.d/override.conf:
  file.managed:
    - template: py
    - source: salt://_templates/systemd.py
    - context:
        default:
          Unit:
            After: consul.service
          Service:
            Environment: KEY=1
            ExecStart: [Null, /usr/local/bin/application]

# This file is managed by salt. Changes will be overwritten.

[Unit]
After=consul.service

[Service]
Environment=KEY=1
ExecStart=
ExecStart=/usr/local/bin/application

Additional arguments

section (str, optional)

Render the given data as a flat dictionary into the given section.

/etc/systemd/resolved.conf.d/override.conf:
  file.managed:
    - template: py
    - source: salt://_templates/systemd.py
    - context:
        default:
          DNS: 127.0.0.1
          Domains: ~consul
        section: Resolve

# This file is managed by salt. Changes will be overwritten.

[Resolve]
DNS=127.0.0.1
Domains=~consul

Text

Renders a list of text blobs into a combined file.

/etc/application/config:
  file.managed:
    - template: py
    - source: salt://_templates/text.py
    - context:
        default: |
          First blob.
        source:
          - pillar:key:one
          - pillar:key:two

# This file is managed by salt. Changes will be overwritten.

First blob.


# pillar:key:one

Blob from first pillar key.


# pillar:key:two

Blob from second pillar key.

Note: The text template recognizes comment_prefix from template.managed and uses this to prefix source comments.

Yaml2

Renders into a YAML document.

/etc/application/config.yaml:
  file.managed:
    - template: py
    - source: salt://_templates/yaml2.py
    - context:
        default:
          database:
            host: 127.0.0.1
            port: 1234
        source: pillar:key

# This file is managed by salt. Changes will be overwritten.

database:
  host: 127.0.0.1
  port: 1234
  name: from_pillar

Additional arguments

root (str, optional)

A colon-separated string to recursively nest the data into the given path. Useful if applications expected the configuration in a specific path but you do not want have that in the source pillar.

/rails/config/database.yaml:
  file.managed:
    - template: py
    - source: salt://_templates/yaml2.py
    - context:
        source: myapp:rails:database
        root: production

# This file is managed by salt. Changes will be overwritten.

production:
  adapter: postgresql
  hostname: 127.0.0.1

config (ini/properties)

Renders into an ini/properties file using Pythons configparser module.

/etc/application/config.ini:
  file.managed:
    - template: py
    - source: salt://_templates/config.py
    - context:
        default:
          DEFAULT:
            enabled: 'yes'
          DATABASE:
            host: 127.0.0.1
            port: 1234
        source: pillar:key

# This file is managed by salt. Changes will be overwritten.

[DEFAULT]
enabled = yes

[DATABASE]
host = 127.0.0.1
port = 1234

Additional arguments

section (str, optional)

A section name to scope all data into. Useful when the target file only needs a single section.

/etc/application/config.ini:
  file.managed:
    - template: py
    - source: salt://_templates/config.py
    - context:
        source: app:config
        section: [config]

# This file is managed by salt. Changes will be overwritten.

[config]
database = postgresql
hostname = 127.0.0.1

Execution modules

template.managed

This execution module takes a string or a list of lines and renders this into a consistent text. It will add preamble and ensure there is a final newline.

The preamble text is loaded via config.get using the template_managed key. Therefore the preamble can be specified everywhere including the salt master configuration. This allows to easily set custom message specific to a salt master, e.g.:

# /etc/salt/master
template_managed: >
    This file is part of the salt.example.org
    collective. Resistance is futile.

All provided templates here use template.managed to render the final output. Options from the template are passed through to the module function.

Arguments

text (string or list, required)

A text string or a list of lines.

preamble (bool, default: True)

Set to False to not add a preamble.

comment_prefix (string, default: "#")

The string to prepend each line from preamble and comment with. If set to False, no preamble or comment will be added.

comment (string, optional)

An additional comment to be added in front of the text.

Example: Using it in your own template

#!py

def run():
    # generate complex config file
    config = "Very complex config!"

    return __salt__["template.managed"](config, sign="//")

// This file is managed by salt. Changes will be overwritten.

Very complex config!