whentimeslows/website
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Edits "Creating a Deployment" section (#5195)

Browse Source 
* Edits "Creating a Deployment" section

* Explains the example Deployment
* Explains command output
* Comprehensive edit for reader comprehension, length, and style

* Update deployment.md
This commit is contained in:
Ryan McGinnis
2017-09-01 10:55:03 -07:00
committed by Andrew Chen
parent 69d2091ca6
commit 7f828b9ee3
1 changed files with 57 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/concepts/workloads/controllers/deployment.md
+57 -36
View File
@@ -27,84 +27,106 @@ The following are typical use cases for Deployments:
* [Create a Deployment to rollout a ReplicaSet](#creating-a-deployment). 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](#updating-a-deployment) 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](#rolling-back-a-deployment) 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.](#scaling-a-deployment)
* [Scale up the Deployment to facilitate more load](#scaling-a-deployment).
* [Pause the Deployment](#pausing-and-resuming-a-deployment) to apply multiple fixes to its PodTemplateSpec and then resume it to start a new rollout.
* [Use the status of the Deployment](#deployment-status) as an indicator that a rollout has stuck
* [Clean up older ReplicaSets](#clean-up-policy) that you don't need anymore
* [Use the status of the Deployment](#deployment-status) as an indicator that a rollout has stuck.
* [Clean up older ReplicaSets](#clean-up-policy) that you don't need anymore.
## Creating a Deployment
Here is an example Deployment. It creates a ReplicaSet to bring up three nginx Pods.
The following is an example of a Deployment. It creates a ReplicaSet to bring up three `nginx` Pods:
{% include code.html language="yaml" file="nginx-deployment.yaml" ghlink="/docs/concepts/workloads/controllers/nginx-deployment.yaml" %}
Run the example by downloading the example file and then running this command:
In this example:
* A Deployment named `nginx` is created.
* The `nginx` Deployment creates three replicated Pods.
* The Pods are created from the `template` field.
The `template` field contains the following instructions:
* Create one container in each Pod.
* Label the container `app: nginx`.
* Run the [Docker Hub](https://hub.docker.com) image `nginx` 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:
```shell
$ kubectl create -f docs/user-guide/nginx-deployment.yaml --record
deployment "nginx-deployment" created
kubectl create -f https://raw.githubusercontent.com/kubernetes/kubernetes.github.io/master/docs/concepts/workloads/controllers/nginx-deployment.yaml
```
Setting the kubectl flag `--record` to `true` allows you to record current command in the annotations of
the resources being created or updated. It is useful for future introspection: for example, to see the
commands executed in each Deployment revision.
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.
Then running `get` immediately will give:
Next, run `kubectl get deployments`. The output is similar to the following:
```shell
$ kubectl get deployments
NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE
nginx-deployment 3 0 0 0 1s
```
This indicates that the Deployment's number of desired replicas is 3 (according to deployment's `.spec.replicas`),
the number of current replicas (`.status.replicas`) is 0, the number of up-to-date replicas (`.status.updatedReplicas`)
is 0, and the number of available replicas (`.status.availableReplicas`) is also 0.
When you inspect the Deployments in your cluster, the following fields are displayed:
To see the Deployment rollout status, run:
* `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 accoridng 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:
```shell
$ kubectl rollout status deployment/nginx-deployment
Waiting for rollout to finish: 2 out of 3 new replicas have been updated...
deployment "nginx-deployment" successfully rolled out
```
Running the `get` again a few seconds later should give:
Run the `kubectl get deployments` again a few seconds later:
```shell
$ kubectl get deployments
NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE
nginx-deployment 3 3 3 3 18s
```
This indicates that the Deployment has created all three replicas, and all replicas are up-to-date (contains the
latest pod template) and available (pod status is ready for at least Deployment's `.spec.minReadySeconds`). Running
`kubectl get rs` and `kubectl get pods` will show the ReplicaSet (RS) and Pods created.
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`:
```shell
$ kubectl get rs
NAME DESIRED CURRENT READY AGE
nginx-deployment-2035384211 3 3 3 18s
```
You may notice that the name of the ReplicaSet is always `<the name of the Deployment>-<hash value of the pod template>`.
Notice that the name of the ReplicaSet is always formatted as `[DEPLOYMENT-NAME]-[POD-TEMPALTE-HASH-VALUE]`. The hash value is automatically generated when the Deployemnt is created.
To see the labels automatically generated for each pod, run `kubectl get pods --show-labels`. The following output is returned:
```shell
$ kubectl get pods --show-labels
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 at all times.
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`). That is, don't overlap with other controllers (including other Deployments, ReplicaSets,
StatefulSets, etc.). Kubernetes doesn't stop you from overlapping, and if multiple
controllers have overlapping selectors, those controllers may fight with each other and won't behave
correctly.
**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.
{: .note}
### Pod-template-hash label
@@ -112,11 +134,10 @@ correctly.
**Note:** Do not change this label.
{: .note}
Note the pod-template-hash label in the example output in the pod labels above. This label is added by the
Deployment controller to every ReplicaSet that a Deployment creates or adopts. Its purpose is to make sure that child
ReplicaSets of a Deployment do not overlap. It is computed by hashing the PodTemplate of the ReplicaSet
and using the resulting hash as the label value that will be added in the ReplicaSet selector, pod template labels,
and in any existing Pods that the ReplicaSet may have.
The `pod-template-hash label` is added by the Deployment controller to every ReplicaSet that a Deployment creates or adopts.
This label ensures that child ReplicaSets of a Deployment do not overlap. It is generated by hashing the `PodTemplate` of the ReplicaSet and using the resulting hash as the label value that is added to the ReplicaSet selector, Pod template labels,
and in any existing Pods that the ReplicaSet might have.
## Updating a Deployment