Add reference documentation for built-in controllers

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

@@ -0,0 +1,5 @@
+---
+title: "Controllers"
+weight: 20
+---
+

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

@@ -0,0 +1,57 @@
+---
+title: PodPreset controller
+content_template: templates/concept
+---
+
+{{% capture overview %}}
+
+The PodPreset admission controller injects configuration data into
+{{< glossary_tooltip text="pods" term_id="pod" >}} when they are created.
+
+The configuration data can include {{< glossary_tooltip text="Secrets" term_id="secret" >}},
+{{< glossary_tooltip text="Volumes" term_id="volume" >}}, volume mounts,
+and {{< glossary_tooltip text="environment variables" term_id="container-env-variables" >}}.
+
+{{% /capture %}}
+
+{{% capture body %}}
+
+## Controller behavior
+
+This is a mutating
+[admission controller](/docs/reference/access-authn-authz/admission-controllers/#what-are-they)
+that acts on Pod creation requests.
+
+When a pod creation request arrives for processing, the controller:
+
+1. Retrieves all `PodPresets` available for use.
+1. Checks if the label selectors of any `PodPreset` match the labels on the
+   Pod being created.
+1. Attempts to merge the various resources defined by the `PodPreset` into the
+   Pod being created.
+1. On error, throws an event documenting the merge error on the Pod, and then
+   allows creation of the the Pod _without_ any injected resources from the `PodPreset`.
+1. Annotates the resulting modified Pod spec to indicate that it has been
+   modified by a `PodPreset`. The annotation is of the form
+   `podpreset.admission.kubernetes.io/podpreset-<pod-preset name>: "<resource version>"`.
+
+Each Pod can be matched by zero or more Pod Presets; and each `PodPreset` can be
+applied to zero or more pods. When a `PodPreset` is applied to one or more
+Pods, Kubernetes modifies the Pod Spec. For changes to `Env`, `EnvFrom`, and
+`VolumeMounts`, Kubernetes modifies the container spec for all containers in
+the Pod; for changes to `Volume`, Kubernetes modifies the Pod Spec.
+
+{{< note >}}
+A Pod Preset is capable of modifying the following fields in a Pod spec when appropriate:
+- The `.spec.containers` field.
+- The `initContainers` field (requires Kubernetes version 1.14.0 or later).
+{{< /note >}}
+
+{{% /capture %}}
+
+{{% capture whatsnext %}}
+
+* Learn how to [enable PodPreset](/docs/concepts/workloads/pods/podpreset/#enable-pod-preset)
+* Try to [inject information into Pods Using a PodPreset](/docs/tasks/inject-data-application/podpreset/)
+
+{{% /capture %}}

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

@@ -0,0 +1,155 @@
+---
+title: Built-in controllers
+content_template: templates/concept
+weight: 10
+---
+
+{{% capture overview %}}
+
+This page lists the {{< glossary_tooltip text="controllers" term_id="controller" >}}
+that come as part of Kubernetes itself.
+{{% /capture %}}
+
+
+{{% capture body %}}
+
+Kubernetes comes with a number of built-in controllers that run as part
+of the {{< glossary_tooltip term_id="kube-controller-manager" >}}.
+
+If your cluster is deployed against a cloud service provider, you can
+use the cloud-controller-manager to run additional provider-specific
+controllers such as
+[Route](/docs/concepts/architecture/cloud-controller/#route-controller).
+
+The cloud controller manager provides an abstract API (in Go) that
+allows cloud vendors to plug in their custom implementation.
+
+The built-in {{< glossary_tooltip term_id="kube-scheduler" text="scheduler" >}}
+is itself a specialized controller. The scheduler's purpose is to reconcile the
+desired set of running Pods and match that against the available Nodes,
+optimizing against discovered constraints.
+{{< glossary_tooltip term_id="kubelet" >}} will update the actual state each
+time it starts or stops a scheduled Pod.
+
+Because its work is essential to Kubernetes' operation, the scheduler
+runs separately from the kube-controller-manager. This separation helps
+with control plane performance.
+
+The controllers that run inside kube-controller-manager are:
+
+## Controllers for running workloads on Kubernetes {#controllers-workloads}
+
+* [CronJob controller](/docs/reference/controllers/cronjob/)
+* [DaemonSet controller](/docs/reference/controllers/daemonset/)
+* [Deployment controller](/docs/reference/controllers/deployment/)
+* [Job controller](/docs/reference/controllers/job/)
+* [ReplicaSet controller](/docs/reference/controllers/replicaset/)
+* [StatefulSet controller](/docs/reference/controllers/statefulset/)
+* [Service controller](/docs/reference/controllers/service/)
+
+## Pod management controllers {#controllers-pod-management}
+
+* [Horizontal Pod Autoscaler](/docs/reference/controllers/horizontal-pod-autoscaler/)
+* [PodDisruptionBudget controller](/docs/reference/controllers/poddisruptionbudget/)
+* [PodPreset controller](/docs/reference/access-authn-authz/admission-controllers/#podpreset)
+
+## Resource management controllers {#controllers-resource-management}
+
+* [Resource quota controller](/docs/reference/access-authn-authz/admission-controllers/#resourcequota)
+
+## Certificate controllers {#controllers-certificates}
+
+* [Root CA controller](/docs/reference/controllers/certificate-root-ca-publisher/)
+
+There are also a set of three controllers that work together to provide signed
+{{< glossary_tooltip text="certificates" term_id="certificate" >}} on demand, for use within your cluster:
+
+[Certificate signer](/docs/reference/controllers/certificate-signer)
+: A controller that signs certificates based on a certificate signing request (CSR),
+  once approved. The issued certificates will have a signing chain back to the root CA.
+
+[Certificate signature approver](/docs/reference/controllers/certificate-approver/)
+: An automated approver for valid certificate signing requests. Requests are approved
+  automatically if the request came from a Node known to Kubernetes.
+
+[CSR cleaner](/docs/reference/controllers/certificate-cleaner/)
+: The CSRs within your cluster have a lifetime. This controller removes CSRs that have
+  expired without being approved.
+
+{{< note >}}
+If you wanted to have something that isn't a Node use a signing request to obtain valid
+cluster certificates, you can implement that in your own custom controller.
+The built-in controller will automatically know not to intervene, because it only acts
+on signing requests that come from nodes.
+{{< /note >}}
+
+## Storage controllers {#controllers-storage}
+
+There are a set of built-in controllers for storage management.
+
+* [Volume attach / detach controller](/docs/reference/controllers/volume-attach-detach/)
+* [PersistentVolume controller](/docs/reference/controllers/volume-persistentvolume/)
+* [PersistentVolumeClaim controller](/docs/reference/controllers/volume-persistentvolumeclaim/)
+* [PersistentVolumeClaim in-use protection controller](/docs/reference/controllers/volume-persistentvolumeclaim-protection/)
+
+## Networking controllers {#controllers-networking}
+
+* [Endpoint controller](/docs/reference/controllers/endpoint)
+* [Service controller](/docs/reference/controllers/service)
+* [Node IP address management controller](/docs/reference/controllers/node-ipam/)
+
+## Cluster orchestration controllers {#controllers-cluster-orchestration}
+
+* [ServiceAccount controller](/docs/reference/controllers/serviceaccount/)
+* [ServiceAccount token controller](/docs/reference/controllers/serviceaccount-token/)
+* [ClusterRole aggregation controller](/docs/reference/controllers/clusterrole-aggregation)
+
+## Garbage collection & expiry controllers {#controllers-gc-expiry}
+
+### Time-to-live (TTL) controller {#controller-ttl}
+
+The [TTL controller](/docs/reference/controllers/ttl/) sets TTL
+annotations on Nodes based on cluster size.
+kubelet consumes these annotations as a hint about how long it can cache
+object data that it has fetched from the
+{{< glossary_tooltip text="API server" term_id="kube-apiserver" >}}.
+
+### TTL-after-finished controller {#controller-ttl-after-finished}
+
+The [TTL-after-finished controller](/docs/reference/controllers/ttl-after-finished)
+cleans up finished task objects; currently, just Jobs.
+
+### Garbage collector {#controller-garbagecollector}
+
+The [garbage collector](/docs/reference/controllers/garbage-collector/) watches
+for changes to objects that have dependencies, and spots objects that are eligible
+for garbage collection. Once identified these are queued for (attempts at) deletion.
+
+Other controllers can rely on this behavior to take care of cascading deletion
+of objects via parent-child relationships.
+
+### Pod garbage collector {#controller-pod-garbage-collector}
+
+The [pod garbage collector](/docs/reference/controllers/pod-garbage-collector/)
+takes care of cleaning up {{< glossary_tooltip text="Pods" term_id="pod" >}} that
+are terminated, so that the resources for tracking those Pods can be reclaimed.
+
+### Certificate signing request cleaner {#controller-certificate-cleaner}
+
+The [CSR cleaner](/docs/reference/controllers/certificate-cleaner/)
+removes old certificate signing requests that haven't been approved and signed.
+
+### Node lifecycle controller {#controller-node-lifecycle}
+
+The [node lifecycle controller](/docs/reference/controllers/node-lifecycle)
+observes the behavior of kubelet on a node, and sets (potentially also removes)
+{{< glossary_tooltip text="taints" term_id="taint" >}} on Nodes that reflect its
+findings.
+
+### Namespace lifecycle controller {#controller-namespace}
+
+When you (or any Kubernetes API client) remove a {{< glossary_tooltip term_id="namespace" >}},
+the [namespace controller](/docs/reference/controllers/namespace/) makes sure that objects in
+that namespace are removed before the namespace itself is removed.
+
+{{% /capture %}}

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

@@ -0,0 +1,37 @@
+---
+title: Certificate signature approver
+content_template: templates/concept
+---
+
+{{% capture overview %}}
+
+The CertificateSigningRequest approver controller (aka CSR approver) is
+part of a set of built-in controllers for certificate management.
+
+{{% /capture %}}
+
+
+{{% capture body %}}
+The CSR approver is built in to kube-controller-manager.
+
+## Controller behavior
+
+This controller acts specifically on CertificateSigningRequests (CSR) that come from
+kubelet (or that purport to come from kubelet).
+
+When kubelet is setting up on a new node, kubelet will generate a CSR and submit it
+to the Kubernetes API server using its
+[bootstrap](/docs/reference/access-authn-authz/bootstrap-tokens/)
+authentication and authorization.
+
+This controller watches for CertificateSigningRequests from kubelet. For each submitted
+CertificateSigningRequest, this controller creates a SubjectAccessReview to verify
+whether this Node's kubelet is allowed to have its certificate signed.
+
+If the request is authentic and the SubjectAccessReview passes, the controller marks the
+CSR as approved. This approval allows the Certificate signer to issue a certificate.
+
+{{% /capture %}}
+{{% capture whatsnext %}}
+* Read about the [certificate signer](/docs/reference/controllers/certificate-signer/)
+{{% /capture %}}

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

@@ -0,0 +1,27 @@
+---
+title: Certificate signing request cleaner
+content_template: templates/concept
+---
+
+{{% capture overview %}}
+
+This controller removes certificate signing requests that have expired without being approved.
+
+{{% /capture %}}
+
+{{% capture body %}}
+
+The CSR cleaner is built in to kube-controller-manager.
+
+## Controller behavior
+
+This controller watches for CertificateSigningRequest (CSR) objects and their approvals.
+
+After a CSR has been in the system for a certain amount of time, without being approved,
+this controller will delete it.
+
+{{% /capture %}}
+{{% capture whatsnext %}}
+* Read about the [certificate approver](/docs/reference/controllers/certificate-approver/)
+* Read about the [certificate signer](/docs/reference/controllers/certificate-signer/)
+{{% /capture %}}

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

@@ -0,0 +1,28 @@
+---
+title: Root CA controller
+content_template: templates/concept
+---
+
+{{% capture overview %}}
+
+Kubernetes clusters have a [certificate authority](/docs/concepts/cluster-administration/certificates/)
+(CA) that the control plane uses to authenticate different components. This
+controller manages a ConfigMap in every configured namespace, so that Pods
+in that namespace have access to the cluster's root CA and can validate other
+components' identity.
+
+{{% /capture %}}
+
+{{% capture body %}}
+
+The root CA controller is built in to kube-controller-manager.
+
+## Controller behavior
+
+This controller watches for namespaces being created. For every new namespace the
+controller adds a ConfigMap containing the cluster's root certificate.
+
+{{% /capture %}}
+{{% capture whatsnext %}}
+* Read about the [certificate approver](/docs/reference/controllers/certificate-approver/)
+{{% /capture %}}

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

@@ -0,0 +1,31 @@
+---
+title: Certificate signer controller
+content_template: templates/concept
+---
+
+{{% capture overview %}}
+
+A controller that signs {{< glossary_tooltip text="certificates" term_id="certificate" >}},
+based on a certificate signing request (CSR), once approved. The issued
+certificates will have a signing chain back to the cluster's root CA.
+
+{{% /capture %}}
+
+{{% capture body %}}
+
+The certificate signer is built in to kube-controller-manager. You can add your own controller,
+either to work alongside this built-in controller, or to work in its place.
+
+## Controller behavior
+
+This controller watches for CertificateSigningRequest (CSR) objects and their approvals.
+When the certificate signer sees an approved request, it signs the request using the
+configured certificate and key (typically, this will be the cluster root CA).
+
+The controller stores the issued certificate in the `status.certificate` field of the
+CertificateSigningRequest object.
+
+{{% /capture %}}
+{{% capture whatsnext %}}
+* Read about the [certificate approver](/docs/reference/controllers/certificate-approver/)
+{{% /capture %}}

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

@@ -0,0 +1,30 @@
+---
+title: ClusterRole aggregation controller
+content_template: templates/concept
+---
+
+{{% capture overview %}}
+
+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
+{{< glossary_tooltip text="Role-Based Access Control" term_id="rbac" >}} (RBAC).
+
+
+{{% /capture %}}
+
+{{% capture body %}}
+
+The ClusterRole aggregation controller is built in to kube-controller-manager.
+
+## Controller behavior
+
+This controller manages the permissions of aggregated ClusterRoles. The controller
+watches ClusterRoles for changes.
+
+If the controller sees changes (add / remove / update) to a ClusterRole that matches
+the clusterRoleSelectors for any existing ClusterRole, it will calcluate the rules
+for the ClusterRole that had clusterRoleSelectors set.
+
+See [Aggregated ClusterRoles](/docs/reference/access-authn-authz/rbac/#aggregated-clusterroles)
+for more information on this.
+
+{{% /capture %}}