Concepts

Edit This Page

Pod Preset

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.

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 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.

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.
  2. Check if the label selectors of any PodPreset matches the labels on the pod being created.
  3. Attempt to merge the various resources defined by the PodPreset into the Pod being created.
  4. On error, throw an event documenting the merge error on the pod, and create the pod without any injected resources from the PodPreset.
  5. Annotate 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 .spec.containers field in a Pod spec when appropriate. No resource definition from the Pod Preset will be applied to the initContainers field.

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. In minikube add this flag --extra-config=apiserver.runtime-config=settings.k8s.io/v1alpha1=true while starting the cluster.
  2. You have enabled the admission controller PodPreset. One way to doing this is to include PodPreset in the --enable-admission-plugins option value specified for the API server. In minikube add this flag --extra-config=apiserver.enable-admission-plugins=Initializers,NamespaceLifecycle,LimitRanger,ServiceAccount,DefaultStorageClass,DefaultTolerationSeconds,NodeRestriction,MutatingAdmissionWebhook,ValidatingAdmissionWebhook,ResourceQuota,PodPreset while starting the cluster.
  3. You have defined your Pod Presets by creating PodPreset objects in the namespace you will use.

What's next

Feedback