Skip to content

Commit 77b4856

Browse files
sftimsftim
committed
Add controller concept
1 parent d3c216f commit 77b4856

File tree

4 files changed

+167
-12
lines changed

4 files changed

+167
-12
lines changed

‎content/en/docs/concepts/_index.md

+5-5
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ The Concepts section helps you learn about the parts of the Kubernetes system an
1717

1818
To work with Kubernetes, you use *Kubernetes API objects* to describe your cluster's *desired state*: what applications or other workloads you want to run, what container images they use, the number of replicas, what network and disk resources you want to make available, and more. You set your desired state by creating objects using the Kubernetes API, typically via the command-line interface, `kubectl`. You can also use the Kubernetes API directly to interact with the cluster and set or modify your desired state.
1919

20-
Once you've set your desired state, the *Kubernetes Control Plane* makes the cluster's current state match the desired state via the Pod Lifecycle Event Generator (PLEG). To do so, Kubernetes performs a variety of tasks automatically--such as starting or restarting containers, scaling the number of replicas of a given application, and more. The Kubernetes Control Plane consists of a collection of processes running on your cluster:
20+
Once you've set your desired state, the *Kubernetes Control Plane* makes the cluster's current state match the desired state via the Pod Lifecycle Event Generator (PLEG). To do so, Kubernetes performs a variety of tasks automatically--such as starting or restarting containers, scaling the number of replicas of a given application, and more. The Kubernetes Control Plane consists of a collection of processes running on your cluster:
2121

2222
* The **Kubernetes Master** is a collection of three processes that run on a single node in your cluster, which is designated as the master node. Those processes are: [kube-apiserver](/docs/admin/kube-apiserver/), [kube-controller-manager](/docs/admin/kube-controller-manager/) and [kube-scheduler](/docs/admin/kube-scheduler/).
2323
* Each individual non-master node in your cluster runs two processes:
@@ -26,7 +26,7 @@ Once you've set your desired state, the *Kubernetes Control Plane* makes the clu
2626

2727
## Kubernetes Objects
2828

29-
Kubernetes contains a number of abstractions that represent the state of your system: deployed containerized applications and workloads, their associated network and disk resources, and other information about what your cluster is doing. These abstractions are represented by objects in the Kubernetes API; see the [Kubernetes Objects overview](/docs/concepts/abstractions/overview/) for more details.
29+
Kubernetes contains a number of abstractions that represent the state of your system: deployed containerized applications and workloads, their associated network and disk resources, and other information about what your cluster is doing. These abstractions are represented by objects in the Kubernetes API. See [Understanding Kubernetes Objects](/docs/concepts/overview/working-with-objects/kubernetes-objects/) for more details.
3030

3131
The basic Kubernetes objects include:
3232

@@ -35,12 +35,12 @@ The basic Kubernetes objects include:
3535
* [Volume](/docs/concepts/storage/volumes/)
3636
* [Namespace](/docs/concepts/overview/working-with-objects/namespaces/)
3737

38-
In addition, Kubernetes contains a number of higher-level abstractions called Controllers. Controllers build upon the basic objects, and provide additional functionality and convenience features. They include:
38+
Kubernetes also contains higher-level abstractions that rely on [Controllers](/docs/concepts/architecture/controller/) to build upon the basic objects, and provide additional functionality and convenience features. These include:
3939

40-
* [ReplicaSet](/docs/concepts/workloads/controllers/replicaset/)
4140
* [Deployment](/docs/concepts/workloads/controllers/deployment/)
42-
* [StatefulSet](/docs/concepts/workloads/controllers/statefulset/)
4341
* [DaemonSet](/docs/concepts/workloads/controllers/daemonset/)
42+
* [StatefulSet](/docs/concepts/workloads/controllers/statefulset/)
43+
* [ReplicaSet](/docs/concepts/workloads/controllers/replicaset/)
4444
* [Job](/docs/concepts/workloads/controllers/jobs-run-to-completion/)
4545

4646
## Kubernetes Control Plane

