Add concept page for Operators (#14458)

* Add concept page for Operator pattern

* Link to article about Operator best practices

content/en/docs/concepts/extend-kubernetes/extend-cluster.md

@@ -16,7 +16,7 @@ there is rarely a need to fork or submit patches to the Kubernetes
 project code.
 
 This guide describes the options for customizing a Kubernetes
-cluster. It is aimed at {{< glossary_tooltip text="Cluster Operators" term_id="cluster-operator" >}} who want to
+cluster. It is aimed at {{< glossary_tooltip text="cluster operators" term_id="cluster-operator" >}} who want to
 understand how to adapt their Kubernetes cluster to the needs of
 their work environment. Developers who are prospective {{< glossary_tooltip text="Platform Developers" term_id="platform-developer" >}} or Kubernetes Project {{< glossary_tooltip text="Contributors" term_id="contributor" >}} will also find it
 useful as an introduction to what extension points and patterns
@@ -122,7 +122,7 @@ For more about Custom Resources, see the [Custom Resources concept guide](/docs/
 
 ### Combining New APIs with Automation
 
-Often, when you add a new API, you also add a control loop that reads and/or writes the new APIs. When the combination of a Custom API and a control loop is used to manage a specific, usually stateful, application, this is called the *Operator* pattern. Custom APIs and control loops can also be used to control other resources, such as storage, policies, and so on.
+The combination of a custom resource API and a control loop is called the [Operator pattern](/docs/concepts/extend-kubernetes/operator/). The Operator pattern is used to manage specific, usually stateful, applications. These custom APIs and control loops can also be used to control other resources, such as storage or policies.
 
 ### Changing Built-in Resources
 
@@ -205,7 +205,6 @@ the nodes chosen for a pod.
   * [Network Plugins](/docs/concepts/cluster-administration/network-plugins/)
   * [Device Plugins](/docs/concepts/cluster-administration/device-plugins/)
 * Learn about [kubectl plugins](/docs/tasks/extend-kubectl/kubectl-plugins/)
-* See examples of Automation
+* Learn about the [Operator pattern](/docs/concepts/extend-kubernetes/operator/)
-  * [List of Operators](https://github.com/operator-framework/awesome-operators)
 
 {{% /capture %}}

content/en/docs/concepts/extend-kubernetes/operator.md

@@ -0,0 +1,131 @@
+---
+title: Operator pattern
+content_template: templates/concept
+weight: 30
+---
+
+{{% capture overview %}}
+
+Operators are software extensions to Kubernetes that make use of third-party
+resources to manage applications and their components. Operators follow
+Kubernetes principles, notably the [control loop](/docs/concepts/#kubernetes-control-plane).
+
+{{% /capture %}}
+
+
+{{% capture body %}}
+
+## Motivation
+
+The Operator pattern aims to capture the key aim of a human operator who
+is managing a service or set of services. Human operators who look after
+specific applications and services have deep knowledge of how the system
+ought to behave, how to deploy it, and how to react if there are problems.
+
+People who run workloads on Kubernetes often like to use automation to take
+care of repeatable tasks. The Operator pattern captures how you can write
+code to automate a task beyond what Kubernetes itself provides.
+
+## Operators in Kubernetes
+
+Kubernetes is designed for automation. Out of the box, you get lots of
+built-in automation from the core of Kubernetes. You can use Kubernetes
+to automate deploying and running workloads, *and* you can automate how
+Kubernetes does that.
+
+Kubernetes' {{< glossary_tooltip text="controllers" term_id="controller" >}}
+concept lets you extend the cluster's behaviour without modifying the code
+of Kubernetes itself.
+Operators are clients of the Kubernetes API that act as controllers for
+a [Custom Resource](/docs/concepts/api-extension/custom-resources/).
+
+## An example Operator {#example}
+
+Some of the things that you can use an operator to automate include:
+
+* deploying an application on demand
+* taking and restoring backups of that application's state
+* handling upgrades of the application code alongside related changes such
+  as database schemas or extra configuration settings
+* publishing a Service to applications that don't support Kubernetes APIs to
+  discover them
+* simulating failure in all or part of your cluster to test its resilience
+* choosing a leader for a distributed application without an internal
+  member election process
+
+What might an Operator look like in more detail? Here's an example in more
+detail:
+
+1. A custom resource named SampleDB, that you can configure into the cluster.
+2. A Deployment that makes sure a Pod is running that contains the
+   controller part of the operator.
+3. A container image of the operator code.
+4. Controller code that queries the control plane to find out what SampleDB
+   resources are configured.
+5. The core of the Operator is code to tell the API server how to make
+   reality match the configured resources.
+   * If you add a new SampleDB, the operator sets up PersistentVolumeClaims
+     to provide durable database storage, a StatefulSet to run SampleDB and
+     a Job to handle initial configuration.
+   * If you delete it, the Operator takes a snapshot, then makes sure that
+     the the StatefulSet and Volumes are also removed.
+6. The operator also manages regular database backups. For each SampleDB
+   resource, the operator determines when to create a Pod that can connect
+   to the database and take backups. These Pods would rely on a ConfigMap
+   and / or a Secret that has database connection details and credentials.
+7. Because the Operator aims to provide robust automation for the resource
+   it manages, there would be additional supporting code. For this example,
+   code checks to see if the database is running an old version and, if so,
+   creates Job objects that upgrade it for you.
+
+## Deploying Operators
+
+The most common way to deploy an Operator is to add the
+Custom Resource Definition and its associated Controller to your cluster.
+The Controller will normally run outside of the
+{{< glossary_tooltip text="control plane" term_id="control-plane" >}},
+much as you would run any containerized application.
+For example, you can run the controller in your cluster as a Deployment.
+
+## Using an Operator {#using-operators}
+
+Once you have an Operator deployed, you'd use it by adding, modifying or
+deleting the kind of resource that the Operator uses. Following the above
+example, you would set up a Deployment for the Operator itself, and then:
+
+```shell
+kubectl get SampleDB                   # find configured databases
+
+kubectl edit SampleDB/example-database # manually change some settings
+```
+
+&hellip;and that's it! The Operator will take care of applying the changes
+as well as keeping the existing service in good shape.
+
+## Writing your own Operator {#writing-operator}
+
+If there isn't an Operator in the ecosystem that implements the behavior you
+want, you can code your own. In [What's next](#what-s-next) you'll find a few
+links to libraries and tools you can use to write your own cloud native
+Operator.
+
+You also implement an Operator (that is, a Controller) using any language / runtime
+that can act as a [client for the Kubernetes API](/docs/reference/using-api/client-libraries/).
+
+{{% /capture %}}
+
+{{% capture whatsnext %}}
+
+* Learn more about [Custom Resources](/docs/concepts/extend-kubernetes/api-extension/custom-resources/)
+* Find ready-made operators on [OperatorHub.io](https://operatorhub.io/) to suit your use case
+* Use existing tools to write your own operator, eg:
+  * using [KUDO](https://kudo.dev/) (Kubernetes Universal Declarative Operator)
+  * using [kubebuilder](https://book.kubebuilder.io/)
+  * using [Metacontroller](https://metacontroller.app/) along with WebHooks that
+    you implement yourself
+  * using the [Operator Framework](https://github.com/operator-framework/getting-started)
+* [Publish](https://operatorhub.io/) your operator for other people to use
+* Read [CoreOS' original article](https://coreos.com/blog/introducing-operators.html) that introduced the Operator pattern
+* Read an [article](https://cloud.google.com/blog/products/containers-kubernetes/best-practices-for-building-kubernetes-operators-and-stateful-apps) from Google Cloud about best practices for building Operators
+
+{{% /capture %}}

content/en/docs/concepts/services-networking/service.md

@@ -432,7 +432,8 @@ specifying `"None"` for the cluster IP (`.spec.clusterIP`).
 
 You can use a headless Service to interface with other service discovery mechanisms,
 without being tied to Kubernetes' implementation. For example, you could implement
-a custom [Operator](https://coreos.com/operators/) to be built on the API.
+a custom {{< glossary_tooltip term_id="operator-pattern" text="Operator" >}} upon
+this API.
 
 For such `Services`, a cluster IP is not allocated, kube-proxy does not handle
 these Services, and there is no load balancing or proxying done by the platform

content/en/docs/reference/glossary/operator-pattern.md

@@ -0,0 +1,24 @@
+---
+title: Operator pattern
+id: operator-pattern
+date: 2019-05-21
+full_link: /docs/concepts/extend-kubernetes/operator/
+short_description: >
+  A specialized controller used to manage a custom resource
+
+aka:
+tags:
+- architecture
+---
+ The [operator pattern](/docs/concepts/extend-kubernetes/operator/) is a system
+design that links a {{< glossary_tooltip term_id="controller" >}} to one or more custom
+resources.
+
+<!--more-->
+
+You can extend Kubernetes by adding controllers to your cluster, beyond the built-in
+controllers that come as part of Kubernetes itself.
+
+If a running application acts as a controller and has API access to carry out tasks
+against a custom resource that's defined in the control plane, that's an example of
+the Operator pattern.

content/en/docs/reference/kubectl/cheatsheet.md

@@ -348,7 +348,7 @@ Kubectl verbosity is controlled with the `-v` or `--v` flags followed by an inte
 
 Verbosity | Description
 --------------| -----------
-`--v=0` | Generally useful for this to ALWAYS be visible to an operator.
+`--v=0` | Generally useful for this to *always* be visible to a cluster operator.
 `--v=1` | A reasonable default log level if you don't want verbosity.
 `--v=2` | Useful steady state information about the service and important log messages that may correlate to significant changes in the system. This is the recommended default log level for most systems.
 `--v=3` | Extended information about changes.