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
Binaries
For binaries please visit the Releases Page.
The binaries are statically compiled and does not require any dependencies.
Via Go
$ go get github.com/VirtusLab/render
kubectl command
Place the kubectl-render_apply
script somewhere in your path and kubectl will automatically find it.
Usage
$ render --help
NAME:
render - Universal file renderer
USAGE:
render [global options] command [command options] [arguments...]
VERSION:
v0.1.2-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 parsedstdin
andstdout
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
Example usage of render-apply
with --in
and --config
:
$ kubectl render-apply --in deployment.yaml.tmpl --config deployment.config.yaml
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
All syntax and functions:
Custom functions
render
- calls therender
from inside of the template, making the renderer recursive (also accepts an optional template parameters override)readFile
- reads a file from a path, relative paths are translated to absolute paths, based onroot
functionroot
- the root path, used for relative to absolute path translation in any file based operations; by defaultPWD
is usedtoYaml
- provides a configuration data structure fragment as a YAML formatgzip
,ungzip
- usegzip
compression and extraction inside the templates, for best results use withb64enc
andb64dec
See also example template 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 withgzip
andb64enc
decryptAWS
- decrypts data using AWS KMS, for best results use withungzip
andb64dec
encryptGCP
- encrypts data using GCP KMS, for best results use withgzip
andb64enc
decryptGCP
- decrypts data using GCP KMS, for best results use withungzip
andb64dec
encryptAzure
- encrypts data using Azure Key Vault, for best results use withgzip
andb64enc
decryptAzure
- decrypts data using Azure Key Vault, for best results use withungzip
andb64dec
Helm compatibility
As of now, there is a limited Helm 2 Chart compatibility, simple Charts will render just fine.
To mimic Helm behaviour --unsafe-ignore-missing-keys
option.
There is no plan to implement full compatibility with Helm, because of unnecessary complexity that would bring.
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
.
Contribution
Feel free to file issues or pull requests.
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
go get -u github.com/golang/dep/cmd/dep
make all
The name
We believe in obvious names. It renders. It's a verb. It's render
.