kubectl rollout and kubectl rollout restart: Managing Kubernetes Deployments

What Is the kubectl rollout Command? 

kubectl is the command line interface (CLI) that allows you to manage Kubernetes clusters. The kubectl rollout command is used to manage the rollout of updates to applications running on the platform, as part of the Kubernetes deployment process. It can be used to manage three Kubernetes objects: Deployment, DaemonSet, and StatefulSet. The rollout process is a gradual, step-by-step recreation of pods.

The command provides several sub-commands that allow you to manage different aspects of a rollout. Most notably, the kubectl rollout restart command is used to start a new rollout process. 

The kubectl rollout command allows you to view the status of a rollout, manage the updates to deployments, check the history of rollouts, and restart a rollout if required. This command is particularly useful when managing complex applications that involve multiple deployments, requiring frequent updates and careful monitoring of the rollout process.This is part of a series of articles about kubectl

Use Cases of kubectl rollout 

Following are the primary uses of the kubectl rollout command:

• Viewing rollout status: This is a critical part of managing deployments, as it allows you to monitor the process and quickly identify any issues or delays.
• Managing deployment updates: During a rollout, there may be times when you need to pause the process to address issues or make adjustments. kubectl rollout lets you pause a rollout, make necessary changes or fixes, and then resume the process.
• Checking rollout history: this is particularly useful when troubleshooting issues or assessing the success of past deployments.
• Restarting rollouts: This can be necessary in situations where a rollout has failed or stalled, or when changes need to be made to the deployment.

Tips from the expert

Itiel Shwartz

Co-Founder & CTO

Itiel is the CTO and co-founder of Komodor. He’s a big believer in dev empowerment and moving fast, has worked at eBay, Forter and Rookout (as the founding engineer). Itiel is a backend and infra developer turned “DevOps”, an avid public speaker that loves talking about things such as cloud infrastructure, Kubernetes, Python, observability, and R&D culture.

In my experience, here are tips that can help you better manage Kubernetes deployments with kubectl rollout:

Regularly Check Rollout Status

Use kubectl rollout status frequently during deployments to monitor progress and catch issues early. This command provides real-time feedback on the deployment process.

Leverage Rollback for Quick Recovery

Utilize kubectl rollout undo to quickly revert to a previous deployment revision in case of issues. This ensures minimal downtime and quick recovery from deployment failures.

Pause and Resume Rollouts for Controlled Deployments

Use kubectl rollout pause to halt a rollout if issues are detected, allowing you to make adjustments before resuming with kubectl rollout resume. This approach minimizes risks during deployments.

Integrate Rollout Commands in CI/CD Pipelines

Automate deployment rollouts by integrating kubectl rollout commands into your CI/CD pipelines. This ensures consistent and reliable deployment processes across environments.

Maintain Detailed Rollout History

Regularly use kubectl rollout history to review past deployment revisions. Detailed history logs help in troubleshooting and understanding deployment trends and patterns.

kubectl rollout Syntax and Sub-Commands 

To use the kubectl rollout command, we must first understand its syntax. The syntax for this command is: 

kubectl rollout SUBCOMMAND

The SUBCOMMAND can be one of the following: 

• status
• pause
• resume
• restart
• undo
• history

Checking Rollout Status

If you want to check the status of a rollout, the command would be:

kubectl rollout status deployment/your-deployment-name

This command returns the real-time status of the deployment, providing valuable information such as the number of replicas created, the number of replicas updated, and the number of replicas available.

Managing Deployment Updates

To manage deployment updates, you can use the pause and resume subcommands. For example, the following command pauses the rollout, giving you time to assess and address any issues: 

kubectl rollout pause deployment/your-deployment-name

To resume the rollout, the command would be:

kubectl rollout resume deployment/your-deployment-name

Restarting a Rollout

To restart a rollout, the command is:

kubectl rollout restart deployment/your-deployment-name

This sub-command will stop the current rollout and start a new one, using the current configuration settings. This is useful in cases where the deployment process is stalled or requires adjustments.

Undoing a Rollout

To undo a rollout, the syntax for the command is:

This command allows you to revert your deployment to a previous revision. This is useful in cases where you’ve made a change that resulted in an issue with your application and you’d like to revert back to a previously known working state.

Checking Rollout History

To check the history of a rollout, you can use the following command:

kubectl rollout history deployment/your-deployment-name

This sub-command provides a list of revisions for your deployment, along with details about each revision. This includes the date and time of the revision, the changes made, and the current status of the revision.

Common Issues With ‘kubectl rollout’ and How to Resolve Them 

Rollout is Stuck or Taking Too Long

One common issue with the kubectl rollout command is that a rollout may get stuck or take longer than expected. This can happen for a variety of reasons, such as network issues, resource limitations, or configuration errors.

To resolve this issue, you can use the kubectl rollout status command to check the status of the rollout and identify any errors. If the rollout is stuck due to a configuration error, you can use the kubectl rollout undo command to revert to the previous configuration and fix the error.

Learn more in our detailed guide to kubectl config (coming soon)

Unexpected Rollout Behavior

Another common issue is unexpected rollout behavior. This can be caused by errors in the deployment configuration, such as incorrect replica counts or incorrect image names.

To resolve this issue, you can use the kubectl rollout history command to check the history of your rollouts and identify any changes that may have led to the unexpected behavior. You can then use the kubectl rollout undo command to revert to a previous configuration and correct the error.

Failed to Rollback

Sometimes, a rollback may fail due to errors in the rollback configuration or issues with the previous configuration. This can leave your deployment in a broken state, affecting the availability of your application.

To resolve this issue, you can use the kubectl rollout history command to identify the error and the kubectl rollout undo command to revert to a previous, working configuration. You can also use the kubectl rollout restart command to start a new rollout with the corrected configuration.

Failed to Restart a Rollout

Finally, there may be times when a rollout fails to restart. This can happen if the current configuration is invalid or if there are issues with the Kubernetes cluster itself.

To resolve this issue, you can use the kubectl rollout status command to check the status of the rollout and identify any errors. You can try the kubectl rollout undo command to revert to a previous configuration.

Kubernetes Troubleshooting With Komodor

Kubernetes is a complex system, and often, something will go wrong, simply because it can. In situations like this, you’ll likely begin the troubleshooting process by reverting to some of the above kubectl commands to try and determine the root cause. This process, however, can often run out of hand and turn into a stressful, ineffective, and time-consuming task.

This is the reason why we created Komodor, a tool that helps dev and ops teams stop wasting their precious time looking for needles in (hay)stacks every time things go wrong.

Acting as a single source of truth (SSOT) for all of your k8s troubleshooting needs, Komodor offers:

• Change intelligence: Every issue is a result of a change. Within seconds we can help you understand exactly who did what and when.
• In-depth visibility: A complete activity timeline, showing all code and config changes, deployments, alerts, code diffs, pod logs and etc. All within one pane of glass with easy drill-down options.
• Insights into service dependencies: An easy way to understand cross-service changes and visualize their ripple effects across your entire system.
• Seamless notifications: Direct integration with your existing communication channels (e.g., Slack) so you’ll have all the information you need, when you need it.

Related content:

Read our guide to kubectl apply.

Read our guide to kubectl patch.

Read our guide to kubectl autocomplete.

If you are interested in checking out Komodor, use this link to sign up for a Free Trial.