feat(managing-deis): add docs for deploy hooks

Author: Matthew Fisher

mkdocs.yml

@@ -52,6 +52,7 @@ pages:
     - Tuning Component Settings: managing-workflow/tuning-component-settings.md
     - Configuring Load Balancers: managing-workflow/configuring-load-balancers.md
     - Configuring DNS: managing-workflow/configuring-dns.md
+    - Deploy Hooks: managing-workflow/deploy-hooks.md
     - Platform Logging: managing-workflow/platform-logging.md
     - Platform Monitoring: managing-workflow/platform-monitoring.md
     - Production Deployments: managing-workflow/production-deployments.md

src/managing-workflow/deploy-hooks.md

@@ -0,0 +1,54 @@
+# Deploy Hooks
+
+Deploy hooks allow an external service to receive a notification whenever a new version of your app
+is pushed to Workflow. It’s useful to help keep the development team informed about deploys, while
+it can also be used to integrate different systems together.
+
+After one or more hooks are setup, hook output and errors appear in your application’s logs:
+
+```
+$ deis logs
+...
+2011-03-15T15:07:29-07:00 deis[api]: Deploy hook sent to http://deis.rocks
+```
+
+Deploy hooks are a generic HTTP hook. An administrator can create and configure multiple deploy
+hooks by [tuning the controller settings][controller-settings] via the Helm chart.
+
+## HTTP POST Hook
+
+The HTTP deploy hook performs an HTTP POST to a URL. The parameters included in the request are the
+same as the variables available in the hook message: `app`, `release`, `release_summary`, `sha` and
+`user`. See below for their descriptions:
+
+```
+app=secure-woodland&release=v4&release_summary=gabrtv%20deployed%35b3726&sha=35b3726&user=gabrtv
+```
+
+Optionally, if a deploy hook secret key is added to the controller through
+[tuning the controller settings][controller-settings], a new `Authorization` header will be
+present in the POST request. The value of this header is computed as the [HMAC][] hex digest of the
+request URL, using the secret as the key.
+
+In order to authenticate that this request came from Workflow, use the secret key, the full URL and
+the HMAC-SHA1 hashing algorithm to compute the signature. In Python, that would look something like
+this:
+
+```python
+import hashlib
+import hmac
+
+hmac.new("my_secret_key", "http://deis.rocks?app=secure-woodland&release=v4&release_summary=gabrtv%20deployed%35b3726&sha=35b3726&user=gabrtv", digestmod=hashlib.sha1).hexdigest()
+```
+
+If the value of the computed HMAC hex digest and the value in the `Authorization` header are
+identical, then the request came from Workflow.
+
+!!! important
+	When computing the signature, ensure that the URL parameters are in alphabetic order. This is
+	critical when computing the cryptographic signature as most web applications don't care about
+	the order of the HTTP parameters, but the cryptographic signature will not be the same.
+
+
+[controller-settings]: tuning-component-settings.md#customizing-the-controller
+[hmac]: https://en.wikipedia.org/wiki/Hash-based_message_authentication_code

src/managing-workflow/tuning-component-settings.md

@@ -45,6 +45,8 @@ REGISTRATION_MODE                               | set registration to "enabled",
 GUNICORN_WORKERS                                | number of [gunicorn][] workers spawned to process requests (default: CPU cores * 4 + 1)
 RESERVED_NAMES                                  | a comma-separated list of names which applications cannot reserve for routing (default: "deis, deis-builder, deis-workflow-manager")
 SLUGRUNNER_IMAGE_NAME                           | the image used to run buildpack application slugs (default: "quay.io/deisci/slugrunner:canary")
+DEIS_DEPLOY_HOOK_URLS                           | a comma-separated list of URLs to send [deploy hooks][] to.
+DEIS_DEPLOY_HOOK_SECRET_KEY                     | a private key used to compute the HMAC signature for deploy hooks.
 DEIS_DEPLOY_REJECT_IF_PROCFILE_MISSING          | rejects a deploy if the previous build had a Procfile but the current deploy is missing it. A 409 is thrown in the API. Prevents accidental process types removal. (default: "false", allowed values: "true", "false")
 DEIS_DEPLOY_PROCFILE_MISSING_REMOVE             | when turned on (default) any missing process type in a Procfile compared to the previous deploy is removed. When set to false will allow an empty Procfile to go through without removing missing process types, note that new images, configs and so on will get updated on all proc types.  (default: "true", allowed values: "true", "false")
 
@@ -128,6 +130,7 @@ API_VERSION       | The version number Workflow Manager sends to the versions AP
 [builder]: ../understanding-workflow/components.md#builder
 [controller]: ../understanding-workflow/components.md#controller
 [database]: ../understanding-workflow/components.md#database
+[deploy hooks]: deploy-hooks.md#http-post-hook
 [Deployments]: http://kubernetes.io/docs/user-guide/deployments/
 [downward-api]: http://kubernetes.io/docs/user-guide/downward-api/
 [gunicorn]: http://gunicorn.org/