Split PodPreset concept out from task doc (#5984)

_data/concepts.yml

@@ -40,6 +40,7 @@ toc:
     - docs/concepts/workloads/pods/pod.md
     - docs/concepts/workloads/pods/pod-lifecycle.md
     - docs/concepts/workloads/pods/init-containers.md
+    - docs/concepts/workloads/pods/podpreset.md
     - docs/concepts/workloads/pods/disruptions.md
   - title: Controllers
     section:

docs/admin/admission-controllers.md

@@ -364,7 +364,8 @@ For more information about persistent volume claims, see ["PersistentVolumeClaim
 ### PodPreset
 
 This plug-in injects a pod with the fields specified in a matching PodPreset.
-See also [Inject Information into Pods Using a PodPreset](/docs/tasks/inject-data-application/podpreset)
+See also [PodPreset concept](docs/concepts/workloads/pods/podpreset/) and
+[Inject Information into Pods Using a PodPreset](/docs/tasks/inject-data-application/podpreset)
 for more information.
 
 ### PodSecurityPolicy

docs/concepts/workloads/pods/podpreset.md

@@ -0,0 +1,79 @@
+---
+approvers:
+- jessfraz
+title: Pod Preset
+---
+
+{% capture overview %}
+This page provides an overview of PodPresets, which are objects for injecting
+certain information into pods at creation time. The information can include
+secrets, volumes, volume mounts, and environment variables.
+{% endcapture %}
+
+{:toc}
+
+{% capture body %}
+## Understanding Pod Presets
+
+A "Pod Preset" is an API resource for injecting additional runtime requirements
+into a Pod at creation time.
+You use [label selectors] (/docs/concepts/overview/working-with-objects/labels/#label-selectors)
+to specify the Pods to which a given Pod Preset applies.
+
+Using a Pod Preset allows pod template authors to not have to explicitly provide 
+all information for every pod. This way, authors of pod templates consuming a
+specific service do not need to know all the details about that service.
+
+For more information about the background, see the [design proposal for PodPreset](https://git.k8s.io/community/contributors/design-proposals/service-catalog/pod-preset.md).
+
+## How It Works
+
+Kubernetes provides an admission controller (`PodPreset`) which, when enabled,
+applies Pod Presets to incoming pod creation requests.
+When a pod creation request occurs, the system does the following:
+
+1. Retrieve all `PodPresets` available for use.
+1. Check if the label selectors of any `PodPreset` matches the labels on the
+   pod being created.
+1. Attempt to merge the various resources defined by the `PodPreset` into the
+   Pod being created.
+1. On error, throw an event documenting the merge error on the pod, and create
+   the pod _without_ any injected resources from the `PodPreset`.
+1. Annotate the resulting mmodified 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 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.
+
+### Disable Pod Preset for a Specific Pod
+
+There may be instances where you wish for a Pod to not be altered by any Pod
+Preset mutations. In these cases, you can add an annotation in the Pod Spec
+of the form: `podpreset.admission.kubernetes.io/exclude: "true"`.
+
+## Enable Pod Preset
+
+In order to use Pod Presets in your cluster you must ensure the following:
+
+1.  You have enabled the API type `settings.k8s.io/v1alpha1/podpreset`. For
+    example, this can be done by including `settings.k8s.io/v1alpha1=true` in
+    the `--runtime-config` option for the API server. 
+1.  You have enabled the admission controller `PodPreset`. One way to doing this
+    is to include `PodPreset` in the `--admission-control` option value specified
+    for the API server.
+1.  You have defined your Pod Presets by creating `PodPreset` objects in the
+    namespace you will use.
+
+{% endcapture %}
+
+{% capture whatsnext %}
+
+* [Injecting data into a Pod using PodPreset](/docs/tasks/inject-data-application/podpreset/)
+
+{% endcapture %}
+
+{% include templates/concept.md %}

docs/tasks/inject-data-application/podpreset.md

@@ -4,66 +4,15 @@ approvers:
 title: Inject Information into Pods Using a PodPreset
 ---
 
-You can use a `podpreset` object to inject certain information into pods at creation
+You can use a `podpreset` object to inject information like secrets, volume
-time. This information can include secrets, volumes, volume mounts, and environment
+mounts, and environment variables etc into pods at creation time.
-variables.
+This task shows some examples on using the `PodPreset` resource.
-
+You can get an overview of PodPresets at
-See [PodPreset proposal](https://git.k8s.io/community/contributors/design-proposals/service-catalog/pod-preset.md) for more information.
+[Understanding Pod Presets](/docs/concepts/workloads/pods/podpreset/).
 
 * TOC
 {:toc}
 
-## What is a Pod Preset?
-
-A _Pod Preset_ is an API resource that you can use to inject additional runtime
-requirements into a Pod at creation time. You use label selectors to specify
-the Pods to which a given Pod Preset applies. Check out more information on [label
-selectors](/docs/concepts/overview/working-with-objects/labels/#label-selectors).
-
-Using a Pod Preset allows pod template authors to not have to explicitly set
-information for every pod. This way, authors of pod templates consuming a
-specific service do not need to know all the details about that service.
-
-## Admission Control
-
-_Admission control_ is how Kubernetes applies Pod Presets to incoming pod
-creation requests. When a pod creation request occurs, the system does the
-following:
-
-1. Retrieve all `PodPresets` available for use.
-1. Match the label selector of the `PodPreset` to the pod being created.
-1. Attempt to merge the various defined resources for the `PodPreset` into the
-   Pod being created.
-1. On error, throw an event documenting the merge error on the pod, and create
-   the pod _without_ any injected resources from the `PodPreset`.
-
-### Behavior
-
-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.
-
-Kubernetes annotates the resulting modified pod spec to show that it was
-modified by a `PodPreset`. The annotation is of the form
-`podpreset.admission.kubernetes.io/podpreset-<pod-preset name>": "<resource version>"`.
-
-
-## Enable Pod Preset
-
-In order to use Pod Presets in your cluster you must ensure the
-following
-
-1.  You have enabled the api type `settings.k8s.io/v1alpha1/podpreset`
-1.  You have enabled the admission controller `PodPreset`
-1.  You have defined your pod presets
-
-## Disable Pod Preset for a pod
-
-There may be instances where you wish for a pod to not be altered by any pod
-preset mutations. For these events, one can add an annotation in the pod spec
-of the form: `podpreset.admission.kubernetes.io/exclude: "true"`.
-
 ## Create a Pod Preset
 
 ### Simple Pod Spec Example