rancher-conf

rancher-conf is a file generator that renders templates using Rancher Metadata.

Core features:

• Powerful template syntax that embraces Rancher services, containers and hosts as first-class objects
• Ability to run arbitrary commands when a file has been updated (e.g. to reload an application's configuration)
• Ability to run check commands on staged files before updating the destination files
• Ability to specify multiple template sets using a TOML config file

Usage

Command Line

rancher-conf [options] source [dest]

options

Flag	Description
config	Path to an optional config file. Options specified on the CLI always take precedence.
metadata-url	Metadata endpoint used when querying the Rancher Metadata API. Default: http://rancher-metadata
metadata-version	Metadata version string used when querying the Rancher Metadata API. Default: latest.
include-inactive	Not yet implemented
interval	Interval (in seconds) for polling the Metadata API for changes. Default: 5.
onetime	Process all templates once and exit. Default: false.
log-level	Verbosity of log output. Default: info.
check-cmd	Command to check the content before updating the destination. Use the {{staging}} placeholder to reference the staging file.
notify-cmd	Command to run after the destination file has been updated.
notify-output	Print the result of the notify command to STDOUT.
version	Show application version and exit.

source

Path to the template.

dest

Path to the destination file. If omitted, then the generated content is printed to STDOUT.

Examples

rancher-conf --onetime --notify-cmd="/usr/sbin/service nginx reload" \
/etc/rancher-conf/nginx.tmpl /etc/nginx/nginx.conf

rancher-conf --interval 2 --check-cmd="/usr/sbin/nginx -t -c {{staging}}" \
--notify-cmd="/usr/sbin/service nginx reload" /etc/rancher-conf/nginx.tmpl /etc/nginx/nginx.conf

Configuration file

You can optionally pass a configuration file to rancher-conf. The configuration file is a TOML file. It allows you to specify multiple template sets grouped by template sections. You can specify the same options as on the command line. Options specified on the command line or via environment variables take precedence over the corresponding values in the configuration file. An example file is available here.

How to dynamically configure your applications with Rancher Metadata

You can bundle rancher-conf with the application image or run it as a service sidekick, that exposes the generated configuration file in a shared volume.

Bundled with application image

Download the binary from the release page. Add the binary to your Docker image and provide a mechanism that runs rancher-conf on container start and then executes the main application. This functionality could be provided by a Bash script executed as image ENTRYPOINT. If you want to reload the application whenever the Metadata referenced in the template changes, you can use a container process supervisor (e.g. S6-overlay) to keep rancher-conf running in the background and notify the application when it needs to reload the configuration (by sending it a SIGHUP for example).

Sidekick Container

Create a new Docker image using finboxio/rancher-conf:latest as base. Add the template(s) and configuration file(s) to the image. Expose the configuration folder as VOLUME. Run rancher-conf on container start, specifying relevant options as command line parameters.

Example acme/nginx-config sidekick image

FROM finboxio/rancher-conf:latest
COPY config.toml /etc/rancher-conf/
COPY nginx.tmpl /etc/rancher-conf/
VOLUME /etc/nginx
CMD ["--config", "/etc/rancher-conf/config.toml"]

Example Rancher Compose file

nginx:
  image: nginx:latest
  volumes_from:
  - config-sidekick
  labels:
    io.rancher.sidekicks: template-sidekick
config-sidekick:
  image: acme/nginx-config

Template Language

Templates are Go text templates. In addition to the built-in functions, rancher-conf exposes functions and methods to easily discover Rancher services, containers and hosts.

Service Discovery Objects

type Service struct {
	Name       string
	Stack      string
	Kind       string
	Vip        string
	Fqdn       string
	Ports      []ServicePort
	Labels     LabelMap
	Metadata   MetadataMap
	Containers []*Container
	Parent     *Service
}

type Container struct {
	UUID      string
	Name      string
	Address   string
	Stack     string
	Health    string
	State     string
	Labels    LabelMap
	Service   *Service
	Host      *Host
	Parent    *Container
	Sidekicks []*Container
}

type Host struct {
	UUID     string
	Name     string
	Address  string
	Hostname string
	Labels   LabelMap
}

type Self struct {
	Stack     string
	Service   *Service
	Container *Container
	Host      *Host
}

type ServicePort struct {
	PublicPort   string
	InternalPort string
	Protocol     string
}

The LabelMap and MetadataMap types implement methods for easily checking the existence of specific keys and accessing their values:

Labels.Exists(key string) bool Returns true if the given label key exists in the map.

Labels.GetValue(key, default string) string Returns the value of the given label key. The function accepts an optional default value that is returned when the key doesn't exist or is set to an empty string.

Metadata.Exists(key string) bool Returns true if the given metadata key exists in the map.

Metadata.GetValue(key, default interface{}) interface{} Returns the value of the given label key. The function accepts an optional default value that is returned when the key doesn't exist.

Examples:

Check if the label exists:

{{range services}}
{{if .Labels.Exists "foo"}}
{{do something}}
{{end}}
{{end}}

Get the value of a Metadata key:

{{range services}}
Metadata foo: {{.Metadata.GetValue "foo"}}
{{end}}

Using a default value:

{{range services}}
Label foo: {{.Labels.GetValue "foo" "default value"}}
{{end}}

Service Discovery Functions

host

Lookup a specific host

Optional argument UUID string Return Type Host

If the argument is omitted the local host is returned:

{{host}}

hosts

Lookup hosts

Optional parameters labelSelector string Returned Type []Host

The function returns a slice of Host which can be used for ranging in a template:

{{range hosts}}
host {{.Name}} {{.Address}}
{{end}}

which would produce something like:

host aws-sm-01 148.210.10.10
host aws-sm-02 148.210.10.11

One or multiple label selectors can be passed as arguments to limit the result to hosts with matching labels. The syntax of the label selector is @label-key=label-value.

The following function returns only hosts that have a label "foo" with the value "bar":

{{hosts "@foo=bar"}}

The label selector syntax supports a regex pattern on it's right side. E.g. to lookup hosts that have a specific label regardless of the value:

{{hosts "@foo=.*"}}

If the argument is omitted all hosts are returned:

{{hosts}}

service

Lookup a specific service

Optional parameter serviceIdentifier string Returned Type Service

The function returns a Service struct. You can use the Containers field for ranging over all containers belonging to the service:

{{with service "web.production"}}
{{range .Containers}}
http://{{.Address}}:9090
{{end}}
{{end}}

which would produce something like:

http://10.12.20.111:9090
http://10.12.20.122:9090

The syntax of the serviceIdentifier parameter is service-name[.stack-name]:

{{service "web.production"}}

If the stack name is omitted the service is looked up in the local stack:

{{service "web"}}

If no argument is given the local service is returned:

{{service}}

services

Lookup services matching the given stack and label selectors

Optional parameters stackSelector string labelSelector string Return Type []Service

Just like with the hosts function multiple label selectors can be passed to select services with matching labels:

{{services "@foo=bar"}}

The stack selector parameter uses the syntax .stack-name:

{{services ".production"}}

Stack and label selectors can be combined like this:

{{services ".production" "@foo=bar"}}

If arguments are omitted then all services are returned:

{{services}}

Helper Functions and Pipes

whereLabelExists

Filter a slice of hosts, services or containers returning the items that have the given label key.

Parameters labelKey string input []Host, []Service or []Container Return Type same as input

whereLabelEquals

Filter a slice of hosts, services or containers returning the items that have the given label key and value.

Arguments labelKey string labelValue string input []Host, []Service or []Container Return Type same as input

{{$ervice := service "web.production"}}
{{range $container := whereLabelEquals "foo" "bar" $service.Containers}}
{{do something with $container}}
{{end}}

whereLabelMatches

Filter a slice of hosts, services or containers returning the items that have the given label and a value matching the regex pattern.

Arguments labelKey string regexPattern string input []Host, []Service or []Container Return Type same as input

groupByLabel

This function takes a slice of hosts, services or containers and groups the items by their value of the given label. It returns a map with label values as key and a slice of corresponding elements items as value.

Arguments label-key string input []Host,[]Service,[]Container Return Type map[string][]Host/[]Service/[]Container

{{range $labelValue, $hosts := hosts | groupByLabel "foo"}}
{{$labelValue}}
{{range $hosts}}
IP: {{.Address}}
{{end}}
{{end}}

base

Alias for the path.Base function

filename: {{$service.Metadata.GetValue "targetPath" | base}}

See Go's path.Base() for more information.

dir

Alias for the path.Dir function

See Go's path.Dir() for more information.

env

Returns the value of the given environment variable or an empty string if the variable isn't set

{{env "FOO_VAR"}}

timestamp

Alias for time.Now

# Generated by rancher-conf {{timestamp}}

The timestamp can be formatted as required by invoking the Format method:

# Generated by rancher-conf {{timestamp.Format "Jan 2, 2006 15:04"}}

See Go's time.Format() for more information about formatting the date according to the layout of the reference time.

split

Alias for strings.Split

{{$items := split $someString ":"}}

See Go's strings.Split() for more information.

join

Alias for strings.Join Takes the given slice of strings as a pipe and joins them on the provided string:

{{$items | join ","}}

See Go's strings.Join() for more information.

toLower

Alias for strings.ToLower Takes the argument as a string and converts it to lowercase.

{{$svc.Metadata.GetValue "foo" | toLower}}

See Go's strings.ToLower() for more information.

toUpper

Alias for strings.ToUpper Takes the argument as a string and converts it to uppercase.

{{$svc.Metadata.GetValue "foo" | toUpper}}

See Go's strings.ToUpper() for more information.

contains

Alias for strings.Contains

See Go's strings.Contains() for more information.

replace

Alias for strings.Replace

{{$foo := $svc.Labels.GetValue "foo"}}
foo: {{replace $foo "-" "_" -1}}

See Go's strings.Replace() for more information.

Examples

TODO