‎content/en/docs/concepts/architecture/cloud-controller.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: Concepts Underlying the Cloud Controller Manager
33
content_template: templates/concept
4-
weight: 30
4+
weight: 40
55
---
66

77
{{% capture overview %}}

‎content/en/docs/concepts/architecture/controller.md

+160
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
---
2+
title: Controllers
3+
content_template: templates/concept
4+
weight: 30
5+
---
6+
7+
{{% capture overview %}}
8+
9+
In robotics and automation, a _control loop_ is
10+
a non-terminating loop that regulates the state of a system.
11+
12+
Here is one example of a control loop: a thermostat in a room.
13+
14+
When you set the temperature, that's telling the thermostat
15+
about your *desired state*. The actual room temperature is the
16+
*current state*. The thermostat acts to bring the current state
17+
closer to the desired state, by turning equipment on or off.
18+
19+
In Kubernetes, a _controller_ is a control loop that watches the
20+
state of your
21+
{{< glossary_tooltip term_id="cluster" text="cluster">}}, then
22+
makes or requests changes. Each controller tries to move the current
23+
cluster state closer to the desired state.
24+
25+
{{% /capture %}}
26+
27+
28+
{{% capture body %}}
29+
30+
## Controller pattern
31+
32+
A controller tracks at least one Kubernetes resource type.
33+
These [objects](/docs/concepts/overview/working-with-objects/kubernetes-objects/)
34+
and their associated data are the desired state, so the
35+
controller(s) for that resource are responsible for making the current
36+
state come closer to that desired state.
37+
38+
The controller might carry the action out itself; more commonly, in Kubernetes,
39+
a controller will send messages to the
40+
{{< glossary_tooltip text="API server" term_id="kube-apiserver" >}} that have
41+
useful side effects.
42+
43+
### Control via API server
44+
45+
The controller for Job is an example of a built-in controller that
46+
makes all of its changes by interacting with your cluster's API server.
47+
48+
{{< glossary_tooltip term_id="job" >}} is a Kubernetes resource that
49+
runs a {{< glossary_tooltip term_id="pod" >}}, or perhaps several Pods,
50+
to carry out a task and then stop.
51+
52+
(Once [scheduled](/docs/concepts/scheduling/), Pod objects become part
53+
of the desired state for a kubelet).
54+
55+
When the Job controller sees a new task it makes sure that, somewhere
56+
in your cluster, the kubelets on a set of Nodes are running the right
57+
number of Pods to get the work done.
58+
The Job controller does not run any Pods or containers
59+
itself. Instead, the Job controller tells the API server to create or remove
60+
Pod [objects](/docs/concepts/overview/working-with-objects/kubernetes-objects/).
61+
Other components in the
62+
{{< glossary_tooltip text="control plane" term_id="control-plane" >}}
63+
act on the new information (there are new Pods to schedule and run),
64+
and eventually the work is done.
65+
66+
After you create a new Job, the desired state is for that Job to
67+
be completed. The Job controller makes the current state be nearer
68+
to the desired state, by creating Pods that do the work you
69+
wanted.
70+
71+
Controllers also update the objects that configure them
72+
For example: once the work is done for a Job, the Job controller
73+
updates that Job object to mark it `Finished`.
74+
75+
(This is a bit like how some thermostats turn a light off to
76+
indicate that the your room is now at the temperature you set).
77+
78+
### Direct control
79+
80+
By contrast with Job, some controllers need to make changes to
81+
things outside of your cluster.
82+
83+
For example, if you use a control loop to make sure there
84+
are enough {{< glossary_tooltip text="Nodes" term_id="node" >}}
85+
in your cluster, then that controller needs something outside the
86+
current cluster to set up new Nodes when needed.
87+
88+
This kind of controller finds its desired state from the API
89+
server and then communicates directly with an external system
90+
to bring the current state closer in line.
91+
92+
(There actually is a controller that horizontally scales the
93+
nodes in your cluster. See
94+
[Cluster autoscaling](https://kubernetes.io/docs/tasks/administer-cluster/cluster-management/#cluster-autoscaling)).
95+
96+
## Desired versus current state {#desired-vs-current}
97+
98+
Kubernetes takes a cloud-native view of systems, and is able to handle
99+
constant change.
100+
101+
Your cluster could be changing at any point as work happens and
102+
control loops automatically fix failures. This means that,
103+
potentially, your cluster never reaches a stable state.
104+
105+
So long as the controllers for your cluster are making useful changes,
106+
it's OK for the current state to be different from the desired state
107+
at a particular moment.
108+
109+
## Design
110+
111+
As a tenet of its design, Kubernetes uses lots of controllers that each manage
112+
a particular aspect of cluster state. Most commonly, a particular control loop
113+
(controller) uses one kind of resource as its desired state, and has a different
114+
kind of resource that it manages to make that desired state happen.
115+
116+
It's useful to have simple controllers rather than one, monolithic set of control
117+
loops that are interlinked. Controllers can fail, so Kubernetes is designed to
118+
allow for that.
119+
120+
For example: a controller for Jobs tracks Job objects (to discover
121+
new work) and Pod object (to run the Jobs, and then to see when the work is
122+
finished). In this case something else creates the Job objects, whereas the Job
123+
controller creates some Pod objects.
124+
125+
{{< note >}}
126+
There can be several controllers that create or update the same kind of object.
127+
Behind the scenes, Kubernetes controllers make sure that they only pay attention
128+
to the resources linked to their controlling resource.
129+
130+
For example, you can have Deployments and Jobs; these both create Pods.
131+
The Job controller does not delete the Pods that your Deployment created,
132+
because there is information ({{< glossary_tooltip term_id="label" text="labels" >}})
133+
the controllers can use to tell those Pods apart.
134+
{{< /note >}}
135+
136+
## Ways of running controllers {#running-controllers}
137+
138+
Kubernetes comes with a set of built-in controllers that run inside
139+
the {{< glossary_tooltip term_id="kube-controller-manager" >}}. These
140+
built-in controllers provide important core behaviors.
141+
142+
The Deployment controller and Job controller are examples of controllers that
143+
come as part of Kubernetes itself (“built-in” controllers).
144+
Kubernetes lets you run a resilient control plane, so that if any of the built-in
145+
controllers were to fail, another part of the control plane will take over the work.
146+
147+
You can find controllers that run outside the control plane, to extend Kubernetes.
148+
Or, if you want, you can write a new controller yourself.
149+
You can run your own controller as a set of Pods,
150+
or externally to Kubernetes. What fits best will depend on what that particular
151+
controller does.
152+
153+
{{% /capture %}}
154+
155+
{{% capture whatsnext %}}
156+
* Read about the [Kubernetes control plane](https://kubernetes.io/docs/concepts/#kubernetes-control-plane)
157+
* Discover some of the basic [Kubernetes objects](https://kubernetes.io/docs/concepts/#kubernetes-objects)
158+
* Learn more about the [Kubernetes API](/docs/concepts/overview/kubernetes-api/)
159+
* If you want to write your own controller, see [Extension Patterns](/docs/concepts/extend-kubernetes/extend-cluster/#extension-patterns) in Extending Kubernetes.
160+
{{% /capture %}}

‎content/en/docs/reference/glossary/controller.md

+1-6
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: Controller
33
id: controller
44
date: 2018-04-12
5-
full_link: /docs/admin/kube-controller-manager/
5+
full_link: /docs/concepts/architecture/controller/
66
short_description: >
77
A control loop that watches the shared state of the cluster through the apiserver and makes changes attempting to move the current state towards the desired state.
88
@@ -12,8 +12,3 @@ tags:
1212
- fundamental
1313
---
1414
A control loop that watches the shared state of the cluster through the {{< glossary_tooltip text="apiserver" term_id="kube-apiserver" >}} and makes changes attempting to move the current state towards the desired state.
15-
16-
<!--more-->
17-
18-
Examples of controllers that ship with Kubernetes today are the replication controller, endpoints controller, namespace controller, and serviceaccounts controller.
19-

0 commit comments

Comments
 (0)