This page describes Kubernetes Deployment objects and their use in Kubernetes Engine.
What is a Deployment?
Deployments represent a set of multiple, identical Pods. 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.
Deployments are well-suited for stateful 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 we recommend using 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.
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/v1beta2 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
nginxis created, indicated by the
- The Deployment creates three replicated Pods, indicated by the
- The Pod template, or
spec: templatefield, indicates that its Pods are labelled
- The Pod template's specification, or
template: specfield, indicates that the Pods run one container,
nginx, which runs the
nginxDocker Hub image at version 1.7.9.
- The Deployment opens port 80 for use by the Pods.
In sum, the Pod template contains the following instructions for Pods created by this Deployment:
- Each Pod is labelled
- Create one container and name it
- Run the
nginximage at version
- Open port
80to send and receive traffic.
For more information about creating Deployments, refer to Creating a Deployment.
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
Kubernetes Engine Workloads menu in Google Cloud Platform 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 least one more than the desired number of replicas, 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
The following is a list of common management tasks for Deployments:
- Inspect a Deployment
- Scale a Deployment
- Autoscale a Deployment using a
- Delete a Deployment
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
status: conditions field.
You can monitor a Deployment's progress or check its status using the
kubectl rollout status