Skip to content

Commit

Permalink
Write better documentation that describes all the features
Browse files Browse the repository at this point in the history
  • Loading branch information
@ekini
Eugene Dementiev authored and ekini committed Dec 2, 2019
1 parent fd68ef3 commit 1ceb81c
Showing 1 changed file with 75 additions and 36 deletions.
111 changes: 75 additions & 36 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.:

```
{
Expand Down Expand Up @@ -49,50 +80,58 @@ 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
```
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", "--"]
Expand All @@ -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
Expand All @@ -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.
```
Expand All @@ -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
Expand Down

0 comments on commit 1ceb81c

Please sign in to comment.