Using pods

A pod is one or more containers deployed together on one host, and the smallest compute unit that can be defined, deployed, and managed.

Understanding pods

Pods are the rough equivalent of a machine instance (physical or virtual) to a Container. Each pod is allocated its own internal IP address, therefore owning its entire port space, and containers within pods can share their local storage and networking.

Pods have a lifecycle; they are defined, then they are assigned to run on a node, then they run until their container(s) exit or they are removed for some other reason. Pods, depending on policy and exit code, might be removed after exiting, or can be retained to enable access to the logs of their containers.

OKD treats pods as largely immutable; changes cannot be made to a pod definition while it is running. OKD implements changes by terminating an existing pod and recreating it with modified configuration, base image(s), or both. Pods are also treated as expendable, and do not maintain state when recreated. Therefore pods should usually be managed by higher-level controllers, rather than directly by users.

Bare pods that are not managed by a replication controller will be not rescheduled upon node disruption.

Example pod configurations

OKD 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 from a Rails application. It demonstrates many features of pods, most of which are discussed in other topics and thus only briefly mentioned here:

Pod object definition (YAML)

  1. kind: Pod
  2. apiVersion: v1
  3. metadata:
  4.   name: example
  5.   namespace: default
  6.   selfLink: /api/v1/namespaces/default/pods/example
  7.   uid: 5cc30063-0265780783bc
  8.   resourceVersion: '165032'
  9.   creationTimestamp: '2019-02-13T20:31:37Z'
  10.   labels:
  11.     app: hello-openshift (1)
  12.   annotations:
  13.     openshift.io/scc: anyuid
  14. spec:
  15.   restartPolicy: Always (2)
  16.   serviceAccountName: default
  17.   imagePullSecrets:
  18.     - name: default-dockercfg-5zrhb
  19.   priority: 0
  20.   schedulerName: default-scheduler
  21.   terminationGracePeriodSeconds: 30
  22.   nodeName: ip-10-0-140-16.us-east-2.compute.internal
  23.   securityContext: (3)
  24.     seLinuxOptions:
  25.       level: 's0:c11,c10'
  26.   containers: (4)
  27.     - resources: {}
  28.       terminationMessagePath: /dev/termination-log
  29.       name: hello-openshift
  30.       securityContext:
  31.         capabilities:
  32.           drop:
  33.             - MKNOD
  34.         procMount: Default
  35.       ports:
  36.         - containerPort: 8080
  37.           protocol: TCP
  38.       imagePullPolicy: Always
  39.       volumeMounts: (5)
  40.         - name: default-token-wbqsl
  41.           readOnly: true
  42.           mountPath: /var/run/secrets/kubernetes.io/serviceaccount (6)
  43.       terminationMessagePolicy: File
  44.       image: registry.redhat.io/openshift4/ose-ogging-eventrouter:v4.3 (7)
  45.   serviceAccount: default (8)
  46.   volumes: (9)
  47.     - name: default-token-wbqsl
  48.       secret:
  49.         secretName: default-token-wbqsl
  50.         defaultMode: 420
  51.   dnsPolicy: ClusterFirst
  52. status:
  53.   phase: Pending
  54.   conditions:
  55.     - type: Initialized
  56.       status: 'True'
  57.       lastProbeTime: null
  58.       lastTransitionTime: '2019-02-13T20:31:37Z'
  59.     - type: Ready
  60.       status: 'False'
  61.       lastProbeTime: null
  62.       lastTransitionTime: '2019-02-13T20:31:37Z'
  63.       reason: ContainersNotReady
  64.       message: 'containers with unready status: [hello-openshift]'
  65.     - type: ContainersReady
  66.       status: 'False'
  67.       lastProbeTime: null
  68.       lastTransitionTime: '2019-02-13T20:31:37Z'
  69.       reason: ContainersNotReady
  70.       message: 'containers with unready status: [hello-openshift]'
  71.     - type: PodScheduled
  72.       status: 'True'
  73.       lastProbeTime: null
  74.       lastTransitionTime: '2019-02-13T20:31:37Z'
  75.   hostIP: 10.0.140.16
  76.   startTime: '2019-02-13T20:31:37Z'
  77.   containerStatuses:
  78.     - name: hello-openshift
  79.       state:
  80.         waiting:
  81.           reason: ContainerCreating
  82.       lastState: {}
  83.       ready: false
  84.       restartCount: 0
  85.       image: openshift/hello-openshift
  86.       imageID: ''
  87.   qosClass: BestEffort
1Pods 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.
2The pod restart policy with possible values Always, OnFailure, and Never. The default value is Always.
3OKD 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.
4containers specifies an array of one or more container definitions.
5The 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 OKD API.
6Specify the volumes to provide for the pod. Volumes mount at the specified path. Do not mount to the container root, /, or any path that is the same in the host and the container. This can corrupt your host system if the container is sufficiently privileged, such as the host /dev/pts files. It is safe to mount the host by using /host.
7Each container in the pod is instantiated from its own container image.
8Pods making requests against the OKD 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.
9The pod defines storage volumes that are available to its container(s) to use. In this case, it provides an ephemeral volume for a secret volume containing the default service account tokens.

If you attach persistent volumes that have high file counts to pods, those pods can fail or can take a long time to start. For more information, see When using Persistent Volumes with high file counts in OpenShift, why do pods fail to start or take an excessive amount of time to achieve “Ready” state?.

This pod definition does not include attributes that are filled by OKD automatically after the pod is created and its lifecycle begins. The Kubernetes pod documentation has details about the functionality and purpose of pods.

Additional resources