Home

Awesome

kube-template

Inspired by HashiCorp's Consul Template, kube-template is a utility that queries a Kubernetes API server and uses its objects as input data for specified set of templates. Also it can run arbitrary commands for templates with updated output.

Please note this is a work in progress.

Build Status

Installation

Go 1.13+ is required to build kube-template. Check your version with go version before build.

Docker

If you want to create a Docker image

Note - the built image is already configured to automatically locate Kubernetes API along with everything is needed to connect (e.g. Certificate Authority file, security token and so on).

Usage

Options

      --alsologtostderr                  log to standard error as well as files
      --command-timeout duration         Default command execution timeout (0 to execute commands without timeout checking) (default 15s)
  -c, --config string                    config file (default is ./kube-template.(yaml|json))
      --dry-run                          don't write template output, dump result to stdout
      --guess-kube-api-settings          guess Kubernetes API settings from POD environment
      --help-md                          get help in Markdown format
  -k, --kube-config string               Kubernetes config file to use
  -l, --left-delimiter string            templating left delimiter (default "{{")
      --log-backtrace-at traceLocation   when logging hits line file:N, emit a stack trace (default :0)
      --log-dir string                   If non-empty, write log files in this directory
      --log-flush-frequency duration     Maximum number of seconds between log flushes (default 5s)
      --logtostderr                      log to standard error instead of files (default true)
      --master string                    Kubernetes API server address (default is http://127.0.0.1:8080/)
      --once                             run template processing once and exit
  -p, --poll-period duration             Kubernetes API server poll period (0 disables server polling) (default 15s)
  -r, --right-delimiter string           templating right delimiter (default "}}")
      --stderrthreshold severity         logs at or above this threshold go to stderr (default 2)
  -t, --template stringSlice             adds a new template to watch on disk in the format
		'templatePath:outputPath[:command]'. This option is additive
		and may be specified multiple times for multiple templates
  -v, --v Level                          log level for V logs
      --version                          display the version number and build timestamp
      --vmodule moduleSpec               comma-separated list of pattern=N settings for file-filtered logging

Command Line

Process single template using data from remote Kubernetes API server and exit:

$ kube-template \
    --master="http://kube-api.server.com:8080" \
    --template="/tmp/input.tmpl:/tmp/output.txt" \ 
    --once

Monitor local Kubernetes API server for updates every 30 seconds and update nginx and haproxy configuration files with reload:

$ kube-template \
    --template="/tmp/nginx.tmpl:/etc/nginx/nginx.conf:service nginx reload" \ 
    --template="/tmp/haproxy.tmpl:/etc/haproxy/haproxy.conf:service haproxy reload" \
    --poll-time=30s

Configuration File

kube-template looks for kube-template.json or kube-template.yaml configuration file in current working directory or file name specified by --config command line option.

YAML configuration file example:

 master: http://localhost:8080
 poll-period: 10s
 command-timeout: 30s

 templates:
   - path: in.txt.tmpl
     output: out.txt
     command: action.sh
     command-timeout: 60s

   - path: in.html.tmpl
     output: out.html

Please note: templates specified on the command line take precedence over those defined in a config file.

Signals

Templating Language

kube-template works with templates in the Go Template format. In addition to the standard template functions, kube-template provides the following functions:

Kubernetes API

pods
{{pods "selector" "namespace"}}

Query Kubernetes API server for pods from given namespace (default if not specified) matching given selector (empty to get all pods).

Example:

{{range pods}}
{{.Name}}: {{.Status.Phase}}
{{end}}
services
{{services "selector" "namespace"}}

Query Kubernetes API server for services from given namespace (default if not specified) matching given selector (empty to get all services).

replicationcontrollers
{{replicationcontrollers "selector" "namespace"}}

Query Kubernetes API server for replication controllers from given namespace (default if not specified) matching given selector (empty to get all replication controllers).

events
{{events "selector" "namespace"}}

Query Kubernetes API server for events from given namespace (default if not specified) matching given selector (empty to get all events).

endpoints
{{endpoints "selector" "namespace"}}

Query Kubernetes API server for endpoints from given namespace (default if not specified) matching given selector (empty to get all endpoints).

nodes
{{nodes "selector"}}

Query Kubernetes API server for nodes matching given selector (empty to get all nodes).

namespaces
{{namespaces "selector"}}

Query Kubernetes API server for namespaces matching given selector (empty to get all namespaces).

componentstatuses
{{componentstatuses "selector"}}

Query Kubernetes API server for component statuses matching given selector (empty to get all componentstatuses).

configmaps
{{configmaps "selector" "namespace"}}

Query Kubernetes API server for config maps from given namespace (default if not specified) matching given selector (empty to get all configmaps).

limitranges
{{limitranges "selector" "namespace"}}

Query Kubernetes API server for limit ranges from given namespace (default if not specified) matching given selector (empty to get all limitranges).

persistentvolumes
{{persistentvolumes "selector"}}

Query Kubernetes API server for persistent volumes matching given selector (empty to get all persistentvolumes).

persistentvolumeclaims
{{persistentvolumeclaims "selector" "namespace"}}

Query Kubernetes API server for persistent volume claims from given namespace (default if not specified) matching given selector (empty to get all persistentvolumeclaims).

podtemplates
{{podtemplates "selector" "namespace"}}

Query Kubernetes API server for pod templates from given namespace (default if not specified) matching given selector (empty to get all podtemplates).

resourcequotas
{{resourcequotas "selector" "namespace"}}

Query Kubernetes API server for resource quotas from given namespace (default if not specified) matching given selector (empty to get all resourcequotas).

secrets
{{secrets "selector" "namespace"}}

Query Kubernetes API server for secrets from given namespace (default if not specified) matching given selector (empty to get all secrets).

serviceaccounts
{{serviceaccounts "selector" "namespace"}}

Query Kubernetes API server for service accounts from given namespace (default if not specified) matching given selector (empty to get all serviceaccounts).

Helper Functions

All Sprig library template functions (string/math/date/etc) are supported (thanks @bpineau).

EXAMPLES

Populate nginx upstream with pods labeled 'name=test-pod':

upstream test-pod-upstream {
{{with $pods := pods "name=test-pod"}}
    ip_hash;
    {{range $pods}}
    server {{.Status.PodIP}}:8080;
    {{end}}
{{else}}
    # No pods with given label were found, use stub server
    server 127.0.0.1:8081;
{{end}}
}

Create haproxy TCP balancer for pods listening on container port 9000:

{{with $pods := pods "name=test-pod"}}
{{$maxconn := 1000}}
listen test-pod-balancer
    bind *:9000
    mode tcp
    maxconn {{mul $maxconn (len $pods)}}
    balance roundrobin
    {{range $pods}}
    server {{.Name}} {{.Status.PodIP}}:9000 maxconn {{$maxconn}} check inter 5000 rise 3 fall 3
    {{end}}
    server stub 127.0.0.1:7690 backup
{{end}}

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request

License

kube-template is released under the Apache 2.0 license. See LICENSE.txt