Edit This Page

Creating Multi-Container Pods

• Creating a pod
  • Using create
  • Pod configuration file
  • The spec schema
    • containers[]
    • restartPolicy
    • volumes[]
  • Sample file
• Viewing a pod
• Deleting a pod

A pod is a group of containers that are scheduled onto the same host. Pods serve as units of scheduling, deployment, and horizontal scaling/replication. Pods share fate, and share some resources, such as storage volumes and IP addresses.

Creating a pod

Multi-container pods must be created with the create command. Properties are passed to the command as a YAML- or JSON-formatted configuration file.

The create command can be used to create a pod directly, or it can create a pod or pods through a Deployment. It is highly recommended that you use a Deployment to create your pods. It watches for failed pods and will start up new pods as required to maintain the specified number.

If you don’t want a Deployment to monitor your pod (e.g. your pod is writing non-persistent data which won’t survive a restart, or your pod is intended to be very short-lived), you can create a pod directly with the create command.

Using create

Note: We recommend using a Deployment to create pods. You should use the instructions below only if you don’t want to create a Deployment.

If your pod will contain more than one container, or if you don’t want to create a Deployment to manage your pod, use the kubectl create command and pass a pod specification as a JSON- or YAML-formatted configuration file.

$ kubectl create -f FILE

Where:

• -f FILE or --filename FILE is the name of a pod configuration file in either JSON or YAML format.

A successful create request returns the pod name. Use the kubectl get command to view status after creation.

Pod configuration file

A pod configuration file specifies required information about the pod. It can be formatted as YAML or as JSON, and supports the following fields:

• JSON
• YAML

