github.com/nxadm/ctwrapper@v0.5.3-0.20200107113753-fb73fb7c1f50/README.md (about) 1 # ctwrapper 2 [![Build Status](https://travis-ci.com/nxadm/ctwrapper.svg?branch=master)](https://travis-ci.com/nxadm/ctwrapper) 3 4 ctwrapper is a small git wrapper to interface with Hashicorp's 5 [consul-template](https://github.com/hashicorp/consul-template). The use case 6 for this tool is providing remote configuration and secrets to containers that 7 require a complex configuration. Many orchestrators and tools, like 8 Hashicorp's [nomad](https://github.com/hashicorp/nomad), only provide 9 mechanisms to provision containers with simple 1-file configuration 10 requirements, e.g. by the 11 [template stanza](https://www.nomadproject.io/docs/job-specification/template.html). 12 13 As an alternative, ctwrapper retrieves a git repository with static files and 14 templates. Templates are passed as arguments to consul-template in order to 15 let consul-template run them and, by example, inject secrets from Vault. 16 Options can be passed to consul-template after "--", e.g. "-exec" to run the 17 actual application. In order to disable Vault support (e.g. when you inject 18 secret by environment variables), pass the "-vault-renew-token=false" option 19 to consul-template. 20 21 In order to use the 22 [consul](https://github.com/hashicorp/consul) and 23 [vault](https://github.com/hashicorp/vault) backends you need to define the 24 necessary environment variables (like VAULT_ADDR, VAULT_TOKEN and/or 25 CONSUL_TOKEN) or pass the '-consul-addr' and/or '-vault-addr' options to 26 consul-template (as passthrough after the '--'). Consult the 27 [consul-template documentation](https://github.com/hashicorp/consul-template) 28 for the parameters for consul-template. 29 30 Anonymous and authenticated git cloning is supported through SSH and HTTP(s). 31 Next to SSH (where the authentication is done by an SSH agent), HTTP(S) Basic 32 Authentication can use the username/password combination supplied on the command 33 line or retrieve the password from Vault. If no authentication is provided, 34 the repo will be retrieved anonymously. 35 36 ctwrapper, being a wrapper for consul-template, expects the latter to be in the 37 PATH or in the working directory. When run from a Docker container, use 38 [the exec variant of ENTRYPOINT and not the shell variant](https://docs.docker.com/engine/reference/builder/#entrypoint). 39 This allows ctwrapper to to preserve the signals received by the container and 40 pass it to consul-template and your application. 41 42 ## Usage 43 44 ``` 45 Usage: 46 ctwrapper [-r <URL>] [-b <branch>] [-c <commit>] [-g <gitDepth>] [-d <dir>] 47 [-e <extension>] [-u <git user>] 48 [-p <git password> | -s <vault path for git password>] 49 [-- <extra consul-template parameters>] 50 ctwrapper [-h] 51 ctwrapper [-v] 52 53 54 Parameters: 55 -r | --repo : Git repo URL. 56 -d | --dir : Directory to download the repo [default: /project]. 57 -b | --branch : Git branch [default: master] 58 -c | --commit : Git commit [default: HEAD]. 59 -g | --git-depth : Git depth [default: 0 (unlimited)]. 60 -u | --git-user : Git HTTPS username (when not using SSH). 61 -p | --git-password : Git HTTPS password (when not using SSH). 62 -s | --git-pass-vault-path : Retrieve the git HTTPS password at Vault path 63 (including the backend). 64 -e | --ext : Template extension [defaul: .tmpl]. 65 -h | --help : This help message. 66 -v | --version : Version message. 67 -- : Extra consul-template parameters, e.g. -exec. 68 69 Besides the default values when applicable, all the parameters can be 70 passed as environment variables by using the full parameter name in capitals 71 without '-': 72 REPO, DIR, BRANCH, COMMIT, GITDEPTH, GITUSER, GITPASSWORD, VAULTPATH, EXT. 73 74 When both command line parameters and environment variables are defined, 75 the first type take precedence. 76 77 For the Vault parameters used in templates, these are retrieved from 78 environment values like VAULT_ADDR, VAULT_TOKEN and other VAULT_* variables). 79 80 Examples: 81 $ ctwrapper -- "echo lala" 82 $ ctwrapper -r git@github.com:nxadm/ctwrapper.git 83 $ ctwrapper -r https://github.com/nxadm/ctwrapper.git -d /var/tmp/project \ 84 -s "secret/production/third-party/repo-password" 85 $ ctwrapper -r https://github.com/nxadm/ctwrapper.git -u foo -p bar \ 86 -d /project -- -vault-addr 'https://10.5.32.5:8200 -exec /sbin/my-server 87 ``` 88 89 You may want to set the depth to a low number (e.g.) in order not to 90 unnecessarily retrieve the complete history of the repo. The `--commit` and 91 `--git-depth` options were included in order to prevent a race condition 92 between CI systems and git commits. If your setup ensures that the specified 93 commit is the last one, you can set `--git-depth` to 1. 94 95 Everything after `--` is directly passed as-is to consul-template. In the most 96 cases you'll pass an `-exec` command to consul-template to start your 97 application this way (quote the command). 98 99 ## Releases 100 101 The creation of binaries found on the 102 [releases tab](https://github.com/nxadm/ctwrapper/releases) is completely 103 automated by Travis CI and created from a version tag in the repo. The 104 sha512 checkums files can be verified with the output of the 105 [Travis build](https://travis-ci.com/nxadm/ctwrapper/branches).