Skip to content

Commit d432671

Browse files
sftimsftim
committed
Add reference documentation for built-in controllers
1 parent 55d6324 commit d432671

35 files changed

+1704
-0
lines changed

‎content/en/docs/reference/controllers/_index.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
title: "Controllers"
3+
weight: 20
4+
---
5+

‎content/en/docs/reference/controllers/admission-pod-preset.md

+57
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
---
2+
title: Pod preset controller
3+
content_template: templates/concept
4+
---
5+
6+
{{% capture overview %}}
7+
8+
The Pod preset admission controller injects configuration data into
9+
{{< glossary_tooltip text="pods" term_id="pod" >}} when they are created.
10+
11+
The configuration data can include {{< glossary_tooltip text="Secrets" term_id="secret" >}},
12+
{{< glossary_tooltip text="Volumes" term_id="volume" >}}, volume mounts,
13+
and {{< glossary_tooltip text="environment variables" term_id="container-env-variables" >}}.
14+
15+
{{% /capture %}}
16+
17+
{{% capture body %}}
18+
19+
## Controller behavior
20+
21+
Pod preset is a mutating
22+
[admission controller](/docs/reference/access-authn-authz/admission-controllers/#what-are-they)
23+
that acts on Pod creation requests.
24+
25+
When a pod creation request arrives for processing, the controller:
26+
27+
1. Retrieves all `PodPresets` available for use.
28+
1. Checks if the label selectors of any `PodPreset` match the labels on the
29+
Pod being created.
30+
1. Attempts to merge the various resources defined by the `PodPreset` into the
31+
Pod being created.
32+
1. On error, throws an event documenting the merge error on the Pod, and then
33+
allows creation of the the Pod _without_ any injected resources from the `PodPreset`.
34+
1. Annotates the resulting modified Pod spec to indicate that it has been
35+
modified by a `PodPreset`. The annotation is of the form
36+
`podpreset.admission.kubernetes.io/podpreset-<pod-preset name>: "<resource version>"`.
37+
38+
Each Pod can be matched by zero or more Pod Presets; and each `PodPreset` can be
39+
applied to zero or more pods. When a `PodPreset` is applied to one or more
40+
Pods, Kubernetes modifies the Pod Spec. For changes to `Env`, `EnvFrom`, and
41+
`VolumeMounts`, Kubernetes modifies the container spec for all containers in
42+
the Pod; for changes to `Volume`, Kubernetes modifies the Pod Spec.
43+
44+
{{< note >}}
45+
A Pod Preset is capable of modifying the following fields in a Pod spec when appropriate:
46+
- The `.spec.containers` field.
47+
- The `initContainers` field (requires Kubernetes version 1.14.0 or later).
48+
{{< /note >}}
49+
50+
{{% /capture %}}
51+
52+
{{% capture whatsnext %}}
53+
54+
* Learn how to [enable PodPreset](/docs/concepts/workloads/pods/podpreset/#enable-pod-preset)
55+
* Try to [inject information into Pods Using a PodPreset](/docs/tasks/inject-data-application/podpreset/)
56+
57+
{{% /capture %}}

‎content/en/docs/reference/controllers/built-in.md

+155
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
---
2+
title: Built-in controllers
3+
content_template: templates/concept
4+
weight: 10
5+
---
6+
7+
{{% capture overview %}}
8+
9+
This page lists the {{< glossary_tooltip text="controllers" term_id="controller" >}}
10+
that come as part of Kubernetes itself.
11+
{{% /capture %}}
12+
13+
14+
{{% capture body %}}
15+
16+
Kubernetes comes with a number of built-in controllers that run as part
17+
of the {{< glossary_tooltip term_id="kube-controller-manager" >}}.
18+
19+
If your cluster is deployed against a cloud service provider, you can
20+
use the cloud-controller-manager to run additional provider-specific
21+
controllers such as
22+
[Route](/docs/concepts/architecture/cloud-controller/#route-controller).
23+
24+
The cloud controller manager provides an abstract API (in Go) that
25+
allows cloud vendors to plug in their custom implementation.
26+
27+
The built-in {{< glossary_tooltip term_id="kube-scheduler" text="scheduler" >}}
28+
is itself a specialized controller. The scheduler's purpose is to reconcile the
29+
desired set of running Pods and match that against the available Nodes,
30+
optimizing against discovered constraints.
31+
{{< glossary_tooltip term_id="kubelet" >}} will update the actual state each
32+
time it starts or stops a scheduled Pod.
33+
34+
Because its work is essential to Kubernetes' operation, the scheduler
35+
runs separately from the kube-controller-manager. This separation helps
36+
with control plane performance.
37+
38+
The controllers that run inside kube-controller-manager are:
39+
40+
## Controllers for running workloads on Kubernetes {#controllers-workloads}
41+
42+
* [CronJob controller](/docs/reference/controllers/cronjob/)
43+
* [DaemonSet controller](/docs/reference/controllers/daemonset/)
44+
* [Deployment controller](/docs/reference/controllers/deployment/)
45+
* [Job controller](/docs/reference/controllers/job/)
46+
* [ReplicaSet controller](/docs/reference/controllers/replicaset/)
47+
* [StatefulSet controller](/docs/reference/controllers/statefulset/)
48+
* [Service controller](/docs/reference/controllers/service/)
49+
50+
## Pod management controllers {#controllers-pod-management}
51+
52+
* [Horizontal Pod Autoscaler](/docs/reference/controllers/horizontal-pod-autoscaler/)
53+
* [PodDisruptionBudget controller](/docs/reference/controllers/poddisruptionbudget/)
54+
* [PodPreset controller](/docs/reference/access-authn-authz/admission-controllers/#podpreset)
55+
56+
## Resource management controllers {#controllers-resource-management}
57+
58+
* [Resource quota controller](/reference/access-authn-authz/admission-controllers/#resourcequota)
59+
60+
## Certificate controllers {#controllers-certificates}
61+
62+
* [Root CA controller](/docs/reference/controllers/certificate-root-ca-publisher/)
63+
64+
There are also a set of three controllers that work together to provide signed
65+
{{< glossary_tooltip text="certificates" term_id="certificate" >}} on demand, for use within your cluster:
66+
67+
[Certificate signer](/docs/reference/controllers/certificate-signer)
68+
: A controller that signs certificates based on a certificate signing request (CSR),
69+
once approved. The issued certificates will have a signing chain back to the root CA.
70+
71+
[Certificate signature approver](/docs/reference/controllers/certificate-approver/)
72+
: An automated approver for valid certificate signing requests. Requests are approved
73+
automatically if the request came from a Node known to Kubernetes.
74+
75+
[CSR cleaner](/docs/reference/controllers/certificate-cleaner/)
76+
: The CSRs within your cluster have a lifetime. This controller removes CSRs that have
77+
expired without being approved.
78+
79+
{{< note >}}
80+
If you wanted to have something that isn't a Node use a signing request to obtain valid
81+
cluster certificates, you can implement that in your own custom controller.
82+
The built-in controller will automatically know not to intervene, because it only acts
83+
on signing requests that come from nodes.
84+
{{< /note >}}
85+
86+
## Storage controllers {#controllers-storage}
87+
88+
There are a set of built-in controllers for storage management.
89+
90+
* [Volume attach / detach controller](/docs/reference/controllers/volume-attach-detach/)
91+
* [PersistentVolume controller](/docs/reference/controllers/volume-persistentvolume/)
92+
* [PersistentVolumeClaim controller](/docs/reference/controllers/volume-persistentvolumeclaim/)
93+
* [PersistentVolumeClaim in-use protection controller](/docs/reference/controllers/volume-persistentvolumeclaim-protection/)
94+
95+
## Networking controllers {#controllers-networking}
96+
97+
* [Endpoint controller](/docs/reference/controllers/endpoint)
98+
* [Service controller](/docs/reference/controllers/service)
99+
* [Node IP address management controller](/docs/reference/controllers/node-ipam/)
100+
101+
## Cluster orchestration controllers {#controllers-cluster-orchestration}
102+
103+
* [ServiceAccount controller](/docs/reference/controllers/serviceaccount/)
104+
* [ServiceAccount token controller](/docs/reference/controllers/serviceaccount-token/)
105+
* [ClusterRole aggregation controller](/docs/reference/controllers/clusterrole-aggregation)
106+
107+
## Garbage collection & expiry controllers {#controllers-gc-expiry}
108+
109+
### Time-to-live (TTL) controller {#controller-ttl}
110+
111+
The [TTL controller](/docs/reference/controllers/ttl/) sets TTL
112+
annotations on Nodes based on cluster size.
113+
kubelet consumes these annotations as a hint about how long it can cache
114+
object data that it has fetched from the
115+
{{< glossary_tooltip text="API server" term_id="kube-apiserver" >}}.
116+
117+
### TTL-after-finished controller {#controller-ttl-after-finished}
118+
119+
The [TTL-after-finished controller](/docs/reference/controllers/ttl-after-finished)
120+
cleans up finished task objects; currently, just Jobs.
121+
122+
### Garbage collector {#controller-garbagecollector}
123+
124+
The [garbage collector](/docs/reference/controllers/garbage-collector/) watches
125+
for changes to objects that have dependencies, and spots objects that are eligible
126+
for garbage collection. Once identified these are queued for (attempts at) deletion.
127+
128+
Other controllers can rely on this behavior to take care of cascading deletion
129+
of objects via parent-child relationships.
130+
131+
### Pod garbage collector {#controller-pod-garbage-collector}
132+
133+
The [pod garbage collector](/docs/reference/controllers/pod-garbage-collector/)
134+
takes care of cleaning up {{< glossary_tooltip text="Pods" term_id="pod" >}} that
135+
are terminated, so that the resources for tracking those Pods can be reclaimed.
136+
137+
### Certificate signing request cleaner {#controller-certificate-cleaner}
138+
139+
The [CSR cleaner](/docs/reference/controllers/certificate-cleaner/)
140+
removes old certificate signing requests that haven't been approved and signed.
141+
142+
### Node lifecycle controller {#controller-node-lifecycle}
143+
144+
The [node lifecycle controller](/docs/reference/controllers/node-lifecycle)
145+
observes the behavior of kubelet on a node, and sets (potentially also removes)
146+
{{< glossary_tooltip text="taints" term_id="taint" >}} on Nodes that reflect its
147+
findings.
148+
149+
### Namespace lifecycle controller {#controller-namespace}
150+
151+
When you (or any Kubernetes API client) remove a {{< glossary_tooltip term_id="namespace" >}},
152+
the [namespace controller](/docs/reference/controllers/namespace/) makes sure that objects in
153+
that namespace are removed before the namespace itself is removed.
154+
155+
{{% /capture %}}

‎content/en/docs/reference/controllers/certificate-approver.md

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
title: Certificate signature approver
3+
content_template: templates/concept
4+
---
5+
6+
{{% capture overview %}}
7+
8+
The CertificateSigningRequest approver controller is part of a set of built-in
9+
controllers for certificate management.
10+
11+
{{% /capture %}}
12+
13+
14+
{{% capture body %}}
15+
The CSR approver is built in to kube-controller-manager.
16+
17+
## Controller behaviour
18+
19+
This controller acts specifically on CertificateSigningRequests (CSR) that come from
20+
kubelet (or that purport to come from kubelet).
21+
22+
When kubelet is setting up on a new node, kubelet will generate a CSR and submit it
23+
to the Kubernetes API server using its
24+
[bootstrap](https://kubernetes.io/docs/reference/access-authn-authz/bootstrap-tokens/)
25+
authentication and authorization.
26+
27+
This controller watches for CertificateSigningRequests from kubelet. For each submitted
28+
CertificateSigningRequest, this controller creates a SubjectAccessReview to verify
29+
whether this Node's kubelet is allowed to have its certificate signed.
30+
31+
If the request is authentic and the SubjectAccessReview passes, the controller marks the
32+
CSR as approved. This approval allows the Certificate signer to issue a certificate.
33+
34+
{{% /capture %}}
35+
{{% capture whatsnext %}}
36+
* Read about the [certificate signer](/docs/reference/controllers/certificate-signer/)
37+
{{% /capture %}}

‎content/en/docs/reference/controllers/certificate-cleaner.md

+27
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
title: Certificate signing request cleaner
3+
content_template: templates/concept
4+
---
5+
6+
{{% capture overview %}}
7+
8+
This controller removes certificate signing requests that have expired without being approved.
9+
10+
{{% /capture %}}
11+
12+
{{% capture body %}}
13+
14+
The CSR cleaner is built in to kube-controller-manager.
15+
16+
## Controller behaviour
17+
18+
This controller watches for CertificateSigningRequest (CSR) objects and their approvals.
19+
20+
After a CSR has been in the system for a certain amount of time, without being approved,
21+
this controller will delete it.
22+
23+
{{% /capture %}}
24+
{{% capture whatsnext %}}
25+
* Read about the [certificate approver](/docs/reference/controllers/certificate-approver/)
26+
* Read about the [certificate signer](/docs/reference/controllers/certificate-signer/)
27+
{{% /capture %}}

‎content/en/docs/reference/controllers/certificate-root-ca-publisher.md

+28
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
title: Root CA controller
3+
content_template: templates/concept
4+
---
5+
6+
{{% capture overview %}}
7+
8+
Kubernetes clusters have a [certificate authority](/docs/concepts/cluster-administration/certificates/)
9+
(CA) that the control plane uses to authenticate different components. This
10+
controller manages a ConfigMap in every configured namespace, so that Pods
11+
in that namespace have access to the cluster's root CA and can validate other
12+
components' identity.
13+
14+
{{% /capture %}}
15+
16+
{{% capture body %}}
17+
18+
The root CA controller is built in to kube-controller-manager.
19+
20+
## Controller behaviour
21+
22+
This controller watches for namespaces being created. For every new namespace the
23+
controller adds a ConfigMap containing the cluster's root certificate.
24+
25+
{{% /capture %}}
26+
{{% capture whatsnext %}}
27+
* Read about the [certificate approver](/docs/reference/controllers/certificate-approver/)
28+
{{% /capture %}}

‎content/en/docs/reference/controllers/certificate-signer.md

+31
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
title: Certificate signer controller
3+
content_template: templates/concept
4+
---
5+
6+
{{% capture overview %}}
7+
8+
A controller that signs {{< glossary_tooltip text="certificates" term_id="certificate" >}},
9+
based on a certificate signing request (CSR), once approved. The issued
10+
certificates will have a signing chain back to the cluster's root CA.
11+
12+
{{% /capture %}}
13+
14+
{{% capture body %}}
15+
16+
The certificate signer is built in to kube-controller-manager. You can add your own controller,
17+
either to work alongside this built-in controller, or to work in its place.
18+
19+
## Controller behaviour
20+
21+
This controller watches for CertificateSigningRequest (CSR) objects and their approvals.
22+
When the certificate signer sees an approved request, it signs the request using the
23+
configured certificate and key (typically, this will be the cluster root CA).
24+
25+
The controller stores the issued certificate in the `status.certificate` field of the
26+
CertificateSigningRequest object.
27+
28+
{{% /capture %}}
29+
{{% capture whatsnext %}}
30+
* Read about the [certificate approver](/docs/reference/controllers/certificate-approver/)
31+
{{% /capture %}}

‎content/en/docs/reference/controllers/clusterrole-aggregation.md

+30
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
title: ClusterRole aggregation controller
3+
content_template: templates/concept
4+
---
5+
6+
{{% capture overview %}}
7+
8+
This controller implements the `aggregationRule` property for [ClusterRoles](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#role-and-clusterrole), which are used in connection with
9+
{{< glossary_tooltip text="Role-Based Access Control" term_id="rbac" >}} (RBAC).
10+
11+
12+
{{% /capture %}}
13+
14+
{{% capture body %}}
15+
16+
The ClusterRole aggregation controller is built in to kube-controller-manager.
17+
18+
## Controller behaviour
19+
20+
This controller manages the permissions of aggregated ClusterRoles. The controller
21+
watches ClusterRoles for changes.
22+
23+
If the controller sees changes (add / remove / update) to a ClusterRole that matches
24+
the clusterRoleSelectors for any existing ClusterRole, it will calcluate the rules
25+
for the ClusterRole that had clusterRoleSelectors set.
26+
27+
See [Aggregated ClusterRoles](/docs/reference/access-authn-authz/rbac/#aggregated-clusterroles)
28+
for more information on this.
29+
30+
{{% /capture %}}

0 commit comments

Comments
 (0)