pod-config.json
{ "kind": "Pod", "apiVersion": "v1", "metadata": { "name": "", "labels": { "name": "" }, "generateName": "", "namespace": "", "annotations": [] }, "spec": { // See 'The spec schema' for details. } }

pod-config.yaml
apiVersion: v1 kind: Pod metadata: name: "" labels: name: "" namespace: "" annotations: [] generateName: "" spec: ? "// See 'The spec schema' for details." : ~

Required fields are:

• kind: Always Pod.
• apiVersion: Currently v1.
• metadata: An object containing:
  • name: Required if generateName is not specified. The name of this pod. It must be an RFC1035 compatible value and be unique within the namespace.
  • labels: Optional. Labels are arbitrary key:value pairs that can be used by Deployment and services for grouping and targeting pods.
  • generateName: Required if name is not set. A prefix to use to generate a unique name. Has the same validation rules as name.
  • namespace: Required. The namespace of the pod.
  • annotations: Optional. A map of string keys and values that can be used by external tooling to store and retrieve arbitrary metadata about objects.
• spec: The pod specification. See The spec schema for details.

The spec schema

A full description of the spec schema is contained in the Kubernetes API reference.

The following fields are required or commonly used in the spec schema:

• JSON
• YAML

pod-spec-common.json
"spec": { "containers": [ { "name": "", "image": "", "command": [ "" ], "args": [ "" ], "env": [ { "name": "", "value": "" } ], "imagePullPolicy": "", "ports": [ { "containerPort": 0, "name": "", "protocol": "" } ], "resources": { "cpu": "" "memory": "" } } ], "restartPolicy": "", "volumes": [ { "name": "", "emptyDir": { "medium": "" }, "secret": { "secretName": "" } } ] }

pod-spec-common.yaml
spec: containers: - args: - "" command: - "" env: - name: "" value: "" image: "" imagePullPolicy: "" name: "" ports: - containerPort: 0 name: "" protocol: "" resources: cpu: "" memory: "" restartPolicy: "" volumes: - emptyDir: medium: "" name: "" secret: secretName: ""

containers[]

A list of containers belonging to the pod. Containers cannot be added or removed once the pod is created, and there must be at least one container in a pod.

The containers object must contain:

• name: Name of the container. It must be a DNS_LABEL and be unique within the pod. Cannot be updated.
• image: Docker image name.

The containers object commonly contains the following optional properties:

• command[]: The entrypoint array. Commands are not executed within a shell. The docker image’s entrypoint is used if this is not provided. Cannot be updated.
• args[]: A command array containing arguments to the entrypoint. The docker image’s cmd is used if this is not provided. Cannot be updated.
• env[]: A list of environment variables in key:value format to set in the container. Cannot be updated.
  • name: The name of the environment variable; must be a C_IDENTIFIER.
  • value: The value of the environment variable. Defaults to empty string.
• imagePullPolicy: The image pull policy. Accepted values are:
  • Always
  • Never
  • IfNotPresentDefaults to Always if :latest tag is specified, or IfNotPresent otherwise. Cannot be updated.
• ports[]: A list of ports to expose from the container. Cannot be updated.
  • containerPort: The port number to expose on the pod’s IP address.
  • name: The name for the port that can be referred to by services. Must be a DNS_LABEL and be unique without the pod.
  • protocol: Protocol for the port. Must be UDP or TCP. Default is TCP.
• resources: The Compute resources required by this container. Contains:
  • cpu: CPUs to reserve for each container. Default is whole CPUs; scale suffixes (e.g. 100m for one hundred milli-CPUs) are supported. If the host does not have enough available resources, your pod will not be scheduled.
  • memory: Memory to reserve for each container. Default is bytes; binary scale suffixes (e.g. 100Mi for one hundred mebibytes) are supported. If the host does not have enough available resources, your pod will not be scheduled.Cannot be updated.

restartPolicy

Restart policy for all containers within the pod. Options are:

• Always
• OnFailure
• Never

volumes[]

A list of volumes that can be mounted by containers belonging to the pod. You must specify a name and a source for each volume. The container must also include a volumeMount with matching name. Source is one of:

• emptyDir: A temporary directory that shares a pod’s lifetime. Contains:
  • medium: The type of storage used to back the volume. Must be an empty string (default) or Memory.
• hostPath: A pre-existing host file or directory. This is generally used for privileged system daemons or other agents tied to the host. Contains:
  • path: The path of the directory on the host.
• secret: Secret to populate volume. Secrets are used to hold sensitive information, such as passwords, OAuth tokens, and SSH keys. Learn more from the docs on secrets. Contains:
  • secretName: The name of a secret in the pod’s namespace.

The name must be a DNS_LABEL and unique within the pod.

Sample file

For example, the following configuration file creates two containers: a redis key-value store image, and a django frontend image.

• JSON
• YAML

pod-sample.json
{ "kind": "Pod", "apiVersion": "v1", "metadata": { "name": "redis-django", "labels": { "app": "webapp" } }, "spec": { "containers": [ { "name": "key-value-store", "image": "redis", "ports": [ { "containerPort": 6379, } ] }, { "name": "frontend", "image": "django", "ports": [ { "containerPort": 8000, } ] } ] } }

pod-sample.yaml
apiVersion: v1 kind: Pod metadata: name: redis-django labels: app: web spec: containers: - name: key-value-store image: redis ports: - containerPort: 6379 - name: frontend image: django ports: - containerPort: 8000

Viewing a pod

To view a specific pod, use the kubectl get command:

$ kubectl get pod NAME
NAME      READY   STATUS    RESTARTS   AGE
example   1/1     Running   0          2d

To return the name of the node on which the pod is scheduled, use the -o wide option:

$ kubectl get pod NAME -o wide
NAME      READY   STATUS    RESTARTS   AGE   NODE
example   1/1     Running   0          2d    gke-example-c6a38-node-xij3

For more details about a pod, including events, use describe in place of get:

$ kubectl describe pod NAME
Name:        example
Namespace:   default
Image(s):    kubernetes/example-php-redis:v2
Node:        gke-example-c6a38461-node-xij3/10.240.34.183
Labels:      name=frontend
Status:      Running
Reason:
Message:
IP:          10.188.2.10
Replication Controllers:  example (5/5 replicas created)
Containers:
  php-redis:
    Image:   kubernetes/example-php-redis:v2
    Limits:
      cpu:   100m
    State:   Running
      Started:   Tue, 04 Aug 2015 09:02:46 -0700
    Ready:   True
    Restart Count: 0
Conditions:
  Type    Status
  Ready   True
Events:
  FirstSeen                       LastSeen                        Coun From                                     SubobjectPath            Reason  Message
  Thu, 06 Aug 2015 11:49:44 -0700 Thu, 06 Aug 2015 11:49:44 -0700 1    {kubelet gke-example-c6a38461-node-xij3} spec.containers{example} started Started with docker id 5705bffa65e2

To list all pods running on a cluster:

$ kubectl get pods

NAME                 READY     STATUS    RESTARTS   AGE
example-xypvc        1/1       Running   0          1m
frontend-7kdod       1/1       Running   0          1d

Deleting a pod

If you created your pod directly with kubectl create, use kubectl delete:

$ kubectl delete pod NAME

A successful delete request returns the name of the deleted pod.