gomplate

README

gomplate

A Go template-based CLI tool. gomplate can be used as an alternative to envsubst but also supports additional template datasources such as: JSON, YAML, AWS EC2 metadata, and Hashicorp Vault secrets.

I really like envsubst for use as a super-minimalist template processor. But its simplicity is also its biggest flaw: it's all-or-nothing with shell-like variables.

Gomplate is an alternative that will let you process templates which also include shell-like variables. Also there are some useful built-in functions that can be used to make templates even more expressive.

• gomplate
  • Installing
    • macOS with homebrew
    • Alpine Linux
    • use with Docker
    • manual install
  • Usage
    • Commandline Arguments
      • --datasource/-d
  • Syntax
    • About .Env
    • Built-in functions
      • contains
        • Example
      • getenv
        • Example
      • hasPrefix
        • Example
      • hasSuffix
        • Example
      • bool
        • Example
      • slice
        • Example
      • split
        • Example
      • title
        • Example
      • toLower
        • Example
      • toUpper
        • Example
      • trim
        • Example
      • json
        • Example
      • jsonArray
        • Example
      • yaml
        • Example
      • yamlArray
        • Example
      • datasource
        • Examples
          • Basic usage
          • Usage with HTTP data
          • Usage with Vault data
      • datasourceExists
      • ec2meta
        • Example
      • ec2dynamic
        • Example
      • ec2region
        • Example
      • ec2tag
        • Example
    • Some more complex examples
      • Variable assignment and if/else
  • Releasing
  • License

Installing

macOS with homebrew

The simplest method for macOS is to use homebrew:

$ brew tap hairyhenderson/tap
$ brew install gomplate
...

Alpine Linux

Currently, gomplate is available in the testing repository.

$ echo "http://dl-cdn.alpinelinux.org/alpine/edge/testing/" >> /etc/apk/repositories
$ apk update
$ apk add gomplate
...

Note: the Alpine version of gomplate may lag behind the latest release of gomplate.

use with Docker

A simple way to get started is with the Docker image.

$ docker run hairyhenderson/gomplate --version

Of course, there are some drawbacks - any files to be used for [datasources][] must be mounted and any environment variables to be used must be passed through:

$ echo 'My voice is my $THING. {{(datasource "vault").value}}' \
  | docker run -e THING=passport -v /home/me/.vault-token:/root/.vault-token hairyhenderson/gomplate -d vault=vault:///secret/sneakers
My voice is my passport. Verify me.

It can be pretty awkward to always type docker run hairyhenderson/gomplate, so this can be made simpler with a shell alias:

$ alias gomplate=docker run hairyhenderson/gomplate
$ gomplate --version
gomplate version 1.2.3

manual install

1. Get the latest gomplate for your platform from the releases page
2. Store the downloaded binary somewhere in your path as gomplate (or gomplate.exe on Windows)
3. Make sure it's executable (on Linux/macOS)
4. Test it out with gomplate --help!

In other words:

$ curl -o /usr/local/bin/gomplate -sSL https://github.com/hairyhenderson/gomplate/releases/download/<version>/gomplate_<os>-<arch>
$ chmod 755 /usr/local/bin/gomplate
$ gomplate --help
...

Please report any bugs found in the issue tracker.

Usage

The usual and most basic usage of gomplate is to just replace environment variables. All environment variables are available by referencing .Env (or getenv) in the template.

The template is read from standard in, and written to standard out.

Use it like this:

$ echo "Hello, {{.Env.USER}}" | gomplate
Hello, hairyhenderson

Commandline Arguments

--datasource/-d

Add a data source in name=URL form. Specify multiple times to add multiple sources. The data can then be used by the datasource function.

A few different forms are valid:

• mydata=file:///tmp/my/file.json
  • Create a data source named mydata which is read from /tmp/my/file.json. This form is valid for any file in any path.
• mydata=file.json
  • Create a data source named mydata which is read from file.json (in the current working directory). This form is only valid for files in the current directory.
• mydata.json
  • This form infers the name from the file name (without extension). Only valid for files in the current directory.

Syntax

About .Env

You can easily access environment variables with .Env, but there's a catch: if you try to reference an environment variable that doesn't exist, parsing will fail and gomplate will exit with an error condition.

