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:<some-version>
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-<time>`. The value stored in the annotation can be a spec hash, a strategic merge patch or the kubectl commands previously executed. We choose strategic merge patch since it's more human-readable than spec hash, and commands like `kubectl edit` won't provide enough useful information.
### Inert Deployments
Users sometimes need to temporarily disable a deployment. See issue [#14516](https://github.com/kubernetes/kubernetes/issues/14516).
### Perm-failed Deployments
The deployment could be marked as "permanently failed" for a given spec hash so that the system won't continue thrashing on a doomed deployment. See issue [#14519](https://github.com/kubernetes/kubernetes/issues/14519).
