Restarting an application across a fleet of servers is a routine maintenance task, but doing it safely can require more work than expected. Teams may need to reload runtime configuration, recover application processes, or recycle long-running services without deploying a new version of the application.
Previously, teams using AWS CodeDeploy often redeployed the current application revision or maintained custom scripts to restart applications across Amazon EC2 and on-premises instances. Redeployment could repeat installation steps that were unnecessary for a restart, while custom scripts required separate logic for health checks, deployment batches, and failure handling.
AWS CodeDeploy now provides a dedicated RESTART deployment mode for supported in-place deployments. It restarts applications using the deployment group's last successful revision while retaining important CodeDeploy deployment controls.
The feature is designed for operational restarts rather than application version changes. Understanding its supported deployment types, lifecycle hooks, and failure behavior is important before using it in production.
What Is the CodeDeploy RESTART Deployment Mode?
The RESTART deployment mode tells CodeDeploy to restart an application on target instances using the revision associated with the deployment group's last successful deployment. It does not require the caller to provide a new application revision.
The feature supports in-place deployments on Amazon EC2 and on-premises instances. It is not supported for Amazon ECS or AWS Lambda deployments.
A restart can be useful when:
- An application needs to reload runtime configuration.
- A long-running process must be recycled.
- A service needs a controlled restart across multiple instances.
- Operators want to automate recovery without maintaining a separate fleet-management script.
- A deployment team needs to restart applications while retaining CodeDeploy's deployment monitoring and lifecycle controls.
The important distinction is that a restart does not mean the application is receiving new code. CodeDeploy reuses the last successful revision associated with the deployment group to perform the restart operation.
How RESTART Differs from a Standard Deployment
A standard CodeDeploy deployment installs a specified application revision. A restart deployment uses the last successful revision already associated with the deployment group.
| Feature | Standard deployment | RESTART deployment |
|---|
| Primary purpose | Deploy an application revision | Restart the application using the last successful revision |
| Revision supplied in request | Normally required for a new deployment | Must not be supplied |
| Downloads a new revision | Depends on the deployment and agent state | Not required when the existing revision is available locally |
| Supported compute platforms | Depends on the deployment configuration | EC2 and on-premises in-place deployments |
| ECS and Lambda support | Supported deployment models are available | Not supported |
| Deployment controls | Uses configured deployment behavior | Retains applicable deployment configuration, lifecycle hooks, and monitoring controls |
The distinction matters because redeploying an unchanged revision and restarting an application are not identical operations. A standard deployment may repeat file installation and other deployment steps. The restart mode is intended to avoid that unnecessary work.
AWS reported that RESTART completed fleet restarts up to 6.1 times faster in its testing compared with previous approaches. This is a reported test result, not a guarantee for every application or environment. Actual duration depends on the fleet, deployment configuration, lifecycle hooks, application startup time, and revision availability.
Prerequisites Before Starting a Restart
Before using RESTART, verify the following requirements.
1. Use a Supported Deployment Group
The deployment group must use the EC2/on-premises compute platform and an in-place deployment strategy. The restart mode is not available for ECS or Lambda deployment groups.
2. Ensure a Successful Deployment Exists
CodeDeploy needs a last successful revision to reapply. If the deployment group does not have a successful deployment, there is no revision for the restart operation to use.
3. Check the CodeDeploy Agent
The CodeDeploy agent should be installed and operational on the target instances. Agent version 2.1.0 introduced native support for the RESTART deployment mode and can reuse the locally stored revision when available.
With older agents, the operation can fall back to downloading the revision. This can reduce the performance benefit, so check agent versions across the fleet before planning a restart.
4. Verify AWS CLI or SDK Support
The client used to create the deployment must support the deploymentMode request field. If the installed AWS CLI or SDK does not recognize the field, update it to a compatible version.
Starting a Restart Deployment with the AWS CLI
The AWS CLI provides a direct way to start a restart deployment.
Run the following command after replacing the application and deployment group names with the names in your AWS account:
aws deploy create-deployment \
--application-name MyApp \
--deployment-group-name MyDeploymentGroup \
--deployment-mode RESTART \
--description "Restart application after configuration update"
The command requests a restart using the deployment group's last successful revision.
Notice that the command does not include an S3 location, GitHub revision, or other application revision parameter. CodeDeploy resolves the revision from the deployment group's deployment history.
If the request succeeds, CodeDeploy returns a deployment ID. You can use that ID to monitor the operation.
Control the Deployment Batch Size
A restart can temporarily reduce the number of healthy application instances. The deployment configuration determines how CodeDeploy progresses through the fleet.
For example, the following command requests a restart using the CodeDeployDefault.OneAtATime deployment configuration:
aws deploy create-deployment \
--application-name MyApp \
--deployment-group-name MyDeploymentGroup \
--deployment-mode RESTART \
--deployment-config-name CodeDeployDefault.OneAtATime \
--description "Restart one instance at a time"
This configuration is useful when limiting simultaneous restarts is more important than completing the operation as quickly as possible. It can also make failures easier to isolate.
However, restarting one instance at a time is not automatically the right choice for every fleet. A larger fleet may need a different batch size to balance deployment duration and availability. Select the deployment configuration according to the application's capacity requirements and failure tolerance.
Do not combine RESTART with updateOutdatedInstancesOnly=true. That option selects instances based on whether they are running the target revision, which conflicts with the purpose of restarting instances on the last successful revision.
Starting a Restart from the AWS Console
Teams that prefer the AWS Management Console can initiate the same operation without constructing a CLI command.
The general workflow is:
- Open the AWS CodeDeploy console and select the application.
- Open the relevant deployment group.
- Choose the option to create a deployment.
- Select Restart as the deployment mode.
- Review the deployment configuration and available settings.
- Start the deployment and monitor its progress.
The exact options displayed depend on the deployment group and the current console interface.
Before confirming the operation, verify that the selected deployment group targets the intended instances. A restart can affect production availability even though the application revision remains unchanged.
Monitoring the Restart Deployment
After creating a restart deployment, use the deployment ID to inspect its status.
For example:
aws deploy get-deployment \
--deployment-id d-EXAMPLE123
Replace d-EXAMPLE123 with the ID returned by your deployment request.
The response contains deployment information, including the status and deployment mode when recorded. The console also provides deployment details that help operators identify whether the operation is a restart.
Monitor the operation for:
- Failed lifecycle hooks.
- Instances that fail to become healthy.
- Application startup failures.
- Deployment alarms entering an alarm state.
- Unexpected increases in request latency or error rates.
A successful API response from create-deployment only confirms that the request was accepted. It does not mean the application restart has completed successfully.
Lifecycle Hooks and Health Checks Still Matter
A controlled restart must account for application behavior before, during, and after the process stops.
For a request-serving application, the stop procedure should prevent new work from being accepted and allow in-flight requests to complete where the application architecture permits it. The startup procedure should verify that the application can initialize and become healthy again.
CodeDeploy's lifecycle hooks provide a place to perform appropriate preparation and validation. Configured deployment controls, health checks, and alarm monitoring remain important because a restart can fail even when the application revision itself is valid.
For example, a process may fail to start because a runtime configuration value is incorrect. A restart operation does not automatically correct that configuration problem. If the application cannot become healthy, deployment safeguards should prevent the operation from progressing through the fleet in a way that causes avoidable service disruption.
Before using RESTART in production, test the lifecycle hooks against both successful and failed startup scenarios.
Automating Restarts for Operational Recovery
The RESTART mode can also serve as a building block for controlled operational automation.
For example, a monitoring system might detect a sustained resource-utilization problem and trigger an automated workflow. That workflow can evaluate the condition and, if the recovery policy permits it, request a CodeDeploy restart.
A responsible automation process should:
- Confirm that the condition is genuine and meets the recovery threshold.
- Check whether another deployment or restart is already running.
- Select the correct deployment group and restart configuration.
- Initiate the restart through an authorized AWS identity.
- Monitor deployment status and application health.
- Stop repeated automation attempts or alert an operator when recovery fails.
Avoid creating an unlimited restart loop. A recurring process failure may indicate a memory leak, an invalid configuration, or another underlying defect that restarting alone will not fix.
Use appropriate permissions, monitoring, and safeguards so an automated recovery mechanism cannot repeatedly disrupt a healthy fleet.
Limitations and Common Mistakes
Expecting RESTART to Deploy New Code
RESTART uses the last successful revision. If the application needs a code update, create a standard deployment with the intended revision instead.
Using an Unsupported Compute Platform
The restart mode is limited to EC2 and on-premises in-place deployments. Do not assume it can be used for ECS or Lambda deployments.
Supplying a Revision in the Restart Request
The revision parameter must not be specified when using RESTART. CodeDeploy resolves the revision from the deployment group's last successful deployment.
Ignoring Application Startup Failures
A restart can expose problems in runtime configuration, dependencies, or application initialization. Keep health checks and lifecycle validation in place.
Choosing an Unsafe Batch Size
Restarting too many instances simultaneously can reduce service capacity. Choose a deployment configuration that maintains sufficient healthy capacity for the expected restart duration.
Assuming Every Restart Will Be Faster
The performance improvement depends on the environment and the amount of work the operation needs to perform. An instance that lacks a usable local revision may need to download it, and application startup time still affects the overall duration.
Summary
AWS CodeDeploy's RESTART deployment mode provides a dedicated way to restart applications across supported EC2 and on-premises in-place deployment groups without specifying a new application revision.
It can simplify routine maintenance, configuration reloads, and controlled application recovery while retaining important CodeDeploy deployment controls. Teams can initiate restarts through the AWS CLI or console, select an appropriate deployment configuration, and monitor the resulting operation through normal deployment tooling.
Before adopting the feature, confirm agent and client compatibility, verify that a successful revision exists, and test lifecycle hooks and health checks. Most importantly, treat a fleet restart as a production change: preserve sufficient healthy capacity, monitor the rollout, and investigate recurring failures rather than relying on repeated restarts as a permanent fix.
Join the conversation! Your thoughts help the community grow.