Merge pull request #29 from github/kpaulisse-documentation-environment

Document environment variable passing for bootstrap and ENC

Author: kpaulisse

doc/advanced-bootstrap.md

@@ -31,3 +31,28 @@ The [example configuration file](/examples/octocatalog-diff.cfg.rb) contains an
 # settings[:bootstrap_script] = '/etc/puppetlabs/repo-bootstrap.sh' # Absolute path
 # settings[:bootstrap_script] = 'script/bootstrap' # Relative path
 ```
+
+## Bootstrap environment
+
+When the bootstrap script runs, a limited set of environment variables are passed from the shell running octocatalog-diff. Only these variables are set:
+
+- `HOME`
+- `PATH`
+- `PWD` (set to the base directory of your Puppet checkout)
+- `BASEDIR` (as explicitly set with `--basedir` CLI option or `settings[:basedir]` setting)
+
+If you wish to set additional environment variables for your bootstrap script, you may do so via the `--bootstrap-environment VAR=value` command line flag, or by defining `settings[:bootstrap_environment] = { 'VAR' => 'value' }` in your configuration file.
+
+As an example, consider that your bootstrap script is written in Python, and needs the `PYTHONPATH` variable set to `/usr/local/lib/python-custom`. Even if this environment variable is set when octocatalog-diff is run, it will not be available to the bootstrap script. You may supply it via the command line:
+
+```
+octocatalog-diff --bootstrap-environment PYTHONPATH=/usr/local/lib/python-custom ...
+```
+
+Or you may specify it in your configuration file:
+
+```
+settings[:bootstrap_environment] = {
+  'PYTHONPATH' => '/usr/local/lib/python-custom'
+}
+```

doc/configuration-enc.md

@@ -67,3 +67,37 @@ For example, when compiling the catalog for `some-node.github.net`, Puppet will
   ```
 
 Sometimes the ENC script requires credentials or makes other assumptions about the system on which it is running. To be able to run the ENC script on systems other than your Puppet master, you will need to ensure that any such credentials are supplied and other assumptions are met.
+
+## Environment
+
+When the ENC is executed, the following environment variables are set to match the environment of the shell in which octocatalog-diff executes:
+
+- `HOME`
+- `PATH`
+- `PWD` (set to the temporary directory as previously described)
+
+No other environment variables are passed from the shell. If you wish to pass additional environment variables, you must explicitly list them with the `--pass-env-vars` CLI flag or `settings[:pass_env_vars]` array in your configuration file.
+
+As an example, consider that your ENC is written in Python, and needs the `PYTHONPATH` variable set to `/usr/local/lib/python-custom`. Even if this environment variable is set when octocatalog-diff is run, it will not be available to the ENC script. You may pass the variable via the command line:
+
+```
+octocatalog-diff --pass-env-vars PYTHONPATH ...
+```
+
+Or you may specify it in your configuration file:
+
+```
+settings[:pass_env_vars] = [ 'PYTHONPATH' ]
+```
+
+If you wish to specify multiple environment variables to pass:
+
+```
+octocatalog-diff --pass-env-vars PYTHONPATH,SECONDVAR,THIRDVAR ...
+```
+
+or
+
+```
+settings[:pass_env_vars] = [ 'PYTHONPATH', 'SECONDVAR', 'THIRDVAR' ]
+```