[WIP] Add controller reference pages

content/en/docs/concepts/workloads/controllers/garbage-collection.md

@@ -17,16 +17,15 @@ that once had an owner, but no longer have an owner.
 ## Owners and dependents
 
 Some Kubernetes objects are owners of other objects. For example, a ReplicaSet
-is the owner of a set of Pods. The owned objects are called *dependents* of the
+owns a set of Pods. The owned objects are called *dependents* of the
 owner object. Every dependent object has a `metadata.ownerReferences` field that
 points to the owning object.
 
 Sometimes, Kubernetes sets the value of `ownerReference` automatically. For
 example, when you create a ReplicaSet, Kubernetes automatically sets the
-`ownerReference` field of each Pod in the ReplicaSet. In 1.8, Kubernetes
+`ownerReference` field of each Pod in the ReplicaSet. Kubernetes
 automatically sets the value of `ownerReference` for objects created or adopted
-by ReplicationController, ReplicaSet, StatefulSet, DaemonSet, Deployment, Job
-and CronJob.
+by workload resources such as {{< glossary_tooltip term_id="deployment" >}}.
 
 You can also specify relationships between owners and dependents by manually
 setting the `ownerReference` field.
@@ -164,20 +163,12 @@ to delete not only the ReplicaSets created, but also their Pods. If this type of
 is not used, only the ReplicaSets will be deleted, and the Pods will be orphaned.
 See [kubeadm/#149](https://github.com/kubernetes/kubeadm/issues/149#issuecomment-284766613) for more information.
 
-## Known issues
-
-Tracked at [#26120](https://github.com/kubernetes/kubernetes/issues/26120)
-
 {{% /capture %}}
 
-
 {{% capture whatsnext %}}
 
-[Design Doc 1](https://git.k8s.io/community/contributors/design-proposals/api-machinery/garbage-collection.md)
-
-[Design Doc 2](https://git.k8s.io/community/contributors/design-proposals/api-machinery/synchronous-garbage-collection.md)
+* Read the reference documentation for the [garbage collector](/docs/reference/controllers/garbage-collector/)
+* Read [Garbage collection design document 1](https://git.k8s.io/community/contributors/design-proposals/api-machinery/garbage-collection.md)
+* Read [Garbage collection design document 2](https://git.k8s.io/community/contributors/design-proposals/api-machinery/synchronous-garbage-collection.md)
 
 {{% /capture %}}
-
-
-

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

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

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

@@ -0,0 +1,59 @@
+---
+toc_hide: true
+toc_hide: true
+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,49 @@
+---
+title: Built-in controllers
+content_template: templates/concept
+weight: 10
+---
+
+{{% capture overview %}}
+
+Kubernetes comes with a number of built-in 
+{{< glossary_tooltip text="controllers" term_id="controller" >}} that run as
+part of the {{< glossary_tooltip term_id="kube-controller-manager" >}}.
+
+This page summarizes the types of controller that come as part of Kubernetes
+itself.
+
+{{% /capture %}}
+
+{{% capture body %}}
+
+The built-in {{< glossary_tooltip term_id="kube-scheduler" >}}
+is itself a specialized controller. [Scheduling](/docs/concepts/scheduling/)
+means matching the desired set of running
+{{< glossary_tooltip text="Pods" term_id="pod" >}} against the available
+{{< glossary_tooltip text="Nodes" term_id="node" >}}.
+
+The kube-scheduler runs separately from the kube-controller-manager. This
+separation helps with control plane performance.
+
+{{< note >}}
+If your cluster is deployed against a cloud service provider, you can
+use the
+[cloud-controller-manager](/docs/reference/command-line-tools-reference/cloud-controller-manager/)
+to run additional provider-specific controllers such as
+[Route](/docs/concepts/architecture/cloud-controller/#route-controller).
+{{< /note >}}
+
+
+## Controllers grouped by purpose
+
+* [Workload controllers](/docs/reference/controllers/workload-controllers/)
+* [Pod management controllers](/docs/reference/controllers/workload-controllers/)
+* [Resource management controllers](/docs/reference/controllers/resource-management-controllers/)
+* [Certificate controllers](/docs/reference/controllers/certificate-controllers/)
+* [Storage controllers](/docs/reference/controllers/storage-controllers/)
+* [Networking controllers](/docs/reference/controllers/network-controllers/)
+* [Cluster orchestration controllers](/docs/reference/controllers/cluster-orchestration-controllers/)
+* [Resource clean-up controllers](/docs/reference/controllers/resource-cleanup-controllers/)
+
+{{% /capture %}}

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

@@ -0,0 +1,42 @@
+---
+toc_hide: true
+title: Certificate signature approver
+content_template: templates/concept
+---
+
+{{% capture overview %}}
+
+The CertificateSigningRequest approver
+{{< glossary_tooltip term_id="controller" text="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 the {{< glossary_tooltip term_id="kube-controller-manager" >}}.
+
+## Controller behavior
+
+This controller acts specifically on CertificateSigningRequests (CSR) that come from
+the kubelet (or that purport to come from kubelet).
+
+When the kubelet is setting up on a new node, the kubelet generates a CSR and submits
+it to the Kubernetes API server using
+[bootstrap](/docs/reference/access-authn-authz/bootstrap-tokens/)
+authentication and authorization.
+
+This controller watches for CertificateSigningRequests from a kubelet. For each
+submitted CertificateSigningRequest, this controller creates a
+SubjectAccessReview object 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](/docs/reference/controllers/certificate-signer) to issue a certificate.
+
+{{% /capture %}}
+{{% capture whatsnext %}}
+* Read about the [certificate signer](/docs/reference/controllers/certificate-signer/)
+* Read about other [certificate controllers](/docs/reference/controllers/certificate-controllers/)
+{{% /capture %}}

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

@@ -0,0 +1,30 @@
+---
+toc_hide: true
+title: Certificate signing request cleaner
+content_template: templates/concept
+---
+
+{{% capture overview %}}
+
+This {{< glossary_tooltip term_id="controller" >}} removes certificate signing
+requests (CSRs) that have expired without being approved.
+
+{{% /capture %}}
+
+{{% capture body %}}
+
+The CSR cleaner is built in to the {{< glossary_tooltip term_id="kube-controller-manager" >}}.
+
+## Controller behavior
+
+This controller watches for CertificateSigningRequest objects and their approvals.
+
+After a CSR has been in the system for a certain amount of time without being approved,
+this controller deletes it.
+
+{{% /capture %}}
+{{% capture whatsnext %}}
+* Read about the [certificate approver](/docs/reference/controllers/certificate-approver/)
+* Read about the [certificate signer](/docs/reference/controllers/certificate-signer/)
+* Learn about other [resource clean-up controllers](/docs/reference/controllers/resource-cleanup-controllers/)
+{{% /capture %}}

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

@@ -0,0 +1,64 @@
+---
+title: Certificate controllers
+content_template: templates/concept
+weight: 50
+---
+
+{{% capture overview %}}
+
+This page lists the
+{{< glossary_tooltip term_id="certificate" text="certificate" >}}
+{{< glossary_tooltip text="controllers" term_id="controller" >}}
+that come as part of Kubernetes itself.
+
+{{% /capture %}}
+
+{{% capture body %}}
+
+## Root certificate publisher
+
+The [root certificate publisher](/docs/reference/controllers/certificate-root-ca-publisher/)
+manages a {{< glossary_tooltip term_id="configmap" >}} in every configured Namespace, so that Pods in that
+namespace have access to the cluster's root certificate. Pods can load that
+ConfigMap and use the cluster root certificate to validate other components'
+identities.
+
+## Certificate signing controllers
+
+There are a set of three controllers that work together to provide signed
+certificates on demand, for use within your cluster:
+
+### Certificate signature approver
+
+The [certificate signature approver](/docs/reference/controllers/certificate-approver/)
+automates approval of certificate signing requests made by a Node within your
+cluster.
+
+{{< note >}}
+If you want to enable something that isn't a Node to use a CertificateSigningRequest and
+obtain valid cluster certificates, you can implement that in a new
+[custom controller](/docs/concepts/extend-kubernetes/extend-cluster/#extension-patterns).
+
+The built-in certificate signature approver only reacts to certificate signing
+requests that come from cluster nodes.
+{{< /note >}}
+
+### CertificateSigningRequest signer
+
+The [certificate signer](/docs/reference/controllers/certificate-signer/) is 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.
+
+### CSR cleaner
+
+Within your cluster, CertificateSigningRequests (CSRs) stay valid only for a
+limited time.
+The [CSR cleaner](/docs/reference/controllers/certificate-cleaner/)
+removes CertificateSigningRequests that have expired without being approved.
+
+{{% /capture %}}
+
+{{% capture whatsnext %}}
+* Read about [storage controllers](/docs/reference/controllers/storage-controllers/)
+{{% /capture %}}

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

@@ -0,0 +1,32 @@
+---
+toc_hide: true
+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 {{< glossary_tooltip term_id="controller" text="controller" >}} manages a
+{{< glossary_tooltip term_id="configmap" >}} in every configured
+{{< glossary_tooltip term_id="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 the {{< glossary_tooltip term_id="kube-controller-manager" >}}.
+
+## Controller behavior
+
+This controller watches for Namespaces. For every new Namespace, the
+controller adds a ConfigMap containing the cluster's root certificate.
+
+{{% /capture %}}
+{{% capture whatsnext %}}
+* Read about other [certificate controllers](/docs/reference/controllers/certificate-controllers/)
+{{% /capture %}}

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

@@ -0,0 +1,35 @@
+---
+toc_hide: true
+title: Certificate signer controller
+content_template: templates/concept
+---
+
+{{% capture overview %}}
+
+A {{< glossary_tooltip term_id="controller" text="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 the {{< glossary_tooltip term_id="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/)
+* Read about other [certificate controllers](/docs/reference/controllers/certificate-controllers/)
+{{% /capture %}}