Restarting an application across multiple servers sounds straightforward until it becomes a production operation. A restart can interrupt traffic, reduce available capacity, expose configuration problems, or leave a fleet partially recovered. Teams often handle these operations with custom scripts or redeploy the current application revision, even when the application files have not changed.

AWS CodeDeploy now provides a dedicated RESTART deployment mode for Amazon EC2 and on-premises instances. It restarts applications using the last successful deployment revision while retaining CodeDeploy's deployment controls, including deployment configurations, lifecycle hooks, health checks, and configured alarm monitoring. AWS reported that the operation completed up to 6.1 times faster in its testing, although actual results depend on the environment.

For DevOps engineers, this feature offers a more controlled way to perform routine application restarts without building a separate fleet-management workflow.

Why Restarting a Fleet Needs Deployment Controls

Application restarts are common during routine operations. A service might need to reload runtime configuration, recover from unhealthy processes, or release resources accumulated during a long-running workload. Some teams also schedule periodic restarts for services that gradually consume more memory or other resources.

The difficulty is coordinating the restart across a fleet.

Consider a service running on 20 EC2 instances behind a load balancer. Restarting every instance simultaneously could remove the entire service from rotation. Restarting instances one by one is safer, but a custom script must still determine when each instance is healthy enough for the next restart.

A simple shell loop does not automatically provide:

Redeploying the current application revision is another option, but a standard deployment repeats deployment work that might not be necessary.

CodeDeploy's RESTART mode addresses this problem by treating the restart as a managed deployment operation rather than an unrelated maintenance script.

How CodeDeploy RESTART Mode Works

In a standard CodeDeploy deployment, the deployment request identifies the application revision to deploy. With RESTART, CodeDeploy instead resolves the revision from the deployment group's last successful deployment.

The service then runs the restart through the existing deployment workflow. It applies the deployment group's configuration, executes the applicable lifecycle hooks, and monitors the configured deployment health and alarm conditions.

The distinction is important: RESTART does not mean deploying a new application version. It means restarting the application using the revision associated with the last successful deployment.

The feature is supported for EC2 and on-premises in-place deployments. It is not supported for Amazon ECS or AWS Lambda deployment groups.

What happens during a restart?

A typical operation follows this sequence:

  1. An operator or automation system requests a restart deployment.

  2. CodeDeploy identifies the deployment group's last successful revision.

  3. The deployment runs according to the configured deployment strategy and lifecycle hooks.

  4. The application is restarted and the deployment's validation checks run.

  5. CodeDeploy records the outcome and applies the configured failure behavior if the operation encounters a problem.

The CodeDeploy agent can reuse the revision archive already available on an instance. If that copy is missing or incomplete, the agent downloads the revision instead. Consequently, the feature can reduce unnecessary work, but it does not guarantee that every restart will avoid network downloads.

Start a Restart Deployment With the AWS CLI

The simplest way to initiate a restart is through the AWS CLI. You need an existing CodeDeploy application and deployment group configured for EC2 or on-premises in-place deployments, along with correctly configured instances and compatible CodeDeploy agents.

Use the following command, replacing the example names with your actual resources:

aws deploy create-deployment \
  --application-name MyApp \
  --deployment-group-name MyDeploymentGroup \
  --deployment-mode RESTART \
  --description "Restart application after runtime configuration update"

The --deployment-mode RESTART argument tells CodeDeploy to reuse the last successful revision rather than requiring a new revision in the request.

CodeDeploy returns a deployment ID when the request is accepted. Use that ID to inspect the operation.

aws deploy get-deployment \
  --deployment-id d-EXAMPLE123

Replace d-EXAMPLE123 with the actual ID returned by your deployment request.

The request intentionally omits a revision argument. CodeDeploy resolves the revision from deployment history, so providing a revision or a source location such as an S3 or GitHub revision is not appropriate for this mode.

Control the deployment batch size

You can also specify a deployment configuration to control how instances are processed. For example, the following command requests a one-at-a-time deployment:

aws deploy create-deployment \
  --application-name MyApp \
  --deployment-group-name MyDeploymentGroup \
  --deployment-mode RESTART \
  --deployment-config-name CodeDeployDefault.OneAtATime \
  --description "Restart one host at a time"

This is useful when application availability is more important than completing the restart quickly. The appropriate configuration depends on fleet size, redundancy, startup time, and the number of healthy instances the service must maintain.

For production workloads, do not assume that a faster restart is automatically a safer restart. Select a batch size that preserves enough capacity to serve traffic while instances recover.

Use the CodeDeploy Console

