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: Pod preset controller
+content_template: templates/concept
+---
+
+{{% capture overview %}}
+
+The Pod preset 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
+
+Pod preset 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` matches 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/attach-detach.md

@@ -0,0 +1,39 @@
+---
+title: Volume attach / detach controller
+content_template: templates/concept
+---
+
+{{% capture overview %}}
+
+The {{< glossary_tooltip text="Volume" term_id="volume" >}}
+attach / detach controller is part of a set of built-in controllers for storage management.
+
+{{% /capture %}}
+
+{{% capture body %}}
+
+## Controller behavior
+
+The volume attach / detach controller is responsible for attaching and detaching
+all Volumes across a cluster. This controller watches the API server for Pod
+creation and termination.
+
+Once a new pod is scheduled, the volume attach / detach controller works out what
+volumes need to be attached and signals this (via the API server) to kubelet and
+to storage services. The controller updates `.status.volumesAttached` on the
+Node where the Pod is scheduled, and kubelet updates `.status.VolumesInUse` once
+it starts using the Volume (ie, mounting it for a container in a Pod).
+
+When a pod is terminated, the controller makes sure that the existing attached
+volumes are detached. After signalling for kubelet to unmount the volume, the
+volume attach / detach controller waits for graceful unmount before attempting
+to detach it.
+
+Different nodes might have different ways of attaching volumes, and different
+Volumes can have different values for VolumeNodeAffinity, so the decision
+around volume attachment happens after scheduling.
+
+To learn more about how Kubernetes manages storage and makes this storage
+available to Pods, refer to the [storage](/docs/concepts/storage/persistent-volumes/) documentation.
+
+{{% /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
+run 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](/reference/access-authn-authz/admission-controllers/#resourcequota)
+
+## Certificate controllers {#controllers-certificates}
+
+* [Root CA controller](/docs/reference/controllers/certificate-root-ca/)
+
+There are also a set of three controllers that work together to provide signed
+certificates on demand, for use within your cluster:
+
+[Certificate signer](/docs/reference/controllers/certificate-signer)
+: 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 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 o
+nsigning requests that come from 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/attach-detach/)
+* [PersistentVolume controller](/docs/reference/controllers/persistentvolume/)
+* [PersistentVolumeClaim controller](/docs/reference/controllers/persistentvolumeclaim/)
+
+## 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 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 [certificate 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,36 @@
+---
+title: Certificate signature approver
+content_template: templates/concept
+---
+
+{{% capture overview %}}
+
+The CertificateSigningRequest approver controller is part of a set of built-in
+controllers for certificate management.
+
+{{% /capture %}}
+
+
+{{% capture body %}}
+The certificate approver is built in to kube-controller-manager.
+
+## Controller behaviour
+
+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 authentication and authorization.
+
+This controller watches for CertificateSigningRequests from kubelet. For each submitted
+CertificateSigningRequest, this controller creates a SubjectAccessReview to verify Kubelet's
+entitlement to have the certificate signed (based on the API server's authorization mechanisms).
+
+If the request is authentica and the SubjectAccessReview passes, the controller marks the
+CSR as approved. This approval allows the Certificate signer can 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 certificate cleaner is built in to kube-controller-manager.
+
+## Controller behaviour
+
+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.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 behaviour
+
+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,30 @@
+---
+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 behaviour
+
+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 into the status field of the CSR.
+
+{{% /capture %}}
+{{% capture whatsnext %}}
+* Read about the [certificate approver](/docs/reference/controllers/certificate-approver/)
+{{% /capture %}}