Add docs for healthcheck

docs/content/en/docs/workflows/ci-cd.md

@@ -6,6 +6,102 @@ weight: 40
 
 Skaffold offers several sub-commands for its workflows that make it quite flexible when integrating with CI/CD pipelines.
 
+
+## Waiting for Skaffold deployments using `healthcheck`
+{{< maturity "deploy.status_check" >}}
+
+`skaffold deploy` optionally performs a `healthcheck` for [`Deployment` kind](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) resources and waits for them to be stable.
+This feature is very handy to use in Continous Delivery pipeline to ensure the deployed resources are
+in healthy state before proceeding with the next steps in pipeline.
+
+{{<alert title="Note">}}
+`healthcheck` is disabled by default; it can be enabled with the `--stauts-check` flag.
+
+If this flag is not set, no healthcheck will be performed.
+{{</alert>}}
+
+To enable status check, use flag, `--status-check`,
+```bash
+skaffold run --status-check
+```
+
+To determine if a `Deployment` kind resource is up and running, Skaffold relies on `kubectl rollout status` to obtain its status.
+
+```bash
+Waiting for deployments to stabilize
+ - default:deployment/leeroy-app Waiting for rollout to finish: 0 of 1 updated replicas are available...
+ - default:deployment/leeroy-web Waiting for rollout to finish: 0 of 1 updated replicas are available...
+ - default:deployment/leeroy-web is ready. [1/2 deployment(s) still pending]
+ - default:deployment/leeroy-app is ready.
+Deployments stabilized in 2.168799605s
+```
+
+**Configuring status check time for deploy `healthcheck`**
+
+You can also configure the time for deployments to stabilize with `statusCheckDeadlineSeconds` config field.
+
+To configure deployments to stabilize with 5 minutes use,
+{{% readfile file="samples/deployers/healthcheck.yaml" %}}
+
+With `--status-check` flag, for each `Deployment` kind resource, `skaffold deploy` will wait for 
+[`progressDeadlineSeconds`](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#progress-deadline-seconds)
+mentioned in its specification.
+
+If the `Deployment.spec.progressDeadlineSeconds` is not set, Skaffold will wait for
+
+1. Time set in Skaffold deploy config field `statusCheckDeadlineSeconds` if set, or
+2. default 10 minutes.
+
+In case you have both `statusCheckDeadlineSeconds` and `Deployment.spec.progressDeadlineSeconds` set, precedence
+is given to `Deployment.spec.progressDeadline` **only if it is within** `statusCheckDeadlineSeconds`.
+
+e.g. if for below `Deployment` with `progressDeadlineSeconds` set to 5 minutes, 
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: getting-started
+spec:
+  progressDeadlineSeconds: 300
+  template:
+    spec:
+      containers:
+      - name: cannot-run
+        image: gcr.io/k8s-skaffold/getting-started-foo
+```
+
+if the `skaffold.yaml` overrides the whole deploy to stabilize in a minute, 
+
+```yaml
+apiVersion: skaffold/v1
+deploy:
+  statusCheckDeadlineSeconds: 60
+  kubectl:
+    manifests:
+    - k8s-*
+```
+
+Running `skaffold deploy`
+
+```code
+skaffold deploy --status-check
+```
+will error out, within 1 minute.
+
+```bash
+Tags used in deployment:
+Starting deploy...
+kubectl client version: 1.11+
+kubectl version 1.12.0 or greater is recommended for use with Skaffold
+ - deployment.apps/getting-started created
+Waiting for deployments to stabilize
+ - default:deployment/getting-started Waiting for rollout to finish: 0 of 1 updated replicas are available...
+ - default:deployment/getting-started failed. Error: received Ctrl-C or deployments could not stabilize within 1m: kubectl rollout status command interrupted.
+FATA[0006] 1/1 deployment(s) failed
+```
+
+
 ## `skaffold build | skaffold deploy`
 
 `skaffold build` will build your project's artifacts, and push the build images to the specified registry. If your project is already configured to run with Skaffold, `skaffold build` can be a very lightweight way of setting up builds for your CI pipeline. Passing the `--file-output` flag to Skaffold build will also write out your built artifacts in JSON format to a file on disk, which can then by passed to `skaffold deploy` later on. This is a great way of "committing" your artifacts when they have reached a state that you're comfortable with, especially for projects with multiple artifacts for multiple services.
@@ -85,7 +181,4 @@ skaffold render | kubectl apply -f -
 gives us the one line output telling us the only thing we need to know:
 ```code
 pod/getting-started configured
-```
-
-## Waiting for Skaffold deployments using `healthcheck`
-{{< maturity "deploy.status_check" >}}
+```

docs/content/en/samples/deployers/healthcheck.yaml

@@ -0,0 +1,5 @@
+deploy:
+  statusCheckDeadlineSeconds: 300
+  kubectl:
+    manifests:
+    - k8s-*