Merge pull request #273 from slack/upgrading-workflow

doc(upgrades): expand upgrade documentation

Author: slack

src/managing-workflow/upgrading-workflow.md

@@ -1,39 +1,32 @@
 # Upgrading Workflow
 
-To upgrade to a newer version of Workflow, run the following:
-
-```
-$ helmc uninstall workflow-beta4 -n deis
-$ helmc fetch deis/workflow-rc1
-$ helmc generate -x manifests workflow-rc1
-$ cp `helmc home`/workspace/charts/workflow-beta4/manifests/deis-database-secret-creds.yaml \
-    `helmc home`/workspace/charts/workflow-rc1/manifests/
-$ helmc install workflow-rc1
-```
+Deis Workflow releases may be upgraded in-place with minimal downtime. This upgrade process requires:
 
-Make sure to copy the existing `deis-database-secret-creds.yaml` manifest into the new chart
-location *after* `helmc generate` to keep database credentials intact.
+* Helm Classic, version [0.8.0 or newer](https://github.com/helm/helm-classic/releases/tag/0.8.0)
+* Configured Off-Cluster Storage
+* A copy of the database and builder secrets from your running cluster
+* Workflow manifests annotated with `helm-keep: true` (rc1 or later)
 
 ## Off-Cluster Storage Required
 
 A Workflow upgrade requires using off-cluster object storage, since the default
-in-cluster storage is ephemeral. Upgrading Workflow with the in-cluster default
-of [Minio][] will result in data loss.
+in-cluster storage is ephemeral. **Upgrading Workflow with the in-cluster default
+of [Minio][] will result in data loss.**
 
 See [Configuring Object Storage][] to learn how to store your Workflow data off-cluster.
 
-## Keeping Essential Pieces
+## Keeping Essential Components
 
 !!! note
     "Keeper" upgrade behavior requires Helm Classic 0.8.0 or newer and the workflow-rc1
     or workflow-dev chart.
 
-Helm Classic recognizes when a manifest inside a chart is marked as a "keeper" and will leave
-it alone during `helmc uninstall`.
+Helm Classic recognizes when a manifest inside a chart is marked as a "keeper"
+and will not uninstall the annotated resource during `helmc uninstall`.
 
-The Workflow Chart marks the "deis" Kubernetes `Namespace` and the `Service` for the registry
-and for the router as keepers. This keeps the external `LoadBalancer` intact so that routing
-and DNS are preserved while reinstalling Workflow.
+The Workflow Chart marks the "deis" Kubernetes `Namespace` and the `Service`
+for the registry and router as keepers. This leaves the external `LoadBalancer`
+intact so routing and DNS are preserved while reinstalling Workflow.
 
 To remove Workflow completely from a Kubernetes cluster, run the following:
 
@@ -45,6 +38,61 @@ $ kubectl delete ns deis  # Be sure you want to delete the
 
 See the Helm Classic documentation for more detail about [keeper manifests].
 
+## Process
+
+To verify that the namespace, router and registry are marked as "keepers" run the following kubectl command for each component:
+
+```
+$ kubectl --namespace=deis get service deis-router \
+	--output=go-template='{{ index .metadata.annotations "helm-keep" | println }}'
+true
+```
+
+Manifests that are annotated correctly should return the value "true". To add a missing annotation, use `kubectl annotate`:
+
+```
+$ kubectl --namespace=deis annotate namespace deis helm-keep=true
+namespace "deis" annotated
+```
+
+To upgrade to a newer version of Workflow, run the following:
+
+```
+# update the charts repo
+$ helmc update
+
+# fetch your current database credentials
+$ kubectl --namespace=deis get secret database-creds -o yaml > ~/active-deis-database-secret-creds.yaml
+# fetch the ssh key for the builder component
+$ kubectl --namespace=deis get secret builder-ssh-private-keys -o yaml > ~/active-deis-builder-secret-ssh-private-keys.yaml
+
+# fetch new chart
+$ helmc fetch deis/workflow-rc1
+
+# update your off-cluster storage configuration
+$ $EDITOR $(helmc home)/workspace/charts/workflow-beta4/tpl/generate_params.toml
+
+# generate new templates
+$ helmc generate -x manifests workflow-rc1
+
+# copy your active database secrets into the helmc workspace
+$ cp ~/active-deis-database-secret-creds.yaml \
+	$(helmc home)/workspace/charts/workflow-rc1-manifests/deis-database-secret-creds.yaml
+
+# copy your active builder ssh keys into the helmc workspace
+$ cp ~/active-deis-builder-secret-ssh-private-keys.yaml \
+	$(helmc home)/workspace/charts/workflow-rc1/manifests/deis-builder-secret-ssh-private-keys.yaml
+
+# uninstall workflow
+$ helmc uninstall workflow-beta4 -n deis
+
+# install workflow rc1
+$ helmc install workflow-rc1
+```
+
+Make sure to copy the existing `deis-database-secret-creds.yaml` manifest into the new chart
+location *after* `helmc generate` to keep database credentials intact.
+
 [configuring object storage]: ../installing-workflow/configuring-object-storage.md
 [keeper manifests]: http://helm-classic.readthedocs.io/en/latest/awesome/#keeper-manifests
 [minio]: https://github.com/deis/minio