Deployments

A Deployment controller provides declarative updates for Pods and ReplicaSets.

You describe a desired state in a Deployment object, and the Deployment controller changes the actual state to the desired state at a controlled rate.

You can define Deployments to create new ReplicaSets, or to remove existing Deployments and adopt all their resources with new Deployments.

Note: You should not manage ReplicaSets owned by a Deployment.

All the use cases should be covered by manipulating the Deployment object. Consider opening an issue in the main Kubernetes repository if your use case is not covered below.

• Use Case
• Creating a Deployment
  • Pod-template-hash label
• Updating a Deployment
  • Rollover (aka multiple updates in-flight)
  • Label selector updates
• Rolling Back a Deployment
  • Checking Rollout History of a Deployment
  • Rolling Back to a Previous Revision
• Scaling a Deployment
  • Proportional scaling
• Pausing and Resuming a Deployment
• Deployment status
  • Progressing Deployment
  • Complete Deployment
  • Failed Deployment
  • Operating on a failed deployment
• Clean up Policy
• Use Cases
  • Canary Deployment
• Writing a Deployment Spec
  • Pod Template
  • Replicas
  • Selector
  • Strategy
    • Recreate Deployment
    • Rolling Update Deployment
      • Max Unavailable
      • Max Surge
  • Progress Deadline Seconds
  • Min Ready Seconds
  • Rollback To
  • Revision History Limit
  • Paused
• Alternative to Deployments
  • kubectl rolling update

Use Case

The following are typical use cases for Deployments:

• Create a Deployment to rollout a ReplicaSet. The ReplicaSet creates Pods in the background. Check the status of the rollout to see if it succeeds or not.
• Declare the new state of the Pods by updating the PodTemplateSpec of the Deployment. A new ReplicaSet is created and the Deployment manages moving the Pods from the old ReplicaSet to the new one at a controlled rate. Each new ReplicaSet updates the revision of the Deployment.
• Rollback to an earlier Deployment revision if the current state of the Deployment is not stable. Each rollback updates the revision of the Deployment.
• Scale up the Deployment to facilitate more load.
• Pause the Deployment to apply multiple fixes to its PodTemplateSpec and then resume it to start a new rollout.
• Use the status of the Deployment as an indicator that a rollout has stuck.
• Clean up older ReplicaSets that you don’t need anymore.

Creating a Deployment

The following is an example of a Deployment. It creates a ReplicaSet to bring up three nginx Pods:

apiVersion: apps/v1 # for versions before 1.9.0 use apps/v1beta2
kind: Deployment
metadata:
  name: nginx-deployment
  labels:
    app: 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-deployment is created, indicated by the metadata: name field.
• The Deployment creates three replicated Pods, indicated by the replicas field.
• The selector field defines how the Deployment finds which Pods to manage. In this case, we simply select on one label defined in the Pod template (app: nginx). However, more sophisticated selection rules are possible, as long as the Pod template itself satisfies the rule.
• 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.

Note: matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is “key”, the operator is “In”, and the values array contains only “value”. The requirements are ANDed.

The template field contains the following instructions:

• The Pods are labeled app: nginx
• Create one container and name it nginx.
• Run the nginx image at version 1.7.9.
• Open port 80 so that the container can send and accept traffic.

To create this Deployment, run the following command:

kubectl create -f https://raw.githubusercontent.com/kubernetes/website/master/docs/concepts/workloads/controllers/nginx-deployment.yaml

Note: You can append --record to this command to record the current command in the annotations of the created or updated resource. This is useful for future review, such as investigating which commands were executed in each Deployment revision.

Next, run kubectl get deployments. The output is similar to the following:

NAME               DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE
nginx-deployment   3         0         0            0           1s

When you inspect the Deployments in your cluster, the following fields are displayed:

• NAME lists the names of the Deployments in the cluster.
• DESIRED displays the desired number of replicas of the application, which you define when you create the Deployment. This is the desired state.
• CURRENT displays how many replicas are currently running.
• UP-TO-DATE displays the number of replicas that have been updated to achieve the desired state.
• AVAILABLE displays how many replicas of the application are available to your users.
• AGE displays the amount of time that the application has been running.

Notice how the values in each field correspond to the values in the Deployment specification:

• The number of desired replicas is 3 according to spec: replicas field.
• The number of current replicas is 0 according to the .status.replicas field.
• The number of up-to-date replicas is 0 according to the .status.updatedReplicas field.
• The number of available replicas is 0 according to the .status.availableReplicas field.

To see the Deployment rollout status, run kubectl rollout status deployment/nginx-deployment. This command returns the following output:

Waiting for rollout to finish: 2 out of 3 new replicas have been updated...
deployment "nginx-deployment" successfully rolled out

Run the kubectl get deployments again a few seconds later:

NAME               DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE
nginx-deployment   3         3         3            3           18s

Notice that the Deployment has created all three replicas, and all replicas are up-to-date (they contain the latest Pod template) and available (the Pod status is Ready for at least the value of the Deployment’s .spec.minReadySeconds field).

To see the ReplicaSet (rs) created by the deployment, run kubectl get rs:

NAME                          DESIRED   CURRENT   READY   AGE
nginx-deployment-2035384211   3         3         3       18s

Notice that the name of the ReplicaSet is always formatted as [DEPLOYMENT-NAME]-[POD-TEMPLATE-HASH-VALUE]. The hash value is automatically generated when the Deployment is created.

To see the labels automatically generated for each pod, run kubectl get pods --show-labels. The following output is returned:

NAME                                READY     STATUS    RESTARTS   AGE       LABELS
nginx-deployment-2035384211-7ci7o   1/1       Running   0          18s       app=nginx,pod-template-hash=2035384211
nginx-deployment-2035384211-kzszj   1/1       Running   0          18s       app=nginx,pod-template-hash=2035384211
nginx-deployment-2035384211-qqcnn   1/1       Running   0          18s       app=nginx,pod-template-hash=2035384211

The created ReplicaSet ensures that there are three nginx Pods running at all times.

Note: You must specify an appropriate selector and Pod template labels in a Deployment (in this case, app: nginx). Do not overlap labels or selectors with other controllers (including other Deployments and StatefulSets). Kubernetes doesn’t stop you from overlapping, and if multiple controllers have overlapping selectors those controllers might conflict and behave unexpectedly.

Pod-template-hash label