Sometimes, this behaviour is desired; if the output is unusable without certain strings, this is a sure way to know that variables are missing!

If you want different behaviour, try getenv (below).

Built-in functions

In addition to all of the functions and operators that the Go template language provides (if, else, eq, and, or, range, etc...), there are some additional functions baked in to gomplate:

contains

Contains reports whether the second string is contained within the first. Equivalent to strings.Contains

Example

input.tmpl:

{{if contains .Env.FOO "f"}}yes{{else}}no{{end}}

$ FOO=foo gomplate < input.tmpl
yes
$ FOO=bar gomplate < input.tmpl
no

getenv

Exposes the os.Getenv function.

This is a more forgiving alternative to using .Env, since missing keys will return an empty string.

An optional default value can be given as well.

Example

$ echo 'Hello, {{getenv "USER"}}' | gomplate
Hello, hairyhenderson
$ echo 'Hey, {{getenv "FIRSTNAME" "you"}}!' | gomplate
Hey, you!

hasPrefix

Tests whether the string begins with a certain substring. Equivalent to strings.HasPrefix

Example

input.tmpl:

{{if hasPrefix .Env.URL "https"}}foo{{else}}bar{{end}}

$ URL=http://example.com gomplate < input.tmpl
bar
$ URL=https://example.com gomplate < input.tmpl
foo

hasSuffix

Tests whether the string ends with a certain substring. Equivalent to strings.HasSuffix

Example

input.tmpl:

{{.Env.URL}}{{if not (hasSuffix .Env.URL ":80")}}:80{{end}}

$ URL=http://example.com gomplate < input.tmpl
http://example.com:80

bool

Converts a true-ish string to a boolean. Can be used to simplify conditional statements based on environment variables or other text input.

Example

input.tmpl:

{{if bool (getenv "FOO")}}foo{{else}}bar{{end}}

$ gomplate < input.tmpl
bar
$ FOO=true gomplate < input.tmpl
foo

slice

Creates a slice. Useful when needing to range over a bunch of variables.

Example

input.tmpl:

{{range slice "Bart" "Lisa" "Maggie"}}
Hello, {{.}}
{{- end}}

$ gomplate < input.tmpl
Hello, Bart
Hello, Lisa
Hello, Maggie

split

Creates a slice by splitting a string on a given delimiter. Equivalent to strings.Split

Example

input.tmpl:

{{range split "Bart,Lisa,Maggie"}}
Hello, {{.}}
{{- end}}

$ gomplate < input.tmpl
Hello, Bart
Hello, Lisa
Hello, Maggie

title

Convert to title-case. Equivalent to strings.Title

Example

$ echo '{{title "hello, world!"}}' | gomplate
Hello, World!

toLower

Convert to lower-case. Equivalent to strings.ToLower

Example

$ echo '{{toLower "HELLO, WORLD!"}}' | gomplate
hello, world!

toUpper

Convert to upper-case. Equivalent to strings.ToUpper

Example

$ echo '{{toUpper "hello, world!"}}' | gomplate
HELLO, WORLD!

trim

Trims a string by removing the given characters from the beginning and end of the string. Equivalent to strings.Trim

Example

input.tmpl:

Hello, {{trim .Env.FOO " "}}!

$ FOO="  world " | gomplate < input.tmpl
Hello, world!

json

Converts a JSON string into an object. Only works for JSON Objects (not Arrays or other valid JSON types). This can be used to access properties of JSON objects.

Example

input.tmpl:

Hello {{ (getenv "FOO" | json).hello }}

$ export FOO='{"hello":"world"}'
$ gomplate < input.tmpl
Hello world

jsonArray

Converts a JSON string into a slice. Only works for JSON Arrays.

Example

input.tmpl:

Hello {{ index (getenv "FOO" | jsonArray) 1 }}

$ export FOO='[ "you", "world" ]'
$ gomplate < input.tmpl
Hello world

yaml

Converts a YAML string into an object. Only works for YAML Objects (not Arrays or other valid YAML types). This can be used to access properties of YAML objects.

Example

input.tmpl:

Hello {{ (getenv "FOO" | yaml).hello }}

$ export FOO='hello: world'
$ gomplate < input.tmpl
Hello world

yamlArray

Converts a YAML string into a slice. Only works for YAML Arrays.

Example

input.tmpl:

