From 20e45f13315fde00c713af9fe5b83ba5e8475c6a Mon Sep 17 00:00:00 2001 From: Tim Bannister Date: Fri, 12 Jul 2019 01:57:07 +0100 Subject: [PATCH] Add concept page for Operators (#14458) * Add concept page for Operator pattern * Link to article about Operator best practices --- .../extend-kubernetes/extend-cluster.md | 7 +- .../concepts/extend-kubernetes/operator.md | 131 ++++++++++++++++++ .../concepts/services-networking/service.md | 3 +- .../reference/glossary/operator-pattern.md | 24 ++++ .../en/docs/reference/kubectl/cheatsheet.md | 2 +- 5 files changed, 161 insertions(+), 6 deletions(-) create mode 100644 content/en/docs/concepts/extend-kubernetes/operator.md create mode 100755 content/en/docs/reference/glossary/operator-pattern.md diff --git a/content/en/docs/concepts/extend-kubernetes/extend-cluster.md b/content/en/docs/concepts/extend-kubernetes/extend-cluster.md index 61d0aacb9c..d5ab77a28b 100644 --- a/content/en/docs/concepts/extend-kubernetes/extend-cluster.md +++ b/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 - * [List of Operators](https://github.com/operator-framework/awesome-operators) +* Learn about the [Operator pattern](/docs/concepts/extend-kubernetes/operator/) {{% /capture %}} diff --git a/content/en/docs/concepts/extend-kubernetes/operator.md b/content/en/docs/concepts/extend-kubernetes/operator.md new file mode 100644 index 0000000000..4a8d744db7 --- /dev/null +++ b/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 +``` + +…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 %}} diff --git a/content/en/docs/concepts/services-networking/service.md b/content/en/docs/concepts/services-networking/service.md index b1a2cc0f90..36febaa30c 100644 --- a/content/en/docs/concepts/services-networking/service.md +++ b/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 diff --git a/content/en/docs/reference/glossary/operator-pattern.md b/content/en/docs/reference/glossary/operator-pattern.md new file mode 100755 index 0000000000..2b244093d2 --- /dev/null +++ b/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. + + + +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. diff --git a/content/en/docs/reference/kubectl/cheatsheet.md b/content/en/docs/reference/kubectl/cheatsheet.md index 74efeb19bb..19a0b78f4f 100644 --- a/content/en/docs/reference/kubectl/cheatsheet.md +++ b/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.