Deployment

This page describes Kubernetes Deployment objects and their use in Google Kubernetes Engine (GKE).

What is a Deployment?

Deployments represent a set of multiple, identical Pods with no unique identities. A Deployment runs multiple replicas of your application and automatically replaces any instances that fail or become unresponsive. In this way, Deployments help ensure that one or more instances of your application are available to serve user requests. Deployments are managed by the Kubernetes Deployment controller.

Deployments use a Pod template, which contains a specification for its Pods. The Pod specification determines how each Pod should look like: what applications should run inside its containers, which volumes the Pods should mount, its labels, and more.

When a Deployment's Pod template is changed, new Pods are automatically created one at a time.

Usage patterns

Deployments are well-suited for stateless applications that use ReadOnlyMany or ReadWriteMany volumes mounted on multiple replicas, but are not well-suited for workloads that use ReadWriteOnce volumes. For stateful applications using ReadWriteOnce volumes, use StatefulSets. StatefulSets are designed to deploy stateful applications and clustered applications that save data to persistent storage, such as Compute Engine persistent disks. StatefulSets are suitable for deploying Kafka, MySQL, Redis, ZooKeeper, and other applications needing unique, persistent identities and stable hostnames.

Creating Deployments

You can create a Deployment using the kubectl apply, or kubectl create commands.

Once created, the Deployment ensures that the desired number of Pods are running and available at all times. The Deployment automatically replaces Pods that fail or are evicted from their nodes.

The following is an example of a Deployment manifest file in YAML format:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.7.9
        ports:
        - containerPort: 80

In this example:

A Deployment named nginx is created, indicated by the metadata: name field.
The Deployment creates three replicated Pods, indicated by the replicas field.
The Pod template, or spec: template field, indicates that its Pods are labelled app: nginx.
The Pod template's specification, or template: spec field, indicates that the Pods run one container, nginx, which runs the nginx Docker Hub image at version 1.7.9.
The Deployment opens port 80 for use by the Pods.

For more information on Deployment specifications, see the Kubernetes API documentation.

In sum, the Pod template contains the following instructions for Pods created by this Deployment:

Each Pod is labelled app: nginx.
Create one container and name it nginx.
Run the nginx image at version 1.7.9.
Open port 80 to send and receive traffic.

For more information about creating Deployments, refer to Creating a Deployment.

Updating Deployments

You can update a Deployment by making changes to the Deployment's Pod template specification. Making changes to the specification field automatically triggers an update rollout. You can use kubectl, the Kubernetes API, or the GKE Workloads menu in Google Cloud Console.

By default, when a Deployment triggers an update, the Deployment stops the Pods, gradually scales down the number of Pods to zero, then drains and terminates the Pods. Then, the Deployment uses the updated Pod template to bring up new Pods.

Old Pods are not removed until a sufficient number of new Pods are Running, and new Pods are not created until a sufficient number of old Pods have been removed. To see in which order Pods are brought up and are removed, you can run kubectl describe deployments.

Deployments can ensure that at least one less than the desired number of replicas are running, with at most one Pod being unavailable. Similarly, Deployments can ensure that at most one more than the desired number of replicas are running, with at most one more Pod than desired running.

You can roll back an update using the kubectl rollout undo command. You can also use kubectl rollout pause to temporarily halt a Deployment.

Managing Deployments

The following is a list of common management tasks for Deployments:

Status and lifecycle

Deployments can be in one of three states during its lifecycle: progressing, completed, or failed.

A progressing state indicates that the Deployment is in process of performing its tasks, like bringing up or scaling its Pods.

A completed state indicates that the Deployment has successfully completed its tasks, all of its Pods are running with the latest specification and are available, and no old Pods are still running.

A failed state indicates that the Deployment has encountered one or more issues that prevent it from completing its tasks. Some causes include insufficient quotas or permissions, image pull errors, limit ranges, or runtime errors. To investigate what causes a Deployment to fail, you can run kubectl get deployment [DEPLOYMENT+NAME] -o yaml and examine the messages in the status: conditions field.

You can monitor a Deployment's progress or check its status using the kubectl rollout status command.