diff --git a/README.md b/README.md index e8ade54..5e8570c 100644 --- a/README.md +++ b/README.md @@ -3,14 +3,45 @@ SSM Parent ---------- -This is mostly a parent process for Docker with one addition: it can read from AWS SSM Parameter store. +This is wrapper entrypoint for Docker to do one thing: fetch parameters from SSM Parameter store and expose them as environment variables to the underlying process. Please note, that it still requires a proper `init` process, for example the one embedded into Docker can be used with `docker run --init`. -The way it works is that ssm-parent can be used as an entrypoint for Docker. Firstly, it retrieves all specified parameters, then injects them to the environment, -and finally runs the command using `execve` syscall. +``` +SSM-Parent is a docker entrypoint. + +It gets specified parameters (possibly secret) from AWS SSM Parameter Store, +then exports them to the underlying process. Or creates a .env file to be consumed by an application. + +It reads parameters in the following order: path->name->plain-path->plain-name. +So that every rightmost parameter overrides the previous one. + +Usage: + ssm-parent [command] + +Available Commands: + dotenv Writes dotenv file + help Help about any command + print Prints the specified parameters. + run Runs the specified command + +Flags: + -c, --config string Path to the config file (optional). Allows to set transformations + -d, --debug Turn on debug logging + -e, --expand Expand arguments and values using shell-style syntax + -h, --help help for ssm-parent + -n, --name strings Name of the SSM parameter to retrieve. Expects JSON in the value. Can be specified multiple times. + -p, --path strings Path to a SSM parameter. Expects JSON in the value. Can be specified multiple times. + --plain-name strings Name of the SSM parameter to retrieve. Expects actual parameter in the value. Can be specified multiple times. + --plain-path strings Path to a SSM parameter. Expects actual parameter in the value. Can be specified multiple times. + -r, --recursive Walk through the provided SSM paths recursively. + -s, --strict Strict mode. Fail if found less parameters than number of names. + --version version for ssm-parent + +Use "ssm-parent [command] --help" for more information about a command. +``` -All parameters must be in JSON format, i.e.: +The SSM parameter names or paths can be specified with `-p` or `-n` flags. In this case all parameters must be in JSON format, i.e.: ``` { @@ -49,42 +80,50 @@ One can also specify `--plain-name` and `--plain-path` command line options to r ### How to use +Determine the paths you want to read and try it out with `ssm-parent print` to see the resulting JSON output. +Then use `ssm-parent run` or `ssm-parent dotenv`. -That should be pretty self-explanatory. +### Variables transformations -``` -SSM-Parent is a docker entrypoint. +To transform variables, a config file is needed due to the complex nature of it. `ssm-parent` supports all config formats supported by https://github.com/spf13/viper, i.e. `.toml`, `.yaml`, `.json`. -It gets specified parameters (possibly secret) from AWS SSM Parameter Store, -then exports them to the underlying process. Or creates a .env file to be consumed by an application. +All configuration entities can be specified in there rather than as flags. +The supported transformations are: -It reads parameters in the following order: path->name->plain-path->plain-name. -So that every rightmost parameter overrides the previous one. +1. rename - renames env vars +2. delete - deletes env vars +3. template - templates env vars -Usage: - ssm-parent [command] +Rename and template transormations expect a dictionary rule. The delete transormation expects an array. +Template transformation uses (Go templates)[https://golang.org/pkg/text/template/], and the environment variables map is passed as `.`. -Available Commands: - dotenv Writes dotenv file - help Help about any command - print Prints the specified parameters. - run Runs the specified command +There are the following extra functions available in templates: url_host, url_user, url_password, url_path, url_scheme and trim_prefix. The current list of the custom functions can be found here https://github.com/springload/ssm-parent/blob/master/ssm/transformations/template_funcs.go#L9 -Flags: - -e, --expand Expand arguments and values using shell-style syntax - -h, --help help for ssm-parent - -n, --name stringArray Name of the SSM parameter to retrieve. Expects JSON in the value. Can be specified multiple times. - -p, --path stringArray Path to a SSM parameter. Expects JSON in the value. Can be specified multiple times. - --plain-name stringArray Name of the SSM parameter to retrieve. Expects actual parameter in the value. Can be specified multiple times. - --plain-path stringArray Path to a SSM parameter. Expects actual parameter in the value. Can be specified multiple times. - -r, --recursive Walk through the provided SSM paths recursively. - -s, --strict Strict mode. Fail if found less parameters than number of names. - --version version for ssm-parent +There is practically no limit on the number of transformations and they are applied in order from top to the bottom. -Use "ssm-parent [command] --help" for more information about a command. -``` +Below there is an example that recursively gets parameters from `/$PROJECT/common/` and `/$PROJECT/$ENVIRONMENT` and constructs variables out of +`DATABASE_URL` to be consumed by an PHP application. It also renames `AWS_BUCKET` to `AWS_S3_BUCKET` and removes `DATABASE_URL` afterwards. -The command `ssm-parent print` can be used to check the result. +```yaml +recursive: true +expand: true +debug: true +paths: ["/$PROJECT/common/", "/$PROJECT/$ENVIRONMENT"] + +transformations: + - action: template + rule: + SS_DATABASE_SERVER: "{{ url_host .DATABASE_URL }}" + SS_DATABASE_USERNAME: "{{ url_user .DATABASE_URL }}" + SS_DATABASE_PASSWORD: "{{ url_password .DATABASE_URL }}" + SS_DATABASE_NAME: "{{ with $x := url_path .DATABASE_URL }}{{ trim_prefix $x \"/\" }}{{end}}" + - action: rename + rule: + AWS_BUCKET: AWS_S3_BUCKET + - action: delete + rule: + - DATABASE_URL +``` ### Example Dockerfile part @@ -92,7 +131,7 @@ The command `ssm-parent print` can be used to check the result. ENV PROJECT myproject ENV ENVIRONMENT production -RUN wget -O /tmp/ssm-parent.tar.gz https://github.com/springload/ssm-parent/releases/download/v0.9/ssm-parent_0.9_linux_amd64.tar.gz && \ +RUN wget -O /tmp/ssm-parent.tar.gz https://github.com/springload/ssm-parent/releases/download/v1.4.1/ssm-parent_1.4.1_linux_amd64.tar.gz && \ tar xvf /tmp/ssm-parent.tar.gz && mv ssm-parent /usr/bin/ssm-parent && rm /tmp/ssm-parent.tar.gz ENTRYPOINT ["/usr/bin/ssm-parent", "run", "-e", "-p", "/$PROJECT/$ENVIRONMENT/backend/", "-r", "--"] @@ -102,8 +141,8 @@ CMD ["caddy" , "--conf", "/etc/Caddyfile", "--log", "stdout"] ### Use as a Docker stage ``` -# get the ssm-parent as a stage -FROM springload/ssm-parent as ssm-parent +# get the ssm-parent as a Docker stage +FROM springload/ssm-parent:1.4.1 as ssm-parent # your main stage FROM alpine @@ -130,7 +169,7 @@ exec $@ ### .env file generation -Sometimes you just want a .env file, and now it is also possible. +Sometimes you just want a .env file, and it is also possible. Just specify all the same parameters, but use `dotenv` command instead with a filename to generate `.env` file. ``` @@ -140,7 +179,7 @@ Just specify all the same parameters, but use `dotenv` command instead with a fi ### How to build -This project uses `go mod` as a dependency manager. Go v.1.12 was used. +This project uses `go mod` as a dependency manager. Go v.1.13 was used. ``` $git clone https://github.com/springload/ssm-parent.git