diff --git a/_data/concepts.yml b/_data/concepts.yml index 742f389f3aded..cb457699fa2d8 100644 --- a/_data/concepts.yml +++ b/_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: diff --git a/docs/admin/admission-controllers.md b/docs/admin/admission-controllers.md index 24df556b4d12f..806646a784ce7 100644 --- a/docs/admin/admission-controllers.md +++ b/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 diff --git a/docs/concepts/workloads/pods/podpreset.md b/docs/concepts/workloads/pods/podpreset.md new file mode 100644 index 0000000000000..c2e1305e1c929 --- /dev/null +++ b/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-": ""`. + +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 %} diff --git a/docs/tasks/inject-data-application/podpreset.md b/docs/tasks/inject-data-application/podpreset.md index c49f0f07f97c2..d2571ab8442c0 100644 --- a/docs/tasks/inject-data-application/podpreset.md +++ b/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 -time. This information can include secrets, volumes, volume mounts, and environment -variables. - -See [PodPreset proposal](https://git.k8s.io/community/contributors/design-proposals/service-catalog/pod-preset.md) for more information. +You can use a `podpreset` object to inject information like secrets, volume +mounts, and environment variables etc into pods at creation time. +This task shows some examples on using the `PodPreset` resource. +You can get an overview of PodPresets at +[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-": ""`. - - -## 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