voletc

README

vol-etc

Overview

voletc (pronounced vol etc) is a Docker Volume Plugin that allows to create volumes containing application configurations that can be accessed on any of your docker nodes.

Once created the application no longer needs to worry about obtaining application specific configurations. The mounted volume will contain all of config file/s based on the templates and keys you've specified during volume creation.

The configuration data can be stored in consul or etcd but currently only consul support exists.

A config volume name must be in the following format

<name>-<version>-<environment>

Based on this a volume is created per unique name, version and environment. The layout looks like this:

• Each application has versions.
• Each version contains an associated template along with environments.
• Each environment contains its keys.
• Templates are shared across each environment and per environment keys are applied to the template

Volumes can be managed directly through docker and via the CLI.

Docker

The Docker CLI can be used to manage volumes using the voletc driver and driver specific options.

Creating volumes

docker volume create --name test-0.1.0-dev -d voletc \
	--opt=subpath/key=value \
	--opt=template:config.json='{"key":"${subpath/key}"}'

This creates a config volume with a template that will be called config.json and will also contain a key called subpath/key with a value of value persisting them to the backend. When docker requests the volume to be mounted the configuration files will be dynamically generated and available on the newly created volume.

template is a keyword signifying that key contains template data rather than just key value data.

Using volumes

docker run --rm -it -v test-0.1.1-dev:/opt/myconfigs/ busbox

Your config should now be available at /opt/myconfigs/config.json in the running container. If there are multiple config files they will all be located under /opt/myconfigs. The naming of the config is controlled by what has been supplied as part of the --opt=template:<name>.<ext> argument at the time of creation.

Removing volumes

docker volume rm test-0.1.1-dev

Removing a volume removes all the associated keys from the backend for the given environment. It does not remove the template (as it is associated to the version).

Currently, there is not a way via Docker to change volumes configs once they have been created. You can either use the CLI or destroy and re-create the volume.

Command Line

The command line tool provides more functionality in regards to volume management than are available through docker.

Usage:

  voletc [options] <cmd> [name] [key=value] [key=value]

  vol etc is a distributed, persistent configuration volume with Docker
  support.  It is a tool that runs as a service as well as a tool to
  manage volumes.

  Key-value pairs are are specified in the following format: path/to/key=value.
  Templates and template files are also specified in the same format but must be
  prefixed with 'template:'.  When using file paths, absolute or relative paths
  must be specified

  Key-Value Examples:

  - Template key with file path as value.  The contents of the file are used.

    template:config.json=./etc/config.json

  - Template key with content as value

    template:config.json='{"k": "${path/to/key}"}'

  - Key-Value

    db/host=127.0.0.1

Commands:

  ls        List volumes
  create    Create new volume
  edit      Edit volume configurations
  info      Show volume info
  rm        Destroy volume i.e. remove all keys
  render    Show rendered volume templates
  mount     Mount config volume via fuse (experimental)
  version   Show version

Global Options:

  -H        Backend URI                       (default: consul://localhost:8500)
  -prefix   Prefix on filesystem and backend  (default: voletc)
  -server   Start docker plugin service

Service Options:

  -b        Address the service listens on    (default: 127.0.0.1:8989)
  -dir      Directory to store data under     (default: /opt)

Client Options:

  -e        Key to encrypt/decrypt data.  Must be atleast 16
            characters in length.

Aside from the global options each command also has its specific options.

Create a volume

voletc create test-0.1.1-dev \
	db/name=dbname \
	db/user=dbuser \
	template:config.json=./config.json \
	template:inline.json='{"db_name": "${db/name}", "db_user": "${db/user}"}'

To simply simulate the creation rather than actually creating the volume, use the -dryrun flag.

Get volume details

voletc info test-0.1.1-dev

List volumes

voletc ls

Edit a volume

voletc edit test-0.1.1-dev db/user=new_user

To simply simulate the update rather than actually updating the volume configs, use the -dryrun flag.

Render volume templates

voletc render test-0.1.1-dev

Remove a volume

voletc rm test-0.1.1-dev

To remove the volume without being prompted include the -y flag.

Installation

The current supported platforms are Linux and OS X. Download the package from the releases page.

Linux

Download the linux package from here. Once downloaded, untar and execute the installer.

# Untar
tar -C / -zxf voletc-0.1.6-linux.tgz

This will install the binary and startup script in the following locations.

• /usr/local/bin/voletc
• /etc/init/voletc.conf

You can now start/stop the daemon as follows:

# Start the agent
start voletc

# Make sure it is running
status voletc

To troubleshoot the service check the log located at /var/log/voletc.log

OS X

Download the darwin package from here. Once downloaded, untar the package. You can now start using the voletc binary. A detailed description on the usage can be found in the CLI section.

Roadmap

• Support for an encryption interface for stored data.
• Support for etcd as a backend.