From 1c606b65327fcb5a2996d925fc3b11a3c3b29f83 Mon Sep 17 00:00:00 2001 From: Janet Kuo Date: Tue, 8 Dec 2015 16:23:49 -0800 Subject: [PATCH 1/3] Proposal for deploy in kubectl --- docs/proposals/deploy.md | 152 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 152 insertions(+) create mode 100644 docs/proposals/deploy.md diff --git a/docs/proposals/deploy.md b/docs/proposals/deploy.md new file mode 100644 index 00000000000..45a59e89e3b --- /dev/null +++ b/docs/proposals/deploy.md @@ -0,0 +1,152 @@ + + + + +WARNING +WARNING +WARNING +WARNING +WARNING + +

PLEASE NOTE: This document applies to the HEAD of the source tree

+ +If you are using a released version of Kubernetes, you should +refer to the docs that go with that version. + + +The latest release of this document can be found +[here](http://releases.k8s.io/release-1.1/docs/proposals/deploy.md). + +Documentation for other releases can be found at +[releases.k8s.io](http://releases.k8s.io). + +-- + + + + + + + +- [Deploy through CLI](#deploy-through-cli) + - [Motivation](#motivation) + - [Requirements](#requirements) + - [Related `kubectl` Commands](#related-kubectl-commands) + - [`kubectl run`](#kubectl-run) + - [`kubectl scale` and `kubectl autoscale`](#kubectl-scale-and-kubectl-autoscale) + - [`kubectl rollout`](#kubectl-rollout) + - [`kubectl set`](#kubectl-set) + - [Example](#example) + - [Support in Deployment](#support-in-deployment) + - [Deployment Status](#deployment-status) + - [Deployment Version](#deployment-version) + - [Inert Deployments](#inert-deployments) + - [Perm-failed Deployments](#perm-failed-deployments) + + + +# Deploy through CLI + +## Motivation + +Users can use Deployments or `kubectl rolling-update` to deploy in their Kubernetes clusters. A Deployment provides declarative update for Pods and ReplicationControllers, whereas `rolling-update` allows the users to update their earlier deployment without worrying about schemas and configurations. Users need a way that's similar to `rolling-update` to manage their Deployments more easily. + +`rolling-update` expects ReplicationController as the only resource type it deals with. It's not trivial to support exactly the same behavior with Deployment, which requires: +- Print out scaling up/down events. +- Stop the deployment if users press Ctrl-c. +- The controller should not make any more changes once the process ends. (Delete the deployment when status.replicas=status.updatedReplicas=spec.replicas) + +So, instead, this document proposes another way to support easier deployment management via Kubernetes CLI (`kubectl`). + +## Requirements + +The followings are operations we need to support for the users to easily managing deployments: + +- **Create**: To create deployments. +- **Rollback**: To restore to an earlier version of deployment. +- **Watch the status**: To watch for the status update of deployments. +- **Pause/resume**: To pause a deployment mid-way, and to resume it. (A use case is to support canary deployment.) +- **Version information**: To record and show version information that's meaningful to users. This can be useful for rollback. + +## Related `kubectl` Commands + +### `kubectl run` + +`kubectl run` should support the creation of Deployment (already implemented) and DaemonSet resources. + +### `kubectl scale` and `kubectl autoscale` + +Users may use `kubectl scale` or `kubectl autoscale` to scale up and down Deployments (both already implemented). + +### `kubectl rollout` + +`kubectl rollout` supports both Deployment and DaemonSet. It has the following subcommands: +- `kubectl rollout undo` works like rollback; it allows the users to rollback to a previous version of deployment. +- `kubectl rollout pause` allows the users to pause a deployment. +- `kubectl rollout resume` allows the users to resume a paused deployment. +- `kubectl rollout status` shows the status of a deployment. +- `kubectl rollout history` shows meaningful version information of all previous deployments. + +### `kubectl set` + +`kubectl set` has the following subcommands: +- `kubectl set env` allows the users to set environment variables of Kubernetes resources. It should support Pod, ReplicationController, ReplicaSet, Deployment, and DaemonSet. +- `kubectl set image` allows the users to update the image of deployments. Users will use `--container` and `--image` flags to update the image of a container. + +### Example + +With the commands introduced above, here's an example of deployment management: + +```console +# Create a Deployment +$ kubectl run nginx --image=nginx --replicas=2 --generator=deployment/v1beta1 + +# Watch the Deployment status +$ kubectl rollout status deployment/nginx + +# Update the Deployment +$ kubectl set image deployment/nginx --container=nginx --image=nginx: + +# Pause the Deployment +$ kubectl rollout pause deployment/nginx + +# Resume the Deployment +$ kubectl rollout resume deployment/nginx + +# Check the change history (deployment versions) +$ kubectl rollout history deployment/nginx + +# Rollback to a previous version. +$ kubectl rollout undo deployment/nginx --to-version= +``` + +## Support in Deployment + +### Deployment Status + +Deployment status should summarize information about Pods, which includes: +- The number of pods of each version. +- The number of ready/not ready pods. + +See issue [#17164](https://github.com/kubernetes/kubernetes/issues/17164). + +### Deployment Version + +We store previous deployment versions information in deployment annotation `kubectl.kubernetes.io/deployment-version-