

Pods are the rough equivalent of OpenShift Enterprise v2 gears, with containers the rough equivalent of v2 cartridge instances. 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.


OpenShift Enterprise treats pods as largely immutable; changes cannot be made to a pod definition while it is running. OpenShift Enterprise 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 manage pods with higher-level controllers, rather than directly by users.

The following example definition of a pod provides a long-running service, which is actually a part of the OpenShift Enterprise infrastructure: the private Docker registry. It demonstrates many features of pods, most of which are discussed in other topics and thus only briefly mentioned here.

Pod object definition example
apiVersion: v1
kind: Pod
  annotations: { ... }
  labels:                                (1)
    deployment: docker-registry-1
    deploymentconfig: docker-registry
    docker-registry: default
  generateName: docker-registry-1-       (2)
  containers:                            (3)
  - env:                                 (4)
      value: ...
      value: ...
      value: "false"
      value: ...
      value: https://master.example.com:8443
    image: openshift/origin-docker-registry:v0.6.2 (5)
    imagePullPolicy: IfNotPresent
    name: registry
    ports:                              (6)
    - containerPort: 5000
      protocol: TCP
    resources: {}
    securityContext: { ... }            (7)
    volumeMounts:                       (8)
    - mountPath: /registry
      name: registry-storage
      name: default-token-br6yz
      readOnly: true
  dnsPolicy: ClusterFirst
  - name: default-dockercfg-at06w
  restartPolicy: Always
  serviceAccount: default               (9)
  volumes:                              (10)
  - emptyDir: {}
    name: registry-storage
  - name: default-token-br6yz
      secretName: default-token-br6yz
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 docker-registry=default.
2 Pods must have a unique name within their namespace. A pod definition may specify the basis of a name with the generateName attribute and random characters will be added automatically to generate a unique name.
5 Each container in the pod is instantiated from its own Docker image.
9 Pods making requests against the OpenShift Enterprise 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.

This pod definition does not include attributes that are filled by OpenShift Enterprise automatically after the pod is created and its lifecycle begins. The Kubernetes API documentation has complete details of the pod REST API object attributes, and the Kubernetes pod documentation has details about the functionality and purpose of pods.





Service object definition example
apiVersion: v1
kind: Service
  name: docker-registry      (1)
  selector:                  (2)
    docker-registry: default
  portalIP:   (3)
  - nodePort: 0
    port: 5000               (4)
    protocol: TCP
    targetPort: 5000         (5)
4 Port the service listens on.

The Kubernetes service documentation has more information about services.



Most objects can include labels in their metadata. Labels can be used to group arbitrarily-related objects; for example, all of the pods, services, replication controllers, and deployment configurations of a particular application can be grouped.

Labels are simple key-value pairs, as in the following example:

Key-value pairs example
  key1: value1
  key2: value2


  • A pod consisting of an nginx Docker container, with the label role=webserver.

  • A pod consisting of an Apache httpd Docker container, with the same label role=webserver.


The Kubernetes labels documentation has more information about labels.