// Module included in the following assemblies:
//
// * nodes/nodes-pods-using.adoc

[id="nodes-pods-using-example_{context}"]
= Example pod configurations

{product-title} leverages the Kubernetes concept of a _pod_, which is one or more containers deployed
together on one host, and the smallest compute unit that can be defined,
deployed, and managed.

The following is an example definition of a pod that provides a long-running
service, which is actually a part of the {product-title} infrastructure: the
integrated container image registry. It demonstrates many features of pods, most of
which are discussed in other topics and thus only briefly mentioned here:

[id="example-pod-definition_{context}"]
.`Pod` object definition (YAML)

[source,yaml]
----
kind: Pod
apiVersion: v1
metadata:
  name: example
  namespace: default
  selfLink: /api/v1/namespaces/default/pods/example
  uid: 5cc30063-0265780783bc
  resourceVersion: '165032'
  creationTimestamp: '2019-02-13T20:31:37Z'
  labels:                  <1>
    app: hello-openshift
  annotations:
    openshift.io/scc: anyuid
spec:
  restartPolicy: Always      <2>
  serviceAccountName: default
  imagePullSecrets:
    - name: default-dockercfg-5zrhb
  priority: 0
  schedulerName: default-scheduler
  terminationGracePeriodSeconds: 30
  nodeName: ip-10-0-140-16.us-east-2.compute.internal
  securityContext:     <3>
    seLinuxOptions:
      level: 's0:c11,c10'
  containers:          <4>
    - resources: {}
      terminationMessagePath: /dev/termination-log
      name: hello-openshift
      securityContext:
        capabilities:
          drop:
            - MKNOD
        procMount: Default
      ports:
        - containerPort: 8080
          protocol: TCP
      imagePullPolicy: Always
      volumeMounts:             <5>
        - name: default-token-wbqsl
          readOnly: true
          mountPath: /var/run/secrets/kubernetes.io/serviceaccount
      terminationMessagePolicy: File
      image: registry.redhat.io/openshift4/ose-ogging-eventrouter:v4.3 <6>
  serviceAccount: default     <7>
  volumes:                    <8>
    - name: default-token-wbqsl
      secret:
        secretName: default-token-wbqsl
        defaultMode: 420
  dnsPolicy: ClusterFirst
status:
  phase: Pending
  conditions:
    - type: Initialized
      status: 'True'
      lastProbeTime: null
      lastTransitionTime: '2019-02-13T20:31:37Z'
    - type: Ready
      status: 'False'
      lastProbeTime: null
      lastTransitionTime: '2019-02-13T20:31:37Z'
      reason: ContainersNotReady
      message: 'containers with unready status: [hello-openshift]'
    - type: ContainersReady
      status: 'False'
      lastProbeTime: null
      lastTransitionTime: '2019-02-13T20:31:37Z'
      reason: ContainersNotReady
      message: 'containers with unready status: [hello-openshift]'
    - type: PodScheduled
      status: 'True'
      lastProbeTime: null
      lastTransitionTime: '2019-02-13T20:31:37Z'
  hostIP: 10.0.140.16
  startTime: '2019-02-13T20:31:37Z'
  containerStatuses:
    - name: hello-openshift
      state:
        waiting:
          reason: ContainerCreating
      lastState: {}
      ready: false
      restartCount: 0
      image: openshift/hello-openshift
      imageID: ''
  qosClass: BestEffort
----

<1> Pods can be "tagged" with one or more labels, which can then
be used to select and manage groups of pods in a single operation. The labels
are stored in key/value format in the `metadata` hash. One label in this
example is `registry=default`.
<2> The pod restart policy with possible values `Always`, `OnFailure`, and `Never`. The default value is `Always`.
<3> {product-title} defines a security context for containers which specifies whether they are allowed to run as
privileged containers, run as a user of their choice, and more. The default context is very restrictive
but administrators can modify this as needed.
<4> `containers` specifies an array of one or more container definitions.
<5> The container specifies where external storage volumes are mounted within the container. In this case, there is a volume for storing access to credentials the registry needs for making requests against the {product-title} API.
<6> Each container in the pod is instantiated from its own container image.
<7> Pods making requests against the {product-title} API is a common enough pattern
that there is a `serviceAccount` field for specifying which service account user the pod should
authenticate as when making the requests. This enables fine-grained access
control for custom infrastructure components.
<8> The pod defines storage volumes that are available to its container(s) to
use. In this case, it provides an ephemeral volume for the registry storage and
a `secret` volume containing the service account credentials.

[NOTE]
====
This pod definition does not include attributes that
are filled by {product-title} automatically after the pod is created and
its lifecycle begins. The
link:https://kubernetes.io/docs/concepts/workloads/pods/pod/[Kubernetes pod documentation] has details about the functionality and purpose of pods.
====