Update managing deployments user guide

2016-03-18 16:35:38 -07:00
parent 8f8a777ae2
commit 248744f93b
6 changed files with 334 additions and 270 deletions
@@ -6,6 +6,12 @@

 ## Overview

+To update a service without an outage, `kubectl` supports what is called ['rolling update'](/docs/user-guide/kubectl/kubectl_rolling-update), which updates one pod at a time, rather than taking down the entire service at the same time. See the [rolling update design document](https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/docs/design/simple-rolling-update.md) and the [example of rolling update](/docs/user-guide/update-demo/) for more information.
+
+Note that `kubectl rolling-update` only supports Replication Controllers. However, if you deploy applications with Replication Controllers, 
+consider switching them to [Deployments](/docs/user-guide/deployments/). A Deployments is a higher-level controller that automates rolling updates 
+of applications declaratively, and therefore is recommended. If you still want to keep your Replication Controllers and use `kubectl rolling-update`, keep reading:
+
 A rolling update applies changes to the configuration of pods being managed by
 a replication controller. The changes can be passed as a new replication
 controller configuration file; or, if only updating the image, a new container
@@ -115,6 +121,124 @@ Optional fields are:
 Additional information about the `kubectl rolling-update` command is available
 from the [`kubectl` reference](/docs/user-guide/kubectl/kubectl_rolling-update/).

+## Walkthrough
+
+Let's say you were running version 1.7.9 of nginx:
+
+```yaml
+apiVersion: v1
+kind: ReplicationController
+metadata:
+  name: my-nginx
+spec:
+  replicas: 5
+  template:
+    metadata:
+      labels:
+        app: nginx
+    spec:
+      containers:
+      - name: nginx
+        image: nginx:1.7.9
+        ports:
+        - containerPort: 80
+```
+
+To update to version 1.9.1, you can use [`kubectl rolling-update --image`](https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/docs/design/simple-rolling-update.md) to specify the new image:
+
+```shell
+$ kubectl rolling-update my-nginx --image=nginx:1.9.1
+Created my-nginx-ccba8fbd8cc8160970f63f9a2696fc46
+```
+
+In another window, you can see that `kubectl` added a `deployment` label to the pods, whose value is a hash of the configuration, to distinguish the new pods from the old:
+
+```shell
+$ kubectl get pods -l app=nginx -L deployment
+NAME                                              READY     STATUS    RESTARTS   AGE       DEPLOYMENT
+my-nginx-ccba8fbd8cc8160970f63f9a2696fc46-k156z   1/1       Running   0          1m        ccba8fbd8cc8160970f63f9a2696fc46
+my-nginx-ccba8fbd8cc8160970f63f9a2696fc46-v95yh   1/1       Running   0          35s       ccba8fbd8cc8160970f63f9a2696fc46
+my-nginx-divi2                                    1/1       Running   0          2h        2d1d7a8f682934a254002b56404b813e
+my-nginx-o0ef1                                    1/1       Running   0          2h        2d1d7a8f682934a254002b56404b813e
+my-nginx-q6all                                    1/1       Running   0          8m        2d1d7a8f682934a254002b56404b813e
+```
+
+`kubectl rolling-update` reports progress as it progresses:
+
+```
+Scaling up my-nginx-ccba8fbd8cc8160970f63f9a2696fc46 from 0 to 3, scaling down my-nginx from 3 to 0 (keep 3 pods available, don't exceed 4 pods)
+Scaling my-nginx-ccba8fbd8cc8160970f63f9a2696fc46 up to 1
+Scaling my-nginx down to 2
+Scaling my-nginx-ccba8fbd8cc8160970f63f9a2696fc46 up to 2
+Scaling my-nginx down to 1
+Scaling my-nginx-ccba8fbd8cc8160970f63f9a2696fc46 up to 3
+Scaling my-nginx down to 0
+Update succeeded. Deleting old controller: my-nginx
+Renaming my-nginx-ccba8fbd8cc8160970f63f9a2696fc46 to my-nginx
+replicationcontroller "my-nginx" rolling updated
+```
+
+If you encounter a problem, you can stop the rolling update midway and revert to the previous version using `--rollback`:
+
+```shell
+$ kubectl rolling-update my-nginx --rollback
+Setting "my-nginx" replicas to 1
+Continuing update with existing controller my-nginx.
+Scaling up nginx from 1 to 1, scaling down my-nginx-ccba8fbd8cc8160970f63f9a2696fc46 from 1 to 0 (keep 1 pods available, don't exceed 2 pods)
+Scaling my-nginx-ccba8fbd8cc8160970f63f9a2696fc46 down to 0
+Update succeeded. Deleting my-nginx-ccba8fbd8cc8160970f63f9a2696fc46
+replicationcontroller "my-nginx" rolling updated
+```
+
+This is one example where the immutability of containers is a huge asset.
+
+If you need to update more than just the image (e.g., command arguments, environment variables), you can create a new replication controller, with a new name and distinguishing label value, such as:
+
+```yaml
+apiVersion: v1
+kind: ReplicationController
+metadata:
+  name: my-nginx-v4
+spec:
+  replicas: 5
+  selector:
+    app: nginx
+    deployment: v4
+  template:
+    metadata:
+      labels:
+        app: nginx
+        deployment: v4
+    spec:
+      containers:
+      - name: nginx
+        image: nginx:1.9.2
+        args: [“nginx”,”-T”]
+        ports:
+        - containerPort: 80
+```
+
+and roll it out:
+
+```shell
+$ kubectl rolling-update my-nginx -f ./nginx-rc.yaml
+Created my-nginx-v4
+Scaling up my-nginx-v4 from 0 to 5, scaling down my-nginx from 4 to 0 (keep 4 pods available, don't exceed 5 pods)
+Scaling my-nginx-v4 up to 1
+Scaling my-nginx down to 3
+Scaling my-nginx-v4 up to 2
+Scaling my-nginx down to 2
+Scaling my-nginx-v4 up to 3
+Scaling my-nginx down to 1
+Scaling my-nginx-v4 up to 4
+Scaling my-nginx down to 0
+Scaling my-nginx-v4 up to 5
+Update succeeded. Deleting old controller: my-nginx
+replicationcontroller "my-nginx-v4" rolling updated
+```
+
+You can also run the [update demo](/docs/user-guide/update-demo/) to see a visual representation of the rolling update process.
+
 ## Troubleshooting

 If the `timeout` duration is reached during a rolling update, the operation will