Harmonize Pod Preset tasks (#18128)

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

@@ -2,23 +2,19 @@
 reviewers:
 - jessfraz
 title: Inject Information into Pods Using a PodPreset
+min-kubernetes-server-version: v1.10
 content_template: templates/task
 weight: 60
 ---
 
 {{% capture overview %}}
 
-You can use a `PodPreset` object to inject information like secrets, volume
+This page shows how to use PodPreset objects to inject information like {{< glossary_tooltip text="Secrets" term_id="secret" >}}, volume mounts, and {{< glossary_tooltip text="environment variables" term_id="container-env-variables" >}} into Pods at creation time.
-mounts, and environment variables etc into pods at creation time.
-This task shows some examples on using the `PodPreset` resource.
 
 {{% /capture %}}
 
 {{% capture prerequisites %}}
 
-Get an overview of PodPresets at
-[Understanding Pod Presets](/docs/concepts/workloads/pods/podpreset/).
-
 {{< include "task-tutorial-prereqs.md" >}} {{< version-check >}}
 
 {{% /capture %}}
@@ -26,157 +22,295 @@ Get an overview of PodPresets at
 {{% capture steps %}}
 
 
-## Simple Pod Spec Example
+## Use Pod presets to inject environment variables and volumes
 
-This is a simple example to show how a Pod spec is modified by the Pod
+In this step, you create a preset that has a volume mount and one environment variable.
-Preset.
+Here is the manifest for the PodPreset:
 
 {{< codenew file="podpreset/preset.yaml" >}}
 
+In the manifest, you can see that the preset has an environment variable definition called `DB_PORT`
+and a volume mount definition called `cache-volume` which is mounted under `/cache`. The {{< glossary_tooltip text="selector" term_id="selector" >}} specifies that
+the preset will act upon any Pod that is labeled `role:frontend`.
+
 Create the PodPreset:
 
 ```shell
 kubectl apply -f https://k8s.io/examples/podpreset/preset.yaml
 ```
 
-Examine the created PodPreset:
+Verify that the PodPreset has been created:
 
 ```shell
 kubectl get podpreset
 ```
 ```
-NAME             AGE
+NAME             CREATED AT
-allow-database   1m
+allow-database   2020-01-24T08:54:29Z
 ```
 
-The new PodPreset will act upon any pod that has label `role: frontend`.
+This manifest defines a Pod labelled `role: frontend` (matching the PodPreset's selector):
 
 {{< codenew file="podpreset/pod.yaml" >}}
 
-Create a pod:
+Create the Pod:
 
 ```shell
 kubectl create -f https://k8s.io/examples/podpreset/pod.yaml
 ```
 
-List the running Pods:
+Verify that the Pod is running:
 
 ```shell
 kubectl get pods
 ```
+
+The output shows that the Pod is running:
+
 ```
 NAME      READY     STATUS    RESTARTS   AGE
 website   1/1       Running   0          4m
 ```
 
-**Pod spec after admission controller:**
+View the Pod spec altered by the admission controller in order to see the effects of the preset
-
+having been applied:
-{{< codenew file="podpreset/merged.yaml" >}}
-
-To see above output, run the following command:
 
 ```shell
 kubectl get pod website -o yaml
 ```
 
-## Pod Spec with ConfigMap Example
+{{< codenew file="podpreset/merged.yaml" >}}
 
-This is an example to show how a Pod spec is modified by the Pod Preset
+The `DB_PORT` environment variable, the `volumeMount` and the `podpreset.admission.kubernetes.io` annotation
-that defines a `ConfigMap` for Environment Variables.
+of the Pod verify that the preset has been applied.
 
-**User submitted pod spec:**
+## Pod spec with ConfigMap example
 
-{{< codenew file="podpreset/pod.yaml" >}}
+This is an example to show how a Pod spec is modified by a Pod preset
+that references a ConfigMap containing environment variables.
 
-**User submitted `ConfigMap`:**
+Here is the manifest containing the definition of the ConfigMap:
 
 {{< codenew file="podpreset/configmap.yaml" >}}
 
-**Example Pod Preset:**
+Create the ConfigMap:
+
+```shell
+kubectl create -f https://k8s.io/examples/podpreset/configmap.yaml
+```
+
+Here is a PodPreset manifest referencing that ConfigMap:
 
 {{< codenew file="podpreset/allow-db.yaml" >}}
 
-**Pod spec after admission controller:**
+Create the preset that references the ConfigMap:
 
-{{< codenew file="podpreset/allow-db-merged.yaml" >}}
+```shell
+kubectl create -f https://k8s.io/examples/podpreset/allow-db.yaml
+```
 
-## ReplicaSet with Pod Spec Example
+The following manifest defines a Pod matching the PodPreset for this example:
-
-The following example shows that only the pod spec is modified by the Pod
-Preset.
-
-**User submitted ReplicaSet:**
-
-{{< codenew file="podpreset/replicaset.yaml" >}}
-
-**Example Pod Preset:**
-
-{{< codenew file="podpreset/preset.yaml" >}}
-
-**Pod spec after admission controller:**
-
-Note that the ReplicaSet spec was not changed, users have to check individual pods
-to validate that the PodPreset has been applied.
-
-{{< codenew file="podpreset/replicaset-merged.yaml" >}}
-
-## Multiple PodPreset Example
-
-This is an example to show how a Pod spec is modified by multiple Pod
-Injection Policies.
-
-**User submitted pod spec:**
 
 {{< codenew file="podpreset/pod.yaml" >}}
 
-**Example Pod Preset:**
+Create the Pod:
+
+```shell
+kubectl create -f https://k8s.io/examples/podpreset/pod.yaml
+```
+
+View the Pod spec altered by the admission controller in order to see the effects of the preset
+having been applied:
+
+```shell
+kubectl get pod website -o yaml
+```
+
+{{< codenew file="podpreset/allow-db-merged.yaml" >}}
+
+The `DB_PORT` environment variable and the `podpreset.admission.kubernetes.io` annotation of the Pod
+verify that the preset has been applied.
+
+## ReplicaSet with Pod spec example
+
+This is an example to show that only Pod specs are modified by Pod presets. Other workload types 
+like ReplicaSets or Deployments are unaffected.
+
+Here is the manifest for the PodPreset for this example:
 
 {{< codenew file="podpreset/preset.yaml" >}}
 
-**Another Pod Preset:**
+Create the preset:
+
+```shell
+kubectl apply -f https://k8s.io/examples/podpreset/preset.yaml
+```
+
+This manifest defines a ReplicaSet that manages three application Pods:
+
+{{< codenew file="podpreset/replicaset.yaml" >}}
+
+Create the ReplicaSet:
+
+```shell
+kubectl create -f https://k8s.io/examples/podpreset/replicaset.yaml
+```
+
+Verify that the Pods created by the ReplicaSet are running:
+
+```shell
+kubectl get pods
+```
+
+The output shows that the Pods are running:
+
+```
+NAME             READY   STATUS    RESTARTS   AGE
+frontend-2l94q   1/1     Running   0          2m18s
+frontend-6vdgn   1/1     Running   0          2m18s
+frontend-jzt4p   1/1     Running   0          2m18s
+```
+
+View the `spec` of the ReplicaSet:
+
+```shell
+kubectl get replicasets frontend -o yaml
+```
+
+{{< note >}}
+The ReplicaSet object's `spec` was not changed, nor does the ReplicaSet contain a
+`podpreset.admission.kubernetes.io` annotation. This is because a PodPreset only
+applies to Pod objects.
+
+To see the effects of the preset having been applied, you need to look at individual Pods.
+{{< /note >}}
+
+The command to view the specs of the affected Pods is:
+
+```shell
+kubectl get pod --selector=role=frontend -o yaml
+```
+
+{{< codenew file="podpreset/replicaset-merged.yaml" >}}
+
+Again the `podpreset.admission.kubernetes.io` annotation of the Pods
+verifies that the preset has been applied.
+
+## Multiple Pod presets example
+
+This is an example to show how a Pod spec is modified by multiple Pod presets.
+
+
+Here is the manifest for the first PodPreset:
+
+{{< codenew file="podpreset/preset.yaml" >}}
+
+Create the first PodPreset for this example:
+
+```shell
+kubectl apply -f https://k8s.io/examples/podpreset/preset.yaml
+```
+
+Here is the manifest for the second PodPreset:
 
 {{< codenew file="podpreset/proxy.yaml" >}}
 
-**Pod spec after admission controller:**
+Create the second preset:
+
+```shell
+kubectl apply -f https://k8s.io/examples/podpreset/proxy.yaml
+```
+
+Here's a manifest containing the definition of an applicable Pod (matched by two PodPresets):
+
+{{< codenew file="podpreset/pod.yaml" >}}
+
+Create the Pod:
+
+```shell
+kubectl create -f https://k8s.io/examples/podpreset/pod.yaml
+```
+
+View the Pod spec altered by the admission controller in order to see the effects of both presets
+having been applied:
+
+```shell
+kubectl get pod website -o yaml
+```
 
 {{< codenew file="podpreset/multi-merged.yaml" >}}
 
-## Conflict Example
+The `DB_PORT` environment variable, the `proxy-volume` VolumeMount and the two `podpreset.admission.kubernetes.io`
+annotations of the Pod verify that both presets have been applied.
 
-This is an example to show how a Pod spec is not modified by the Pod Preset
+## Conflict example
-when there is a conflict.
 
-**User submitted pod spec:**
+This is an example to show how a Pod spec is not modified by a Pod preset when there is a conflict.
+The conflict in this example consists of a `VolumeMount` in the PodPreset conflicting with a Pod that defines the same `mountPath`.
 
-{{< codenew file="podpreset/conflict-pod.yaml" >}}
+Here is the manifest for the PodPreset:
-
-**Example Pod Preset:**
 
 {{< codenew file="podpreset/conflict-preset.yaml" >}}
 
-**Pod spec after admission controller will not change because of the conflict:**
+Note the `mountPath` value of `/cache`.
+
+Create the preset:
+
+```shell
+kubectl apply -f https://k8s.io/examples/podpreset/conflict-preset.yaml
+```
+
+Here is the manifest for the Pod:
 
 {{< codenew file="podpreset/conflict-pod.yaml" >}}
 
-**If we run `kubectl describe...` we can see the event:**
+Note the volumeMount element with the same path as in the PodPreset.
+
+Create the Pod:
 
 ```shell
-kubectl describe ...
+kubectl create -f https://k8s.io/examples/podpreset/conflict-pod.yaml
-```
-```
-....
-Events:
-  FirstSeen             LastSeen            Count   From                    SubobjectPath               Reason      Message
-  Tue, 07 Feb 2017 16:56:12 -0700   Tue, 07 Feb 2017 16:56:12 -0700 1   {podpreset.admission.kubernetes.io/podpreset-allow-database }    conflict  Conflict on pod preset. Duplicate mountPath /cache.
 ```
 
-## Deleting a Pod Preset
+View the Pod spec:
 
-Once you don't need a pod preset anymore, you can delete it with `kubectl`:
+```shell
+kubectl get pod website -o yaml
+```
+
+{{< codenew file="podpreset/conflict-pod.yaml" >}}
+
+You can see there is no preset annotation (`podpreset.admission.kubernetes.io`). Seeing no annotation tells you that no preset has not been applied to the Pod.
+
+However, the
+[PodPreset admission controller](https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/#podpreset)
+logs a warning containing details of the conflict.
+You can view the warning using `kubectl`:
+
+```shell
+kubectl -n kube-system logs -l=component=kube-apiserver
+```
+
+The output should look similar to:
+
+```
+W1214 13:00:12.987884       1 admission.go:147] conflict occurred while applying podpresets: allow-database on pod:  err: merging volume mounts for allow-database has a conflict on mount path /cache: 
+v1.VolumeMount{Name:"other-volume", ReadOnly:false, MountPath:"/cache", SubPath:"", MountPropagation:(*v1.MountPropagationMode)(nil), SubPathExpr:""}
+does not match
+core.VolumeMount{Name:"cache-volume", ReadOnly:false, MountPath:"/cache", SubPath:"", MountPropagation:(*core.MountPropagationMode)(nil), SubPathExpr:""}
+ in container
+```
+
+Note the conflict message on the path for the VolumeMount.
+
+## Deleting a PodPreset
+
+Once you don't need a PodPreset anymore, you can delete it with `kubectl`:
 
 ```shell
 kubectl delete podpreset allow-database
 ```
+The output shows that the PodPreset was deleted:
 ```
 podpreset "allow-database" deleted
 ```

content/en/examples/podpreset/allow-db-merged.yaml

@@ -14,9 +14,6 @@ spec:
       volumeMounts:
         - mountPath: /cache
           name: cache-volume
-        - mountPath: /etc/app/config.json
-          readOnly: true
-          name: secret-volume
       ports:
         - containerPort: 80
       env:
@@ -32,6 +29,3 @@ spec:
   volumes:
     - name: cache-volume
       emptyDir: {}
-    - name: secret-volume
-      secret:
-        secretName: config-details

content/en/examples/podpreset/allow-db.yaml

@@ -19,12 +19,6 @@ spec:
   volumeMounts:
     - mountPath: /cache
       name: cache-volume
-    - mountPath: /etc/app/config.json
-      readOnly: true
-      name: secret-volume
   volumes:
     - name: cache-volume
       emptyDir: {}
-    - name: secret-volume
-      secret:
-        secretName: config-details