Skip to content

Commit 9a7b191

Browse files
sftimk8s-ci-robot
sftim
authored and
k8s-ci-robot
committed
Add concept page about Controllers (#15733)
* Add controller concept * Fix controller glossary entries * Link from Understanding Kubernetes Objects to Controllers
1 parent bf83aaf commit 9a7b191

File tree

14 files changed

+203
-31
lines changed

14 files changed

+203
-31
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

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

‎content/en/docs/concepts/overview/components.md

+1
Original file line numberDiff line numberDiff line change
@@ -115,6 +115,7 @@ saving container logs to a central log store with search/browsing interface.
115115
{{% /capture %}}
116116
{{% capture whatsnext %}}
117117
* Learn about [Nodes](/docs/concepts/architecture/nodes/)
118+
* Learn about [Controllers](/docs/concepts/architecture/controller/)
118119
* Learn about [kube-scheduler](/docs/concepts/scheduling/kube-scheduler/)
119120
* Read etcd's official [documentation](https://etcd.io/docs/)
120121
{{% /capture %}}

‎content/en/docs/concepts/overview/working-with-objects/kubernetes-objects.md

+1
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,7 @@ and the `spec` format for a `Deployment` can be found
7373

7474
{{% capture whatsnext %}}
7575
* Learn about the most important basic Kubernetes objects, such as [Pod](/docs/concepts/workloads/pods/pod-overview/).
76+
* Learn about [controllers](/docs/concepts/architecture/controller/) in Kubernetes
7677
{{% /capture %}}
7778

7879

‎content/en/docs/concepts/workloads/controllers/cron-jobs.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ If `startingDeadlineSeconds` is set to a large value or left unset (the default)
3636
and if `concurrencyPolicy` is set to `Allow`, the jobs will always run
3737
at least once.
3838

39-
For every CronJob, the CronJob controller checks how many schedules it missed in the duration from its last scheduled time until now. If there are more than 100 missed schedules, then it does not start the job and logs the error
39+
For every CronJob, the CronJob {{< glossary_tooltip term_id="controller" >}} checks how many schedules it missed in the duration from its last scheduled time until now. If there are more than 100 missed schedules, then it does not start the job and logs the error
4040

4141
````
4242
Cannot determine if job needs to be started. Too many missed start time (> 100). Set or decrease .spec.startingDeadlineSeconds or check clock skew.

‎content/en/docs/concepts/workloads/controllers/daemonset.md

+4-4
Original file line numberDiff line numberDiff line change
@@ -86,10 +86,10 @@ When the two are specified the result is ANDed.
8686
If the `.spec.selector` is specified, it must match the `.spec.template.metadata.labels`. Config with these not matching will be rejected by the API.
8787

8888
Also you should not normally create any Pods whose labels match this selector, either directly, via
89-
another DaemonSet, or via other controller such as ReplicaSet. Otherwise, the DaemonSet
90-
controller will think that those Pods were created by it. Kubernetes will not stop you from doing
91-
this. One case where you might want to do this is manually create a Pod with a different value on
92-
a node for testing.
89+
another DaemonSet, or via another workload resource such as ReplicaSet. Otherwise, the DaemonSet
90+
{{< glossary_tooltip term_id="controller" >}} will think that those Pods were created by it.
91+
Kubernetes will not stop you from doing this. One case where you might want to do this is manually
92+
create a Pod with a different value on a node for testing.
9393

9494
### Running Pods on Only Some Nodes
9595

‎content/en/docs/concepts/workloads/controllers/deployment.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -13,10 +13,10 @@ weight: 30
1313

1414
{{% capture overview %}}
1515

16-
A _Deployment_ controller provides declarative updates for [Pods](/docs/concepts/workloads/pods/pod/) and
16+
A _Deployment_ provides declarative updates for [Pods](/docs/concepts/workloads/pods/pod/) and
1717
[ReplicaSets](/docs/concepts/workloads/controllers/replicaset/).
1818

19-
You describe a _desired state_ in a Deployment, and the Deployment controller changes the actual state to the desired state at a controlled rate. You can define Deployments to create new ReplicaSets, or to remove existing Deployments and adopt all their resources with new Deployments.
19+
You describe a _desired state_ in a Deployment, and the Deployment {{< glossary_tooltip term_id="controller" >}} changes the actual state to the desired state at a controlled rate. You can define Deployments to create new ReplicaSets, or to remove existing Deployments and adopt all their resources with new Deployments.
2020

2121
{{< note >}}
2222
Do not manage ReplicaSets owned by a Deployment. Consider opening an issue in the main Kubernetes repository if your use case is not covered below.

‎content/en/docs/concepts/workloads/controllers/jobs-run-to-completion.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -173,10 +173,10 @@ parallelism, for a variety of reasons:
173173
- For _fixed completion count_ Jobs, the actual number of pods running in parallel will not exceed the number of
174174
remaining completions. Higher values of `.spec.parallelism` are effectively ignored.
175175
- For _work queue_ Jobs, no new Pods are started after any Pod has succeeded -- remaining Pods are allowed to complete, however.
176-
- If the controller has not had time to react.
177-
- If the controller failed to create Pods for any reason (lack of `ResourceQuota`, lack of permission, etc.),
176+
- If the Job {{< glossary_tooltip term_id="controller" >}} has not had time to react.
177+
- If the Job controller failed to create Pods for any reason (lack of `ResourceQuota`, lack of permission, etc.),
178178
then there may be fewer pods than requested.
179-
- The controller may throttle new Pod creation due to excessive previous pod failures in the same Job.
179+
- The Job controller may throttle new Pod creation due to excessive previous pod failures in the same Job.
180180
- When a Pod is gracefully shut down, it takes time to stop.
181181

182182
## Handling Pod and Container Failures

‎content/en/docs/concepts/workloads/controllers/replicaset.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ ReplicaSet's identifying information within their ownerReferences field. It's th
3232
knows of the state of the Pods it is maintaining and plans accordingly.
3333

3434
A ReplicaSet identifies new Pods to acquire by using its selector. If there is a Pod that has no OwnerReference or the
35-
OwnerReference is not a controller and it matches a ReplicaSet's selector, it will be immediately acquired by said
35+
OwnerReference is not a {{< glossary_tooltip term_id="controller" >}} and it matches a ReplicaSet's selector, it will be immediately acquired by said
3636
ReplicaSet.
3737

3838
## When to use a ReplicaSet

‎content/en/docs/concepts/workloads/controllers/statefulset.md

+5-4
Original file line numberDiff line numberDiff line change
@@ -32,8 +32,8 @@ following.
3232

3333
In the above, stable is synonymous with persistence across Pod (re)scheduling.
3434
If an application doesn't require any stable identifiers or ordered deployment,
35-
deletion, or scaling, you should deploy your application with a controller that
36-
provides a set of stateless replicas. Controllers such as
35+
deletion, or scaling, you should deploy your application using a workload object
36+
that provides a set of stateless replicas.
3737
[Deployment](/docs/concepts/workloads/controllers/deployment/) or
3838
[ReplicaSet](/docs/concepts/workloads/controllers/replicaset/) may be better suited to your stateless needs.
3939

@@ -164,8 +164,9 @@ This must be done manually.
164164

165165
### Pod Name Label
166166

167-
When the StatefulSet controller creates a Pod, it adds a label, `statefulset.kubernetes.io/pod-name`,
168-
that is set to the name of the Pod. This label allows you to attach a Service to a specific Pod in
167+
When the StatefulSet {{< glossary_tooltip term_id="controller" >}} creates a Pod,
168+
it adds a label, `statefulset.kubernetes.io/pod-name`, that is set to the name of
169+
the Pod. This label allows you to attach a Service to a specific Pod in
169170
the StatefulSet.
170171

171172
## Deployment and Scaling Guarantees

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

+15-4
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
@@ -11,9 +11,20 @@ tags:
1111
- architecture
1212
- fundamental
1313
---
14-
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.
14+
In Kubernetes, controllers are control loops that watch the state of your
15+
{{< glossary_tooltip term_id="cluster" text="cluster">}}, then make or request
16+
changes where needed.
17+
Each controller tries to move the current cluster state closer to the desired
18+
state.
1519

16-
<!--more-->
20+
<!--more-->
1721

18-
Examples of controllers that ship with Kubernetes today are the replication controller, endpoints controller, namespace controller, and serviceaccounts controller.
22+
Controllers watch the shared state of your cluster through the
23+
{{< glossary_tooltip text="apiserver" term_id="kube-apiserver" >}} (part of the
24+
{{< glossary_tooltip term_id="control-plane" >}}).
1925

26+
Some controllers also run inside the control plane, providing control loops that
27+
are core to Kubernetes' operations. For example: the deployment controller, the
28+
daemonset controller, the namespace controller, and the persistent volume
29+
controller (and others) all run within the
30+
{{< glossary_tooltip term_id="kube-controller-manager" >}}.

‎content/en/docs/reference/glossary/kube-controller-manager.md

+2-3
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: kube-controller-manager
33
id: kube-controller-manager
44
date: 2018-04-12
5-
full_link: /docs/reference/generated/kube-controller-manager/
5+
full_link: /docs/reference/command-line-tools-reference/kube-controller-manager/
66
short_description: >
77
Component on the master that runs controllers.
88
@@ -13,7 +13,6 @@ tags:
1313
---
1414
Component on the master that runs {{< glossary_tooltip text="controllers" term_id="controller" >}}.
1515

16-
<!--more-->
16+
<!--more-->
1717

1818
Logically, each {{< glossary_tooltip text="controller" term_id="controller" >}} is a separate process, but to reduce complexity, they are all compiled into a single binary and run in a single process.
19-

0 commit comments

Comments
 (0)