Merge pull request #201 from cyberark/summon-symlinks

Adding an example of using symbolic links to map to a tempfile.

README.md

@@ -148,7 +148,8 @@ VARIABLE_WITH_DEFAULT: !var:default='defaultvalue' path/to/variable
 
 `summon` supports a number of flags.
 
-* `-p, --provider` specify the path to the [provider](provider/README.md) summon should use.
+* `-p, --provider <path-to-provider>` specify the path to the
+[provider](provider/README.md) summon should use.
 
     If the provider is in the default path, `/usr/local/lib/summon/` (or
     `%ProgramW6432%\Cyberark Conjur\Summon\Providers` on Windows) you can just
@@ -174,12 +175,13 @@ VARIABLE_WITH_DEFAULT: !var:default='defaultvalue' path/to/variable
     summon -D ENV=production --yaml 'SQL_PASSWORD: !var env/$ENV/db-password' deploy.sh
     ```
 
-* `--yaml` secrets.yml as a literal string.
+* `--yaml <YAML-string>` Passes secrets.yml as a literal string.
 
-    This flag is used to pass `secrets.yml` to the provider as a literal string
-    (see example above).
+    This flag is used to pass a literal YAML string to the provider in place
+    of the `secrets.yml` file (see example above).
 
-* `-i, --ignore` A secret path for which to ignore provider errors.
+* `-i, --ignore <path-to-provider>` A secret path for which to ignore provider
+errors.
 
     This flag can be useful for when you have secrets that you don't need access to for development. For example API keys for monitoring tools. This flag can be used multiple times.
 
@@ -228,6 +230,13 @@ This file is created on demand - only when `@SUMMONENVFILE` appears in the
 arguments of the command summon is wrapping. This feature is not Docker-specific; if you have another tools that reads variables in `VAR=VAL` format
 you can use `@SUMMONENVFILE` just the same.
 
+## Fixed tempfile name
+
+There are times when you would like to have certain secrets values available at
+fixed locations, e.g. `/etc/ssl/cert.pem` for an SSL certificate. This can be
+accomplished by using symbolic links as described in the
+[symbolic link example](examples/symlinks/README.md).
+
 ## Contributing
 
 For more info on contributing, please see [CONTRIBUTING.md](CONTRIBUTING.md).

examples/symlinks/README.md

@@ -0,0 +1,57 @@
+# Using Symbolic links to specify a fixed file name
+
+The scripts here can be used with Summon to populate a specific file
+as was noted in this [issue](https://github.com/cyberark/summon/issues/190).
+Here are two examples of using Summon with symbolic links.
+
+## Method 1
+
+When you have a relatively small number of secrets variables that you'd
+like to map to fixed file locations, you can invoke Summon with
+commands to explicitly add symbolic links before, and to remove those
+symbolic links after calling your application script.
+
+__For example:__
+
+Set the provider environmental variable and use `cat` as the user app.
+
+```
+summon sh -c 'ln -sf $FOO secrets-dir/foo.example.com &&
+cat secrets-dir/foo.example.com && rm secrets-dir/foo.example.com'
+```
+
+## Method 2
+
+When you have several secrets variables that you'd like to map to
+fixed locations, then you may want to use the `summon-symlinks` helper
+script that is in the example directory.
+
+This script provides a wrapper for a Summon subcommand to
+perform the following:
+
+- Add symbolic links mapping tempfiles for given secrets variables to
+   fixed locations (before invoking subcommand)
+- Remove these symbolic links (after invoking subcommand)
+
+Summon-symlinks uses an additional yaml file called secrets-symlinks.yml.
+This yaml file maps the secrets variable to the fixed file location.
+You can specify what file that `summon-symlinks` will use by setting
+the `SUMMON_SYMLINKS` environmental variable.
+If `SUMMON_SYMLINKS` is not set it defaults to secrets-symlinks.yml.
+
+__For example:__
+
+Set the provider environmental variable and use `cat` as the user app.
+
+```
+summon ./summon-symlinks cat secrets-dir/foo.example.com
+```
+
+__NOTE: Care should be take to avoid running the commands described
+for either Method 1 or Method 2 concurrently.
+In these examples we remove the symbolic link as the last step.
+If multiple session are running concurrently the symbolic link could be
+removed by the first session that ends. If removing the symbolic link is
+ommitted, the symbolic link will be orphaned.__
+
+The above examples were tested in a Linux (Ubuntu) end macOS nvironment.

examples/symlinks/secrets-symlinks.yml

@@ -0,0 +1,2 @@
+FOO: secrets-dir/foo.example.com
+BAR: secrets-dir/bar.example.com

examples/symlinks/secrets.yml

@@ -0,0 +1,2 @@
+FOO: !file:var example.com/foo
+BAR: !file:var example.com/bar

examples/symlinks/summon-symlinks

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+parse_symlink() {
+  while IFS=':' read -r a b; do
+    # Remove leading and trailing spaces from key and value.
+    # shellcheck disable=SC2001
+    a=$(echo "${a}" | sed 's/^[ \t]*//;s/[ \t]*$//')
+    b=$(echo "${b}" | sed 's/^[ \t]*//;s/[ \t]*$//')
+    if [ $# -ne 0 ]
+      then
+        ln -sf "$(printenv "${a}")" "$b"
+    else
+        rm "$b" 
+    fi
+  done < "${SUMMON_SYMLINKS:-./secrets-symlinks.yml}"
+}
+
+
+function cleanup() {
+  parse_symlink
+}
+
+parse_symlink init
+
+trap cleanup EXIT
+"$@"