docs(managing-workflow): document all available environment variables

Author: Matthew Fisher

mkdocs.yml

@@ -47,7 +47,7 @@ pages:
     - Domains and Routing: applications/domains-and-routing.md
     - SSL Certificates: applications/ssl-certificates.md
   - Managing Workflow:
-    - Configuring Components: managing-workflow/component-configuration.md
+    - 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
     - Platform Logging: managing-workflow/platform-logging.md

src/managing-workflow/component-configuration.md

@@ -48,7 +48,7 @@ crucial. See [Platform SSL][] for the platform.
 
 
 [configuring object storage]: ../installing-workflow/configuring-object-storage.md
-[customizing controller]: component-configuration.md#customizing-the-controller
+[customizing controller]: tuning-component-settings.md#customizing-the-controller
 [database]: ../understanding-workflow/components.md#database
 [logger]: ../understanding-workflow/components.md#logger
 [minio]: ../understanding-workflow/components.md#minio

src/managing-workflow/production-deployments.md

@@ -0,0 +1,119 @@
+# Tuning Component Settings
+
+Helm Charts are a set of Kubernetes manifests that reflect best practices for deploying an
+application or service. Helm is heavily influenced by [Homebrew](http://brew.sh/), including the
+[formula model](https://github.com/Homebrew/homebrew-core). A Helm Chart is to Helm as a Formula
+is to Homebrew.
+
+After you cetch the Workflow chart, you can customize the chart using `helmc edit` before using
+`helmc generate` and `helmc install` to complete the installation. To customize the respective
+component, edit `tpl/deis-<component>-rc.yaml` and modify the `env` section of the component to
+tune these settings.
+
+For example, to allow only administrators to register new accounts in the controller,
+edit `tpl/deis-controller-rc.yaml` and add the following under the `env` section:
+
+```
+env:
+  - name: REGISTRATION_MODE
+    value: "admin_only"
+```
+
+## Customizing the Builder
+
+The following environment variables are tunable for the [Builder][] component:
+
+Setting | Description
+------- | ---------------------------------
+DEBUG   | Enable debug log output (default: false)
+
+## Customizing the Controller
+
+The following environment variables are tunable for the [Controller][] component:
+
+Setting                                         | Description
+----------------------------------------------- | ---------------------------------
+REGISTRATION_MODE                               | set registration to "enabled", "disabled", or "admin_only" (default: "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")
+SLUG_BUILDER_IMAGE_PULL_POLICY                  | the kubernetes [image pull policy][pull-policy] for slugbuilder (default: "Always")
+DOCKER_BUILDER_IMAGE_PULL_POLICY                | the kubernetes [image pull policy][pull-policy] for dockerbuilder (default: "Always")
+DEIS_DEPLOY_BATCHES                             | the number of pods to bring up and take down sequentially during a scale (default: all)
+KUBERNETES_POD_TERMINATION_GRACE_PERIOD_SECONDS | how many seconds kubernetes waits for a pod to finish work after a SIGTERM before sending SIGKILL (default: 30)
+
+## Customizing the Database
+
+The following environment variables are tunable for the [Database][] component:
+
+Setting           | Description
+----------------- | ---------------------------------
+BACKUP_FREQUENCY  | how often the database should perform a base backup (default: "12h")
+BACKUPS_TO_RETAIN | number of base backups the backing store should retain (default: 5)
+
+## Customizing Fluentd
+
+The following environment variables are tunable for [Fluentd][logger]:
+
+Setting           | Description
+----------------- | ---------------------------------
+SYSLOG_HOST_1     | The hostname of a remote syslog endpoint for shipping logs
+SYSLOG_PORT_1     | The port of a remote syslog endpoint for shipping logs
+
+## Customizing the Logger
+
+The following environment variables are tunable for the [Logger][] component:
+
+Setting           | Description
+----------------- | ---------------------------------
+STORAGE_ADAPTER   | How to store logs that are sent to the logger (default: "memory")
+NUMBER_OF_LINES   | How many lines to store in the ring buffer (default: 1000)
+
+## Customizing the Monitor
+
+The monitor component uses [Telegraf](https://github.com/influxdata/telegraf) under the hood, and
+derives most of its configuration from it. Please see
+[telegraf configuration](https://github.com/influxdata/telegraf/blob/master/docs/CONFIGURATION.md)
+for more information on tuning the [Monitor][] component.
+
+## Customizing the Registry
+
+The [Registry][] component can be tuned by following the
+[deis/distribution config doc](https://github.com/deis/distribution/blob/master/docs/configuration.md).
+
+## Customizing the Router
+
+The majority of router settings are tunable through annotations, which allows the router to be
+re-configured with zero downtime post-installation. You can find the list of annotations to tune
+[here](https://github.com/deis/router#annotations).
+
+The following environment variables are tunable for the [Router][] component:
+
+Setting           | Description
+----------------- | ---------------------------------
+POD_NAMESPACE     | The pod namespace the router resides in. This is set by the [Kubernetes downward API][downward-api].
+
+## Customizing Workflow Manager
+
+The following environment variables are tunable for [Workflow Manager][]:
+
+Setting                            | Description
+---------------------------------- | ---------------------------------
+CHECK_VERSIONS    | Enables the external version check at <https://versions.deis.com/> (default: "true")
+POLL_INTERVAL_SEC | The interval when Workflow Manager performs a version check, in seconds (default: 43200, or 12 hours)
+VERSIONS_API_URL  | The versions API URL (default: "<https://versions-staging.deis.com>")
+DOCTOR_API_URL    | The doctor API URL (default: "<https://doctor-staging.deis.com>")
+API_VERSION       | The version number Workflow Manager sends to the versions API (default: "v2")
+
+
+[builder]: ../understanding-workflow/components.md#builder
+[controller]: ../understanding-workflow/components.md#controller
+[database]: ../understanding-workflow/components.md#database
+[downward-api]: http://kubernetes.io/docs/user-guide/downward-api/
+[gunicorn]: http://gunicorn.org/
+[logger]: ../understanding-workflow/components.md#logger-fluentd-logger
+[monitor]: ../understanding-workflow/components.md#monitor
+[pull-policy]: http://kubernetes.io/docs/user-guide/images/
+[registry]: ../understanding-workflow/components.md#registry
+[router]: ../understanding-workflow/components.md#router
+[workflow manager]: ../understanding-workflow/components.md#workflow-manager