Teams that prefer a graphical workflow can initiate a restart through the CodeDeploy console.

Open the relevant application, select its deployment group, and choose the option to create a deployment. Select Restart as the deployment mode, then review the deployment configuration and other available settings before starting the operation.

After the deployment begins, inspect its status and the results for individual instances. This is especially useful when the restart is part of a maintenance window and operators need to verify that the fleet recovered successfully.

The console and CLI both use CodeDeploy's deployment workflow, so teams can choose the interface that fits their operational process.

Automate Restarts With Monitoring and Remediation

The feature becomes more useful when combined with existing monitoring and event-driven automation.

For example, a service might experience gradual memory growth. An operations team could use a CloudWatch alarm to identify a sustained resource-utilization problem, route the event through Amazon EventBridge, and invoke an AWS Lambda function that requests a CodeDeploy restart deployment.

A simplified architecture looks like this:

This approach can be useful for long-running JVM services, self-managed brokers, or other applications where a controlled restart is an established recovery action.

However, automation should not restart a service merely because a single metric crosses a threshold. A restart may hide symptoms without addressing the underlying problem. Before enabling automatic remediation, define the trigger conditions, suppress repeated requests, limit concurrent operations, and provide a clear escalation path when recovery fails.

For stateful systems, validate the application's recovery and consistency requirements before automating restarts. Restarting a process is not a substitute for ensuring that the application can recover safely.

Important Constraints and Compatibility Checks

Before using RESTART, confirm that the deployment group and instances meet the feature's requirements.

A successful deployment must already exist

CodeDeploy uses the deployment group's last successful revision. A deployment group without a successful revision to reuse cannot perform the intended restart operation.

Before scheduling a fleet restart, verify the deployment history and confirm that the successful revision represents the application version you want running.

Use EC2 or on-premises in-place deployments

RESTART is intended for EC2 and on-premises in-place deployments. It does not support ECS or Lambda deployment groups.

On-premises instances must still be registered and configured for CodeDeploy, with the agent installed and able to communicate with the service.

Do not supply a new revision

The restart request must not include the revision parameter or its source-location details. CodeDeploy determines the revision from the deployment group's last successful deployment.

This also means that RESTART is not a mechanism for deploying uncommitted configuration files or an application version that has not been successfully deployed.

Do not combine it with outdated-instance-only updates

The updateOutdatedInstancesOnly option must not be set to true for a restart deployment. That option selects instances based on whether they are already running the target revision, which conflicts with the purpose of restarting instances on the last successful revision.

Review automation code that constructs deployment requests dynamically. A request that works for a standard deployment may need separate handling for RESTART.

Troubleshooting Failed Restart Deployments

A restart deployment can fail for the same broad operational reasons that affect other deployment workflows. The useful difference is that the operation is visible in CodeDeploy rather than being hidden inside a separate script.

Start by checking the deployment status and the affected instance results.

If the request is rejected, verify the deployment mode, deployment group type, and request parameters. Remove any revision information and confirm that updateOutdatedInstancesOnly is not enabled.

If an instance cannot find its revision, inspect the CodeDeploy agent logs and deployment history. The agent can reuse a local revision archive when it is available, but an absent or incomplete copy requires a download. Confirm that the instance can communicate with CodeDeploy and access the required revision source when a download is necessary.

If lifecycle validation fails, inspect the applicable hooks and their logs. A restart may reveal application startup problems that were not visible before the operation. Validate dependencies, runtime configuration, permissions, and service readiness checks.

If a deployment stops because of health or alarm conditions, investigate the underlying capacity or application issue before retrying. Repeating the restart without addressing the cause can create a loop of failed remediation attempts.

A useful operational practice is to test the restart against a small, representative deployment group before applying it to the full fleet. Confirm both successful recovery and expected behavior when an instance fails to restart.

Summary

AWS CodeDeploy's RESTART deployment mode gives teams a managed way to restart applications on EC2 and on-premises fleets without treating every restart as a new application deployment.

It reuses the deployment group's last successful revision and integrates the operation with existing deployment configurations, lifecycle hooks, health requirements, alarm monitoring, and deployment history. This can reduce unnecessary work and make maintenance and remediation workflows easier to audit.

Before adopting it, verify that the deployment group is supported, a successful revision exists, the CodeDeploy agents are ready, and the chosen deployment configuration preserves sufficient capacity. For automated restarts, add safeguards against repeated triggers and make sure a restart is an appropriate response to the condition being detected.

The main benefit is operational consistency: routine application restarts can follow the same controlled deployment process used for application releases.