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).