Skip to content
Permalink
Browse files

Add concept page for Operators (#14458)

* Add concept page for Operator pattern

* Link to article about Operator best practices
  • Loading branch information...
sftim authored and k8s-ci-robot committed Jul 12, 2019
1 parent a6fc4c1 commit 20e45f13315fde00c713af9fe5b83ba5e8475c6a
@@ -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 %}}
@@ -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 %}}
@@ -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
@@ -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.
@@ -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.

0 comments on commit 20e45f1

Please sign in to comment.
You can’t perform that action at this time.