# Configuration changes When you modify configuration option settings in the **Configuration** section of the [environment management console](environments-console.md), AWS Elastic Beanstalk propagates the change to all affected resources. These resources include the load balancer that distributes traffic to the Amazon EC2 instances running your application, the Auto Scaling group that manages those instances, and the EC2 instances themselves. Many configuration changes can be applied to a running environment without replacing existing instances. For example, setting a [health check URL](environments-cfg-clb.md#using-features.managing.elb.healthchecks) triggers an environment update to modify the load balancer settings, but doesn't cause any downtime because the instances running your application continue serving requests while the update is propagated. Configuration changes that modify the [launch configuration](command-options-general.md#command-options-general-autoscalinglaunchconfiguration) or [VPC settings](command-options-general.md#command-options-general-ec2vpc) require terminating all instances in your environment and replacing them. For example, when you change the instance type or SSH key setting for your environment, the EC2 instances must be terminated and replaced. Elastic Beanstalk provides several policies that determine how this replacement is done. + **Rolling updates** – Elastic Beanstalk applies your configuration changes in batches, keeping a minimum number of instances running and serving traffic at all times. This approach prevents downtime during the update process. For details, see [Rolling updates](using-features.rollingupdates.md). + **Immutable updates** – Elastic Beanstalk launches a temporary Auto Scaling group outside of your environment with a separate set of instances running with the new configuration. Then Elastic Beanstalk places these instances behind your environment's load balancer. Old and new instances both serve traffic until the new instances pass health checks. At that time, Elastic Beanstalk moves the new instances into your environment's Auto Scaling group and terminates the temporary group and old instances. For details, see [Immutable updates](environmentmgmt-updates-immutable.md). + **Disabled** – Elastic Beanstalk makes no attempt to avoid downtime. It terminates your environment's existing instances and replaces them with new instances running with the new configuration. **Warning** Some policies replace all instances during the deployment or update. This causes all accumulated [Amazon EC2 burst balances](https://docs.aws.amazon.com/AWSEC2/latest/DeveloperGuide/burstable-performance-instances.html) to be lost. It happens in the following cases: Managed platform updates with instance replacement enabled Immutable updates Deployments with immutable updates or traffic splitting enabled **Supported update types** | Rolling update setting | Load-balanced environments | Single-instance environments | Legacy Windows server environments† | | --- | --- | --- | --- | | Disabled | ![\[Yes\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/icon-yes.png) Yes | ![\[Yes\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/icon-yes.png) Yes | ![\[Yes\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/icon-yes.png) Yes | | Rolling Based on Health | ![\[Yes\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/icon-yes.png) Yes | ![\[No\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/icon-no.png) No | ![\[Yes\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/icon-yes.png) Yes | | Rolling Based on Time | ![\[Yes\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/icon-yes.png) Yes | ![\[No\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/icon-no.png) No | ![\[Yes\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/icon-yes.png) Yes | | Immutable | ![\[Yes\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/icon-yes.png) Yes | ![\[Yes\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/icon-yes.png) Yes | ![\[No\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/icon-no.png) No | † For the purpose of this table, a *Legacy Windows Server Environment* is an environment based on a [Windows Server platform configuration](https://docs.aws.amazon.com/elasticbeanstalk/latest/platforms/platforms-supported.html#platforms-supported.net) that use an IIS version earlier than IIS 8.5. **Topics** + [ # Elastic Beanstalk rolling environment configuration updates ](using-features.rollingupdates.md) + [ # Immutable environment updates ](environmentmgmt-updates-immutable.md) # Elastic Beanstalk rolling environment configuration updates Rolling updates When a [configuration change requires replacing instances](environments-updating.md), Elastic Beanstalk can perform the update in batches to avoid downtime while the change is propagated. During a rolling update, capacity is only reduced by the size of a single batch, which you can configure. Elastic Beanstalk takes one batch of instances out of service, terminates them, and then launches a batch with the new configuration. After the new batch starts serving requests, Elastic Beanstalk moves on to the next batch. Rolling configuration update batches can be processed periodically (time-based), with a delay between each batch, or based on health. For time-based rolling updates, you can configure the amount of time that Elastic Beanstalk waits after completing the launch of a batch of instances before moving on to the next batch. This pause time allows your application to bootstrap and start serving requests. With health-based rolling updates, Elastic Beanstalk waits until instances in a batch pass health checks before moving on to the next batch. The health of an instance is determined by the health reporting system, which can be basic or enhanced. With [basic health](using-features.healthstatus.md), a batch is considered healthy as soon as all instances in it pass Elastic Load Balancing (ELB) health checks. With [enhanced health reporting](health-enhanced.md), all of the instances in a batch must pass multiple consecutive health checks before Elastic Beanstalk will move on to the next batch. In addition to ELB health checks, which check only your instances, enhanced health monitors application logs and the state of your environment's other resources. In a web server environment with enhanced health, all instances must pass 12 health checks over the course of two minutes (18 checks over three minutes for worker environments). If any instance fails one health check, the count resets. If a batch doesn't become healthy within the rolling update timeout (default is 30 minutes), the update is canceled. Rolling update timeout is a [configuration option](command-options.md) that is available in the `aws:autoscaling:updatepolicy:rollingupdate` namespace. If your application doesn't pass health checks with `Ok` status but is stable at a different level, you can set the `HealthCheckSuccessThreshold` option in the [`aws:elasticbeanstalk:healthreporting:system`](command-options-general.md#command-options-general-elasticbeanstalkhealthreporting) namespace to change the level at which Elastic Beanstalk considers an instance to be healthy. If the rolling update process fails, Elastic Beanstalk starts another rolling update to roll back to the previous configuration. A rolling update can fail due to failed health checks or if launching new instances causes you to exceed the quotas on your account. If you hit a quota on the number of Amazon EC2 instances, for example, the rolling update can fail when it attempts to provision a batch of new instances. In this case, the rollback fails as well. A failed rollback ends the update process and leaves your environment in an unhealthy state. Unprocessed batches are still running instances with the old configuration, while any batches that completed successfully have the new configuration. To fix an environment after a failed rollback, first resolve the underlying issue that caused the update to fail, and then initiate another environment update. An alternative method is to deploy the new version of your application to a different environment and then perform a CNAME swap to redirect traffic with zero downtime. See [Blue/Green deployments with Elastic Beanstalk](using-features.CNAMESwap.md) for more information. ## Rolling updates versus rolling deployments Rolling updates occur when you change settings that require new Amazon EC2 instances to be provisioned for your environment. This includes changes to the Auto Scaling group configuration, such as instance type and key-pair settings, and changes to VPC settings. In a rolling update, each batch of instances is terminated before a new batch is provisioned to replace it. [Rolling deployments](using-features.rolling-version-deploy.md) occur whenever you deploy your application and can typically be performed without replacing instances in your environment. Elastic Beanstalk takes each batch out of service, deploys the new application version, and then places it back in service. The exception to this is if you change settings that require instance replacement at the same time you deploy a new application version. For example, if you change the [key name](command-options-general.md#command-options-general-autoscalinglaunchconfiguration) settings in a [configuration file](ebextensions.md) in your source bundle and deploy it to your environment, you trigger a rolling update. Instead of deploying your new application version to each batch of existing instances, a new batch of instances is provisioned with the new configuration. In this case, a separate deployment doesn't occur because the new instances are brought up with the new application version. Anytime new instances are provisioned as part of an environment update, there is a deployment phase where your application's source code is deployed to the new instances and any configuration settings that modify the operating system or software on the instances are applied. [Deployment health check settings](using-features.rolling-version-deploy.md#environments-cfg-rollingdeployments-console) (**Ignore health check**, **Healthy threshold**, and **Command timeout**) also apply to health-based rolling updates and immutable updates during the deployment phase. ## Configuring rolling updates You can enable and configure rolling updates in the Elastic Beanstalk console. **To enable rolling updates** 1. Open the [Elastic Beanstalk console](https://console.aws.amazon.com/elasticbeanstalk), and in the **Regions** list, select your AWS Region. 1. In the navigation pane, choose **Environments**, and then choose the name of your environment from the list. 1. In the navigation pane, choose **Configuration**. 1. In the **Rolling updates and deployments** configuration category, choose **Edit**. 1. In the **Configuration updates** section, for **Rolling update type**, select one of the **Rolling** options. ![\[The configuration updates section on the modify rolling updates and deployments configuration page\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/aeb-config-rolling-updates-health.png) 1. Choose **Batch size**, **Minimum capacity**, and **Pause time** settings. 1. To save the changes choose **Apply** at the bottom of the page. The **Configuration updates** section of the **Rolling updates and deployments** page has the following options for rolling updates: + **Rolling update type** – Elastic Beanstalk waits after it finishes updating a batch of instances before moving on to the next batch, to allow those instances to finish bootstrapping and start serving traffic. Choose from the following options: + **Rolling based on Health** – Wait until instances in the current batch are healthy before placing instances in service and starting the next batch. + **Rolling based on Time** – Specify an amount of time to wait between launching new instances and placing them in service before starting the next batch. + **Immutable** – Apply the configuration change to a fresh group of instances by performing an [immutable update](environmentmgmt-updates-immutable.md). + **Batch size** – The number of instances to replace in each batch, between **1** and **10000**. By default, this value is one-third of the minimum size of the Auto Scaling group, rounded up to a whole number. + **Minimum capacity** – The minimum number of instances to keep running while other instances are updated, between **0** and **9999**. The default value is either the minimum size of the Auto Scaling group or one less than the maximum size of the Auto Scaling group, whichever number is lower. + **Pause time** (time-based only) – The amount of time to wait after a batch is updated before moving on to the next batch, to allow your application to start receiving traffic. Between 0 seconds and one hour. ## The aws:autoscaling:updatepolicy:rollingupdate namespace You can also use the [configuration options](command-options.md) in the `aws:autoscaling:updatepolicy:rollingupdate` namespace to configure rolling updates. Use the `RollingUpdateEnabled` option to enable rolling updates, and `RollingUpdateType` to choose the update type. The following values are supported for `RollingUpdateType`: + `Health` – Wait until instances in the current batch are healthy before placing instances in service and starting the next batch. + `Time` – Specify an amount of time to wait between launching new instances and placing them in service before starting the next batch. + `Immutable` – Apply the configuration change to a fresh group of instances by performing an [immutable update](environmentmgmt-updates-immutable.md). When you enable rolling updates, set the `MaxBatchSize` and `MinInstancesInService` options to configure the size of each batch. For time-based and health-based rolling updates, you can also configure a `PauseTime` and `Timeout`, respectively. For example, to launch up to five instances at a time, while maintaining at least two instances in service, and wait five minutes and 30 seconds between batches, specify the following options and values. **Example .ebextensions/timebased.config** ``` option_settings: aws:autoscaling:updatepolicy:rollingupdate: RollingUpdateEnabled: true MaxBatchSize: 5 MinInstancesInService: 2 RollingUpdateType: Time PauseTime: PT5M30S ``` To enable health-based rolling updates, with a 45-minute timeout for each batch, specify the following options and values. **Example .ebextensions/healthbased.config** ``` option_settings: aws:autoscaling:updatepolicy:rollingupdate: RollingUpdateEnabled: true MaxBatchSize: 5 MinInstancesInService: 2 RollingUpdateType: Health Timeout: PT45M ``` `Timeout` and `PauseTime` values must be specified in [ISO8601 duration](http://en.wikipedia.org/wiki/ISO_8601#Durations): `PT#H#M#S`, where each \$1 is the number of hours, minutes, or seconds, respectively. The EB CLI and Elastic Beanstalk console apply recommended values for the preceding options. You must remove these settings if you want to use configuration files to configure the same. See [Recommended values](command-options.md#configuration-options-recommendedvalues) for details. # Immutable environment updates Immutable updates Immutable environment updates are an alternative to [rolling updates](using-features.rollingupdates.md). Immutable environment updates ensure that configuration changes that require replacing instances are applied efficiently and safely. If an immutable environment update fails, the rollback process requires only terminating an Auto Scaling group. A failed rolling update, on the other hand, requires performing an additional rolling update to roll back the changes. To perform an immutable environment update, Elastic Beanstalk creates a second, temporary Auto Scaling group behind your environment's load balancer to contain the new instances. First, Elastic Beanstalk launches a single instance with the new configuration in the new group. This instance serves traffic alongside all of the instances in the original Auto Scaling group that are running the previous configuration. When the first instance passes health checks, Elastic Beanstalk launches additional instances with the new configuration, matching the number of instances running in the original Auto Scaling group. When all of the new instances pass health checks, Elastic Beanstalk transfers them to the original Auto Scaling group, and terminates the temporary Auto Scaling group and old instances. **Note** During an immutable environment update, the capacity of your environment doubles for a short time when the instances in the new Auto Scaling group start serving requests and before the original Auto Scaling group's instances are terminated. If your environment has many instances, or you have a low [on-demand instance quota](https://aws.amazon.com/ec2/faqs/#How_many_instances_can_I_run_in_Amazon_EC2), ensure that you have enough capacity to perform an immutable environment update. If you are near the quota, consider using rolling updates instead. Immutable updates require [enhanced health reporting](health-enhanced.md) to evaluate your environment's health during the update. Enhanced health reporting combines standard load balancer health checks with instance monitoring to ensure that the instances running the new configuration are [serving requests successfully](health-enhanced.md#health-enhanced-factors). You can also use immutable updates to deploy new versions of your application, as an alternative to rolling deployments. When you [configure Elastic Beanstalk to use immutable updates for application deployments](using-features.rolling-version-deploy.md), it replaces all instances in your environment every time you deploy a new version of your application. If an immutable application deployment fails, Elastic Beanstalk reverts the changes immediately by terminating the new Auto Scaling group. This can prevent partial fleet deployments, which can occur when a rolling deployment fails after some batches have already completed. **Warning** Some policies replace all instances during the deployment or update. This causes all accumulated [Amazon EC2 burst balances](https://docs.aws.amazon.com/AWSEC2/latest/DeveloperGuide/burstable-performance-instances.html) to be lost. It happens in the following cases: Managed platform updates with instance replacement enabled Immutable updates Deployments with immutable updates or traffic splitting enabled If an immutable update fails, the new instances upload [bundle logs](using-features.logging.md) to Amazon S3 before Elastic Beanstalk terminates them. Elastic Beanstalk leaves logs from a failed immutable update in Amazon S3 for one hour before deleting them, instead of the standard 15 minutes for bundle and tail logs. **Note** If you use immutable updates for application version deployments, but not for configuration, you might encounter an error if you attempt to deploy an application version that contains configuration changes that would normally trigger a rolling update (for example, configurations that change instance type). To avoid this, make the configuration change in a separate update, or configure immutable updates for both deployments and configuration changes. You can't perform an immutable update in concert with resource configuration changes. For example, you can't change [settings that require instance replacement](environments-updating.md) while also updating other settings, or perform an immutable deployment with configuration files that change configuration settings or additional resources in your source code. If you attempt to change resource settings (for example, load balancer settings) and concurrently perform an immutable update, Elastic Beanstalk returns an error. If your resource configuration changes aren't dependent on your source code change or on instance configuration, perform them in two updates. If they are dependent, perform a [blue/green deployment](using-features.CNAMESwap.md) instead. ## Configuring immutable updates You can enable and configure immutable updates in the Elastic Beanstalk console. **To enable immutable updates (console)** 1. Open the [Elastic Beanstalk console](https://console.aws.amazon.com/elasticbeanstalk), and in the **Regions** list, select your AWS Region. 1. In the navigation pane, choose **Environments**, and then choose the name of your environment from the list. 1. In the navigation pane, choose **Configuration**. 1. In the **Rolling updates and deployments** configuration category, choose **Edit**. 1. In the **Configuration Updates** section, set **Rolling update type** to **Immutable**. ![\[The configuration updates section on the modify rolling updates and deployments configuration page\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/environments-mgmt-updates-immutable.png) 1. To save the changes choose **Apply** at the bottom of the page. ## The aws:autoscaling:updatepolicy:rollingupdate namespace You can also use the options in the `aws:autoscaling:updatepolicy:rollingupdate` namespace to configure immutable updates. The following example [configuration file](ebextensions.md) enables immutable updates for configuration changes. **Example .ebextensions/immutable-updates.config** ``` option_settings: aws:autoscaling:updatepolicy:rollingupdate: RollingUpdateType: Immutable ``` The following example enables immutable updates for both configuration changes and deployments. **Example .ebextensions/immutable-all.config** ``` option_settings: aws:autoscaling:updatepolicy:rollingupdate: RollingUpdateType: Immutable aws:elasticbeanstalk:command: DeploymentPolicy: Immutable ``` The EB CLI and Elastic Beanstalk console apply recommended values for the preceding options. You must remove these settings if you want to use configuration files to configure the same. See [Recommended values](command-options.md#configuration-options-recommendedvalues) for details.