ctwrapper

README

ctwrapper

ctwrapper is a small git wrapper to interface with Hashicorp's consul-template. The use case for this tool is providing remote configuration and secrets to containers that require a complex configuration. Many orchestrators and tools, like Hashicorp's nomad, only provide mechanisms to provision containers with simple 1-file configuration requirements, e.g. by the template stanza.

As an alternative, ctwrapper retrieves a git repository with static files and templates. Templates are passed as arguments to consul-template in order to let consul-template run them and, by example, inject secrets from Vault. Options can be passed to consul-template, e.g. "-exec" to run the actual application.

In order to use the consul and
vault backends you need to define the necessary environment variables (like VAULT_ADDR, VAULT_TOKEN and/or CONSUL_TOKEN) or pass the '-consul-addr' and/or '-vault-addr' options to consul-template (as passthrough after the '--'). Consult the consul-template documentation for the parameters for consul-template.

Anonymous and authenticated git cloning is supported through SSH and HTTP(s). Next to SSH (where the authentication is done by an SSH agent), HTTP(S) Basic Authentication can use the username/password combination supplied on the command line or retrieve the password from Vault. If no authentication is provided, the repo will be retrieved anonymously.

ctwrapper, being a wrapper for consul-template, expects the latter to be in the PATH or in the working directory.

Usage

Usage:
  ctwrapper [-r <URL>] [-b <branch>] [-c <commit>] [-g <gitDepth>] [-d <dir>]
            [-e <extension>] [-u <git user>]
			[-p <git password> | -s <vault path for git password>]
            [-- <extra consul-template parameters>]
  ctwrapper [-h]
  ctwrapper [-v]


Parameters:
  -r  | --repo                : Git repo URL.
  -d  | --dir                 : Directory to download the repo [default: /project].
  -b  | --branch              : Git branch [default: master]
  -c  | --commit              : Git commit [default: HEAD].
  -g  | --git-depth           : Git depth  [default: 0 (unlimited)].
  -u  | --git-user            : Git HTTPS username (when not using SSH).
  -p  | --git-password        : Git HTTPS password (when not using SSH).
  -s  | --git-pass-vault-path : Retrieve the git HTTPS password at Vault path
                                (including the backend).
  -e  | --ext                 : Template extension [defaul: .tmpl].
  -h  | --help                : This help message.
  -v  | --version             : Version message.
  --                          : Extra consul-template parameters, e.g. -exec.

Besides the default values when applicable, all the parameters can be
passed as environment variables by using the full parameter name in capitals
without '-':
REPO, DIR, BRANCH, COMMIT, GITDEPTH, GITUSER, GITPASSWORD, VAULTPATH, EXT.

When both command line parameters and environment variables are defined,
the first type take precedence.

For the Vault parameters used in templates, these are retrieved from
environment values like VAULT_ADDR, VAULT_TOKEN and other VAULT_* variables).

Examples:
  $ ctwrapper -- "echo lala"                                                                       
  $ ctwrapper -r git@github.com:nxadm/ctwrapper.git      
  $ ctwrapper -r https://github.com/nxadm/ctwrapper.git -d /var/tmp/project \           
    -s "secret/production/third-party/repo-password"                            
  $ ctwrapper -r https://github.com/nxadm/ctwrapper.git -u foo -p bar \           
    -d /project -- -vault-addr 'https://10.5.32.5:8200 -exec /sbin/my-server

You may want to set the depth to a low number (e.g.) in order not to unnecessarily retrieve the complete history of the repo. The --commit and --git-depth options were included in order to prevent a race condition between CI systems and git commits. If your setup ensures that the specified commit is the last one, you can set --git-depth to 1.

Everything after -- is directly passed as-is to consul-template. In the most cases you'll pass an -exec command to consul-template to start your application this way (quote the command).

Releases

The creation of binaries found on the releases tab is completely automated by Travis CI and created from a version tag in the repo. The sha512 checkums files can be verified with the output of the Travis build.