Try Kubernetes

Documentation for Kubernetes v1.4 is no longer actively maintained. The version you are currently viewing is a static snapshot. For up-to-date documentation, see the latest version.

Edit This Page

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:

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:

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:

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:

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:

The containers object commonly contains the following optional properties:

restartPolicy

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

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:

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.

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-1934187764-scau1   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-1934187764-scau1   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-1934187764-scau1
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-1934187764-scau1   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.

Analytics

Create an Issue Edit this Page