Restarting an application across a fleet of servers is a common operational task. Teams may need to apply runtime configuration changes, recover unhealthy processes, or return application instances to a known state without changing the deployed application version.
Previously, AWS CodeDeploy users often had to redeploy the existing revision or use custom scripts to restart applications across EC2 and on-premises fleets. Both approaches introduced extra work. Redeploying could repeat unnecessary deployment steps, while custom scripts required separate orchestration, monitoring, and failure-handling logic.
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 CodeDeploy's deployment controls.
For DevOps engineers, this makes routine fleet restarts easier to manage through the same deployment system used for application releases.
What Is the New CodeDeploy RESTART Mode?
AWS CodeDeploy automates application deployments to Amazon EC2 instances, on-premises servers, AWS Lambda functions, and Amazon ECS services, depending on the deployment type.
Its new RESTART mode targets EC2 and on-premises in-place deployment groups. Instead of supplying a new application revision, the developer asks CodeDeploy to restart the application using the last successful revision associated with the deployment group.
The deployment still follows CodeDeploy's lifecycle and monitoring mechanisms. The service can process instances according to the selected deployment configuration, execute applicable lifecycle hooks, evaluate configured alarms, and stop the deployment when its failure conditions are met.
The feature is particularly useful when the application version should remain unchanged but its processes need to be restarted.
For example, suppose a Java application runs on 20 EC2 instances. An operations team changes a runtime configuration value and needs to restart the application across the fleet. A RESTART deployment can perform the operation through CodeDeploy without requiring the team to package and upload another application revision.
Why Restarting a Fleet Can Be Complicated
A restart may appear simple on a single server, but coordinating it across production instances introduces several operational concerns.
Challenge | Manual or redeployment-based approach | RESTART deployment mode |
|---|
Application revision | May require another deployment of the existing revision | Resolves the last successful revision automatically |
Fleet coordination | Requires scripts or additional orchestration | Uses the deployment group's deployment configuration |
Lifecycle operations | Must be implemented or coordinated separately | Uses the applicable CodeDeploy lifecycle hooks |
Health monitoring | Depends on the custom restart process | Retains configured deployment monitoring and health requirements |
Failure handling | Must be designed into the script or orchestration | Uses CodeDeploy's deployment failure behavior |
Operational visibility | May require separate logging and status tracking | Appears as a CodeDeploy deployment |
The main benefit is not simply executing a restart command. It is managing the restart as a tracked deployment operation with established controls.
This matters when a fleet contains multiple instances and the team must preserve enough healthy capacity to serve requests throughout the operation.
How RESTART Deployment Mode Works
The process starts when a developer creates a deployment and sets the deployment mode to RESTART.
CodeDeploy identifies the last successful revision associated with the deployment group and applies the restart workflow to the target instances.
The CodeDeploy agent can use the revision already stored on an instance. If that local copy is missing or incomplete, the agent downloads the revision as a fallback.
A typical workflow looks like this:
The developer selects the application and deployment group.
CodeDeploy resolves the last successful revision.
The deployment begins according to the configured deployment strategy.
The agent uses the locally available revision when possible.
Applicable lifecycle hooks execute as the deployment progresses.
CodeDeploy evaluates deployment health and configured alarms.
The deployment completes or stops according to its configured failure behavior.
The local revision optimization helps avoid unnecessary downloads when the required application revision is already present.
AWS reported that the new mode ran up to 6.1 times faster in its testing compared with the previous approaches. This is a workload-specific result, not a guarantee that every fleet restart will achieve the same improvement. Actual performance depends on the deployment configuration, revision availability, lifecycle hooks, and application startup behavior.
Starting a Restart Deployment With the AWS CLI
The AWS CLI provides a straightforward way to initiate a restart deployment.
Use the following command after replacing the application and deployment group names with your own values:
aws deploy create-deployment \
--application-name MyApp \
--deployment-group-name MyDeploymentGroup \
--deployment-mode RESTART \
--description "Restart processes after a runtime configuration update"
The command asks CodeDeploy to restart the target fleet using the deployment group's last successful revision.
Notice that the request does not include an application revision such as an S3 bundle or GitHub revision. CodeDeploy resolves the revision from deployment history.
If the request succeeds, the service returns a deployment ID similar to this example:
{
"deploymentId": "d-EXAMPLE123"
}
The identifier can then be used to inspect the deployment's status.
Restarting One Instance at a Time
For an application that needs to preserve as much serving capacity as possible, the team can specify 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 instructs CodeDeploy to process instances one at a time, subject to the deployment group's applicable settings and deployment requirements.
For larger fleets, the team may choose a different supported deployment configuration. The right choice depends on available capacity, the application's availability requirements, and how quickly the fleet must complete the restart.
Choosing a Deployment Strategy
Restarting an application across a fleet requires balancing deployment speed against service availability.
Strategy | Main advantage | Main consideration |
|---|
One instance at a time | Limits the number of instances being restarted simultaneously | Takes longer for large fleets |
Larger deployment batches | Can complete the restart more quickly | More instances may be unavailable simultaneously |
Custom restart script | Provides application-specific control | Requires separate coordination, monitoring, and error handling |
Standard redeployment | Useful when the application revision must also change | Can repeat work that is unnecessary for a restart-only operation |
The RESTART mode does not eliminate the need to select an appropriate deployment configuration. It gives the team a dedicated restart operation that can use the existing CodeDeploy deployment controls.
For a customer-facing application, one instance at a time may be a reasonable starting point. Teams can consider larger batches after validating their capacity requirements and recovery behavior.
Monitoring the Restart Deployment
Once the deployment starts, developers can monitor it through the CodeDeploy console or the AWS CLI.
To retrieve deployment details, run:
aws deploy get-deployment \
--deployment-id d-EXAMPLE123
Replace d-EXAMPLE123 with the actual deployment ID returned by the create-deployment request.
The deployment progresses through CodeDeploy's normal lifecycle states, including Created, InProgress, and a terminal state.
The deployment details include a deploymentMode field that identifies the operation as RESTART. This helps distinguish restart deployments from standard deployments when reviewing operational history.
Monitoring is important because a restart can fail even when no application code has changed. A process might fail to start, a lifecycle hook might return an error, or a configured CloudWatch alarm might indicate unhealthy behavior.
Teams should monitor both the CodeDeploy status and application-level indicators such as:
Application health-check failures
Request error rates
Response latency
Process startup failures
CPU and memory utilization
Load balancer target health
Configured CloudWatch alarms
A successful deployment indicates that the configured deployment process completed. It should not replace application-level verification that the service is functioning correctly.
Important Limitations and Compatibility Requirements
The new deployment mode has specific constraints that developers must understand before integrating it into existing automation.
Supported Deployment Groups
RESTART supports EC2 and on-premises in-place deployment groups. It does not support Amazon ECS or AWS Lambda deployment groups.
Teams using those platforms must continue to use the restart or replacement mechanisms appropriate to their deployment architecture.
A Successful Revision Must Exist
CodeDeploy needs a successful revision in the deployment group's history to determine which application version to reapply.
If the deployment group has no successful revision, the restart operation cannot resolve the required application version.
Do Not Specify a New Revision
When using RESTART, do not provide revision-related parameters such as revision, s3Location, gitHubLocation, or deploymentRevisions.
The service determines the revision from the deployment group's last successful deployment.
Do Not Combine It With Outdated-Instance-Only Updates
The updateOutdatedInstancesOnly option must not be enabled for a restart deployment.
That option selects instances that are not running the target revision. A restart deployment, by contrast, targets the current successful revision. Combining these behaviors would create conflicting deployment requirements.
Verify the CodeDeploy Agent Version
The CodeDeploy agent version 2.1.0 introduced native support for the RESTART deployment mode. Before using the feature, verify that the target instances have a compatible agent version and that the required version is available in the AWS Region where the fleet operates.
These requirements should be checked in deployment automation before the restart is scheduled.
Common Mistakes to Avoid
Using RESTART When a New Version Is Required
A restart deployment reuses the last successful revision. It is not a substitute for deploying a new application version.
If the application code or packaged configuration must change, use a standard deployment with the intended revision.
Restarting Too Many Instances at Once
A large restart batch can temporarily reduce serving capacity or cause a spike in application initialization requests.
Choose the deployment configuration according to the fleet size, redundancy, and availability requirements.
Ignoring Lifecycle Hooks
Restart deployments continue to use applicable CodeDeploy lifecycle behavior. Existing hooks may perform application shutdown, configuration checks, startup operations, or validation.
Review those scripts to ensure that they are safe to run during a restart and do not repeat unintended side effects.
Assuming a Restart Is Always Faster
The speed advantage depends on the environment. Instances with a missing local revision may need to download it, and lengthy startup scripts can dominate the total duration.
Measure the actual restart workflow before changing operational service-level expectations.
Skipping Post-Restart Verification
A deployment can complete while the application still has an application-specific problem that is not covered by the configured deployment checks.
Verify application health and important business operations after the restart.
Best Practices for Production Fleets
Follow these practices when adopting the new deployment mode:
Confirm the deployment type. Ensure the deployment group uses a supported EC2 or on-premises in-place configuration.
Verify deployment history. Confirm that the deployment group has a successful revision to reuse.
Update and validate the agent. Check compatibility across every target instance.
Choose a suitable deployment configuration. Start with smaller batches when availability is a priority.
Review lifecycle hooks. Ensure existing scripts behave correctly during repeated restart operations.
Configure health checks and alarms. Use appropriate signals to detect unhealthy application behavior.
Test on a representative fleet. Validate the process in a non-production environment before running it against critical workloads.
Monitor the complete operation. Track deployment status, application startup, and service health.
Keep restart and rollback procedures separate. A restart does not automatically restore a previous application version or undo a problematic configuration change.
These practices help teams make fleet restarts more predictable without treating them as risk-free operations.
Conclusion
AWS CodeDeploy's RESTART deployment mode provides a dedicated way to restart applications across existing EC2 and on-premises fleets using the deployment group's last successful revision.
By reusing the available revision and retaining deployment controls such as batch sizing, lifecycle hooks, health checks, and configured alarms, the feature reduces the need for custom restart scripts or unnecessary redeployment work.
For DevOps teams, the practical benefit is a more consistent operational workflow. Before adopting it, verify compatibility, choose a suitable deployment configuration, review lifecycle hooks, and validate the application after the restart.
The result is a more controlled way to handle routine fleet operations while keeping them within the existing CodeDeploy deployment process.
Join the conversation! Your thoughts help the community grow.