kubectl-rollout

Start a rolling restart of a resource

$ kubectl rollout restart [resource_type]/[resource_name]

$ kubectl rollout status [resource_type]/[resource_name]

$ kubectl rollout undo [resource_type]/[resource_name]

$ kubectl rollout history [resource_type]/[resource_name]

kubectl rollout SUBCOMMAND (TYPE/NAME | TYPE NAME) [options]

Common Subcommands:
  status     Show the status of the rollout.
  history    Show the history of the rollout.
  undo       Roll back to a previous revision.
  pause      Mark the provided resource as paused.
  resume     Resume a paused resource.
  restart    Restart a resource.

TYPE/NAME | TYPE NAME
    Specifies the Kubernetes resource type (e.g., deployment, daemonset, statefulset) and its name. For example, deployment/my-app or deployment my-app.

SUBCOMMAND
    The specific operation to perform: status, history, undo, pause, resume, or restart.

--namespace, -n name
    If present, the namespace scope for this request. Defaults to the namespace configured in the current context.

--kubeconfig path
    Path to the kubeconfig file to use for CLI requests.

--context name
    The name of the kubeconfig context to use.

--watch, -w
    (status subcommand only) Watch for the rollout status to complete. The command will exit with success when the rollout completes.

--timeout duration
    (status subcommand only) The length of time to wait before giving up on a rollout. Defaults to 5m0s (5 minutes).

--to-revision revision
    (undo subcommand only) The revision to roll back to. If not specified, rolls back to the previous revision.

--revision revision
    (history subcommand only) See the details for a specific revision number.

The kubectl rollout command provides essential tools for managing and monitoring the lifecycle of application deployments within Kubernetes. It enables administrators and developers to inspect the status of ongoing rollouts, view the history of past revisions, pause and resume deployments, and perform rollbacks to previous stable versions. This command is crucial for maintaining application availability and ensuring controlled, progressive updates of resources like Deployments, DaemonSets, and StatefulSets. It consolidates various operations related to the rollout process, making it simpler to manage application updates, debug issues during deployment, and react quickly to potential problems by reverting to a known good state. This command is a cornerstone for operational excellence in a Kubernetes environment.

kubectl rollout commands are primarily designed for resources that support versioned updates and rollbacks, namely Deployments, DaemonSets, and StatefulSets. Not all Kubernetes resource types have the concept of a "rollout." The restart subcommand works by patching an annotation on the Pod template, which triggers a new rollout; it does not directly "restart" pods in the traditional sense. Proper understanding of Kubernetes deployment strategies (e.g., RollingUpdate) is beneficial for effective use of these commands.

In Kubernetes, a rollout refers to the process of updating an application's running instances (pods) in a controlled manner. This typically involves creating new pods with the updated configuration and gracefully terminating old ones, ensuring minimal downtime. kubectl rollout commands help monitor and manage these transitions.

The undo subcommand does not simply revert to a previous state. Instead, it creates a new revision based on the specified historical revision. This new revision becomes the latest one, and the deployment controller rolls out the changes, effectively bringing the application back to a previously stable state. This mechanism ensures that the rollback itself is treated as a new deployment.

Pausing a deployment (using pause) can be useful during complex updates or troubleshooting. When paused, no new rollouts can be triggered for the deployment. Once an issue is resolved or a multi-step update is ready to continue, the deployment can be resumed (using resume), allowing pending updates to proceed or new rollouts to be initiated.

The kubectl rollout command has been an integral part of kubectl since early versions of Kubernetes, providing a robust interface for managing application updates. Its capabilities have evolved with Kubernetes itself, reflecting best practices for declarative infrastructure management. It standardizes common operational tasks related to continuous delivery within a Kubernetes environment, abstracting away much of the underlying complexity of deployment strategies.

kubectl(1), kubectl apply(1), kubectl get(1), kubectl describe(1), kubectl set(1)