render

Universal data-driven templates for generating textual output. Can be used as a single static binary (no dependencies) or as a golang library.

Just some of the things to render:

• configuration files
• Infrastructure as Code files (e.g. CloudFormation templates)
• Kubernetes manifests

The renderer extends go-template and Sprig functions.

If you are interested in one of the use cases, take a look at this blog post about Kubernetes resources rendering. Also see Helm compatibility.

• Installation
  • Official binary releases
  • Compile from master via Go get
• Usage
  • Command line
  • Notable standard and sprig functions
  • Custom functions
  • Helm compatibility
  • Limitations and future work
• Contribution
• Development
• The Name

Installation

Official binary releases

For binaries please visit the Releases Page.

The binaries are statically compiled and does not require any dependencies.

Usage

$ render --help
NAME:
   render - Universal file renderer

USAGE:
   render [global options] command [command options] [arguments...]

VERSION:
   v0.2.0-86eb03f

AUTHOR:
   VirtusLab

COMMANDS:
     help, h  Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --debug, -d                   run in debug mode
   --indir value                 the input directory, can't be used with --out
   --outdir value                the output directory, the same as --outdir if empty, can't be used with --in
   --in value                    the input template file, stdin if empty, can't be used with --outdir
   --out value                   the output file, stdout if empty, can't be used with --indir
   --config value                optional configuration YAML file, can be used multiple times
   --set value, --var value      additional parameters in key=value format, can be used multiple times
   --unsafe-ignore-missing-keys  do not fail on missing map key and print '<no value>' ('missingkey=invalid')
   --help, -h                    show help
   --version, -v                 print the version

Notes:

• --in, --out take only files (not directories), --in will consume any file as long as it can be parsed
• stdin and stdout can be used instead of --in and --out
• --config accepts any YAML file, can be used multiple times, the values of the configs will be merged
• --set, --var are the same (one is used in Helm, the other in Terraform), we provide both for convenience, any values set here will override values form configuration files

Command line

Example usage of render with stdin, stdout and --var:

$ echo "something {{ .value }}" | render --var "value=new"
something new

Example usage of render with --in, --out and --config:

$ echo "something {{ .value }}" > test.txt.tmpl
$ echo "value: new" > test.config.yaml
$ ./render --in test.txt.tmpl --out test.txt --config test.config.yaml
$ cat test.txt
something new

Also see a more advanced template example.

As a library

package example

import (
    "github.com/VirtusLab/render/renderer"
    "github.com/VirtusLab/render/renderer/parameters"
)

func CustomRender(template string, opts []string, params parameters.Parameters) (string, error) {
    return renderer.New(
    	renderer.WithOptions(opts...),
        renderer.WithParameters(params),
        renderer.WithSprigFunctions(),
        renderer.WithExtraFunctions(),
        renderer.WithCryptFunctions(),
    ).Render(template)
}

See also other functions.

Also see tests for more usage examples.

Notable standard and sprig functions

• indent
• default
• ternary
• toJson
• b64enc, b64dec

All syntax and functions:

• Go template functions
• Sprig functions

Custom functions

• render - calls the render from inside of the template, making the renderer recursive (also accepts an optional template parameters override)
• toYaml - provides a configuration data structure fragment as a YAML format
• fromYaml - marshalls YAML data to a data structure (supports multi-documents)
• fromJson - marshalls JSON data to a data structure
• jsonPath - provides data structure manipulation with JSONPath (kubectl dialect)
• n - used with range to allow easy iteration over integers form the given start to end (inclusive)
• gzip, ungzip - use gzip compression and extraction inside the templates, for best results use with b64enc and b64dec
• readFile - reads a file from a path, relative paths are translated to absolute paths, based on root function or property
• writeFile - writes a file to a path, relative paths are translated to absolute paths, based on root function or property
• root - the root path, used for relative to absolute path translation in any file based operations; by default PWD is used

See also examples and a more detailed documentation.

Cloud KMS (AWS, Amazon, Google) based cryptography functions form crypt:

• encryptAWS - encrypts data using AWS KMS, for best results use with gzip and b64enc
• decryptAWS - decrypts data using AWS KMS, for best results use with ungzip and b64dec
• encryptGCP - encrypts data using GCP KMS, for best results use with gzip and b64enc
• decryptGCP - decrypts data using GCP KMS, for best results use with ungzip and b64dec
• encryptAzure - encrypts data using Azure Key Vault, for best results use with gzip and b64enc
• decryptAzure - decrypts data using Azure Key Vault, for best results use with ungzip and b64dec

Helm compatibility

As of now, there is a limited Helm 2 Chart compatibility, simple Charts will render just fine.

To mimic Helm behaviour regarding to missing keys use --unsafe-ignore-missing-keys option.

There is no plan to implement full compatibility with Helm, because of unnecessary complexity that would bring.

If you need full Helm compatilble rendering see: helm-nomagic.

Limitations and future work

Planned new features

• .renderignore files #12

Operating system support

We provide cross-compiled binaries for most platforms, but is currently used mainly with linux/amd64.

Community & Contribution

There is a dedicated channel #render on virtuslab-oss.slack.com (Invite form)

Feel free to file issues or pull requests.

Before any big pull request please consult the maintainers to ensure a common direction.

Development

export GOPATH=$HOME/go
export PATH=$PATH:$GOPATH/bin

mkdir -p $GOPATH/src/github.com/VirtusLab
cd $GOPATH/src/github.com/VirtusLab/render
git clone [email protected]:VirtusLab/render.git
cd render

make all

The name

We believe in obvious names. It renders. It's a verb. It's render.