Hello {{ index (getenv "FOO" | yamlArray) 1 }}

$ export FOO='[ "you", "world" ]'
$ gomplate < input.tmpl
Hello world

datasource

Parses a given datasource (provided by the --datasource/-d argument).

Currently, file://, http://, https://, and vault:// URLs are supported.

Currently-supported formats are JSON and YAML.

Examples

Basic usage

person.json:

{
  "name": "Dave"
}

input.tmpl:

Hello {{ (datasource "person").name }}

$ gomplate -d person.json < input.tmpl
Hello Dave

Usage with HTTP data

$ echo 'Hello there, {{(datasource "foo").headers.Host}}...' | gomplate -d foo=https://httpbin.org/get
Hello there, httpbin.org...

Usage with Vault data

The special vault:// URL scheme can be used to retrieve data from Hashicorp Vault. To use this, you must put the Vault server's URL in the $VAULT_ADDR environment variable.

Currently, the app-id auth backend is supported, as well as Vault tokens obtained through external means.

To use a Vault datasource with a single secret, just use a URL of vault:///secret/mysecret. Note the 3 /s - the host portion of the URL is left empty.

$ echo 'My voice is my passport. {{(datasource "vault").value}}' \
  | gomplate -d vault=vault:///secret/sneakers
My voice is my passport. Verify me.

You can also specify the secret path in the template by using a URL of vault:// (or vault:///, or vault:):

$ echo 'My voice is my passport. {{(datasource "vault" "secret/sneakers").value}}' \
  | gomplate -d vault=vault://
My voice is my passport. Verify me.

And the two can be mixed to scope secrets to a specific namespace:

$ echo 'db_password={{(datasource "vault" "db/pass").value}}' \
  | gomplate -d vault=vault:///secret/production
db_password=prodsecret

datasourceExists

Tests whether or not a given datasource was defined on the commandline (with the --datasource/-d argument). This is intended mainly to allow a template to be rendered differently whether or not a given datasource was defined.

Note: this does not verify if the datasource is reachable.

Useful when used in an if/else block

$ echo '{{if (datasourceExists "test")}}{{datasource "test"}}{{else}}no worries{{end}}' | gomplate
no worries

ec2meta

Queries AWS EC2 Instance Metadata for information. This only retrieves data in the meta-data path -- for data in the dynamic path use ec2dynamic.

This only works when running gomplate on an EC2 instance. If the EC2 instance metadata API isn't available, the tool will timeout and fail.

Example

$ echo '{{ec2meta "instance-id"}}' | gomplate
i-12345678

ec2dynamic

Queries AWS EC2 Instance Dynamic Metadata for information. This only retrieves data in the dynamic path -- for data in the meta-data path use ec2meta.

This only works when running gomplate on an EC2 instance. If the EC2 instance metadata API isn't available, the tool will timeout and fail.

Example

$ echo '{{ (ec2dynamic "instance-identity/document" | json).region }}' | ./gomplate
us-east-1

ec2region

Queries AWS to get the region. An optional default can be provided, or returns unknown if it can't be determined for some reason.

Example

In EC2

$ echo '{{ ec2region }}' | ./gomplate
us-east-1

Not in EC2

$ echo '{{ ec2region }}' | ./gomplate
unknown
$ echo '{{ ec2region "foo" }}' | ./gomplate
foo

ec2tag

Queries the AWS EC2 API to find the value of the given user-defined tag. An optional default can be provided.

Example

$ echo 'This server is in the {{ ec2tag "Account" }} account.' | ./gomplate
foo
$ echo 'I am a {{ ec2tag "classification" "meat popsicle" }}.' | ./gomplate
I am a meat popsicle.

Some more complex examples

Variable assignment and if/else

input.tmpl:

{{ $u := getenv "USER" }}
{{ if eq $u "root" -}}
You are root!
{{- else -}}
You are not root :(
{{- end}}

$ gomplate < input.tmpl
You are not root :(
$ sudo gomplate < input.tmpl
You are root!

Releasing

Right now the release process is semi-automatic.

1. Create a release tag: git tag -a v0.0.9 -m "Releasing v0.9.9" && git push --tags
2. Build binaries & compress most of them: make build-release
3. Create a release in github!

License

The MIT License

Copyright (c) 2016 Dave Henderson