PodDisruptionBudget documentation Improvements (#4140)

* Changes from #3885

Title: Update PDB documentation to explain new field
Author: foxish

* Added Placeholder Disruptions Concept Guide

New file: docs/concepts/workloads/pods/disruptions.md
Intented contents: concept for Pod Disruption Budget,
 cross reference to Eviction and Preemption docs.
Linked from: concepts > workloads > pods

* Added placeholder Configuring PDB Task

New file: docs/tasks/run-application/configure-pdb.md
Intented contents: task for writing a Pod Disruption Budget.
Linked from: tasks > configuring-applications > configure pdb.

* Add refs to the "drain a node" task.

* Refactor PDB docs.

Move the "Requesting an eviction" section from:
docs/tasks/administer-cluster/configure-pod-disruption-budget.md
-- which is going away -- to:
docs/tasks/administer-cluster/safely-drain-node.md

The move is verbatim, except for an introductory sentence.

Also added assignees.

* Refactor of PDB docs

Moved the section:
Specifying a PodDisruptionBudget
from:
docs/tasks/administer-cluster/configure-pod-disruption-budget.md
to:
docs/tasks/run-application/configure-pdb.md
because that former file is going away.
Move is verbatim.

* Explain how Eviction tools should handle failures

* Refactor PDB docs

Move text from:
docs/tasks/administer-cluster/configure-pod-disruption-budget.md
to:
docs/concepts/workloads/pods/disruptions.md

Delete the now empty:
docs/tasks/administer-cluster/configure-pod-disruption-budget.md

Added a redirects_from section to the new doc, containing the path
of the now-deleted doc, plus all the redirects from the deleted
doc.

* Expand PDB Concept guide

Building on a little content from the old task,
greatly expanded the Disruptions concept
guide, including an abstract example.

* Update creating a pdb Task.

* Address review comments.

* Fixed for all cody-clark's review comments

* Address review comments from mml

* Address review comments from maisem

* Fix missing backtick

docs/tasks/administer-cluster/safely-drain-node.md

@@ -1,6 +1,9 @@
 ---
 assignees:
 - davidopp
+- mml
+- foxish
+- kow3ns
 title: Safely Drain a Node while Respecting Application SLOs
 ---
 
@@ -14,8 +17,12 @@ disruption SLOs you have specified using PodDisruptionBudget.
 This task assumes that you have met the following prerequisites:
 
 * You are using Kubernetes release >= 1.5.
-* You have created [PodDisruptionBudget(s)](/docs/tasks/configure-pod-container/configure-pod-disruption-budget/) to express the
-application-level disruption SLOs you want the system to enforce.
+* Either:
+  1. You do not require your applications to be highly available during the
+     node drain, or
+  1. You have read about the [PodDisruptionBudget concept](/docs/concepts/workloads/pods/disruptions.md)
+     and [Configured PodDisruptionBudgets](/docs/tasks/run-application/configure-pdb.md) for
+     applications that need them.
 
 {% endcapture %}
 
@@ -81,11 +88,75 @@ that only one pod is unavailable at any given time. Any drains that
 would cause the number of ready replicas to fall below the specified
 budget are blocked.
 
+## The Eviction API
+
+If you prefer not to use [kubectl drain](/docs/user-guide/kubectl/v1.6/#drain) (such as
+to avoid calling to an external command, or to get finer control over over the pod
+eviction process), you can also programmatically cause evictions using the eviction API.
+
+You should first be familiar with using [Kubernetes language clients](/docs/tasks/administer-cluster/access-cluster-api.md#programmatic-access-to-the-api).
+
+The eviction subresource of a
+pod can be thought of as a kind of policy-controlled DELETE operation on the pod
+itself.  To attempt an eviction (perhaps more REST-precisely, to attempt to
+*create* an eviction), you POST an attempted operation.  Here's an example:
+
+```json
+{
+  "apiVersion": "policy/v1beta1",
+  "kind": "Eviction",
+  "metadata": {
+    "name": "quux",
+    "namespace": "default"
+  }
+}
+```
+
+You can attempt an eviction using `curl`:
+
+```bash
+$ curl -v -H 'Content-type: application/json' http://127.0.0.1:8080/api/v1/namespaces/default/pods/quux/eviction -d @eviction.json
+```
+
+The API can respond in one of three ways.
+
+- If the eviction is granted, then the pod is deleted just as if you had sent
+  a `DELETE` request to the pod's URL and you get back `200 OK`.
+- If the current state of affairs wouldn't allow an eviction by the rules set
+  forth in the budget, you get back `429 Too Many Requests`.  This is
+  typically used for generic rate limiting of *any* requests, but here we mean
+  that this request isn't allowed *right now* but it may be allowed later.
+  Currently, callers do not get any `Retry-After` advice, but they may in
+  future versions.
+- If there is some kind of misconfiguration, like multiple budgets pointing at
+  the same pod, you will get `500 Internal Server Error`.
+
+For a given eviction request, there are two cases.
+
+- There is no budget that matches this pod.  In this case, the server always
+  returns `200 OK`.
+- There is at least one budget.  In this case, any of the three above responses may
+ apply.
+
+In some cases, an application may reach a broken state where it will never return anything
+other than 429 or 500.  This can happen, for example, if the replacement pod created by the
+application's controller does not become ready, or if the last pod evicted has a very long
+termination grace period.
+
+In this case, there are two potential solutions:
+
+- Abort or pause the automated operation.  Investigate the reason for the stuck application, and restart the automation.
+- After a suitably long wait, `DELETE` the pod instead of using the eviction API.
+
+Kubernetes does not specify what the behavior should be in this case; it is up to the
+application owners and cluster owners to establish an agreement on behavior in these cases.
 
 {% endcapture %}
 
 {% capture whatsnext %}
-*TODO: link to other docs about Stateful Set?*
+
+* Follow steps to protect your application by [configuring a Pod Disruption Budget](/docs/tasks/run-application//configure-pdb.md).
+
 {% endcapture %}
 
 {% include templates/task.md %}