# Managing Elastic Beanstalk environments
This chapter describes how to create and manage your Elastic Beanstalk environments. This introductory page provides an overview of updates, maintenance, and configurations that you'll apply over time as your application and environment evolve.
**Environment functions**
You can create and manage separate environments for development, testing, and production use, and you can [deploy any version](using-features.deploy-existing-version.md) of your application to any environment. Environments can be long-running or temporary. When you terminate an environment, you can save its configuration to recreate it later.
**Application deployments**
As you develop your application, you will deploy it often, possibly to several different environments for different purposes. Elastic Beanstalk lets you [configure how deployments are performed](using-features.rolling-version-deploy.md). You can deploy to all of the instances in your environment simultaneously, or split a deployment into batches with rolling deployments.
**Configuration changes**
[Configuration changes](environments-updating.md) are processed separately from deployments, and have their own scope. For example, if you change the type of the EC2 instances running your application, all of the instances must be replaced. On the other hand, if you modify the configuration of the environment's load balancer, that change can be made in-place without interrupting service or lowering capacity. You can also apply configuration changes that modify the instances in your environment in batches with [rolling configuration updates](using-features.rollingupdates.md).
**Note**
Modify the resources in your environment only by using Elastic Beanstalk. If you modify resources using another service's console, CLI commands, or SDKs, Elastic Beanstalk won't be able to accurately monitor the state of those resources, and you won't be able to save the configuration or reliably recreate the environment. Out-of band-changes can also cause issues when updating or terminating an environment.
**Platform updates**
When you launch an environment, you choose a platform version. We update platforms periodically with new platform versions to provide performance improvements and new features. You can [update your environment to the latest platform version](using-features.platform.upgrade.md) at any time. See the *AWS Elastic Beanstalk Platforms* guide for a list of [supported platforms](https://docs.aws.amazon.com/elasticbeanstalk/latest/platforms/platforms-supported.html) and a [platform version history](https://docs.aws.amazon.com/elasticbeanstalk/latest/platforms/platform-history.html) that includes the date ranges they were current.
**Architecture options**
As your application grows in complexity, you can split it into multiple components, each running in a separate environment. For long-running workloads, you can launch [worker environments](using-features-managing-env-tiers.md) that process jobs from an Amazon Simple Queue Service (Amazon SQS) queue.
**Topics**
+ [Using the Elastic Beanstalk environment management console](environments-console.md)
+ [Creating an Elastic Beanstalk environment](using-features.environments.md)
+ [Managing multiple Elastic Beanstalk environments as a group with the EB CLI](ebcli-compose.md)
+ [Deploying applications to Elastic Beanstalk environments](using-features.deploy-existing-version.md)
+ [Configuration changes](environments-updating.md)
+ [Updating your Elastic Beanstalk environment's platform version](using-features.platform.upgrade.md)
+ [Canceling environment configuration updates and application deployments](using-features.rollingupdates.cancel.md)
+ [Rebuilding Elastic Beanstalk environments](environment-management-rebuild.md)
+ [Environment types](using-features-managing-env-types.md)
+ [Elastic Beanstalk worker environments](using-features-managing-env-tiers.md)
+ [Creating links between Elastic Beanstalk environments](environment-cfg-links.md)
+ [Recovering your Elastic Beanstalk environment from an invalid state](environment-management-invalid-stack.md)
# Using the Elastic Beanstalk environment management console
This section describes how you can manage your Elastic Beanstalk environment using the environment management console. The console provides the capability to manage your environment's configuration and perform common actions. These actions include restarting the web servers running in your environment, cloning your environment, or rebuilding your environment from scratch.
**Topics**
+ [Accessing the environment management console](environments-dashboard.md)
+ [Environment overview pane](environments-dashboard-envoverview.md)
+ [Environment detail](environments-dashboard-tabs.md)
+ [Environment actions](environments-dashboard-actions.md)
# Accessing the environment management console
The following procedure provides steps to launch the environment management console.
If you're already logged in to the Elastic Beanstalk console, you can also launch the environment management page from the [Application management console](applications-console.md). Select an environment from the list to display the management console details for the selected environment.
**To access the environment management 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.
The following image illustrates the environment management console.
![\[Image of the environment management console.\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/environment-overview-v2-margin.png)
The top pane is the **Environment overview** page. It shows top-level information about your environment.
The bottom half of the page displays tabs that provide more detailed information. The **Events** tab displays by default. The pages that are linked to the tabs, are also listed on the left navigation pane under the environment.
The console's navigation pane shows the name of the application that's deployed to the environment, with related application management pages. The environment name is also displayed on the navigation page, followed by the environment management pages. The links listed under the environment name also include **Go to environment** and **Configuration**, in addition to the tabbed pages previously mentioned.
# Environment overview pane
This topic describes the information that the **Environment overview** pane provides. It shows top-level information about your environment and is located on the top half of the environment management console.
The following image displays the **Environment overview** pane.
![\[Images that displays the top half of the Environment Overview page. The status label next to the platform version displays Update.\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/environment-overview-v2-top-part-OK-status.png)
## Health
The overall health of the environment. If the health of your environment degrades, the **View causes** link displays next to the environment health. Select this link to view the **Health** tab with more details.
## Domain
The environment's **Domain**, or URL, is located in the upper portion of the **Environment overview** page, below the environment's **Health**. This is the URL of the web application that the environment is running. You can launch the application be selecting the URL.
## Environment id
The environment ID. This is an internal ID that's generated when the environment is created.
## Application name
The name of the application that is deployed and running on your environment.
## Running version
The name of the application version that is deployed and running on your environment. Choose **Upload and deploy** to upload a [source bundle](applications-sourcebundle.md) and deploy it to your environment. This option creates a new application version.
## Platform
The name of the platform version running on your environment. Typically, this comprises the architecture, operating system (OS), language, and application server (collectively known as the *platform branch*), with a specific platform version number.
If your platform version is not the most recently available, then a status label displays next to it in the **Platform** section. The **Update** label indicates that although the platform version is supported a newer version is available. The platform version may also be labeled as **Deprecated** or **Retired**. Select **Change version** to update your platform branch to a newer version. For more information about the *states* of a platform version, see the *Platform Branch* section in the [Elastic Beanstalk platforms glossary](platforms-glossary.md). The previous image on this page illustrates the **Update** status label for the given platform.
# Environment detail
This topic describes the additional information that the environment management console provides from the left navigation pane and the tabbed pages.
The following image illustrates the environment management console.
![\[Image of the environment management console.\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/environment-overview-v2-margin.png)
The bottom half of the environment management console lists tabs that provide more detailed and varied information about the environment. You can either select the tab page or the page label from the left navigation pane.
From the left navigation pane of the console under the environment name, there are two choices that are not in the tabbed pages. These are **Go to environment** and **Configuration**.
**Note**
Select **Go to environment** to launch your application.
## Configuration
Use the **Configuration** page on the left navigation pane to view and update current configuration settings for your environment and its resources. This includes networking configuration, database configuration, load balancing, notifications, health monitoring settings, managed platform update configuration, deployment configuration, instance log streaming, CloudWatch integration, AWS X-Ray, proxy server settings, environment properties, and platform specific options. Use the settings on this page to customize the behavior of your environment during deployments, enable additional features, and modify the instance type and other settings that you chose during environment creation.
For more information, see [Configuring Elastic Beanstalk environments](customize-containers.md).
## Events
The **Events** page shows the event stream for your environment. Elastic Beanstalk outputs event messages whenever you interact with the environment, and when any of your environment's resources are created or modified as a result.
For more information, see [Viewing an Elastic Beanstalk environment's event stream](using-features.events.md).
## Health
If enhanced health monitoring is enabled, this page lists the EC2 instances in your environment and the live health information for each instance.
The **Overall health** page shows health data as an average for all of your environment’s instances combined.
The **Enhanced instance health** pane shows live health information for each individual EC2 instance in your environment. Enhanced health monitoring enables Elastic Beanstalk to closely monitor the resources in your environment so that it can assess the health of your application more accurately.
When enhanced health monitoring is enabled, this page shows information about the requests served by the instances in your environment and metrics from the operating system, including latency, load, and CPU utilization.
For more information, see [Enhanced health reporting and monitoring in Elastic Beanstalk](health-enhanced.md).
## Logs
The **Logs** page lets you retrieve logs from the EC2 instances in your environment. When you request logs, Elastic Beanstalk sends a command to the instances, which then upload logs to your Elastic Beanstalk storage bucket in Amazon S3. When you request logs on this page, Elastic Beanstalk automatically deletes them from Amazon S3 after 15 minutes.
You can also configure your environment's instances to upload logs to Amazon S3 for permanent storage after they have been rotated locally.
For more information, see [Viewing logs from Amazon EC2 instances in your Elastic Beanstalk environment](using-features.logging.md).
## Monitoring
The **Monitoring** page shows an overview of health information for your environment. This includes the default set of metrics provided by Elastic Load Balancing and Amazon EC2, and graphs that show how the environment's health has changed over time.
For more information, see [Monitoring environment health in the AWS management console](environment-health-console.md).
## Alarms
The **Existing alarms** page shows information about any alarms that you have configured for your environment. You can use the options on this page to create or delete alarms.
For more information, see [Manage alarms](using-features.alarms.md).
## Managed updates
The **Managed updates** page shows information about upcoming and completed managed platform updates and instance replacement.
The managed update feature lets you configure your environment to update to the latest platform version automatically during a weekly maintenance window that you choose. In between platform releases, you can choose to have your environment replace all of its Amazon EC2 instances during the maintenance window. This can alleviate issues that occur when your application runs for extended periods of time.
For more information, see [Managed platform updates](environment-platform-update-managed.md).
## Tags
The **Tags** page shows the tags that Elastic Beanstalk applied to the environment when you created it, and any tags that you added. You can add, edit, and delete custom tags. You can't edit or delete the tags that Elastic Beanstalk applied.
Environment tags are applied to every resource that Elastic Beanstalk creates to support your application.
For more information, see [Tagging resources in your Elastic Beanstalk environments](using-features.tagging.md).
# Environment actions
This topic describes the common operations that you can select to perform on your environment from the **Actions** drop-down menu on the environment management console.
The following image illustrates the environment management console. The **Actions** drop-down menu is on the right side of the header that displays the environment name, next to the **Refresh** button.
![\[Image of the environment management console showing the Actions drop-down menu.\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/environment-overview-v2-margin.png)
**Note**
Some actions are only available under certain conditions, remaining disabled until the right conditions are met.
## Load configuration
Load a previously saved configuration. Configurations are saved to your application and can be loaded by any associated environment. If you've made changes to your environment's configuration, you can load a saved configuration to undo those changes. You can also load a configuration that you saved from a different environment running the same application to propagate configuration changes between them.
## Save configuration
Save the current configuration of your environment to your application. Before you make changes to your environment's configuration, save the current configuration so that you can roll back later, if needed. You can also apply a saved configuration when you launch a new environment.
## Swap environment Domains (URLs)
Swap the CNAME of the current environment with a new environment. After a CNAME swap, all traffic to the application using the environment URL goes to the new environment. When you are ready to deploy a new version of your application, you can launch a separate environment under the new version. When the new environment is ready to start taking requests, perform a CNAME swap to start routing traffic to the new environment. Doing this doesn't interrupt your services. For more information, see [Blue/Green deployments with Elastic Beanstalk](using-features.CNAMESwap.md).
## Clone environment
Launch a new environment with the same configuration as your currently running environment.
## Clone with latest platform
Clone your current environment with the latest version of the in-use Elastic Beanstalk platform. This option is available only when a newer version of the current environment's platform is available for use.
## Abort current operation
Stop an in-progress environment update. Stopping an operation can cause some of the instances in your environment to be in a different state than others, depending on how far the operation progressed. This option is available only when your environment is being updated.
## Restart app servers
Restart the web server that is running on your environment's instances. This option doesn't terminate or restart any AWS resources. If your environment is acting strangely in response to some bad requests, restarting the application server can restore functionality temporarily while you troubleshoot the root cause.
## Rebuild environment
Terminate all resources in the running environment and build a new environment with the same settings. This operation takes several minutes, similar to the amount of time needed for deploying a new environment from scratch. Any Amazon RDS instances that are running in your environment's data tier are deleted during a rebuild. If you need the data, create a snapshot. You can create a snapshot manually [in the RDS console](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_CreateSnapshot.html) or configure your data tier's Deletion Policy to create a snapshot automatically before deleting the instance. This is the default setting when you create a data tier.
## Terminate environment
Terminate all resources in the running environment and remove the environment from the application. If you have an RDS instance that is running in a data tier and you need to retain its data, make sure the *database deletion policy* is set to either `Snapshot` or `Retain`. For more information, see [Database lifecycle](using-features.managing.db.md#environments-cfg-rds-lifecycle) in the *Configuring environments* chapter of this guide.
# Creating an Elastic Beanstalk environment
The following procedure launches a new environment running the default application. These steps are simplified to get your environment up and running quickly, using default option values.
**Note about permissions**
Creating an environment requires the permissions in the Elastic Beanstalk full access managed policy. See [Elastic Beanstalk user policy](concepts-roles-user.md) for details.
**To launch an environment with an application (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 **Applications**. Select an existing application in the list. You can also choose to create one, following the instructions in [Managing applications](applications.md).
1. On the application overview page, choose **Create environment**.
This launches the **Create environment** wizard. The wizard provides a set of steps for you to create a new environment.
1. For **Environment tier**, choose the **Web server environment** or **Worker environment** [environment tier](concepts.md#concepts-tier). You can't change an environment's tier after creation.
**Note**
The [.NET on Windows Server platform](create_deploy_NET.md) doesn't support the worker environment tier.
The **Application information** fields default, based on the application that you previously chose.
In the **Environment information** grouping the **Environment name** defaults, based on the application name. If you prefer a different environment name you can enter another value in the field. You can optionally enter a **Domain** name; otherwise Elastic Beanstalk autogenerates a value. You can also optionally enter an **Environment description.**
1. For **Platform**, select the platform and platform branch that match the language your application uses.
**Note**
Elastic Beanstalk supports multiple [versions](concepts.platforms.md) for most of the platforms that are listed. By default, the console selects the recommended version for the platform and platform branch you choose. If your application requires a different version, you can select it here. For information about supported platform versions, see [Elastic Beanstalk supported platforms](concepts.platforms.md).
1. For **Application code**, you have several choices to proceed.
+ To launch the default sample application without supplying the source code, choose **Sample application**. This action chooses the single page application that Elastic Beanstalk provides for the platform you previously selected.
+ If you downloaded a sample application from this guide, or you have your own source code for an application, do the following steps.
1. Select **Upload your code**.
1. Next choose **Local file**, then under **Upload application**, select **Choose file**.
1. Your client machine's operating system will present you with an interface to select the local file that you downloaded. Select the source bundle file and continue.
1. Your choice for **Presets** depends on your purpose for the environment.
+ If you're creating a sample environment to learn about Elastic Beanstalk or a development environment, choose **Single instance (free tier eligible)**.
+ If you're creating a production environment or an environment to learn more about load balancing, choose one of the **High availability** options.
1. Choose **Next**.
**To configure service access**
Next, you need two roles. A *service role* allows Elastic Beanstalk to monitor your EC2 instances and upgrade you environment’s platform. An *EC2 instance profile* role permits tasks such as writing logs and interacting with other services.
**To create or select the Service role**
1. If you have previously created a **Service role** and would like to choose an existing one, select the value from the **Service role** drop-down and skip the remainder of these steps to create a Service role.
1. If you don't see any values listed for **Service role**, or you'd like to create a new one, continue with the next steps.
1. For **Service role**, choose **Create role**.
1. For **Trusted entity type**, choose **AWS service**.
1. For **Use case**, choose **Elastic Beanstalk – Environment**.
1. Choose **Next**.
1. Verify that **Permissions policies** include the following, then choose **Next**:
+ `AWSElasticBeanstalkEnhancedHealth`
+ `AWSElasticBeanstalkManagedUpdatesCustomerRolePolicy`
1. Choose **Create role**.
1. Return to the **Configure service access** tab, refresh the list, then select the newly created service role.
**To create or select an EC2 instance profile**
1. If you have previously created an **EC2 instance profile** and would like to choose an existing one, select the value from the **EC2 instance profile** drop-down and skip the remainder of these steps to create an EC2 instance profile.
1. If you don't see any values listed for **EC2 instance profile**, or you'd like to create a new one, continue with the next steps.
1. Choose **Create role**.
1. For **Trusted entity type**, choose **AWS service**.
1. For **Use case**, choose** Elastic Beanstalk – Compute**.
1. Choose **Next**.
1. Verify that **Permissions policies** include the following, then choose **Next**:
+ `AWSElasticBeanstalkWebTier`
+ `AWSElasticBeanstalkWorkerTier`
+ `AWSElasticBeanstalkMulticontainerDocker`
1. Choose **Create role**.
1. Return to the **Configure service access** tab, refresh the list, then select the newly created EC2 instance profile.
**To finish configuring and creating your application**
1. (Optional) If you previously created an EC2 key pair, you can select it from the **EC2 key pair** field dropdown. You would use it to securely log in to the Amazon EC2 instance that Elastic Beanstalk provisions for your application. If you skip this step, you can always create and assign an EC2 key pair after the environment is created. For more information, see [EC2 key pair](using-features.managing.security.md#using-features.managing.security.keypair).
1. Choose **Skip to Review** on the **Configure service access** page.
1. The **Review** page displays a summary of all your choices.
To further customize your environment, choose **Edit** next to the step that includes any items you want to configure. You can set the following options only during environment creation:
+ Environment name
+ Domain name
+ Platform version
+ Processor
+ Load balancer type
+ Tier
You can change the following settings after environment creation, but they require new instances or other resources to be provisioned and can take a long time to apply:
+ Instance type, root volume, key pair, and AWS Identity and Access Management (IAM) role
+ Internal Amazon RDS database
+ VPC
For details on all available settings, see [The create new environment wizard](environments-create-wizard.md).
1. Choose **Submit** at the bottom of the page to initialize the creation of your new environment.
While Elastic Beanstalk creates your environment, you are redirected to the [Elastic Beanstalk console](environments-console.md). When the environment health turns green, choose the URL next to the environment name to view the running application. This URL is generally accessible from the internet unless you configure your environment to use a [custom VPC with an internal load balancer](environments-create-wizard.md#environments-create-wizard-network).
**Topics**
+ [The create new environment wizard](environments-create-wizard.md)
+ [Clone an Elastic Beanstalk environment](using-features.managing.clone.md)
+ [Terminate an Elastic Beanstalk environment](using-features.terminating.md)
+ [Creating Elastic Beanstalk environments with the AWS CLI](environments-create-awscli.md)
+ [Creating Elastic Beanstalk environments with the API](environments-create-api.md)
+ [Constructing a Launch Now URL](launch-now-url.md)
+ [Creating and updating groups of Elastic Beanstalk environments](environment-mgmt-compose.md)
# The create new environment wizard
This topic describes the **Create environment** wizard and all the ways you can use it to configure the environment you want to create.
**Note**
In [Creating an Elastic Beanstalk environment](using-features.environments.md) we show how to launch the **Create environment** wizard and quickly create an environment with default values and recommended settings. This current topic will walk you through all of the options.
## Wizard page
The **Create environment** wizard provides a set of steps for you to create a new environment.
![\[The Create environment wizard on the Elastic Beanstalk console\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/create-new-env-wizard-step01.png)
**Environment tier**
For **environment tier**, choose the **Web server environment** or **Worker environment** [environment tier](concepts.md#concepts-tier). You can't change an environment's tier after creation.
![\[Environment tier section of the environment wizard.\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/step-01-environemnt-tier.png)
**Note**
The [.NET on Windows Server platform](create_deploy_NET.md) doesn't support the worker environment tier.
**Application information**
If you launched the wizard by selecting **Create new environment** from the **Application overview** page, then the **Application name** is prefilled. Otherwise, enter an application name. Optionally, add [application tags](applications-tagging.md).
![\[Application information section of the environment wizard.\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/step-01-application-information.png)
**Environment information**
Set the environment's name and domain, and create a description for your environment. Be aware that these environment settings cannot change after the environment is created.
![\[Environment information section of the environment wizard.\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/step-01-environment-information.png)
+ **Name** – Enter a name for the environment. The form provides a generated name.
+ **Domain** – (web server environments) Enter a unique domain name for your environment. The default name is the environment's name. You can enter a different domain name. Elastic Beanstalk uses this name to create a unique CNAME for the environment. To check whether the domain name you want is available, choose **Check Availability**.
+ **Description** – Enter a description for this environment.
### Select a platform for the new environment
You can create a new environment from two types of platforms:
+ Managed platform
+ Custom platform
**Managed platform**
In most cases you use an Elastic Beanstalk managed platform for your new environment. When the new environment wizard starts, it selects the **Managed platform** option by default.
![\[Managed platform option in the create new environment wizard\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/wizard-defaultenvironment.png)
Select a platform, a platform branch within that platform, and a specific platform version in the branch. When you select a platform branch, the recommended version within the branch is selected by default. In addition, you can select any platform version you've used before.
**Note**
For a production environment, we recommend that you choose a platform version in a supported platform branch. For details about platform branch states, see the *Platform Branch* definition in the [Elastic Beanstalk platforms glossary](platforms-glossary.md).
**Custom platform**
If an off-the-shelf platform doesn't meet your needs, you can create a new environment from a custom platform. To specify a custom platform, choose the **Custom platform** option, and then select one of the available custom platforms. If there are no custom platforms available, this option is dimmed.
### Provide application code
Now that you have selected the platform to use, the next step is to provide your application code.
![\[Providing application code in the create new environment wizard of the Elastic Beanstalk console\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/wizard-environment-appcode.png)
You have several options:
+ You can use the sample application that Elastic Beanstalk provides for each platform.
+ You can use code that you already deployed to Elastic Beanstalk. Choose **Existing version** and your application in the **Application code** section.
+ You can upload new code. Choose **Upload your code**, and then choose **Upload**. You can upload new application code from a local file, or you can specify the URL for the Amazon S3 bucket that contains your application code.
**Note**
Depending on the platform version you selected, you can upload your application in a ZIP [source bundle](applications-sourcebundle.md), a [WAR file](java-tomcat-platform.md), or a [plaintext Docker configuration](docker.md). The file size limit is 500 MB.
When you choose to upload new code, you can also provide tags to associate with your new code. For more information about tagging an application version, see [Tagging application versions](applications-versions-tagging.md).
![\[Uploading new application code in the create new environment wizard of the Elastic Beanstalk console\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/wizard-environment-appcode-upload.png)
For quick environment creation using default configuration options, you can now choose **Create environment**. Choose **Configure more options** to make additional configuration changes, as described in the following sections.
## Wizard configuration page
When you choose **Configure more options**, the wizard shows the **Configure** page. On this page you can select a configuration preset, change the platform version you want your environment to use, or make specific configuration choices for the new environment.
### Choose a preset configuration
On the **Presets** section of the page, Elastic Beanstalk provides several configuration presets for different use cases. Each preset includes recommended values for several [configuration options](command-options.md).
![\[Configuration presets section in the configuration page of the create new environment wizard\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/wizard-presets.png)
The **High availability** presets include a load balancer, and are recommended for production environments. Choose them if you want an environment that can run multiple instances for high availability and scale in response to load. The **Single instance** presets are primarily recommended for development. Two of the presets enable Spot Instance requests. For details about Elastic Beanstalk capacity configuration, see [Auto Scaling group](using-features.managing.as.md).
The last preset, **Custom configuration**, removes all recommended values except role settings and uses the API defaults. Choose this option if you are deploying a source bundle with [configuration files](ebextensions.md) that set configuration options. **Custom configuration** is also selected automatically if you modify either the **Low cost** or **High availability** configuration presets.
### Customize your configuration
In addition to (or instead of) choosing a configuration preset, you can fine-tune [configuration options](command-options.md) in your environment. The **Configure** wizard wizard shows several configuration categories. Each configuration category displays a summary of values for a group of configuration settings. Choose **Edit** to edit this group of settings.
**Topics**
+ [Software settings](#environments-create-wizard-software)
+ [Instances](#environments-create-wizard-instances)
+ [Capacity](#environments-create-wizard-capacity)
+ [Load balancer](#environments-create-wizard-loadbalancer)
+ [Rolling updates and deployments](#environments-create-wizard-deployment-settings)
+ [Security](#environments-create-wizard-security)
+ [Monitoring](#environments-create-wizard-monitoring)
+ [Managed updates](#environments-create-wizard-managed)
+ [Notifications](#environments-create-wizard-notifications)
+ [Network](#environments-create-wizard-network)
+ [Database](#environments-create-wizard-database)
+ [Tags](#environments-create-wizard-tags)
+ [Worker environment](#environments-create-wizard-worker)
#### Software settings
Use the **Modify software** configuration page to configure the software on the Amazon Elastic Compute Cloud (Amazon EC2) instances that run your application. You can configure environment properties, AWS X-Ray debugging, instance log storing and streaming, and platform-specific settings. For details, see [Environment variables and other software settings](environments-cfg-softwaresettings.md).
![\[Modify software configuration page\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/wizard-software.png)
#### Instances
Use the **Modify instances** configuration page to configure the Amazon EC2 instances that run your application. For details, see [The Amazon EC2 instances for your Elastic Beanstalk environment](using-features.managing.ec2.md).
![\[Modify instances configuration page\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/wizard-instances.png)
#### Capacity
Use the **Modify capacity** configuration page to configure the compute capacity of your environment and **Auto Scaling group** settings to optimize the number and type of instances you're using. You can also change your environment capacity based on triggers or on a schedule.
A load-balanced environment can run multiple instances for high availability and prevent downtime during configuration updates and deployments. In a load-balanced environment, the domain name maps to the load balancer. In a single-instance environment, it maps to an elastic IP address on the instance.
**Warning**
A single-instance environment isn't production ready. If the instance becomes unstable during deployment, or Elastic Beanstalk terminates and restarts the instance during a configuration update, your application can be unavailable for a period of time. Use single-instance environments for development, testing, or staging. Use load-balanced environments for production.
For more information about environment capacity settings, see [Auto Scaling your Elastic Beanstalk environment instances](using-features.managing.as.md) and [The Amazon EC2 instances for your Elastic Beanstalk environment](using-features.managing.ec2.md).
![\[Modify capacity configuration page\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/wizard-capacity.png)
#### Load balancer
Use the **Modify load balancer** configuration page to select a load balancer type and to configure settings for it. In a load-balanced environment, your environment's load balancer is the entry point for all traffic headed for your application. Elastic Beanstalk supports several types of load balancer. By default, the Elastic Beanstalk console creates an Application Load Balancer and configures it to serve HTTP traffic on port 80.
**Note**
You can only select your environment's load balancer type during environment creation.
For more information about load balancer types and settings, see [Load balancer for your Elastic Beanstalk environment](using-features.managing.elb.md) and [Configuring HTTPS for your Elastic Beanstalk environment](configuring-https.md).
![\[Load balancer configuration during environment creation\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/wizard-elb.png)
**Note**
The Classic Load Balancer (CLB) option is disabled on the **Create Environment** console wizard. If you have an existing environment configured with a Classic Load Balancer you can create a new one by [cloning the existing environment](using-features.managing.clone.md) using either the Elastic Beanstalk console or the [EB CLI](using-features.managing.clone.md#using-features.managing.clone.CLI). You also have the option to use the EB CLI or the [AWS CLI](environments-create-awscli.md) to create a new environment configured with a Classic Load Balancer. These command line tools will create a new environment with a CLB even if one doesn’t already exist in your account.
#### Rolling updates and deployments
Use the **Modify rolling updates and deployments** configuration page to configure how Elastic Beanstalk processes application deployments and configuration updates for your environment.
Application deployments happen when you upload an updated application source bundle and deploy it to your environment. For more information about configuring deployments, see [Deployment policies and settings](using-features.rolling-version-deploy.md).
![\[Application deployments section in the modify rolling updates and deployments configuration page\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/environment-cfg-rollingdeployments.png)
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 more information about setting the update type and other options, see [Configuration changes](environments-updating.md).
![\[Configuration updates section in the modify rolling updates and deployments configuration page\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/aeb-config-rolling-updates-health.png)
#### Security
Use the **Configure service access** page to configure service and instance security settings.
For a description of Elastic Beanstalk security concepts, see [Elastic Beanstalk Service roles, instance profiles, and user policies](concepts-roles.md).
The first time you create an environment in the Elastic Beanstalk console, you must create an EC2 instance profile with a default set of permissions. If the **EC2 instance profile** dropdown list doesn't show any values to choose from, expand the procedure that follows. It provides steps to create a Role that you can subsequently select for the **EC2 instance profile**.
##### Create IAM Role for EC2 instance profile
**To create or select an EC2 instance profile**
1. If you have previously created an **EC2 instance profile** and would like to choose an existing one, select the value from the **EC2 instance profile** drop-down and skip the remainder of these steps to create an EC2 instance profile.
1. If you don't see any values listed for **EC2 instance profile**, or you'd like to create a new one, continue with the next steps.
1. Choose **Create role**.
1. For **Trusted entity type**, choose **AWS service**.
1. For **Use case**, choose** Elastic Beanstalk – Compute**.
1. Choose **Next**.
1. Verify that **Permissions policies** include the following, then choose **Next**:
+ `AWSElasticBeanstalkWebTier`
+ `AWSElasticBeanstalkWorkerTier`
+ `AWSElasticBeanstalkMulticontainerDocker`
1. Choose **Create role**.
1. Return to the **Configure service access** tab, refresh the list, then select the newly created EC2 instance profile.
![\[Configure service access\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/configure-service-access.png)
#### Monitoring
Use the **Modify monitoring** configuration page to configure health reporting, monitoring rules, and health event streaming. For details, see [Enabling Elastic Beanstalk enhanced health reporting](health-enhanced-enable.md), [Configuring enhanced health rules for an environment](health-enhanced-rules.md), and [Streaming Elastic Beanstalk environment health information to Amazon CloudWatch Logs](AWSHowTo.cloudwatchlogs.envhealth.md).
![\[Modify monitoring configuration page\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/wizard-monitoring.png)
#### Managed updates
Use the **Modify managed updates** configuration page to configure managed platform updates. You can decide if you want them enabled, set the schedule, and configure other properties. For details, see [Managed platform updates](environment-platform-update-managed.md).
![\[Modify managed updates configuration page\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/wizard-managed-updates.png)
#### Notifications
Use the **Modify notifications** configuration page to specify an email address to receive [email notifications](using-features.managing.sns.md) for important events from your environment.
![\[Modify notifications configuration page\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/wizard-notifications.png)
#### Network
If you have created a [custom VPC](using-features.managing.vpc.md), the **Modify network** configuration page to configure your environment to use it. If you don't choose a VPC, Elastic Beanstalk uses the default VPC and subnets.
![\[Modify network configuration page\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/wizard-network.png)
#### Database
Use the **Modify database** configuration page to add an Amazon Relational Database Service (Amazon RDS) database to your environment for development and testing. Elastic Beanstalk provides connection information to your instances by setting environment properties for the database hostname, user name, password, table name, and port.
For details, see [Adding a database to your Elastic Beanstalk environment](using-features.managing.db.md).
![\[Modify database configuration page\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/wizard-database.png)
#### Tags
Use the **Modify tags** configuration page to add [tags](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html) to the resources in your environment. For more information about environment tagging, see [Tagging resources in your Elastic Beanstalk environments](using-features.tagging.md).
![\[Modify tags configuration page\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/environment-create-tags.png)
#### Worker environment
If you're creating a *worker tier environment*, use the **Modify worker** configuration page to configure the worker environment. The worker daemon on the instances in your environment pulls items from an Amazon Simple Queue Service (Amazon SQS) queue and relays them as post messages to your worker application. You can choose the Amazon SQS queue that the worker daemon reads from (auto-generated or existing). You can also configure the messages that the worker daemon sends to your application.
For more information, see [Elastic Beanstalk worker environments](using-features-managing-env-tiers.md).
![\[Modify worker configuration page\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/wizard-worker.png)
# Clone an Elastic Beanstalk environment
You can use an existing Elastic Beanstalk environment as the basis for a new environment by cloning the existing environment. For example, you might want to create a clone so that you can use a newer version of the platform branch used by the original environment's platform. Elastic Beanstalk configures the clone with the environment settings used by the original environment. By cloning an existing environment instead of creating a new environment, you don't have to manually configure option settings, environment variables, and other settings that you made with the Elastic Beanstalk service. Elastic Beanstalk also creates a copy of any AWS resource associated with the original environment.
It's important to be aware of the following situations:
+ During the cloning process, Elastic Beanstalk doesn't copy data from Amazon RDS to the clone.
+ Elastic Beanstalk doesn't include any unmanaged changes to resources in the clone. Changes to AWS resources that you make using tools other than the Elastic Beanstalk console, command-line tools, or API are considered unmanaged changes.
+ The security groups for ingress are considered unmanaged changes. Cloned Elastic Beanstalk environments do not carry over the security groups for ingress, leaving the environment open to all internet traffic. You’ll need to reestablish ingress security groups for the cloned environment.
You can only clone an environment to a different platform version of the same platform branch. A different platform branch isn't guaranteed to be compatible. To use a different platform branch, you have to manually create a new environment, deploy your application code, and make any necessary changes in code and options to ensure your application works correctly on the new platform branch.
## AWS management console
**Important**
Cloned Elastic Beanstalk environments do not carry over the security groups for ingress, leaving the environment open to all internet traffic. You’ll need to reestablish ingress security groups for the cloned environment.
You can see resources that may not be cloned by checking the drift status of your environment configuration. For more information, see [Detect drift on an entire CloudFormation stack ](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/detect-drift-stack.html) in the *AWS CloudFormation User Guide*.
**To clone an environment**
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. On the environment overview page, choose **Actions**.
1. Choose **Clone environment**.
1. On the **Clone environment** page, review the information in the **Original Environment** section to verify that you chose the environment from which you want to create a clone.
1. In the **New Environment** section, you can optionally change the **Environment name**, **Environment URL**, **Description**, **Platform version**, and **Service role** values that Elastic Beanstalk automatically set based on the original environment.
**Note**
If the platform version used in the original environment isn't the one recommended for use in the platform branch, you are warned that a different platform version is recommended. Choose **Platform version**, and you can see the recommended platform version on the list—for example, **3.3.2 (Recommended)**.
1. When you are ready, choose **Clone**.
## Elastic Beanstalk command line interface (EB CLI)
**Important**
Cloned Elastic Beanstalk environments do not carry over the security groups for ingress, leaving the environment open to all internet traffic. You’ll need to reestablish ingress security groups for the cloned environment.
You can see resources that may not be cloned by checking the drift status of your environment configuration. For more information, see [Detect drift on an entire CloudFormation stack ](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/detect-drift-stack.html) in the *AWS CloudFormation User Guide*.
Use the **eb clone** command to clone a running environment, as follows.
```
~/workspace/my-app$ eb clone my-env1
Enter name for Environment Clone
(default is my-env1-clone): my-env2
Enter DNS CNAME prefix
(default is my-env1-clone): my-env2
```
You can specify the name of the source environment in the clone command, or leave it out to clone the default environment for the current project folder. The EB CLI prompts you to enter a name and DNS prefix for the new environment.
By default, **eb clone** creates the new environment with the latest available version of the source environment's platform. To force the EB CLI to use the same version, even if there is a newer version available, use the `--exact` option.
```
~/workspace/my-app$ eb clone --exact
```
For more information about this command, see [eb clone](eb3-clone.md).
# Terminate an Elastic Beanstalk environment
You can terminate a running AWS Elastic Beanstalk environment using the Elastic Beanstalk console. By doing this, you avoid incurring charges for unused AWS resources.
**Note**
You can always launch a new environment using the same version later.
If you have data from an environment that you want to preserve, set the database deletion policy to `Retain` before terminating the environment. This keeps the database operational outside of Elastic Beanstalk. After this, any Elastic Beanstalk environments must connect to it as an external database. If you want to back up the data without keeping the database operational, set the deletion policy to take a snapshot of the database before terminating the environment. For more information, see [Database lifecycle](using-features.managing.db.md#environments-cfg-rds-lifecycle) in the *Configuring environments* chapter of this guide.
Elastic Beanstalk might fail to terminate your environment. One common reason is that the security group of another environment has a dependency on the security group of the environment that you want to terminate. For instructions on how to avoid this problem, see [EC2 security groups](using-features.managing.ec2.console.md#using-features.managing.ec2.securitygroups) on the *EC2 Instances* page of this guide.
**Important**
If you terminate an environment, you must also delete any CNAME mappings that you created, as other customers can reuse an available hostname. Be sure to delete DNS records that point to your terminated environment to prevent a *dangling DNS entry*. A dangling DNS entry can expose internet traffic destined for your domain to security vulnerabilities. It can also present other risks.
For more information, see [Protection from dangling delegation records in Route 53](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/protection-from-dangling-dns.html) in the *Amazon Route 53 Developer Guide*. You can also learn more about dangling DNS entries in [Enhanced Domain Protections for Amazon CloudFront Requests](https://aws.amazon.com/blogs/security/enhanced-domain-protections-for-amazon-cloudfront-requests/) in the *AWS Security Blog*.
## Elastic Beanstalk console
**To terminate an environment**
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. Choose **Actions**, and then choose **Terminate environment**.
1. Use the on-screen dialog box to confirm environment termination.
**Note**
When you terminate your environment, the CNAME that's associated with the terminated environment is freed up to be used by anyone.
It takes a few minutes for Elastic Beanstalk to terminate the AWS resources that are running in the environment.
## AWS CLI
**To terminate an environment**
+ Run the following command.
```
$ aws elasticbeanstalk terminate-environment --environment-name my-env
```
## API
**To terminate an environment**
+ Call `TerminateEnvironment` with the following parameter:
`EnvironmentName` = `SampleAppEnv`
```
1. https://elasticbeanstalk.us-west-2.amazon.com/?EnvironmentName=SampleAppEnv
2. &Operation=TerminateEnvironment
3. &AuthParams
```
# Creating Elastic Beanstalk environments with the AWS CLI
For details about the AWS CLI commands for Elastic Beanstalk, see the [AWS CLI Command Reference](https://docs.aws.amazon.com/cli/latest/reference/elasticbeanstalk).
1. Check if the CNAME for the environment is available.
```
$ aws elasticbeanstalk check-dns-availability --cname-prefix my-cname
{
"Available": true,
"FullyQualifiedCNAME": "my-cname.elasticbeanstalk.com"
}
```
1. Make sure your application version exists.
```
$ aws elasticbeanstalk describe-application-versions --application-name my-app --version-label v1
```
If you don't have an application version for your source yet, create it. For example, the following command creates an application version from a source bundle in Amazon Simple Storage Service (Amazon S3).
```
$ aws elasticbeanstalk create-application-version --application-name my-app --version-label v1 --source-bundle S3Bucket=amzn-s3-demo-bucket,S3Key=my-source-bundle.zip
```
1. Create a configuration template for the application.
```
$ aws elasticbeanstalk create-configuration-template --application-name my-app --template-name v1 --solution-stack-name "64bit Amazon Linux 2015.03 v2.0.0 running Ruby 2.2 (Passenger Standalone)"
```
1. Create environment.
```
$ aws elasticbeanstalk create-environment --cname-prefix my-cname --application-name my-app --template-name v1 --version-label v1 --environment-name v1clone --option-settings file://options.txt
```
Option Settings are defined in the **options.txt** file:
```
[
{
"Namespace": "aws:autoscaling:launchconfiguration",
"OptionName": "IamInstanceProfile",
"Value": "aws-elasticbeanstalk-ec2-role"
}
]
```
The above option setting defines the IAM instance profile. You can specify the ARN or the profile name.
1. Determine if the new environment is Green and Ready.
```
$ aws elasticbeanstalk describe-environments --environment-names my-env
```
If the new environment does not come up Green and Ready, you should decide if you want to retry the operation or leave the environment in its current state for investigation. Make sure to terminate the environment after you are finished, and clean up any unused resources.
**Note**
You can adjust the timeout period if the environment doesn't launch in a reasonable time.
# Creating Elastic Beanstalk environments with the API
1. Call `CheckDNSAvailability` with the following parameter:
+ `CNAMEPrefix` = `SampleApp`
**Example**
```
1. https://elasticbeanstalk.us-east-2.amazonaws.com/?CNAMEPrefix=sampleapplication
2. &Operation=CheckDNSAvailability
3. &AuthParams
```
1. Call `DescribeApplicationVersions` with the following parameters:
+ `ApplicationName` = `SampleApp`
+ `VersionLabel` = `Version2`
**Example**
```
1. https://elasticbeanstalk.us-east-2.amazonaws.com/?ApplicationName=SampleApp
2. &VersionLabel=Version2
3. &Operation=DescribeApplicationVersions
4. &AuthParams
```
1. Call `CreateConfigurationTemplate` with the following parameters:
+ `ApplicationName` = `SampleApp`
+ `TemplateName` = `MyConfigTemplate`
+ `SolutionStackName` = `64bit%20Amazon%20Linux%202015.03%20v2.0.0%20running%20Ruby%202.2%20(Passenger%20Standalone)`
**Example**
```
1. https://elasticbeanstalk.us-east-2.amazonaws.com/?ApplicationName=SampleApp
2. &TemplateName=MyConfigTemplate
3. &Operation=CreateConfigurationTemplate
4. &SolutionStackName=64bit%20Amazon%20Linux%202015.03%20v2.0.0%20running%20Ruby%202.2%20(Passenger%20Standalone)
5. &AuthParams
```
1. Call `CreateEnvironment` with one of the following sets of parameters.
1. Use the following for a web server environment tier:
+ `EnvironmentName` = `SampleAppEnv2`
+ `VersionLabel` = `Version2`
+ `Description` = `description`
+ `TemplateName` = `MyConfigTemplate`
+ `ApplicationName` = `SampleApp`
+ `CNAMEPrefix` = `sampleapplication`
+ `OptionSettings.member.1.Namespace` = `aws:autoscaling:launchconfiguration`
+ `OptionSettings.member.1.OptionName` = `IamInstanceProfile`
+ `OptionSettings.member.1.Value` = `aws-elasticbeanstalk-ec2-role`
**Example**
```
1. https://elasticbeanstalk.us-east-2.amazonaws.com/?ApplicationName=SampleApp
2. &VersionLabel=Version2
3. &EnvironmentName=SampleAppEnv2
4. &TemplateName=MyConfigTemplate
5. &CNAMEPrefix=sampleapplication
6. &Description=description
7. &Operation=CreateEnvironment
8. &OptionSettings.member.1.Namespace=aws%3Aautoscaling%3Alaunchconfiguration
9. &OptionSettings.member.1.OptionName=IamInstanceProfile
10. &OptionSettings.member.1.Value=aws-elasticbeanstalk-ec2-role
11. &AuthParams
```
1. Use the following for a worker environment tier:
+ `EnvironmentName` = `SampleAppEnv2`
+ `VersionLabel` = `Version2`
+ `Description` = `description`
+ `TemplateName` = `MyConfigTemplate`
+ `ApplicationName` = `SampleApp`
+ `Tier` = `Worker`
+ `OptionSettings.member.1.Namespace` = `aws:autoscaling:launchconfiguration`
+ `OptionSettings.member.1.OptionName` = `IamInstanceProfile`
+ `OptionSettings.member.1.Value` = `aws-elasticbeanstalk-ec2-role`
+ `OptionSettings.member.2.Namespace` = `aws:elasticbeanstalk:sqsd`
+ `OptionSettings.member.2.OptionName` = `WorkerQueueURL`
+ `OptionSettings.member.2.Value` = `sqsd.elasticbeanstalk.us-east-2.amazonaws.com`
+ `OptionSettings.member.3.Namespace` = `aws:elasticbeanstalk:sqsd`
+ `OptionSettings.member.3.OptionName` = `HttpPath`
+ `OptionSettings.member.3.Value` = `/`
+ `OptionSettings.member.4.Namespace` = `aws:elasticbeanstalk:sqsd`
+ `OptionSettings.member.4.OptionName` = `MimeType`
+ `OptionSettings.member.4.Value` = `application/json`
+ `OptionSettings.member.5.Namespace` = `aws:elasticbeanstalk:sqsd`
+ `OptionSettings.member.5.OptionName` = `HttpConnections`
+ `OptionSettings.member.5.Value` = `75`
+ `OptionSettings.member.6.Namespace` = `aws:elasticbeanstalk:sqsd`
+ `OptionSettings.member.6.OptionName` = `ConnectTimeout`
+ `OptionSettings.member.6.Value` = `10`
+ `OptionSettings.member.7.Namespace` = `aws:elasticbeanstalk:sqsd`
+ `OptionSettings.member.7.OptionName` = `InactivityTimeout`
+ `OptionSettings.member.7.Value` = `10`
+ `OptionSettings.member.8.Namespace` = `aws:elasticbeanstalk:sqsd`
+ `OptionSettings.member.8.OptionName` = `VisibilityTimeout`
+ `OptionSettings.member.8.Value` = `60`
+ `OptionSettings.member.9.Namespace` = `aws:elasticbeanstalk:sqsd`
+ `OptionSettings.member.9.OptionName` = `RetentionPeriod`
+ `OptionSettings.member.9.Value` = `345600`
**Example**
```
1. https://elasticbeanstalk.us-east-2.amazonaws.com/?ApplicationName=SampleApp
2. &VersionLabel=Version2
3. &EnvironmentName=SampleAppEnv2
4. &TemplateName=MyConfigTemplate
5. &Description=description
6. &Tier=Worker
7. &Operation=CreateEnvironment
8. &OptionSettings.member.1.Namespace=aws%3Aautoscaling%3Alaunchconfiguration
9. &OptionSettings.member.1.OptionName=IamInstanceProfile
10. &OptionSettings.member.1.Value=aws-elasticbeanstalk-ec2-role
11. &OptionSettings.member.2.Namespace=aws%3Aelasticbeanstalk%3Asqsd
12. &OptionSettings.member.2.OptionName=WorkerQueueURL
13. &OptionSettings.member.2.Value=sqsd.elasticbeanstalk.us-east-2.amazonaws.com
14. &OptionSettings.member.3.Namespace=aws%3elasticbeanstalk%3sqsd
15. &OptionSettings.member.3.OptionName=HttpPath
16. &OptionSettings.member.3.Value=%2F
17. &OptionSettings.member.4.Namespace=aws%3Aelasticbeanstalk%3Asqsd
18. &OptionSettings.member.4.OptionName=MimeType
19. &OptionSettings.member.4.Value=application%2Fjson
20. &OptionSettings.member.5.Namespace=aws%3Aelasticbeanstalk%3Asqsd
21. &OptionSettings.member.5.OptionName=HttpConnections
22. &OptionSettings.member.5.Value=75
23. &OptionSettings.member.6.Namespace=aws%3Aelasticbeanstalk%3Asqsd
24. &OptionSettings.member.6.OptionName=ConnectTimeout
25. &OptionSettings.member.6.Value=10
26. &OptionSettings.member.7.Namespace=aws%3Aelasticbeanstalk%3Asqsd
27. &OptionSettings.member.7.OptionName=InactivityTimeout
28. &OptionSettings.member.7.Value=10
29. &OptionSettings.member.8.Namespace=aws%3Aelasticbeanstalk%3Asqsd
30. &OptionSettings.member.8.OptionName=VisibilityTimeout
31. &OptionSettings.member.8.Value=60
32. &OptionSettings.member.9.Namespace=aws%3Aelasticbeanstalk%3Asqsd
33. &OptionSettings.member.9.OptionName=RetentionPeriod
34. &OptionSettings.member.9.Value=345600
35. &AuthParams
```
# Constructing a Launch Now URL
You can construct a custom URL so that anyone can quickly deploy and run a predetermined web application in AWS Elastic Beanstalk. This URL is called a Launch Now URL. You might need a Launch Now URL, for example, to demonstrate a web application that's built to run on Elastic Beanstalk. With a Launch Now URL, you can use parameters to add the required information to the Create Application wizard in advance. After you add this information to the wizard, anyone can use the URL link to launch an Elastic Beanstalk environment with your web application source in only a few steps. This means users don't need to manually upload or specify the location of the application source bundle. They also don't need to provide any additional information to the wizard.
A Launch Now URL gives Elastic Beanstalk the minimum information that's required to create an application: the application name, solution stack, instance type, and environment type. Elastic Beanstalk uses default values for other configuration details that aren't explicitly specified in your custom Launch Now URL.
A Launch Now URL uses standard URL syntax. For more information, see [RFC 3986 - Uniform Resource Identifier (URI): Generic Syntax](http://tools.ietf.org/html/rfc3986).
## URL parameters
The URL must contain the following parameters, which are case sensitive:
+ **region** – Specify an AWS Region. For a list of Regions that are supported by Elastic Beanstalk, see [AWS Elastic Beanstalk Endpoints and Quotas](https://docs.aws.amazon.com/general/latest/gr/elasticbeanstalk.html) in the *AWS General Reference*.
+ **applicationName** – Specify the name of your application. Elastic Beanstalk displays the application name in the Elastic Beanstalk console to distinguish it from other applications. By default, the application name also forms the basis of the environment name and environment URL.
+ **platform** – Specify the platform version to use for the environment. Use one of the following methods, then URL-encode your choice:
+ Specify a platform ARN without a version. Elastic Beanstalk selects the latest platform version of the corresponding platform major version. For example, to select the latest Python 3.6 platform version, specify `Python 3.6 running on 64bit Amazon Linux`.
+ Specify the platform name. Elastic Beanstalk selects the latest version of the platform's latest language runtime (for example, `Python`).
For a description of all available platforms and their versions, see [Elastic Beanstalk supported platforms](concepts.platforms.md).
You can use the [AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/userguide/) (AWS CLI) to get a list of all the available platform versions with their respective ARNs. The `list-platform-versions` command lists detailed information about all the available platform versions. Use the `--filters` argument to scope down the list. For example, you can scope the list to only show the platform versions of a specific language.
The following example queries all the Python platform versions, and pipes the output through a series of commands. The result is a list of platform version ARNs (without the `/version` tail), in a human-readable format, without URL encoding.
```
$ aws elasticbeanstalk list-platform-versions --filters 'Type="PlatformName",Operator="contains",Values="Python"' | grep PlatformArn | awk -F '"' '{print $4}' | awk -F '/' '{print $2}'
Preconfigured Docker - Python 3.4 running on 64bit Debian
Preconfigured Docker - Python 3.4 running on 64bit Debian
Python 2.6 running on 32bit Amazon Linux
Python 2.6 running on 32bit Amazon Linux 2014.03
...
Python 3.6 running on 64bit Amazon Linux
```
The following example adds a Perl command to the last example to URL-encode the output.
```
$ aws elasticbeanstalk list-platform-versions --filters 'Type="PlatformName",Operator="contains",Values="Python"' | grep PlatformArn | awk -F '"' '{print $4}' | awk -F '/' '{print $2}' | perl -MURI::Escape -ne 'chomp;print uri_escape($_),"\n"'
Preconfigured%20Docker%20-%20Python%203.4%20running%20on%2064bit%20Debian
Preconfigured%20Docker%20-%20Python%203.4%20running%20on%2064bit%20Debian
Python%202.6%20running%20on%2032bit%20Amazon%20Linux
Python%202.6%20running%20on%2032bit%20Amazon%20Linux%202014.03
...
Python%203.6%20running%20on%2064bit%20Amazon%20Linux
```
A Launch Now URL can optionally contain the following parameters. If you don't include the optional parameters in your Launch Now URL, Elastic Beanstalk uses default values to create and run your application. When you don't include the **sourceBundleUrl** parameter, Elastic Beanstalk uses the default sample application for the specified **platform**.
+ **sourceBundleUrl** – Specify the location of your web application source bundle in URL format. For example, if you uploaded your source bundle to an Amazon S3 bucket, you might specify the value of the **sourceBundleUrl** parameter as `https://amzn-s3-demo-bucket.s3.amazonaws.com/myobject`.
**Note**
You can specify the value of the **sourceBundleUrl** parameter as an HTTP URL, but the user's web browser will convert characters as needed by applying HTML URL encoding.
+ **environmentType** – Specify whether the environment is load balanced and scalable or just a single instance. For more information, see [Environment types](using-features-managing-env-types.md). You can specify either `LoadBalancing` or `SingleInstance` as the parameter value.
+ **tierName** – Specify whether the environment supports a web application that processes web requests or a web application that runs background jobs. For more information, see [Elastic Beanstalk worker environments](using-features-managing-env-tiers.md). You can specify either `WebServer` or `Worker`,
+ **instanceType** – Specify a server with the characteristics (including memory size and CPU power) that are most appropriate to your application. For more information about Amazon EC2 instance families and types, see [Instance types](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-types.html) in the *Amazon EC2 User Guide*. For more information about the available instance types across Regions, see [Available instance types](https://docs.aws.amazon.com//AWSEC2/latest/UserGuide/instance-types.html#AvailableInstanceTypes) in the *Amazon EC2 User Guide*.
+ **withVpc** – Specify whether to create the environment in an Amazon VPC. You can specify either `true` or `false`. For more information about using Elastic Beanstalk with Amazon VPC, see [Using Elastic Beanstalk with Amazon VPC](vpc.md).
+ **withRds** – Specify whether to create an Amazon RDS database instance with this environment. For more information, see [Using Elastic Beanstalk with Amazon RDS](AWSHowTo.RDS.md). You can specify either `true` or `false`.
+ **rdsDBEngine** – Specify the database engine that you want to use for your Amazon EC2 instances in this environment. You can specify `mysql`, `oracle-sel`, `sqlserver-ex`, `sqlserver-web`, or `sqlserver-se`. The default value is `mysql`.
+ **rdsDBAllocatedStorage** – Specify the allocated database storage size in gigabytes (GB). You can specify the following values:
+ **MySQL** – `5` to `1024`. The default is `5`.
+ **Oracle** – `10` to `1024`. The default is `10`.
+ **Microsoft SQL Server Express Edition** – `30`.
+ **Microsoft SQL Server Web Edition** – `30`.
+ **Microsoft SQL Server Standard Edition** – `200`.
+ **rdsDBInstanceClass** – Specify the database instance type. The default value is `db.t2.micro` (`db.m1.large` is for an environment that's not running in an Amazon VPC). For a list of database instance classes that are supported by Amazon RDS, see [DB Instance Class](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Concepts.DBInstanceClass.html) in the * Amazon Relational Database Service User Guide*.
+ **rdsMultiAZDatabase** – Specify whether Elastic Beanstalk needs to create the database instance across multiple Availability Zones. You can specify either `true` or `false`. For more information about multiple Availability Zone deployments with Amazon RDS, see [Regions and Availability Zones](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Concepts.RegionsAndAvailabilityZones.html) in the * Amazon Relational Database Service User Guide*.
+ **rdsDBDeletionPolicy** – Specify whether to delete or snapshot the database instance on environment termination. You can specify either `Delete` or `Snapshot`.
## Example
The following is an example Launch Now URL. After you construct your own, you can give it to your users. For example, you can embed the URL on a webpage or in training materials. When users create an application using the Launch Now URL, the Elastic Beanstalk Create an Application wizard requires no additional input.
```
https://console.aws.amazon.com/elasticbeanstalk/home?region=us-west-2#/newApplication?applicationName=YourCompanySampleApp
&platform=PHP%207.3%20running%20on%2064bit%20Amazon%20Linux&sourceBundleUrl=
http://s3.amazonaws.com/amzn-s3-demo-bucket/myobject&environmentType=SingleInstance&tierName=WebServer
&instanceType=m1.small&withVpc=true&withRds=true&rdsDBEngine=
postgres&rdsDBAllocatedStorage=6&rdsDBInstanceClass=db.m1.small&rdsMultiAZDatabase=
true&rdsDBDeletionPolicy=Snapshot
```
**To use the Launch Now URL**
1. Choose the Launch Now URL.
1. After the Elastic Beanstalk console opens, on the **Create a web app** page, choose **Review and launch** to view the settings that Elastic Beanstalk uses to create the application and launch the environment where the application runs.
1. On the **Configure** page, choose **Create app** to create the application.
# Creating and updating groups of Elastic Beanstalk environments
With the AWS Elastic Beanstalk [ComposeEnvironments](https://docs.aws.amazon.com/elasticbeanstalk/latest/api/API_ComposeEnvironments.html) API, you can create and update groups of Elastic Beanstalk environments within a single application. Each environment in the group can run a separate component of a service-oriented architecture application. The `Compose Environments` API takes a list of application versions and an optional group name. Elastic Beanstalk creates an environment for each application version, or, if the environments already exist, deploys the application versions to them.
Create links between Elastic Beanstalk environments to designate one environment as a dependency of another. When you create a group of environments with the `Compose Environments` API, Elastic Beanstalk creates dependent environments only after their dependencies are up and running. For more information on environment links, see [Creating links between Elastic Beanstalk environments](environment-cfg-links.md).
The `Compose Environments` API uses an [environment manifest](environment-cfg-manifest.md) to store configuration details that are shared by groups of environments. Each component application must have an `env.yaml` configuration file in its application source bundle that specifies the parameters used to create its environment.
`Compose Environments` requires the `EnvironmentName` and `SolutionStack` to be specified in the environment manifest for each component application.
You can use the `Compose Environments` API with the Elastic Beanstalk command line interface (EB CLI), the AWS CLI, or an SDK. See [Managing multiple Elastic Beanstalk environments as a group with the EB CLI](ebcli-compose.md) for EB CLI instructions.
## Using the `Compose Environments` API
For example, you could make an application named `Media Library` that lets users upload and manage images and videos stored in Amazon Simple Storage Service (Amazon S3). The application has a front-end environment, `front`, that runs a web application that lets users upload and download individual files, view their library, and initiate batch processing jobs.
Instead of processing the jobs directly, the front-end application adds jobs to an Amazon SQS queue. The second environment, `worker`, pulls jobs from the queue and processes them. `worker` uses a G2 instance type that has a high-performance GPU, while `front` can run on a more cost-effective generic instance type.
You would organize the project folder, `Media Library`, into separate directories for each component, with each directory containing an environment definition file (`env.yaml`) with the source code for each:
```
~/workspace/media-library
|-- front
| `-- env.yaml
`-- worker
`-- env.yaml
```
The following listings show the `env.yaml` file for each component application.
**`~/workspace/media-library/front/env.yaml`**
```
EnvironmentName: front+
EnvironmentLinks:
"WORKERQUEUE" : "worker+"
AWSConfigurationTemplateVersion: 1.1.0.0
EnvironmentTier:
Name: WebServer
Type: Standard
SolutionStack: 64bit Amazon Linux 2015.09 v2.0.4 running Java 8
OptionSettings:
aws:autoscaling:launchconfiguration:
InstanceType: m4.large
```
**`~/workspace/media-library/worker/env.yaml`**
```
EnvironmentName: worker+
AWSConfigurationTemplateVersion: 1.1.0.0
EnvironmentTier:
Name: Worker
Type: SQS/HTTP
SolutionStack: 64bit Amazon Linux 2015.09 v2.0.4 running Java 8
OptionSettings:
aws:autoscaling:launchconfiguration:
InstanceType: g2.2xlarge
```
After [creating an application version](applications-versions.md) for the front-end (`front-v1`) and worker (`worker-v1`) application components, you call the `Compose Environments` API with the version names. In this example, we use the AWS CLI to call the API.
```
# Create application versions for each component:
~$ aws elasticbeanstalk create-application-version --application-name media-library --version-label front-v1 --process --source-bundle S3Bucket="amzn-s3-demo-bucket",S3Key="front-v1.zip"
{
"ApplicationVersion": {
"ApplicationName": "media-library",
"VersionLabel": "front-v1",
"Description": "",
"DateCreated": "2015-11-03T23:01:25.412Z",
"DateUpdated": "2015-11-03T23:01:25.412Z",
"SourceBundle": {
"S3Bucket": "amzn-s3-demo-bucket",
"S3Key": "front-v1.zip"
}
}
}
~$ aws elasticbeanstalk create-application-version --application-name media-library --version-label worker-v1 --process --source-bundle S3Bucket="amzn-s3-demo-bucket",S3Key="worker-v1.zip"
{
"ApplicationVersion": {
"ApplicationName": "media-library",
"VersionLabel": "worker-v1",
"Description": "",
"DateCreated": "2015-11-03T23:01:48.151Z",
"DateUpdated": "2015-11-03T23:01:48.151Z",
"SourceBundle": {
"S3Bucket": "amzn-s3-demo-bucket",
"S3Key": "worker-v1.zip"
}
}
}
# Create environments:
~$ aws elasticbeanstalk compose-environments --application-name media-library --group-name dev --version-labels front-v1 worker-v1
```
The third call creates two environments, `front-dev` and `worker-dev`. The API creates the names of the environments by concatenating the `EnvironmentName` specified in the `env.yaml` file with the `group name` option specified in the `Compose Environments` call, separated by a hyphen. The total length of these two options and the hyphen must not exceed the maximum allowed environment name length of 23 characters.
The application running in the `front-dev` environment can access the name of the Amazon SQS queue attached to the `worker-dev` environment by reading the `WORKERQUEUE` variable. For more information on environment links, see [Creating links between Elastic Beanstalk environments](environment-cfg-links.md).
# Managing multiple Elastic Beanstalk environments as a group with the EB CLI
You can use the EB CLI to create groups of AWS Elastic Beanstalk environments, each running a separate component of a service-oriented architecture application. The EB CLI manages such groups by using the [ComposeEnvironments](https://docs.aws.amazon.com/elasticbeanstalk/latest/api/API_ComposeEnvironments.html) API.
**Note**
Environment groups are different than multiple containers in a Multicontainer Docker environment. With environment groups, each component of your application runs in a separate Elastic Beanstalk environment, with its own dedicated set of Amazon EC2 instances. Each component can scale separately. With Multicontainer Docker, you combine several components of an application into a single environment. All components share the same set of Amazon EC2 instances, with each instance running multiple Docker containers. Choose one of these architectures according to your application's needs.
For details about Multicontainer Docker, see [Using the ECS managed Docker platform branch in Elastic Beanstalk](create_deploy_docker_ecs.md).
Organize your application components into the following folder structure:
```
~/project-name
|-- component-a
| `-- env.yaml
`-- component-b
`-- env.yaml
```
Each subfolder contains the source code for an independent component of an application that will run in its own environment and an environment definition file named `env.yaml`. For details on the `env.yaml` format, see [Environment manifest (`env.yaml`)](environment-cfg-manifest.md).
To use the `Compose Environments` API, first run **eb init** from the project folder, specifying each component by the name of the folder that contains it with the `--modules` option:
```
~/workspace/project-name$ eb init --modules component-a component-b
```
The EB CLI prompts you to [configure each component](eb-cli3-configuration.md), and then creates the `.elasticbeanstalk` directory in each component folder. EB CLI doesn't create configuration files in the parent directory.
```
~/project-name
|-- component-a
| |-- .elasticbeanstalk
| `-- env.yaml
`-- component-b
|-- .elasticbeanstalk
`-- env.yaml
```
Next, run the **eb create** command with a list of environments to create, one for each component:
```
~/workspace/project-name$ eb create --modules component-a component-b --env-group-suffix group-name
```
This command creates an environment for each component. The names of the environments are created by concatenating the `EnvironmentName` specified in the `env.yaml` file with the group name, separated by a hyphen. The total length of these two options and the hyphen must not exceed the maximum allowed environment name length of 23 characters.
To update the environment, use the **eb deploy** command:
```
~/workspace/project-name$ eb deploy --modules component-a component-b
```
You can update each component individually or you can update them as a group. Specify the components that you want to update with the `--modules` option.
The EB CLI stores the group name that you used with **eb create** in the `branch-defaults` section of the EB CLI configuration file under `/.elasticbeanstalk/config.yml`. To deploy your application to a different group, use the `--env-group-suffix` option when you run **eb deploy**. If the group does not already exist, the EB CLI will create a new group of environments:
```
~/workspace/project-name$ eb deploy --modules component-a component-b --env-group-suffix group-2-name
```
To terminate environments, run **eb terminate** in the folder for each module. By default, the EB CLI will show an error if you try to terminate an environment that another running environment is dependent on. Terminate the dependent environment first, or use the `--ignore-links` option to override the default behavior:
```
~/workspace/project-name/component-b$ eb terminate --ignore-links
```
# Deploying applications to Elastic Beanstalk environments
You can use the AWS Elastic Beanstalk console to upload an updated [source bundle](applications-sourcebundle.md) and deploy it to your Elastic Beanstalk environment, or redeploy a previously uploaded version.
Each deployment is identified by a deployment ID. Deployment IDs start at `1` and increment by one with each deployment and instance configuration change. If you enable [enhanced health reporting](health-enhanced.md), Elastic Beanstalk displays the deployment ID in both the [health console](health-enhanced-console.md) and the [EB CLI](health-enhanced-ebcli.md) when it reports instance health status. The deployment ID helps you determine the state of your environment when a rolling update fails.
Elastic Beanstalk provides several deployment policies and settings. For details about configuring a policy and additional settings, see [Deployment policies and settings](using-features.rolling-version-deploy.md). The following table lists the policies and the kinds of environments that support them.
**Supported deployment policies**
| Deployment policy | Load-balanced environments | Single-instance environments | Legacy Windows Server environments† |
| --- | --- | --- | --- |
| **All at once** | ![\[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** | ![\[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 with an additional batch** | ![\[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 | ![\[No\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/icon-no.png) No |
| **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 |
| **Traffic splitting** | ![\[Yes\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/icon-yes.png) Yes (Application Load Balancer) | ![\[No\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/icon-no.png) No | ![\[No\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/icon-no.png) No |
† In 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 uses an IIS version earlier than IIS 8.5.
**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
## Choosing a deployment policy
Choosing the right deployment policy for your application is a tradeoff of a few considerations, and depends on your particular needs. The [Deployment policies and settings](using-features.rolling-version-deploy.md) page has more information about each policy, and a detailed description of the workings of some of them.
The following list provides summary information about the different deployment policies and adds related considerations.
+ **All at once** – The quickest deployment method. Suitable if you can accept a short loss of service, and if quick deployments are important to you. With this method, Elastic Beanstalk deploys the new application version to each instance. Then, the web proxy or application server might need to restart. As a result, your application might be unavailable to users (or have low availability) for a short time.
+ **Rolling** – Avoids downtime and minimizes reduced availability, at a cost of a longer deployment time. Suitable if you can't accept any period of completely lost service. With this method, your application is deployed to your environment one batch of instances at a time. Most bandwidth is retained throughout the deployment.
+ **Rolling with additional batch** – Avoids any reduced availability, at a cost of an even longer deployment time compared to the *Rolling* method. Suitable if you must maintain the same bandwidth throughout the deployment. With this method, Elastic Beanstalk launches an extra batch of instances, then performs a rolling deployment. Launching the extra batch takes time, and ensures that the same bandwidth is retained throughout the deployment.
+ **Immutable** – A slower deployment method, that ensures your new application version is always deployed to new instances, instead of updating existing instances. It also has the additional advantage of a quick and safe rollback in case the deployment fails. With this method, Elastic Beanstalk performs an [immutable update](environmentmgmt-updates-immutable.md) to deploy your application. In an immutable update, a second Auto Scaling group is launched in your environment and the new version serves traffic alongside the old version until the new instances pass health checks.
+ **Traffic splitting** – A canary testing deployment method. Suitable if you want to test the health of your new application version using a portion of incoming traffic, while keeping the rest of the traffic served by the old application version.
The following table compares deployment method properties.
**Deployment methods**
| **Method** | **Impact of failed deployment** | **Deploy time** | **Zero downtime** | **No DNS change** | **Rollback process** | **Code deployed to** |
| --- | --- | --- | --- | --- | --- | --- |
| All at once | Downtime | ![\[Circular icon with a clock face, indicating time-related functionality or waiting period.\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/clock.png) | ![\[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 | Manual redeploy | Existing instances |
| Rolling | Single batch out of service; any successful batches before failure running new application version | ![\[Circular icon with a clock face, indicating time-related functionality or waiting period.\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/clock.png)![\[Circular icon with a clock face, indicating time-related functionality or waiting period.\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/clock.png)† | ![\[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 | Manual redeploy | Existing instances |
| Rolling with an additional batch | Minimal if first batch fails; otherwise, similar to Rolling | ![\[Circular icon with a clock face, indicating time-related functionality or waiting period.\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/clock.png)![\[Circular icon with a clock face, indicating time-related functionality or waiting period.\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/clock.png)![\[Circular icon with a clock face, indicating time-related functionality or waiting period.\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/clock.png)† | ![\[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 | Manual redeploy | New and existing instances |
| Immutable | Minimal | ![\[Circular icon with a clock face, indicating time-related functionality or waiting period.\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/clock.png)![\[Circular icon with a clock face, indicating time-related functionality or waiting period.\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/clock.png)![\[Circular icon with a clock face, indicating time-related functionality or waiting period.\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/clock.png)![\[Circular icon with a clock face, indicating time-related functionality or waiting period.\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/clock.png) | ![\[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 | Terminate new instances | New instances |
| Traffic splitting | Percentage of client traffic routed to new version temporarily impacted | ![\[Circular icon with a clock face, indicating time-related functionality or waiting period.\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/clock.png)![\[Circular icon with a clock face, indicating time-related functionality or waiting period.\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/clock.png)![\[Circular icon with a clock face, indicating time-related functionality or waiting period.\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/clock.png)![\[Circular icon with a clock face, indicating time-related functionality or waiting period.\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/clock.png)†† | ![\[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 | Reroute traffic and terminate new instances | New instances |
| Blue/green | Minimal | ![\[Circular icon with a clock face, indicating time-related functionality or waiting period.\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/clock.png)![\[Circular icon with a clock face, indicating time-related functionality or waiting period.\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/clock.png)![\[Circular icon with a clock face, indicating time-related functionality or waiting period.\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/clock.png)![\[Circular icon with a clock face, indicating time-related functionality or waiting period.\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/clock.png) | ![\[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 | Swap URL | New instances |
† *Varies depending on batch size.*
†† *Varies depending on **evaluation time** option setting.*
## Deploying a new application version
You can perform deployments from your environment's dashboard.
**To deploy a new application version to an Elastic Beanstalk environment**
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. Choose **Upload and deploy**.
1. Use the on-screen form to upload the application source bundle.
1. Choose **Deploy**.
## Redeploying a previous version
You can also deploy a previously uploaded version of your application to any of its environments from the application versions page.
**To deploy an existing application version to an existing environment**
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 **Applications**, and then choose your application's name from the list.
1. In the navigation pane, find your application's name and choose **Application versions**.
1. Select the application version to deploy.
1. Choose **Actions**, and then choose **Deploy**.
1. Select an environment, and then choose **Deploy**.
## Other ways to deploy your application
If you deploy often, consider using the [Elastic Beanstalk Command Line Interface](eb-cli3.md) (EB CLI) to manage your environments. The EB CLI creates a repository alongside your source code. It can also create a source bundle, upload it to Elastic Beanstalk, and deploy it with a single command.
For deployments that depend on resource configuration changes or a new version that can't run alongside the old version, you can launch a new environment with the new version and perform a CNAME swap for a [blue/green deployment](using-features.CNAMESwap.md).
To automate your build, test, and deployment processes, you can implement continuous integration and continuous deployment (CI/CD) with your Elastic Beanstalk environment. For more information, see [Implementing CI/CD integration with your Elastic Beanstalk environment](deployments.cicd.md).
# Deployment policies and settings
AWS Elastic Beanstalk provides several options for how [deployments](using-features.deploy-existing-version.md) are processed, including deployment policies (*All at once*, *Rolling*, *Rolling with additional batch*, *Immutable*, and *Traffic splitting*) and options that let you configure batch size and health check behavior during deployments. By default, your environment uses all-at-once deployments. If you created the environment with the EB CLI and it's a scalable environment (you didn't specify the `--single` option), it uses rolling deployments.
With *rolling deployments*, Elastic Beanstalk splits the environment's Amazon EC2 instances into batches and deploys the new version of the application to one batch at a time. It leaves the rest of the instances in the environment running the old version of the application. During a rolling deployment, some instances serve requests with the old version of the application, while instances in completed batches serve other requests with the new version. For details, see [How rolling deployments work](#environments-cfg-rollingdeployments-method).
To maintain full capacity during deployments, you can configure your environment to launch a new batch of instances before taking any instances out of service. This option is known as a *rolling deployment with an additional batch*. When the deployment completes, Elastic Beanstalk terminates the additional batch of instances.
*Immutable deployments* perform an [immutable update](environmentmgmt-updates-immutable.md) to launch a full set of new instances running the new version of the application in a separate Auto Scaling group, alongside the instances running the old version. Immutable deployments can prevent issues caused by partially completed rolling deployments. If the new instances don't pass health checks, Elastic Beanstalk terminates them, leaving the original instances untouched.
*Traffic-splitting deployments* let you perform canary testing as part of your application deployment. In a traffic-splitting deployment, Elastic Beanstalk launches a full set of new instances just like during an immutable deployment. It then forwards a specified percentage of incoming client traffic to the new application version for a specified evaluation period. If the new instances stay healthy, Elastic Beanstalk forwards all traffic to them and terminates the old ones. If the new instances don't pass health checks, or if you choose to abort the deployment, Elastic Beanstalk moves traffic back to the old instances and terminates the new ones. There's never any service interruption. For details, see [How traffic-splitting deployments work](#environments-cfg-trafficsplitting-method).
**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 your application doesn't pass all health checks, but still operates correctly at a lower health status, you can allow instances to pass health checks with a lower status, such as `Warning`, by modifying the **Healthy threshold** option. If your deployments fail because they don't pass health checks and you need to force an update regardless of health status, specify the **Ignore health check** option.
When you specify a batch size for rolling updates, Elastic Beanstalk also uses that value for rolling application restarts. Use rolling restarts when you need to restart the proxy and application servers running on your environment's instances without downtime.
## Configuring application deployments
In the [environment management console](environments-console.md), enable and configure batched application version deployments by editing **Updates and Deployments** on the environment's **Configuration** page.
**To configure deployments (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 **Application Deployments** section, choose a **Deployment policy**, batch settings, and health check options.
1. To save the changes choose **Apply** at the bottom of the page.
The **Application deployments** section of the **Rolling updates and deployments** page has the following options for application deployments:
+ **Deployment policy** – Choose from the following deployment options:
+ **All at once** – Deploy the new version to all instances simultaneously. All instances in your environment are out of service for a short time while the deployment occurs.
+ **Rolling** – Deploy the new version in batches. Each batch is taken out of service during the deployment phase, reducing your environment's capacity by the number of instances in a batch.
+ **Rolling with additional batch** – Deploy the new version in batches, but first launch a new batch of instances to ensure full capacity during the deployment process.
+ **Immutable** – Deploy the new version to a fresh group of instances by performing an [immutable update](environmentmgmt-updates-immutable.md).
+ **Traffic splitting** – Deploy the new version to a fresh group of instances and temporarily split incoming client traffic between the existing application version and the new one.
For the **Rolling** and **Rolling with additional batch** deployment policies you can configure:
+ **Batch size** – The size of the set of instances to deploy in each batch.
Choose **Percentage** to configure a percentage of the total number of EC2 instances in the Auto Scaling group (up to 100 percent), or choose **Fixed** to configure a fixed number of instances (up to the maximum instance count in your environment's Auto Scaling configuration).
For the **Traffic splitting** deployment policy you can configure the following:
+ **Traffic split** – The initial percentage of incoming client traffic that Elastic Beanstalk shifts to environment instances running the new application version you're deploying.
+ **Traffic splitting evaluation time** – The time period, in minutes, that Elastic Beanstalk waits after an initial healthy deployment before proceeding to shift all incoming client traffic to the new application version that you're deploying.
![\[Elastic Beanstalk application deployment configuration page\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/environment-cfg-rollingdeployments.png)
The **Deployment preferences** section contains options related to health checks.
+ **Ignore health check** – Prevents a deployment from rolling back when a batch fails to become healthy within the **Command timeout**.
+ **Healthy threshold** – Lowers the threshold at which an instance is considered healthy during rolling deployments, rolling updates, and immutable updates.
+ **Command timeout** – The number of seconds to wait for an instance to become healthy before canceling the deployment or, if **Ignore health check** is set, to continue to the next batch.
![\[Elastic Beanstalk application deployments configuration page\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/environment-cfg-healthchecks.png)
## How rolling deployments work
When processing a batch, Elastic Beanstalk detaches all instances in the batch from the load balancer, deploys the new application version, and then reattaches the instances. If you enable [connection draining](environments-cfg-clb.md#using-features.managing.elb.draining), Elastic Beanstalk drains existing connections from the Amazon EC2 instances in each batch before beginning the deployment.
After reattaching the instances in a batch to the load balancer, Elastic Load Balancing waits until they pass a minimum number of Elastic Load Balancing health checks (the **Healthy check count threshold** value), and then starts routing traffic to them. If no [health check URL](environments-cfg-clb.md#using-features.managing.elb.healthchecks) is configured, this can happen very quickly, because an instance will pass the health check as soon as it can accept a TCP connection. If a health check URL is configured, the load balancer doesn't route traffic to the updated instances until they return a `200 OK` status code in response to an `HTTP GET` request to the health check URL.
Elastic Beanstalk waits until all instances in a batch are healthy before moving on to the next batch. With [basic health reporting](using-features.healthstatus.md), instance health depends on the Elastic Load Balancing health check status. When all instances in the batch pass enough health checks to be considered healthy by Elastic Load Balancing, the batch is complete. If [enhanced health reporting](health-enhanced.md) is enabled, Elastic Beanstalk considers several other factors, including the result of incoming requests. With enhanced health reporting, all instances must pass 12 consecutive health checks with an [OK status](health-enhanced-status.md#health-enhanced-status-ok) within two minutes for web server environments, and 18 health checks within three minutes for worker environments.
If a batch of instances does not become healthy within the [command timeout](#environments-cfg-rollingdeployments-console), the deployment fails. After a failed deployment, [check the health of the instances in your environment](health-enhanced-console.md) for information about the cause of the failure. Then perform another deployment with a fixed or known good version of your application to roll back.
If a deployment fails after one or more batches completed successfully, the completed batches run the new version of your application while any pending batches continue to run the old version. You can identify the version running on the instances in your environment on the [health page](health-enhanced-console.md#health-enhanced-console-healthpage) in the console. This page displays the deployment ID of the most recent deployment that executed on each instance in your environment. If you terminate instances from the failed deployment, Elastic Beanstalk replaces them with instances running the application version from the most recent successful deployment.
## How traffic-splitting deployments work
Traffic-splitting deployments allow you to perform canary testing. You direct some incoming client traffic to your new application version to verify the application's health before committing to the new version and directing all traffic to it.
During a traffic-splitting deployment, Elastic Beanstalk creates a new set of instances in a separate temporary Auto Scaling group. Elastic Beanstalk then instructs the load balancer to direct a certain percentage of your environment's incoming traffic to the new instances. Then, for a configured amount of time, Elastic Beanstalk tracks the health of the new set of instances. If all is well, Elastic Beanstalk shifts remaining traffic to the new instances and attaches them to the environment's original Auto Scaling group, replacing the old instances. Then Elastic Beanstalk cleans up—terminates the old instances and removes the temporary Auto Scaling group.
**Note**
The environment's capacity doesn't change during a traffic-splitting deployment. Elastic Beanstalk launches the same number of instances in the temporary Auto Scaling group as there are in the original Auto Scaling group at the time the deployment starts. It then maintains a constant number of instances in both Auto Scaling groups for the deployment duration. Take this fact into account when configuring the environment's traffic splitting evaluation time.
Rolling back the deployment to the previous application version is quick and doesn't impact service to client traffic. If the new instances don't pass health checks, or if you choose to abort the deployment, Elastic Beanstalk moves traffic back to the old instances and terminates the new ones. You can abort any deployment by using the environment overview page in the Elastic Beanstalk console, and choosing **Abort current operation** in **Environment actions**. You can also call the [AbortEnvironmentUpdate](https://docs.aws.amazon.com/elasticbeanstalk/latest/api/API_AbortEnvironmentUpdate.html) API or the equivalent AWS CLI command.
Traffic-splitting deployments require an Application Load Balancer. Elastic Beanstalk uses this load balancer type by default when you create your environment using the Elastic Beanstalk console or the EB CLI.
## Deployment option namespaces
You can use the [configuration options](command-options.md) in the [`aws:elasticbeanstalk:command`](command-options-general.md#command-options-general-elasticbeanstalkcommand) namespace to configure your deployments. If you choose the traffic-splitting policy, additional options for this policy are available in the [`aws:elasticbeanstalk:trafficsplitting`](command-options-general.md#command-options-general-elasticbeanstalktrafficsplitting) namespace.
Use the `DeploymentPolicy` option to set the deployment type. The following values are supported:
+ `AllAtOnce` – Disables rolling deployments and always deploys to all instances simultaneously.
+ `Rolling` – Enables standard rolling deployments.
+ `RollingWithAdditionalBatch` – Launches an extra batch of instances, before starting the deployment, to maintain full capacity.
+ `Immutable` – Performs an [immutable update](environmentmgmt-updates-immutable.md) for every deployment.
+ `TrafficSplitting` – Performs traffic-splitting deployments to canary-test your application deployments.
When you enable rolling deployments, set the `BatchSize` and `BatchSizeType` options to configure the size of each batch. For example, to deploy 25 percent of all instances in each batch, specify the following options and values.
**Example .ebextensions/rolling-updates.config**
```
option_settings:
aws:elasticbeanstalk:command:
DeploymentPolicy: Rolling
BatchSizeType: Percentage
BatchSize: 25
```
To deploy to five instances in each batch, regardless of the number of instances running, and to bring up an extra batch of five instances running the new version before pulling any instances out of service, specify the following options and values.
**Example .ebextensions/rolling-additionalbatch.config**
```
option_settings:
aws:elasticbeanstalk:command:
DeploymentPolicy: RollingWithAdditionalBatch
BatchSizeType: Fixed
BatchSize: 5
```
To perform an immutable update for each deployment with a health check threshold of **Warning**, and proceed with the deployment even if instances in a batch don't pass health checks within a timeout of 15 minutes, specify the following options and values.
**Example .ebextensions/immutable-ignorehealth.config**
```
option_settings:
aws:elasticbeanstalk:command:
DeploymentPolicy: Immutable
HealthCheckSuccessThreshold: Warning
IgnoreHealthCheck: true
Timeout: "900"
```
To perform traffic-splitting deployments, forwarding 15 percent of client traffic to the new application version and evaluating health for 10 minutes, specify the following options and values.
**Example .ebextensions/traffic-splitting.config**
```
option_settings:
aws:elasticbeanstalk:command:
DeploymentPolicy: TrafficSplitting
aws:elasticbeanstalk:trafficsplitting:
NewVersionPercent: "15"
EvaluationTime: "10"
```
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.
# Blue/Green deployments with Elastic Beanstalk
Because AWS Elastic Beanstalk performs an in-place update when you update your application versions, your application might become unavailable to users for a short period of time. To avoid this, perform a blue/green deployment. To do this, deploy the new version to a separate environment, and then swap the CNAMEs of the two environments to redirect traffic to the new version instantly.
A blue/green deployment is also required if you want to update an environment to an incompatible platform version. For more information, see [Updating your Elastic Beanstalk environment's platform version](using-features.platform.upgrade.md).
Blue/green deployments require that your environment runs independently of your production database, if your application uses one. If your environment includes a database that Elastic Beanstalk created on your behalf, the database and connection of the environment isn't preserved unless you take specific actions. If you have a database that you want to retain, use one of the Elastic Beanstalk database lifecycle options. You can choose the Retain option to keep the database and environment operational after decoupling the database. For more information see [Database lifecycle](using-features.managing.db.md#environments-cfg-rds-lifecycle) in the *Configuring environments* chapter of this guide.
For instructions on how to configure your application to connect to an Amazon RDS instance that's not managed by Elastic Beanstalk, see [Using Elastic Beanstalk with Amazon RDS](AWSHowTo.RDS.md).
**To perform a blue/green deployment**
1. Open the [Elastic Beanstalk console](https://console.aws.amazon.com/elasticbeanstalk), and in the **Regions** list, select your AWS Region.
1. [Clone your current environment](using-features.managing.clone.md), or launch a new environment to run the platform version you want.
1. [Deploy the new application version](using-features.deploy-existing-version.md#deployments-newversion) to the new environment.
1. Test the new version on the new environment.
1. On the environment overview page, choose **Actions**, and then choose **Swap environment URLs**.
1. For **Environment name**, select the current environment.
![\[Swap environment URL page\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/aeb-env-swap-url.png)
1. Choose **Swap**.
Elastic Beanstalk swaps the CNAME records of the old and new environments, redirecting traffic from the old version to the new version.
After Elastic Beanstalk completes the swap operation, verify that the new environment responds when you try to connect to the old environment URL. However, do not terminate your old environment until the DNS changes are propagated and your old DNS records expire. DNS servers don't always clear old records from their cache based on the time to live (TTL) that you set on your DNS records.
# Implementing CI/CD integration with your Elastic Beanstalk environment
Elastic Beanstalk integrates with many CI/CD tools to automate your application development workflow. CI/CD practices enable you to automatically build, test, and deploy your applications with minimal manual intervention. Continuous delivery/deployment (CD) extends continuous integration (CI) by automating the deployment process. You can create streamlined deployment pipelines using AWS services like CodePipeline or third-party tools such as Jenkins and GitLab to ensure consistent, reliable deployments to your Elastic Beanstalk environments.
**Topics**
+ [AWS sources to get started](#deployments.cicd.aws-sites)
+ [Additional resources](#deployments.cicd.aws-services.third-party)
+ [Using GitHub Actions to deploy to Elastic Beanstalk](deploying-github-actions.md)
## AWS sources to get started
The following list highlights CI/CD tools and the corresponding AWS resources that provide step-by-step guidance for creating automated deployment pipelines to Elastic Beanstalk environments:
+ **AWS CodePipeline** – This [AWS Getting Started Resource Center](https://aws.amazon.com/getting-started/hands-on/continuous-deployment-pipeline/) tutorial shows you how to set up a continuous deployment pipeline to Elastic Beanstalk from GitHub , S3, or AWS CodeCommit.
+ **GitHub Actions** – See [Using GitHub Actions to deploy to Elastic Beanstalk](deploying-github-actions.md) to learn how to configure YAML-based workflows to set up a continuous deployment pipeline to Elastic Beanstalk directly from GitHub.
+ **GitLab** – This [AWS DevOps Developer Productivity Blog](https://aws.amazon.com/blogs/devops/deploy-a-docker-application-on-aws-elastic-beanstalk-with-gitlab/) post demonstrates how to configure GitLab continuous pipelines to deploy Node.js applications to Elastic Beanstalk Docker environments.
+ **Azure DevOps** – This [.NET on AWS Blog](https://aws.amazon.com/blogs/dotnet/deploy-to-elastic-beanstalk-with-azure-devops/) post guides you through implementing a continuous deployment pipeline from an Azure DevOps Git repository to Elastic Beanstalk using Azure Pipelines.
## Additional resources
The following third-party tools and resources can help you implement automated deployment pipelines to Elastic Beanstalk environments:
+ **Jenkins** – The [AWS EBDeployment Jenkins plugin](https://plugins.jenkins.io/awseb-deployment-plugin/) enables direct deployment to Elastic Beanstalk environments from your Jenkins Job Configuration page.
+ **Circle CI:** – The [Orbs for Elastic Beanstalk](https://circleci.com/developer/orbs/orb/circleci/aws-elastic-beanstalk) provide reusable configuration packages to deploy and scale applications to Elastic Beanstalk.
+ **Bitbucket Pipelines** – The article [Deploy Elastic Beanstalk Application using Bitbucket Pipelines](https://avishayil.medium.com/deploy-to-elastic-beanstalk-using-bitbucket-pipelines-189eb75cf052) provides a basic configuration example for implementing Bitbucket Pipelines with Elastic Beanstalk.
# Using GitHub Actions to deploy to Elastic Beanstalk
[GitHub Actions](https://docs.github.com/en/actions) can automatically deploy your application to Elastic Beanstalk when you push code changes to your repository. The [Elastic Beanstalk Deploy](https://github.com/aws-actions/aws-elasticbeanstalk-deploy) action provides a simple YAML interface that handles creating application versions, uploading source bundles to Amazon S3, and deploying to your Elastic Beanstalk environment.
## Example workflow
The following example workflow deploys an application to an Elastic Beanstalk environment each time you push to the `main` branch. Create a `.yml` file in your repository under `.github/workflows/` .
**Example GitHub Actions workflow for Elastic Beanstalk deployment**
```
name: Deploy to Elastic Beanstalk
on:
push:
branches:
- main
permissions:
id-token: write
contents: read
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Configure AWS credentials
uses: aws-actions/configure-aws-credentials@v4
with:
role-to-assume: arn:aws:iam::123456789012:role/my-github-actions-role
aws-region: us-east-1
- name: Deploy to Elastic Beanstalk
uses: aws-actions/aws-elasticbeanstalk-deploy@v1.0.0
with:
aws-region: us-east-1
application-name: my-application
environment-name: my-application-env
```
This workflow checks out your repository, uses [OpenID Connect (OIDC)](https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services) to authenticate with AWS through the [Configure AWS Credentials](https://github.com/aws-actions/configure-aws-credentials) action, and then deploys your application to Elastic Beanstalk. The deploy action packages your repository contents, uploads the source bundle to Amazon S3, creates a new application version, and creates or updates your environment. By default, it waits for the deployment to complete and the environment to return to a healthy state.
For more configuration options and advanced examples, see the [Elastic Beanstalk Deploy action README](https://github.com/aws-actions/aws-elasticbeanstalk-deploy#readme) on GitHub.
## Additional resources
+ [Elastic Beanstalk Deploy action](https://github.com/aws-actions/aws-elasticbeanstalk-deploy) on GitHub
+ [Configure AWS Credentials action](https://github.com/aws-actions/configure-aws-credentials) on GitHub
+ [Configuring OpenID Connect in Amazon Web Services](https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services) (GitHub documentation)
# 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
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 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.
# Updating your Elastic Beanstalk environment's platform version
Elastic Beanstalk regularly releases new platform versions to update all Linux-based and Windows Server-based [platforms](concepts.platforms.md). New platform versions provide updates to existing software components and support for new features and configuration options. To learn about platforms and platform versions, see [Elastic Beanstalk platforms glossary](platforms-glossary.md).
You can use the Elastic Beanstalk console or the EB CLI to update your environment's platform version. Depending on the platform version you'd like to update to, Elastic Beanstalk recommends one of two methods for performing platform updates.
+ [Method 1 – Update your environment's platform version](#using-features.platform.upgrade.config). We recommend this method when you're updating to the latest platform version within a platform branch—with the same runtime, web server, application server, and operating system, and without a change in the major platform version. This is the most common and routine platform update.
+ [Method 2 – Perform a Blue/Green deployment](#using-features.platform.upgrade.bluegreen). We recommend this method when you're updating to a platform version in a different platform branch—with a different runtime, web server, application server, or operating system, or to a different major platform version. This is a good approach when you want to take advantage of new runtime capabilities or the latest Elastic Beanstalk functionality, or when you want to move off of a deprecated or retired platform branch.
[Migrating from a legacy platform version](using-features.migration.md) requires a blue/green deployment, because these platform versions are incompatible with currently supported versions.
[Migrating a Linux application to Amazon Linux 2](using-features.migration-al.md) requires a blue/green deployment, because Amazon Linux 2 platform versions are incompatible with previous Amazon Linux AMI platform versions.
For more help with choosing the best platform update method, expand the section for your environment's platform.
## Docker
Use [Method 1](#using-features.platform.upgrade.config) to perform platform updates.
## Multicontainer Docker
Use [Method 1](#using-features.platform.upgrade.config) to perform platform updates.
## Preconfigured Docker
Consider the following cases:
+ If you're migrating your application to another platform, for example from *Go 1.4 (Docker)* to *Go 1.11* or from *Python 3.4 (Docker)* to *Python 3.6*, use [Method 2](#using-features.platform.upgrade.bluegreen).
+ If you're migrating your application to a different Docker container version, for example from *Glassfish 4.1 (Docker)* to *Glassfish 5.0 (Docker)*, use [Method 2](#using-features.platform.upgrade.bluegreen).
+ If you're updating to a latest platform version with no change in container version or major version, use [Method 1](#using-features.platform.upgrade.config).
## Go
Use [Method 1](#using-features.platform.upgrade.config) to perform platform updates.
## Java SE
Consider the following cases:
+ If you're migrating your application to a different Java runtime version, for example from *Java 7* to *Java 8*, use [Method 2](#using-features.platform.upgrade.bluegreen).
+ If you're updating to a latest platform version with no change in runtime version, use [Method 1](#using-features.platform.upgrade.config).
## Java with Tomcat
Consider the following cases:
+ If you're migrating your application to a different Java runtime version or Tomcat application server version, for example from *Java 7 with Tomcat 7* to *Java 8 with Tomcat 8.5*, use [Method 2](#using-features.platform.upgrade.bluegreen).
+ If you're migrating your application across major Java with Tomcat platform versions (v1.x.x, v2.x.x, and v3.x.x), use [Method 2](#using-features.platform.upgrade.bluegreen).
+ If you're updating to a latest platform version with no change in runtime version, application server version, or major version, use [Method 1](#using-features.platform.upgrade.config).
## .NET on Windows server with IIS
Consider the following cases:
+ If you're migrating your application to a different Windows operating system version, for example from *Windows Server 2008 R2* to *Windows Server 2016*, use [Method 2](#using-features.platform.upgrade.bluegreen).
+ If you're migrating your application across major Windows Server platform versions, see [Migrating from earlier major versions of the Windows server platform](dotnet-v2migration.md#dotnet-v2migration.migration), and use [Method 2](#using-features.platform.upgrade.bluegreen).
+ If your application is currently running on a Windows Server platform V2.x.x and you're updating to a latest platform version, use [Method 1](#using-features.platform.upgrade.config).
**Note**
[Windows Server platform versions](https://docs.aws.amazon.com/elasticbeanstalk/latest/platforms/platforms-supported.html#platforms-supported.net) earlier than v2 aren't semantically versioned. You can only launch the latest version of each of these Windows Server major platform versions and can't roll back after an upgrade.
## Node.js
Use [Method 2](#using-features.platform.upgrade.bluegreen) to perform platform updates.
## PHP
Consider the following cases:
+ If you're migrating your application to a different PHP runtime version, for example from *PHP 5.6* to *PHP 7.2*, use [Method 2](#using-features.platform.upgrade.bluegreen).
+ If you're migrating your application across major PHP platform versions (v1.x.x and v2.x.x), use [Method 2](#using-features.platform.upgrade.bluegreen).
+ If you're updating to a latest platform version with no change in runtime version or major version, use [Method 1](#using-features.platform.upgrade.config).
## Python
Consider the following cases:
+ If you're migrating your application to a different Python runtime version, for example from *Python 2.7* to *Python 3.6*, use [Method 2](#using-features.platform.upgrade.bluegreen).
+ If you're migrating your application across major Python platform versions (v1.x.x and v2.x.x), use [Method 2](#using-features.platform.upgrade.bluegreen).
+ If you're updating to a latest platform version with no change in runtime version or major version, use [Method 1](#using-features.platform.upgrade.config).
## Ruby
Consider the following cases:
+ If you're migrating your application to a different Ruby runtime version or application server version, for example from *Ruby 2.3 with Puma* to *Ruby 2.6 with Puma*, use [Method 2](#using-features.platform.upgrade.bluegreen).
+ If you're migrating your application across major Ruby platform versions (v1.x.x and v2.x.x), use [Method 2](#using-features.platform.upgrade.bluegreen).
+ If you're updating to a latest platform version with no change in runtime version, application server version, or major version, use [Method 1](#using-features.platform.upgrade.config).
## Method 1 – Update your environment's platform version
Use this method to update to the latest version of your environment's platform branch. If you've previously created an environment using an older platform version, or upgraded your environment from an older version, you can also use this method to revert to a previous platform version, provided that it's in the same platform branch.
**To update your environment's platform version**
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. On the environment overview page, under **Platform**, choose **Change**.
![\[Elastic Beanstalk newer platform available\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/environment-management-platform-change.png)
1. On the **Update platform version** dialog, select a platform version. The newest (recommended) platform version in the branch is selected automatically. You can update to any version that you've used in the past.
![\[Elastic Beanstalk update platform version confirmation\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/environment-management-update-platform-version.png)
1. Choose **Save**.
To further simplify platform updates, Elastic Beanstalk can manage them for you. You can configure your environment to apply minor and patch version updates automatically during a configurable weekly maintenance window. Elastic Beanstalk applies managed updates with no downtime or reduction in capacity, and cancels the update immediately if instances running your application on the new version fail health checks. For details, see [Managed platform updates](environment-platform-update-managed.md).
## Method 2 – Perform a Blue/Green deployment
Use this method to update to a different platform branch—with a different runtime, web server, application server, or operating system, or to a different major platform version. This is typically necessary when you want to take advantage of new runtime capabilities or the latest Elastic Beanstalk functionality. It's also required when you're migrating off of a deprecated or retired platform branch.
When you migrate across major platform versions or to platform versions with major component updates, there's a greater likelihood that your application, or some aspects of it, might not function as expected on the new platform version, and might require changes.
Before performing the migration, update your local development machine to the newer runtime versions and other components of the platform you plan on migrating to. Verify that your application still works as expected, and make any necessary code fixes and changes. Then use the following best practice procedure to safely migrate your environment to the new platform version.
**To migrate your environment to a platform version with major updates**
1. [Create a new environment](using-features.environments.md), using the new target platform version, and deploy your application code to it. The new environment should be in the Elastic Beanstalk application that contains the environment you're migrating. Don't terminate the existing environment yet.
1. Use the new environment to migrate your application. In particular:
+ Find and fix any application compatibility issues that you couldn't discover during the development phase.
+ Ensure that any customizations that your application makes using [configuration files](ebextensions.md) work correctly in the new environment. These might include option settings, additional installed packages, custom security policies, and script or configuration files installed on environment instances.
+ If your application uses a custom Amazon Machine Image (AMI), create a new custom AMI based on the AMI of the new platform version. To learn more, see [Using a custom Amazon machine image (AMI) in your Elastic Beanstalk environment](using-features.customenv.md). Specifically, this is required if your application uses the Windows Server platform with a custom AMI, and you're migrating to a Windows Server V2 platform version. In this case, see also [Migrating from earlier major versions of the Windows server platform](dotnet-v2migration.md#dotnet-v2migration.migration).
Iterate on testing and deploying your fixes until you're satisfied with the application on the new environment.
1. Turn the new environment into your production environment by swapping its CNAME with the existing production environment's CNAME. For details, see [Blue/Green deployments with Elastic Beanstalk](using-features.CNAMESwap.md).
1. When you're satisfied with the state of your new environment in production, terminate the old environment. For details, see [Terminate an Elastic Beanstalk environment](using-features.terminating.md).
# Managed platform updates
AWS Elastic Beanstalk regularly releases [platform updates](using-features.platform.upgrade.md) to provide fixes, software updates, and new features. With managed platform updates, you can configure your environment to automatically upgrade to the latest version of a platform during a scheduled [maintenance window](#environment-platform-update-managed-window). Your application remains in service during the update process with no reduction in capacity. Managed updates are available on both single-instance and load-balanced environments.
**Note**
This feature isn't available on [Windows Server platform versions](https://docs.aws.amazon.com/elasticbeanstalk/latest/platforms/platforms-supported.html#platforms-supported.net) earlier than version 2 (v2).
You can configure your environment to automatically apply [patch version updates](#environment-platform-update-managed-versioning), or both patch and minor version updates. Managed platform updates don't support updates across platform branches (updates to different major versions of platform components such as operating system, runtime, or Elastic Beanstalk components), because these can introduce changes that are backward incompatible.
You can also configure Elastic Beanstalk to replace all instances in your environment during the maintenance window, even if a platform update isn't available. Replacing all instances in your environment is helpful if your application encounters bugs or memory issues when running for a long period.
On environments created on November 25, 2019 or later using the Elastic Beanstalk console, managed updates are enabled by default whenever possible. Managed updates require [enhanced health](health-enhanced.md) to be enabled. Enhanced health is enabled by default when you select one of the [configuration presets](environments-create-wizard.md#environments-create-wizard-presets), and disabled when you select **Custom configuration**. The console can't enable managed updates for older platform versions that don't support enhanced health, or when enhanced health is disabled. When the console enables managed updates for a new environment, the **Weekly update window** is set to a random day of the week at a random time. **Update level** is set to **Minor and patch**, and **Instance replacement** is disabled. You can disable or reconfigure managed updates before the final environment creation step.
For an existing environment, use the Elastic Beanstalk console anytime to configure managed platform updates.
**Important**
A *high number* of Beanstalk environments in one AWS account may present a risk of throttling issues during managed updates. *High number* is a relative amount that depends on how closely you schedule the managed updates for your environments. Over 200 environments in one account scheduled closely could cause throttling issues, although a lower number may also be problematic.
To balance the resource load for managed updates, we advise that you spread out the scheduled maintenance windows for the environments in one account.
Also, consider a multi‐account strategy. For more information, see [Organizing Your AWS Environment Using Multiple Accounts](https://docs.aws.amazon.com/whitepapers/latest/organizing-your-aws-environment/organizing-your-aws-environment.html) on the *AWS Whitepapers & Guides* website.
**To configure managed platform 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 **Managed updates** category, choose **Edit**.
1. Disable or enable **Managed updates**.
1. If managed updates are enabled, select a maintenance window, and then select an **Update level**.
1. (Optional) Select **Instance replacement** to enable weekly instance replacement.
![\[Modify managed updates configuration page\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/environment-platform-update-managed.png)
1. To save the changes choose **Apply** at the bottom of the page.
Managed platform updates depend on [enhanced health reporting](health-enhanced.md) to determine that your application is healthy enough to consider the platform update successful. See [Enabling Elastic Beanstalk enhanced health reporting](health-enhanced-enable.md) for instructions.
**Topics**
+ [Permissions required to perform managed platform updates](#environment-platform-update-managed-perms)
+ [Managed update maintenance window](#environment-platform-update-managed-window)
+ [Minor and patch version updates](#environment-platform-update-managed-versioning)
+ [Immutable environment updates](#environment-platform-update-managed-immutable)
+ [Managing managed updates](#environment-platform-update-managed-managing)
+ [Managed action option namespaces](#environment-platform-update-managed-namespace)
## Permissions required to perform managed platform updates
Elastic Beanstalk needs permission to initiate a platform update on your behalf. To gain these permissions, Elastic Beanstalk assumes the *managed-updates service role*. When you use the default [service role](iam-servicerole.md) for your environment, the Elastic Beanstalk console uses it as the managed-updates service role too. The console assigns the [`AWSElasticBeanstalkManagedUpdatesCustomerRolePolicy`](iam-servicerole.md#iam-servicerole-update) managed policy to your service role. This policy has all permissions that Elastic Beanstalk needs to perform managed platform updates.
For details about other ways to set the managed-updates service role, see [Managing Elastic Beanstalk service roles](iam-servicerole.md).
**Note**
If you use [configuration files](ebextensions.md) to extend your environment to include additional resources, you might need to add permissions to your environment's managed-updates service role. Typically you need to add permissions when you reference these resources by name in other sections or files.
If an update fails, you can find the reason for the failure on the [Managed updates](#environment-platform-update-managed-managing) page.
## Managed update maintenance window
When AWS releases a new version of your environment's platform, Elastic Beanstalk schedules a managed platform update during the next weekly maintenance window. Maintenance windows are two hours long. Elastic Beanstalk starts a scheduled update during the maintenance window. The update might not complete until after the window ends.
**Note**
In most cases, Elastic Beanstalk schedules your managed update to occur during your coming weekly maintenance window. The system considers various aspects of update safety and service availability when scheduling managed updates. In rare cases, an update might not be scheduled for the first coming maintenance window. If this happens, the system tries again during the next maintenance window. To manually apply the managed update, choose **Apply now** as explained in [Managing managed updates](#environment-platform-update-managed-managing) on this page.
## Minor and patch version updates
You can enable managed platform updates to apply patch version updates only, or for both minor and patch version updates. Patch version updates provide bug fixes and performance improvements, and can include minor configuration changes to the on-instance software, scripts, and configuration options. Minor version updates provide support for new Elastic Beanstalk features. You can't apply major version updates, which might make changes that are backward incompatible, with managed platform updates.
In a platform version number, the second number is the minor update version, and the third number is the patch version. For example, a version 2.0.7 platform version has a minor version of 0 and a patch version of 7.
## Immutable environment updates
Managed platform updates perform [immutable environment updates](environmentmgmt-updates-immutable.md) to upgrade your environment to a new platform version. Immutable updates update your environment without taking any instances out of service or modifying your environment, before confirming that instances running the new version pass health checks.
In an immutable update, Elastic Beanstalk deploys as many instances as are currently running with the new platform version. The new instances begin to take requests alongside those running the old version. If the new set of instances passes all health checks, Elastic Beanstalk terminates the old set of instances, leaving only instances with the new version.
Managed platform updates always perform immutable updates, even when you apply them outside of the maintenance window. If you change the platform version from the **Dashboard**, Elastic Beanstalk applies the update policy that you've chosen for configuration updates.
**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
## Managing managed updates
The Elastic Beanstalk console shows detailed information about managed updates on the **Managed updates overview** page.
**To view information about managed 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. Choose **Managed updates**.
The **Managed updates overview** section provides information about scheduled and pending managed updates. The **History** section lists successful updates and failed attempts.
You can choose to apply a scheduled update immediately, instead of waiting until the maintenance window.
**To apply a managed platform update immediately (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. Choose **Managed updates**.
1. Choose **Apply now**.
1. Verify the update details, and then choose **Apply**.
When you apply a managed platform update outside of the maintenance window, Elastic Beanstalk performs an immutable update. If you update the environment's platform from the [Dashboard](environments-dashboard.md), or by using a different client, Elastic Beanstalk uses the update type that you selected for [configuration changes](environments-updating.md).
If you don't have a managed update scheduled, your environment might already be running the latest version. Other reasons for not having an update scheduled include:
+ A [minor version](#environment-platform-update-managed-versioning) update is available, but your environment is configured to automatically apply only patch version updates.
+ Your environment hasn't been scanned since the update was released. Elastic Beanstalk typically checks for updates every hour.
+ An update is pending or already in progress.
When your maintenance window starts or when you choose **Apply now**, scheduled updates go into pending status before execution.
## Managed action option namespaces
You can use [configuration options](command-options.md) in the `aws:elasticbeanstalk:managedactions` and `aws:elasticbeanstalk:managedactions:platformupdate` namespaces to enable and configure managed platform updates.
The `ManagedActionsEnabled` option turns on managed platform updates. Set this option to `true` to enable managed platform updates, and use the other options to configure update behavior.
Use `PreferredStartTime` to configure the beginning of the weekly maintenance window in *day*:*hour*:*minute* format.
Set `UpdateLevel` to `minor` or `patch` to apply both minor and patch version updates, or just patch version updates, respectively.
When managed platform updates are enabled, you can enable instance replacement by setting the `InstanceRefreshEnabled` option to `true`. When this setting is enabled, Elastic Beanstalk runs an immutable update on your environment every week, regardless of whether there is a new platform version available.
The following example [configuration file](ebextensions.md) enables managed platform updates for patch version updates with a maintenance window starting at 9:00 AM UTC each Tuesday.
**Example .ebextensions/managed-platform-update.config**
```
option_settings:
aws:elasticbeanstalk:managedactions:
ManagedActionsEnabled: true
PreferredStartTime: "Tue:09:00"
aws:elasticbeanstalk:managedactions:platformupdate:
UpdateLevel: patch
InstanceRefreshEnabled: true
```
# Migrating your application from a legacy platform version
If you have deployed an Elastic Beanstalk application that uses a legacy platform version, you should migrate your application to a new environment using a non-legacy platform version so that you can get access to new features. If you are unsure whether you are running your application using a legacy platform version, you can check in the Elastic Beanstalk console. For instructions, see [To check if you are using a legacy platform version](#using-features.migration-proc).
## What new features are legacy platform versions missing?
Legacy platforms do not support the following features:
+ Configuration files, as described in the [Advanced environment customization with configuration files (`.ebextensions`)](ebextensions.md) topic
+ ELB health checks, as described in the [Basic health reporting](using-features.healthstatus.md) topic
+ Instance Profiles, as described in the [Managing Elastic Beanstalk instance profiles](iam-instanceprofile.md) topic
+ VPCs, as described in the [Using Elastic Beanstalk with Amazon VPC](vpc.md) topic
+ Data Tiers, as described in the [Adding a database to your Elastic Beanstalk environment](using-features.managing.db.md) topic
+ Worker Tiers, as described in the [Elastic Beanstalk worker environments](concepts-worker.md) topic
+ Single Instance Environments, as described in the [Environment types](using-features-managing-env-types.md) topic
+ Tags, as described in the [Tagging resources in your Elastic Beanstalk environments](using-features.tagging.md) topic
+ Rolling Updates, as described in the [Elastic Beanstalk rolling environment configuration updates](using-features.rollingupdates.md) topic
## Why are some platform versions marked legacy?
Some older platform versions do not support the latest Elastic Beanstalk features. These versions are marked **(legacy)** on the environment overview page in the Elastic Beanstalk console.
**To check if you are using a legacy platform version**
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. On the environment overview page, view the **Platform** name.
Your application is using a legacy platform version if you see **(legacy)** next to the platform's name.
**To migrate your application**
1. Deploy your application to a new environment. For instructions, go to [Creating an Elastic Beanstalk environment](using-features.environments.md).
1. If you have an Amazon RDS DB Instance, update your database security group to allow access to your EC2 security group for your new environment. For instructions on how to find the name of your EC2 security group using the AWS Management Console, see [EC2 security groups](using-features.managing.ec2.console.md#using-features.managing.ec2.securitygroups). For more information about configuring your EC2 security group, go to the "Authorizing Network Access to an Amazon EC2 Security Group" section of [Working with DB Security Groups](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_WorkingWithSecurityGroups.html) in the *Amazon Relational Database Service User Guide*.
1. Swap your environment URL. For instructions, go to [Blue/Green deployments with Elastic Beanstalk](using-features.CNAMESwap.md).
1. Terminate your old environment. For instructions, go to [Terminate an Elastic Beanstalk environment](using-features.terminating.md).
**Note**
If you use AWS Identity and Access Management (IAM) then you will need to update your policies to include CloudFormation and Amazon RDS (if applicable). For more information, see [Using Elastic Beanstalk with AWS Identity and Access Management](AWSHowTo.iam.md).
# Migrating your Elastic Beanstalk Linux application to Amazon Linux 2023 or Amazon Linux 2
This section describes how to migrate your application using one of the following migration paths.
+ Migrate from an *Amazon Linux 2* platform branch to an *Amazon Linux 2023* platform branch.
+ Migrate from an *Amazon Linux AMI (AL1)* platform branch to either an *Amazon Linux 2023* (recommended) or an *Amazon Linux 2* platform branch.
**Topics**
+ [Migration from Amazon Linux 2 to Amazon Linux 2023](using-features.migration-al.generic.from-al2.md)
+ [Migration from Amazon Linux AMI (AL1) to AL2 or AL2023](using-features.migration-al.generic.from-al1.md)
# Migration from Amazon Linux 2 to Amazon Linux 2023
This topic provides guidance to migrate your application from an Amazon Linux 2 platform branch to an Amazon Linux 2023 platform branch.
## Differences and compatibility
**Between the Elastic Beanstalk AL2 and AL2023 platforms**
There is a high degree of compatibility between Elastic Beanstalk Amazon Linux 2 and Amazon Linux 2023 platforms. Although there are some differences to note:
+ **Instance Metadata Service Version 1 (IMDSv1)** – The [DisableIMDSv1](command-options-general.md#command-options-general-autoscalinglaunchconfiguration) option setting defaults to `true` on AL2023 platforms. The default is `false` on AL2 platforms.
+ **pkg-repo instance tool** – The [pkg-repo](custom-platforms-scripts.md#custom-platforms-scripts.pkg-repo) tool is not available for environments running on AL2023 platforms. However, you can still manually apply package and operating system updates to an AL2023 instance. For more information, see [Managing packages and operating system updates](https://docs.aws.amazon.com/linux/al2023/ug/managing-repos-os-updates.html) in the *Amazon Linux 2023 User Guide*.
+ **Apache HTTPd configuration** – The Apache `httpd.conf` file for AL2023 platforms has some configuration settings that are different from those for AL2:
+ Deny access to the server’s entire file system by default. These settings are described in *Protect Server Files by Default* on the Apache website [Security Tips](https://httpd.apache.org/docs/2.4/misc/security_tips.html) page.
+ Deny access to set up of `.htaccess` in all directories, except for those specifically enabled. This setting is described in *Protecting System Settings* on the Apache website [Security Tips](https://httpd.apache.org/docs/2.4/misc/security_tips.html) page. The [Apache HTTP Server Tutorial: .htaccess files ](https://httpd.apache.org/docs/2.4/howto/htaccess.html) page states this setting may help improve performance.
+ Deny access to files with name pattern `.ht*`. This setting prevents web clients from viewing `.htaccess` and `.htpasswd` files.
You can change any of the above configuration settings for your environment. For more information, see [Configuring Apache HTTPD](platforms-linux-extend.proxy.md#platforms-linux-extend.proxy.httpd).
+ **Multiline environment variable support** – AL2023 platforms support multiline values for environment variables and secrets in systemd service configurations. Amazon Linux 2 platforms do not support multiline environment variable values. This enhancement allows you to use multiline secrets and configuration values on AL2023 platforms. For more information about using environment variables and secrets, see [Multiline values in Amazon Linux 2 environment variables](AWSHowTo.secrets.env-vars.md#AWSHowTo.secrets.multiline).
+ **CloudWatch custom log forwarding** – The deprecated CloudWatch Logs agent (`awslogs` package) is not available on AL2023 platforms. If you have custom log forwarding configurations that install and use the deprecated `awslogs` agent, you must update your configuration files to use the unified CloudWatch agent when migrating from Amazon Linux 2 to AL2023. For more information, see [Custom log file streaming](AWSHowTo.cloudwatchlogs.md#AWSHowTo.cloudwatchlogs.streaming.custom).
**Platform-specific differences**
In addition to the base operating system differences, there are platform-specific differences between Amazon Linux 2 and AL2023 runtime platforms:
+ **.NET platform branching** – The .NET platform branching strategy differs between Amazon Linux 2 and AL2023. On Amazon Linux 2, the .NET Core platform maintains a rotating window of .NET major versions within a single platform branch. On AL2023, each platform branch is pinned to a specific .NET major version (for example, .NET 9, .NET 10).
If you deploy framework-dependent applications (applications that rely on the platform's installed .NET runtime), you must select a platform branch that matches your application's target .NET version. If you deploy self-contained applications (applications that bundle their own .NET runtime), you can use any AL2023 .NET platform branch regardless of your application's .NET version, as your application is not dependent on the platform's installed runtime. For more information, see [Bundling applications for the .NET Core on Linux Elastic Beanstalk platform](dotnet-linux-platform-bundle-app.md).
+ **Node.js version selection** – The Node.js platform on Amazon Linux 2 supports specifying a Node.js version in your application's `package.json` file. The Node.js platform on AL2023 does not support this feature. You must use the default Node.js version provided by the platform branch. For more information about Node.js version management, see [Configuring your application's dependencies on Elastic Beanstalk](nodejs-platform-dependencies.md).
+ **Ruby Puma server version** – The Ruby platform on Amazon Linux 2 ignores the Puma version specified in your application's `Gemfile.lock` file and uses the platform default Puma version. The Ruby platform on AL2023 honors the Puma version specified in `Gemfile.lock` if present. If no version is specified, the platform installs the platform default Puma version.
+ **PHP package availability** – Some packages available on Amazon Linux 2 PHP platforms are not available on AL2023 PHP platforms:
+ *MySQL client packages* – The `mysql` and `mysql-devel` command-line client packages are not installed on AL2023 PHP platforms. If your application requires MySQL database connectivity, use the PHP `mysqli` or `pdo_mysql` extensions, which are available on both platforms.
+ *Compass and Ruby tools* – The `ruby-devel` and `rubygems` packages for Compass CSS framework support are not installed on AL2023 PHP platforms. Compass has been deprecated. Consider using modern CSS preprocessing tools as alternatives.
+ **Go version control tools** – The Bazaar version control system (`bzr`) is not available on AL2023 Go platforms. Bazaar is deprecated and not included in the AL2023 package repository. Use Git, Mercurial, or Subversion for version control instead, all of which are available on AL2023 Go platforms.
**Between the Amazon Linux operating systems**
For more information about the differences between the Amazon Linux 2 and Amazon Linux 2023 operating systems, see [Comparing Amazon Linux 2 and Amazon Linux 2023](https://docs.aws.amazon.com/linux/al2023/ug/compare-with-al2.html) in the *Amazon Linux 2023 User Guide*.
For more information about Amazon Linux 2023, see [What is Amazon Linux 2023?](https://docs.aws.amazon.com/linux/al2023/ug/what-is-amazon-linux.html) in the *Amazon Linux 2023 User Guide*.
## General migration process
When you're ready to go to production, Elastic Beanstalk requires a blue/green deployment to perform the upgrade. The following are the general best practice steps that we recommend for migration with a blue/green deployment procedure.
**Preparing to test for your migration**
Before you deploy your application and start testing, review the information in the prior section [Differences and compatibility](#using-features.migration-al.generic.from-al2.differences). Also review the reference cited in that section, [Comparing Amazon Linux 2 and Amazon Linux 2023](https://docs.aws.amazon.com/linux/al2023/ug/compare-with-al2.html) in the *Amazon Linux 2023 User Guide*. Make a note of the specific information from this content that applies or may apply to your application and configuration set up.
**High level migration steps**
1. Create a new environment that's based on an AL2023 platform branch.
1. Deploy your application to the target AL2023 environment.
Your existing production environment will remain active and unaffected, while you iterate through testing and making adjustments to the new environment.
1. Test your application thoroughly in the new environment.
1. When your destination AL2023 environment is ready to go to production, swap the CNAMEs of the two environments to redirect traffic to the new AL2023 environment.
**More detailed migration steps and best practices**
For a more detailed blue/green deployment procedure, see [Blue/Green deployments with Elastic Beanstalk](using-features.CNAMESwap.md).
For more specific guidance and detailed best practice steps, see [Blue/Green method](using-features.platform.upgrade.md#using-features.platform.upgrade.bluegreen).
## More references to help plan your migration
The following references can offer additional information to plan your migration.
+ [ Elastic Beanstalk supported platforms](https://docs.aws.amazon.com/elasticbeanstalk/latest/platforms/platforms-supported.html) in *AWS Elastic Beanstalk Platforms*
+ [Retired platform branch history](platforms-schedule.md#platforms-support-policy.retired)
+ [Elastic Beanstalk Linux platforms](platforms-linux.md)
+ [Platform retirement FAQ](using-features.migration-al.FAQ.md)
# Migration from Amazon Linux AMI (AL1) to AL2 or AL2023
If your Elastic Beanstalk application is based on an Amazon Linux AMI platform branch, use this section to learn how to migrate your application's environments to Amazon Linux 2 or Amazon Linux 2023. Previous generation platform branches based on [Amazon Linux AMI](https://aws.amazon.com/amazon-linux-ami/) are now retired.
We highly recommend that you migrate to Amazon Linux 2023, since it's more recent than Amazon Linux 2. The Amazon Linux 2 operating system will reach end of support before Amazon Linux 2023 does, so you'll benefit from a longer time frame of support if you migrate to Amazon Linux 2023.
It's worthwhile to note that there is a high degree of compatibility between the Elastic Beanstalk Amazon Linux 2 and Amazon Linux 2023 platforms. Although some areas do have differences: the Instance Metadata Service Version 1 (IMDSv1) option default, support for the pkg-repo instance tool, and some Apache HTTPd configuration. For more information, see [Amazon Linux 2023](platforms-linux.md#platforms-linux.versions.al2023)
## Differences and compatibility
The AL2023/AL2 based platform branches aren't guaranteed to be backward compatible with your existing application. It's also important to be aware that even if your application code successfully deploys to the new platform version, it might behave or perform differently due to operating system and run time differences.
Although Amazon Linux AMI and AL2023/AL2 share the same Linux kernel, they differ in the following aspects: their initialization system, the `libc` versions, the compiler tool chain, and various packages. For more information, see [Amazon Linux 2 FAQs](https://aws.amazon.com//amazon-linux-2/faqs/).
The Elastic Beanstalk service has also updated platform specific versions of runtime, build tools, and other dependencies.
Therefore we recommend that you take your time, test your application thoroughly in a development environment, and make any necessary adjustments.
## General migration process
When you're ready to go to production, Elastic Beanstalk requires a blue/green deployment to perform the upgrade. The following are the general best practice steps that we recommend for migration with a blue/green deployment procedure.
**Preparing to test for your migration**
Before you deploy your application and start testing, review the information in [Considerations for all Linux platforms](#using-features.migration-al.generic), which follows later in this topic. Also, review the information that applies to your platform in the [Platform specific considerations](#using-features.migration-al.specific) section that follows. Make a note of the specific information from this content that applies or may apply to your application and configuration set up.
**High level migration steps**
1. Create a new environment that's based on an AL2 or AL2023 platform branch. We recommend that you migrate to an AL2023 platform branch.
1. Deploy your application to the target AL2023/AL2 environment.
Your existing production environment will remain active and unaffected, while you iterate through testing and making adjustments to the new environment.
1. Test your application thoroughly in the new environment.
1. When your destination AL2023/AL2 environment is ready to go to production, swap the CNAMEs of the two environments to redirect traffic to the new environment.
**More detailed migration steps and best practices**
For a more detailed blue/green deployment procedure, see [Blue/Green deployments with Elastic Beanstalk](using-features.CNAMESwap.md).
For more specific guidance and detailed best practice steps, see [Blue/Green method](using-features.platform.upgrade.md#using-features.platform.upgrade.bluegreen).
## More references to help plan your migration
The following references can offer additional information to plan your migration.
+ [Comparing Amazon Linux 2 and Amazon Linux 2023](https://docs.aws.amazon.com/linux/al2023/ug/compare-with-al2.html) *Amazon Linux 2023 User Guide*.
+ [What is Amazon Linux 2023?](https://docs.aws.amazon.com/linux/al2023/ug/what-is-amazon-linux.html) in the *Amazon Linux 2023 User Guide*
+ [ Elastic Beanstalk supported platforms](https://docs.aws.amazon.com/elasticbeanstalk/latest/platforms/platforms-supported.html) in *AWS Elastic Beanstalk Platforms*
+ [Retired platform branch history](platforms-schedule.md#platforms-support-policy.retired)
+ [Elastic Beanstalk Linux platforms](platforms-linux.md)
+ [Platform retirement FAQ](using-features.migration-al.FAQ.md)
## Considerations for all Linux platforms
The following table discusses considerations you should be aware of when planning an application migration to AL2023/AL2. These considerations apply to any of the Elastic Beanstalk Linux platforms, regardless of specific programming languages or application servers.
| **Area** | **Changes and information** |
| --- | --- |
| Configuration Files | On AL2023/AL2 platforms, you can use [configuration files](ebextensions.md) as before, and all sections work the same way. However, specific settings might not work the same as they did on previous Amazon Linux AMI platforms. For example: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/using-features.migration-al.generic.from-al1.html) We recommend using platform hooks to run custom code on your environment instances. You can still use commands and container commands in `.ebextensions` configuration files, but they aren't as easy to work with. For example, writing command scripts inside a YAML file can be cumbersome and difficult to test. You still need to use `.ebextensions` configuration files for any script that needs a reference to an AWS CloudFormation resource. |
| Platform hooks | AL2 platforms introduced a new way to extend your environment's platform by adding executable files to hook directories on the environment's instances. With previous Linux platform versions, you might have used custom platform hooks. These hooks weren't designed for managed platforms and weren't supported, but could work in useful ways in some cases. With AL2023/AL2 platform versions, custom platform hooks don't work. You should migrate any hooks to the new platform hooks. For details see [Platform hooks](platforms-linux-extend.hooks.md). |
| Supported proxy servers | AL2023/AL2 platform versions support the same reverse proxy servers as each platform supported in its Amazon Linux AMI platform versions. All AL2023/AL2; platform versions use nginx as their default reverse proxy server, with the exception of the ECS and Docker platforms. The Tomcat, Node.js, PHP, and Python platform also support Apache HTTPD as an alternative. All platforms enable proxy server configuration in a uniform way, as described in this section. However, configuring the proxy server is slightly different than it was on Amazon Linux AMI. These are the differences for all platforms: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/using-features.migration-al.generic.from-al1.html) For platform-specific proxy configuration changes, see [Platform specific considerations](#using-features.migration-al.specific). For information about proxy configuration on AL2023/AL2 platforms, see [Reverse proxy configuration](platforms-linux-extend.proxy.md). |
| Proxy Configuration Changes | There are proxy configuration changes that apply uniformly to all platforms in addition to proxy configuration changes that are specific to each platform. It's important to refer to both to accurately configure your environments. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/using-features.migration-al.generic.from-al1.html) |
| Instance profile | AL2023/AL2 platforms require an instance profile to be configured. Environment creation might temporarily succeed without one, but the environment might show errors soon after creation when actions requiring an instance profile start failing. For details, see [Managing Elastic Beanstalk instance profiles](iam-instanceprofile.md). |
| Enhanced health | AL2023/AL2 platform versions enable enhanced health by default. This is a change if you don't use the Elastic Beanstalk console to create your environments. The console enables enhanced health by default whenever possible, regardless of platform version. For details, see [Enhanced health reporting and monitoring in Elastic Beanstalk](health-enhanced.md). |
| Custom AMI | If your environment uses a [custom AMI](using-features.customenv.md), create a new AMI based on AL2023/AL2 for your new environment using an Elastic Beanstalk AL2023/AL2 platform. |
| Custom platforms | The managed AMIs of AL2023/AL2 platform versions don't support custom platforms. |
## Platform specific considerations
This section discusses migration considerations specific to particular Elastic Beanstalk Linux platforms.
### Docker
The Docker platform branch family based on Amazon Linux AMI (AL1) includes three platform branches. We recommend a different migration path for each.
| **AL1 Platform branch** | **Migration Path to AL2023/AL2** |
| --- | --- |
| **Area** | **Changes and information** |
| --- | --- |
| Multi-container Docker managed by Amazon ECS running on Amazon Linux AMI (AL1) | ECS based Docker AL2023/AL2 platform branches The *ECS based Docker AL2023/AL2* platform branches offer a straightforward migration path for environments running on the *Multi-container Docker AL1* platform branch. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/using-features.migration-al.generic.from-al1.html) For more information about migrating your applications running on the *Multi-container Docker Amazon Linux* platform branch to an *Amazon ECS running on AL2023/AL2* platform branch, see [Migrating your Elastic Beanstalk application from ECS managed Multi-container Docker on AL1 to ECS on Amazon Linux 2023](migrate-to-ec2-AL2-platform.md). |
| Docker running on Amazon Linux AMI (AL1) Preconfigured Docker (Glassfish 5.0) running Amazon Linux AMI (AL1) | Docker Running on AL2023/AL2 platform branch We recommend that you migrate your applications running on environments based on *Preconfigured Docker (Glassfish 5.0)* or *Docker running on Amazon Linux AMI (AL1) * to environments that are based on the *Docker Running on Amazon Linux 2* or *Docker Running on AL2023* platform branches. If your environment is based on the *Preconfigured Docker (Glassfish 5.0)* platform branch, see [Deploying a GlassFish application to the Docker platform: a migration path to Amazon Linux 2023](create_deploy_dockerpreconfig.md#docker-glassfish-tutorial). The following table lists migration information specific to the platform branch *Docker Running on AL2023/AL2*. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/using-features.migration-al.generic.from-al1.html) |
| Storage | Elastic Beanstalk configures Docker to use [storage drivers](https://docs.docker.com/storage/storagedriver/) to store Docker images and container data. On Amazon Linux AMI, Elastic Beanstalk used the [Device Mapper storage driver](https://docs.docker.com/storage/storagedriver/device-mapper-driver/). To improve performance, Elastic Beanstalk provisioned an extra Amazon EBS volume. On AL2023/AL2 Docker platform versions, Elastic Beanstalk uses the [OverlayFS storage driver](https://docs.docker.com/storage/storagedriver/overlayfs-driver/), and achieves even better performance while not requiring a separate volume anymore. With Amazon Linux AMI, if you used the `BlockDeviceMappings` option of the `aws:autoscaling:launchconfiguration` namespace to add custom storage volumes to a Docker environment, we advised you to also add the `/dev/xvdcz` Amazon EBS volume that Elastic Beanstalk provisions. Elastic Beanstalk doesn't provision this volume anymore, so you should remove it from your configuration files. For details, see [Docker configuration on Amazon Linux AMI (preceding Amazon Linux 2)](create_deploy_docker.container.console.md#docker-alami). |
| Private repository authentication | When you provide a Docker-generated authentication file to connect to a private repository, you no longer need to convert it to the older format that Amazon Linux AMI Docker platform versions required. AL2023/AL2 Docker platform versions support the new format. For details, see [Authenticating with image repositories](docker-configuration.remote-repo.md). |
| Proxy server | AL2023/AL2 Docker platform versions don't support standalone containers that don't run behind a proxy server. On Amazon Linux AMI Docker platform versions, this used to be possible through the `none` value of the `ProxyServer` option in the `aws:elasticbeanstalk:environment:proxy` namespace. |
### Go
The following table lists migration information for the AL2023/AL2 platform versions in the [Go platform](go-environment.md).
| **Area** | **Changes and information** |
| --- | --- |
| Port passing | On AL2023/AL2 platforms, Elastic Beanstalk doesn't pass a port value to your application process through the `PORT` environment variable. You can simulate this behavior for your process by configuring a `PORT` environment property yourself. However, if you have multiple processes, and you're counting on Elastic Beanstalk passing incremental port values to your processes (5000, 5100, 5200 etc.), you should modify your implementation. For details see [Reverse proxy configuration](platforms-linux-extend.proxy.md). |
### Amazon Corretto
The following table lists migration information for the Corretto platform branches in the [Java SE platform](java-se-platform.md).
| **Area** | **Changes and information** |
| --- | --- |
| Corretto vs. OpenJDK | To implement the Java Platform, Standard Edition (Java SE), AL2023/AL2 platform branches use [Amazon Corretto](https://aws.amazon.com/corretto), an AWS distribution of the Open Java Development Kit (OpenJDK). Prior Elastic Beanstalk Java SE platform branches use the OpenJDK packages included with Amazon Linux AMI. |
| Build tools | AL2023/AL2 platforms have newer versions of the build tools: `gradle`, `maven`, and `ant`. |
| JAR file handling | On AL2023/AL2 platforms, if your source bundle (ZIP file) contains a single JAR file and no other files, Elastic Beanstalk no longer renames the JAR file to `application.jar`. Renaming occurs only if you submit a JAR file on its own, not within a ZIP file. |
| Port passing | On AL2023/AL2 platforms, Elastic Beanstalk doesn't pass a port value to your application process through the `PORT` environment variable. You can simulate this behavior for your process by configuring a `PORT` environment property yourself. However, if you have multiple processes, and you're counting on Elastic Beanstalk passing incremental port values to your processes (5000, 5100, 5200 etc.), you should modify your implementation. For details see [Reverse proxy configuration](platforms-linux-extend.proxy.md). |
| Java 7 | Elastic Beanstalk doesn't support an AL2023/AL2 Java 7 platform branch. If you have a Java 7 application, migrate it to Corretto 8 or Corretto 11. |
### Tomcat
The following table lists migration information for the AL2023/AL2 platform versions in the [Tomcat platform](java-tomcat-platform.md).
| **Area** | **Changes and information** |
| --- | --- |
| **Option** | **Migration information** |
| --- | --- |
| Configuration options | On AL2023/AL2 platform versions, Elastic Beanstalk supports only a subset of the configuration options and option values in the `aws:elasticbeanstalk:environment:proxy` namespace. Here's the migration information for each option. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/using-features.migration-al.generic.from-al1.html) The `XX:MaxPermSize` option in the `aws:elasticbeanstalk:container:tomcat:jvmoptions` namespace isn't supported on AL2023/AL2 platform versions. The JVM setting to modify the size of the permanent generation applies only to Java 7 and earlier, and is therefore not applicable to AL2023/AL2 platform versions. |
| Application path | On AL2023/AL2 platforms, the path to the application's directory on Amazon EC2 instances of your environment is `/var/app/current`. It was `/var/lib/tomcat8/webapps` on Amazon Linux AMI platforms. |
| `GzipCompression` | Unsupported on AL2023/AL2 platform versions. |
| `ProxyServer` | AL2023/AL2 Tomcat platform versions support both the nginx and the Apache HTTPD version 2.4 proxy servers. However, Apache version 2.2 isn't supported. On Amazon Linux AMI platform versions, the default proxy was Apache 2.4. If you used the default proxy setting and added custom proxy configuration files, your proxy configuration should still work on AL2023/AL2. However, if you used the `apache/2.2` option value, you now have to migrate your proxy configuration to Apache version 2.4. |
### Node.js
The following table lists migration information for the AL2023/AL2 platform versions in the [Node.js platform](create_deploy_nodejs.container.md).
| **Area** | **Changes and information** |
| --- | --- |
| **Option** | **Migration information** |
| --- | --- |
| Installed Node.js versions | On AL2023/AL2 platforms, Elastic Beanstalk maintains several Node.js platform branches, and only installs the latest version of the Node.js major version corresponding with the platform branch on each platform version. For example, each platform version in the Node.js 12 platform branch only has Node.js 12.x.y installed by default. On Amazon Linux AMI platform versions, we installed the multiple versions of multiple Node.js versions on each platform version, and only maintained a single platform branch. Choose the Node.js platform branch that corresponds with the Node.js major version that your application needs. |
| Apache HTTPD log file names | On AL2023/AL2 platforms, if you use the Apache HTTPD proxy server, the HTTPD log file names are `access_log` and `error_log`, which is consistent with all other platforms that support Apache HTTPD. On Amazon Linux AMI platform versions, these log files were named `access.log` and `error.log`, respectively. For details about log file names and locations for all platforms, see [How Elastic Beanstalk sets up CloudWatch Logs](AWSHowTo.cloudwatchlogs.md#AWSHowTo.cloudwatchlogs.loggroups). |
| Configuration options | On AL2023/AL2 platforms, Elastic Beanstalk doesn't support the configuration options in the `aws:elasticbeanstalk:container:nodejs` namespace. Some of the options have alternatives. Here's the migration information for each option. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/using-features.migration-al.generic.from-al1.html) |
| `NodeCommand` | Use a `Procfile` or the `scripts` keyword in a `package.json` file to specify the start script. |
| `NodeVersion` | Use the `engines` keyword in a `package.json` file to specify the Node.js version. Be aware that you can only specify a Node.js version that correspondes with your platform branch. For example, if you're using the Node.js 12 platform branch, you can specify only a 12.x.y Node.js version. For details, see [Specifying Node.js dependencies with a package.json file](nodejs-platform-dependencies.md#nodejs-platform-packagejson). |
| `GzipCompression` | Unsupported on AL2023/AL2 platform versions. |
| `ProxyServer` | On AL2023/AL2 Node.js platform versions, this option moved to the `aws:elasticbeanstalk:environment:proxy` namespace. You can choose between `nginx` (the default) and `apache`. AL2023/AL2 Node.js platform versions don't support standalone applications that don't run behind a proxy server. On Amazon Linux AMI Node.js platform versions, this used to be possible through the `none` value of the `ProxyServer` option in the `aws:elasticbeanstalk:container:nodejs` namespace. If your environment runs a standalone application, update your code to listen to the port that the proxy server (nginx or Apache) forwards traffic to. var port = process.env.PORT || 5000;
app.listen(port, function() {
console.log('Server running at http://127.0.0.1:%s', port);
});
|
### PHP
The following table lists migration information for the AL2023/AL2 platform versions in the [PHP platform](create_deploy_PHP.container.md).
| **Area** | **Changes and information** |
| --- | --- |
| PHP file processing | On AL2023/AL2 platforms, PHP files are processed using PHP-FPM (a CGI process manager). On Amazon Linux AMI platforms we used mod\$1php (an Apache module). |
| Proxy server | AL2023/AL2 PHP platform versions support both the nginx and the Apache HTTPD proxy servers. The default is nginx. Amazon Linux AMI PHP platform versions supported only Apache HTTPD. If you added custom Apache configuration files, you can set the `ProxyServer` option in the `aws:elasticbeanstalk:environment:proxy` namespace to `apache`. |
### Python
The following table lists migration information for the AL2023/AL2 platform versions in the [Python platform](create-deploy-python-container.md).
| **Area** | **Changes and information** |
| --- | --- |
| WSGI server | On AL2023/AL2 platforms, [Gunicorn](https://gunicorn.org/) is the default WSGI server. By default, Gunicorn listens on port 8000. The port might be different than what your application used on the Amazon Linux AMI platform. If you're setting the `WSGIPath` option of the `[aws:elasticbeanstalk:container:python](command-options-specific.md#command-options-python)` namespace, replace the value with Gunicorn's syntax. For details, see [Python configuration namespaces](create-deploy-python-container.md#python-namespaces). Alternatively, you can use a `Procfile` to specify and configure the WSGI server. For details, see [Configuring the WSGI server with a Procfile on Elastic Beanstalk](python-configuration-procfile.md). |
| Application path | On AL2023/AL2 platforms, the path to the application's directory on Amazon EC2 instances of your environment is `/var/app/current`. It was `/opt/python/current/app` on Amazon Linux AMI platforms. |
| Proxy server | AL2023/AL2 Python platform versions support both the nginx and the Apache HTTPD proxy servers. The default is nginx. Amazon Linux AMI Python platform versions supported only Apache HTTPD. If you added custom Apache configuration files, you can set the `ProxyServer` option in the `aws:elasticbeanstalk:environment:proxy` namespace to `apache`. |
### Ruby
The following table lists migration information for the AL2023/AL2 platform versions in the [Ruby platform](create_deploy_Ruby.container.md).
| **Area** | **Changes and information** |
| --- | --- |
| Installed Ruby versions | On AL2023/AL2 platforms, Elastic Beanstalk only installs the latest version of a single Ruby version, corresponding with the platform branch, on each platform version. For example, each platform version in the Ruby 2.6 platform branch only has Ruby 2.6.x installed. On Amazon Linux AMI platform versions, we installed the latest versions of multiple Ruby versions, for example, 2.4.x, 2.5.x, and 2.6.x. If your application uses a Ruby version that doesn't correspond to the platform branch you're using, we recommend that you switch to a platform branch that has the correct Ruby version for your application. |
| Application server | On AL2023/AL2 platforms, Elastic Beanstalk only installs the Puma application server on all Ruby platform versions. You can use a `Procfile` to start a different application server, and a `Gemfile` to install it. On the Amazon Linux AMI platform, we supported two flavors of platform branches for each Ruby version—one with the Puma application server and the other with the Passenger application server. If your application uses Passenger, you can configure your Ruby environment to install and use Passenger. For more information and examples, see [Using the Elastic Beanstalk Ruby platform](create_deploy_Ruby.container.md). |
# Platform retirement FAQ
**Note**
Elastic Beanstalk retired all platform branches based on Amazon Linux AMI (AL1) on July 18, 2022 .
The answers in this FAQ reference the following topics:
+ [Elastic Beanstalk platform support policy](platforms-support-policy.md)
+ [Retired platform branch history](platforms-schedule.md#platforms-support-policy.retired)
+ [ Elastic Beanstalk supported platforms](https://docs.aws.amazon.com/elasticbeanstalk/latest/platforms/platforms-supported.html) in *AWS Elastic Beanstalk Platforms*
+ [Migrating your Elastic Beanstalk Linux application to Amazon Linux 2023 or Amazon Linux 2](using-features.migration-al.md)
+ [Amazon Linux 2 FAQs](https://aws.amazon.com//amazon-linux-2/faqs/).
## 1. What does retirement of a platform branch mean?
Following the announced retirement date of a platform branch, you will no longer be able to create a new environment based on the retired platform branch, unless you already have an active environment based on that platform branch. For more information, see [FAQ \$111](#using-features.migration-al.FAQ.new-env-create). Elastic Beanstalk will stop providing new maintenance updates for these platform branches. A retired platform branch isn't recommended for use in production environments. For more information, see [FAQ \$15](#using-features.migration-al.FAQ.remove-components).
## 2. Why has AWS retired the AL1-based platforms branches?
Elastic Beanstalk retires platform branches when platform components are deprecated or retired by their vendors. In this case, the Amazon Linux AMI (AL1) has ended standard support as of [December 31, 2020](https://aws.amazon.com/blogs/aws/update-on-amazon-linux-ami-end-of-life/). While Elastic Beanstalk continued to offer AL1 based platforms through 2022, we have since released AL2 and AL2023 and based platforms that have the latest features. In order for customers to continue to benefit from the latest security and features going forward, it's critical for customers to migrate to our AL2 or AL2023 based platforms.
## 3. Which platform branches are retired?
For a list of platform components and platform branches that have been retired, see [Retired platform branch history](platforms-schedule.md#platforms-support-policy.retired).
## 4. Which platforms are currently supported?
See [ Elastic Beanstalk supported platforms](https://docs.aws.amazon.com/elasticbeanstalk/latest/platforms/platforms-supported.html) in *AWS Elastic Beanstalk Platforms*.
## 5. Will Elastic Beanstalk remove or terminate any components of my environment after retirement?
Our policy for retired platform branches does not remove access to environments nor delete resources. However, an environment based on a retired platform branch can end up in an unpredictable situation, because Elastic Beanstalk isn't able to provide security updates, technical support, or hotfixes for retired platform branches due to the supplier marking their component as End of Life (EOL). For example, a detrimental and critical security vulnerability may surface in an environment running on a retired platform branch. Or an EB API action may stop working for the environment if it becomes incompatible with the Elastic Beanstalk service over time. The opportunity for these types of risks increases the longer an environment based on a retired platform branch remains active.
If your application should encounter issues while running on a retired platform branch and you're not able to migrate it to a supported platform, you'll need to consider other alternatives. Workarounds include encapsulating the application into a Docker image to run it as a Docker container. This would allow a customer to use any of our Docker solutions, such as our Elastic Beanstalk AL2023/AL2 Docker platforms, or other Docker based services such as Amazon ECS or Amazon EKS. Non-Docker alternatives include our AWS CodeDeploy service, which allows complete customization of the runtimes you desire.
## 6. Can I submit a request to extend the retirement date?
No. After the retirement date existing environments will continue to function. However, Elastic Beanstalk will no longer provide platform maintenance and security updates. Therefore, it’s critical to migrate to AL2 or AL2023 if you are still running applications on an AL1-based platform. For more information about risks and workarounds, see [FAQ \$15](#using-features.migration-al.FAQ.remove-components).
## 7. What are the workarounds if I can't complete my AL2 or AL2023 migration in time?
Customers may continue to run the environment, although we strongly encourage you to plan to migrate all of your Elastic Beanstalk environments to a supported platform version. Doing so will minimize risk and provide continued benefit from important security, performance, and functionality enhancements offered in more recent releases. For more information about risks and workarounds, see [FAQ \$15](#using-features.migration-al.FAQ.remove-components).
## 8. What is the recommended process to migrate to AL2 or AL2023 platforms?
For comprehensive AL1 to AL2023/AL2 migration instructions, see [Migrating your Elastic Beanstalk Linux application to Amazon Linux 2023 or Amazon Linux 2](using-features.migration-al.md). This topic explains that Elastic Beanstalk requires a blue/green deployment to perform the upgrade.
## 9. If I have an environment running on a retired platform, what would be the impact?
An environment based on a retired platform branch can end up in an unpredictable situation, because Elastic Beanstalk isn't able to provide security updates, technical support, or hotfixes for retired platform branches due to the supplier marking their component as End of Life (EOL). For example, a detrimental and critical security vulnerability may surface in an environment running on a retired platform branch. Or an EB API action may stop working for the environment if it becomes incompatible with the Elastic Beanstalk service over time. The opportunity for these types of risks increases the longer an environment on a retired platform branch remains active. For more information, see [FAQ \$15](#using-features.migration-al.FAQ.remove-components).
## 10. What happens 90 days after the retirement date?
Our policy for retired platform branches does not remove access to environments nor delete resources. However, be aware that an environment based on a retired platform branch can end up in an unpredictable situation, because Elastic Beanstalk isn't able to provide security updates, technical support, or hotfixes for retired platform branches due to the supplier marking their component as End of Life (EOL). For example, a detrimental and critical security vulnerability may surface in an environment running on a retired platform branch. Or an EB API action may stop working for the environment if it becomes incompatible with the Elastic Beanstalk service over time. The opportunity for these types of risks increases the longer an environment on a retired platform branch remains active. For more information see [FAQ \$15](#using-features.migration-al.FAQ.remove-components).
## 11. Can I create a new environment based on a retired platform?
You can create a new environment based on a retired platform branch, if you've already used that platform branch to create an existing environment using the same account and in the same region. The retired platform branch will not be available in the Elastic Beanstalk console. However, for customers that have existing environments based on a retired platform branch, it will be available through the EB CLI, EB API, and AWS CLI. Also, existing customers can use the [Clone environment](using-features.managing.clone.md) and [Rebuild environment](environment-management-rebuild.md) consoles. However, be aware that an environment based on a retired platform branch can end up in an unpredictable situation. For more information, see [FAQ \$15](#using-features.migration-al.FAQ.remove-components).
## 12. If I have an existing environment running on a retired platform branch, until when can I create a new environment based on the retired platform branch? Can I do so using the console, CLI or API?
You can create the environment after the retirement date. However, keep in mind that a retired platform branch can end up in an unpredictable situation. The further out in time such an environment an environment is created or active, the higher the risk for the environment to encounter unexpected issues. For more information about creating a new environment, see [FAQ \$111](#using-features.migration-al.FAQ.new-env-create).
## 13. Can I clone or rebuild my environment which is based on retired platform?
Yes. You can do so using the [Clone environment](using-features.managing.clone.md) and [Rebuild environment](environment-management-rebuild.md) consoles. You can also use the EB CLI, EB API, and AWS CLI. For more information about creating a new environment, see [FAQ \$111](#using-features.migration-al.FAQ.new-env-create).
However, we strongly encourage you to plan to migrate all your Elastic Beanstalk environments to a supported platform version. Doing so will minimize risk and provide continued benefit from important security, performance, and functionality enhancements offered in more recent releases. For more information about risks and workarounds, see [FAQ \$15](#using-features.migration-al.FAQ.remove-components).
## 14. After the retirement date, what would happen to the AWS resources of my Elastic Beanstalk environment that is based on a retired platform branch? For example, if the running EC2 instance gets terminated, would Elastic Beanstalk be able to launch a new AL1 based EC2 instance to maintain capacity?
The environment’s resources would remain active and continue to function. And, yes, Elastic Beanstalk will auto scale for AL1 EC2 instances in the environment. However, Elastic Beanstalk will stop providing new platform maintenance updates to the environment, which can lead to the environment ending up in an unpredictable situation over time. For more information, see [FAQ \$15](#using-features.migration-al.FAQ.remove-components).
## 15. What are key differences between the AL2023/AL2 and Amazon Linux AMI (AL1) operating systems? How are the Elastic Beanstalk AL2023/AL2 platform branches affected?
Although Amazon Linux AMI and AL2023/AL2 share the same Linux kernel, they differ in their initialization system, `libc` versions, the compiler tool chain, and various packages. For more information, see [Amazon Linux 2 FAQs](https://aws.amazon.com//amazon-linux-2/faqs/).
The Elastic Beanstalk service has also updated platform specific versions of runtime, build tools, and other dependencies. The AL2023/AL2 based platform branches aren't guaranteed to be backward compatible with your existing application. Furthermore, even if your application code successfully deploys to the new platform version, it might behave or perform differently due to operating system and run time differences. For a list and description of configurations and customizations that you'll need to review and test, see [Migrating your Elastic Beanstalk Linux application to Amazon Linux 2023 or Amazon Linux 2](using-features.migration-al.md).
# Canceling environment configuration updates and application deployments
You can cancel in-progress updates that are triggered by environment configuration changes. You can also cancel the deployment of a new application version in progress. For example, you might want to cancel an update if you decide you want to continue using the existing environment configuration instead of applying new environment configuration settings. Or, you might realize that the new application version that you are deploying has problems that will cause it to not start or not run properly. By canceling an environment update or application version update, you can avoid waiting until the update or deployment process is done before you begin a new attempt to update the environment or application version.
**Note**
During the cleanup phase in which old resources that are no longer needed are removed, after the last batch of instances has been updated, you can no longer cancel the update.
Elastic Beanstalk performs the rollback the same way that it performed the last successful update. For example, if you have time-based rolling updates enabled in your environment, then Elastic Beanstalk will wait the specified pause time between rolling back changes on one batch of instances before rolling back changes on the next batch. Or, if you recently turned on rolling updates, but the last time you successfully updated your environment configuration settings was without rolling updates, Elastic Beanstalk will perform the rollback on all instances simultaneously.
You cannot stop Elastic Beanstalk from rolling back to the previous environment configuration once it begins to cancel the update. The rollback process continues until all instances in the environment have the previous environment configuration or until the rollback process fails. For application version deployments, canceling the deployment simply stops the deployment; some instances will have the new application version and others will continue to run the existing application version. You can deploy the same or another application version later.
For more information about rolling updates, see [Elastic Beanstalk rolling environment configuration updates](using-features.rollingupdates.md). For more information about batched application version deployments, see [Deployment policies and settings](using-features.rolling-version-deploy.md).
**To cancel an update**
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. On the environment overview page, choose **Actions**, and then choose **Abort current operation**.
# Rebuilding Elastic Beanstalk environments
Your AWS Elastic Beanstalk environment can become unusable if you don't use Elastic Beanstalk functionality to modify or terminate the environment's underlying AWS resources. If this happens, you can **rebuild** the environment to attempt to restore it to a working state. Rebuilding an environment terminates all of its resources and replaces them with new resources with the same configuration.
You can also rebuild terminated environments within six weeks (42 days) of their termination. When you rebuild, Elastic Beanstalk attempts to create a new environment with the same name, ID, and configuration.
## Rebuilding a running environment
You can rebuild an environment through the Elastic Beanstalk console or by using the `RebuildEnvironment` API.
**Warning**
If your environment has a coupled database, **it will be deleted as part of the rebuild**, and the new database in the rebuilt environment will not contain the previous data. If you would like to retain the database or take a snapshot, make sure you have the database deletion policy configured properly for the desired results after it's rebuilt. For more information, see [Database lifecycle](using-features.managing.db.md#environments-cfg-rds-lifecycle).
**To rebuild a running environment (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. Choose **Actions**, and then choose **Rebuild environment**.
1. Choose **Rebuild**.
To rebuild a running environment with the Elastic Beanstalk API, use the [https://docs.aws.amazon.com/elasticbeanstalk/latest/api/API_RebuildEnvironment.html](https://docs.aws.amazon.com/elasticbeanstalk/latest/api/API_RebuildEnvironment.html) action with the AWS CLI or the AWS SDK.
```
$ aws elasticbeanstalk rebuild-environment --environment-id e-vdnftxubwq
```
## Rebuilding a terminated environment
You can rebuild and restore a terminated environment by using the Elastic Beanstalk console, the EB CLI, or the `RebuildEnvironment` API.
**Note**
Unless you are using your own custom domain name with your terminated environment, the environment uses a subdomain of elasticbeanstalk.com. These subdomains are shared within an Elastic Beanstalk region. Therefore, they can be used by any environment created by any customer in the same region. While your environment was terminated, another environment could use its subdomain. In this case, the rebuild would fail.
You can avoid this issue by using a custom domain. See [Your Elastic Beanstalk environment's Domain name](customdomains.md) for details.
Recently terminated environments appear in the application overview for up to an hour. During this time, you can view events for the environment in its [dashboard](environments-console.md), and use the **Restore environment** [action](environments-dashboard-actions.md) to rebuild it.
To rebuild an environment that is no longer visible, use the **Restore terminated environment** option from the application page.
**To rebuild a terminated environment (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 **Applications**, and then choose your application's name from the list.
1. Choose **Actions**, and then choose **Restore terminated environment**.
![\[Actions dropdown menu with "Restore terminated environment" option highlighted.\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/applications-restoreenvironment.png)
1. Choose a terminated environment.
1. Choose **Restore**.
![\[Table showing terminated environment details with options to cancel or restore.\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/applications-restoreenvironment-modal.png)
Elastic Beanstalk attempts to create a new environment with the same name, ID, and configuration. If an environment with the same name or URL exists when you attempt to rebuild, the rebuild fails. Deleting the application version that was deployed to the environment will also cause the rebuild to fail.
If you use the EB CLI to manage your environment, use the **eb restore** command to rebuild a terminated environment.
```
$ eb restore e-vdnftxubwq
```
See [**eb restore**](eb3-restore.md) for more information.
To rebuild a terminated environment with the Elastic Beanstalk API, use the [https://docs.aws.amazon.com/elasticbeanstalk/latest/api/API_RebuildEnvironment.html](https://docs.aws.amazon.com/elasticbeanstalk/latest/api/API_RebuildEnvironment.html) action with the AWS CLI or the AWS SDK.
```
$ aws elasticbeanstalk rebuild-environment --environment-id e-vdnftxubwq
```
# Environment types
In AWS Elastic Beanstalk, you can create a load-balanced, scalable environment or a single-instance environment. The type of environment that you require depends on the application that you deploy. For example, you can develop and test an application in a single-instance environment to save costs and then upgrade that environment to a load-balanced, scalable environment when the application is ready for production.
**Note**
A worker environment tier for a web application that processes background tasks doesn't include a load balancer. However, a worker environment does effectively scale out by adding instances to the Auto Scaling group to process data from the Amazon SQS queue when the load necessitates it.
## Load-balanced, scalable environment
A load-balanced and scalable environment uses the Elastic Load Balancing and Amazon EC2 Auto Scaling services to provision the Amazon EC2 instances that are required for your deployed application. Amazon EC2 Auto Scaling automatically starts additional instances to accommodate increasing load on your application. If the load on your application decreases, Amazon EC2 Auto Scaling stops instances but always leaves your specified minimum number of instances running. If your application requires scalability with the option of running in multiple Availability Zones, use a load-balanced, scalable environment. If you're not sure which environment type to select, you can pick one and, if required, switch the environment type later.
## Single-instance environment
A single-instance environment contains one Amazon EC2 instance with an Elastic IP address. A single-instance environment doesn't have a load balancer, which can help you reduce costs compared to a load-balanced, scalable environment. Although a single-instance environment does use the Amazon EC2 Auto Scaling service, settings for the minimum number of instances, maximum number of instances, and desired capacity are all set to 1. Consequently, new instances are not started to accommodate increasing load on your application.
Use a single-instance environment if you expect your production application to have low traffic or if you are doing remote development. If you're not sure which environment type to select, you can pick one and, if required, you can switch the environment type later. For more information, see [Changing environment type](#using-features.managing.changetype).
## Changing environment type
You can change your environment type to a single-instance or load-balanced, scalable environment by editing your environment's configuration. In some cases, you might want to change your environment type from one type to another. For example, let's say that you developed and tested an application in a single-instance environment to save costs. When your application is ready for production, you can change the environment type to a load-balanced, scalable environment so that it can scale to meet the demands of your customers.
**To change an environment's type**
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 **Capacity** category, choose **Edit**.
1. From the **Environment Type** list, select the type of environment that you want.
![\[The Auto Scaling group section of the modify capacity page\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/using-features-managing-env-types.png)
1. Choose **Save**.
It can take several minutes for the environment to update while Elastic Beanstalk provisions AWS resources.
If your environment is in a VPC, select subnets to place Elastic Load Balancing and Amazon EC2 instances in. Each Availability Zone that your application runs in must have both. See [Using Elastic Beanstalk with Amazon VPC](vpc.md) for details.
# Elastic Beanstalk worker environments
If your AWS Elastic Beanstalk application performs operations or workflows that take a long time to complete, you can offload those tasks to a dedicated *worker environment*. Decoupling your web application front end from a process that performs blocking operations is a common way to ensure that your application stays responsive under load.
A long-running task is anything that substantially increases the time it takes to complete a request, such as processing images or videos, sending email, or generating a ZIP archive. These operations can take only a second or two to complete, but a delay of a few seconds is a lot for a web request that would otherwise complete in less than 500 ms.
One option is to spawn a worker process locally, return success, and process the task asynchronously. This works if your instance can keep up with all of the tasks sent to it. Under high load, however, an instance can become overwhelmed with background tasks and become unresponsive to higher priority requests. If individual users can generate multiple tasks, the increase in load might not correspond to an increase in users, making it hard to scale out your web server tier effectively.
To avoid running long-running tasks locally, you can use the AWS SDK for your programming language to send them to an Amazon Simple Queue Service (Amazon SQS) queue, and run the process that performs them on a separate set of instances. You then design these worker instances to take items from the queue only when they have capacity to run them, preventing them from becoming overwhelmed.
Elastic Beanstalk worker environments simplify this process by managing the Amazon SQS queue and running a [daemon process](#worker-daemon) on each instance that reads from the queue for you. When the daemon pulls an item from the queue, it sends an HTTP POST request locally to `http://localhost/` on port 80 with the contents of the queue message in the body. All that your application needs to do is perform the long-running task in response to the POST. You can [configure the daemon](#using-features-managing-env-tiers-worker-settings) to post to a different path, use a MIME type other than application/JSON, connect to an existing queue, or customize connections (maximum concurrent requests), timeouts, and retries.
![\[Elastic Beanstalk worker environment Amazon SQS message processing\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/aeb-messageflow-worker.png)
With [periodic tasks](#worker-periodictasks), you can also configure the worker daemon to queue messages based on a cron schedule. Each periodic task can POST to a different path. Enable periodic tasks by including a YAML file in your source code that defines the schedule and path for each task.
**Note**
The [.NET on Windows Server platform](create_deploy_NET.md) doesn't support worker environments.
**Topics**
+ [The worker environment SQS daemon](#worker-daemon)
+ [Dead-letter queues](#worker-deadletter)
+ [Periodic tasks](#worker-periodictasks)
+ [Use Amazon CloudWatch for automatic scaling in worker environment tiers](#worker-scaling)
+ [Configuring worker environments](#using-features-managing-env-tiers-worker-settings)
## The worker environment SQS daemon
Worker environments run a daemon process provided by Elastic Beanstalk. This daemon is updated regularly to add features and fix bugs. To get the latest version of the daemon, update to the latest [platform version](concepts.platforms.md).
When the application in the worker environment returns a `200 OK` response to acknowledge that it has received and successfully processed the request, the daemon sends a `DeleteMessage` call to the Amazon SQS queue to delete the message from the queue. If the application returns any response other than `200 OK`, Elastic Beanstalk waits to put the message back in the queue after the configured `ErrorVisibilityTimeout` period. If there is no response, Elastic Beanstalk waits to put the message back in the queue after the `InactivityTimeout` period so that the message is available for another attempt at processing.
**Note**
The properties of Amazon SQS queues (message order, at-least-once delivery, and message sampling) can affect how you design a web application for a worker environment. For more information, see [Properties of Distributed Queues](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/DistributedQueues.html) in the [Amazon Simple Queue Service Developer Guide](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/Welcome.html).
Amazon SQS automatically deletes messages that have been in a queue for longer than the configured `RetentionPeriod`.
The daemon sets the following HTTP headers.
****
| **HTTP headers** |
| --- |
| **Name** | **Value** |
| --- |--- |
| `User-Agent` | `aws-sqsd` `aws-sqsd/1.1`1 |
| `X-Aws-Sqsd-Msgid` | SQS message ID, used to detect message storms (an unusually high number of new messages). |
| `X-Aws-Sqsd-Queue` | Name of the SQS queue. |
| `X-Aws-Sqsd-First-Received-At` | UTC time, in [ISO 8601 format](http://www.w3.org/TR/NOTE-datetime), when the message was first received. |
| `X-Aws-Sqsd-Receive-Count` | SQS message receive count. |
| `X-Aws-Sqsd-Attr-message-attribute-name` | Custom message attributes assigned to the message being processed. The `message-attribute-name` is the actual message attribute name. All string and number message attributes are added to the header. Binary attributes are discarded and not included in the header. |
| `Content-Type` | Mime type configuration; by default, `application/json`. |
## Dead-letter queues
Elastic Beanstalk worker environments support Amazon Simple Queue Service (Amazon SQS) dead-letter queues. A dead-letter queue is a queue where other (source) queues can send messages that for some reason could not be successfully processed. A primary benefit of using a dead-letter queue is the ability to sideline and isolate the unsuccessfully processed messages. You can then analyze any messages sent to the dead-letter queue to try to determine why they were not successfully processed.
If you specify an autogenerated Amazon SQS queue at the time you create your worker environment tier, a dead-letter queue is enabled by default for a worker environment. If you choose an existing SQS queue for your worker environment, you must use SQS to configure a dead-letter queue independently. For information about how to use SQS to configure a dead-letter queue, see [Using Amazon SQS Dead Letter Queues](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/SQSDeadLetterQueue.html).
You cannot disable dead-letter queues. Messages that cannot be delivered are always eventually sent to a dead-letter queue. You can, however, effectively disable this feature by setting the `MaxRetries` option to the maximum valid value of 100.
If a dead-letter queue isn't configured for your worker environment's Amazon SQS queue, Amazon SQS keeps messages on the queue until the retention period expires. For details about configuring the retention period, see [Configuring worker environments](#using-features-managing-env-tiers-worker-settings).
**Note**
The Elastic Beanstalk `MaxRetries` option is equivalent to the SQS `MaxReceiveCount` option. If your worker environment doesn't use an autogenerated SQS queue, use the `MaxReceiveCount` option in SQS to effectively disable your dead-letter queue. For more information, see [Using Amazon SQS Dead Letter Queues](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/SQSDeadLetterQueue.html).
For more information about the lifecycle of an SQS message, go to [Message Lifecycle](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/MessageLifecycle.html).
## Periodic tasks
You can define periodic tasks in a file named `cron.yaml` in your source bundle to add jobs to your worker environment's queue automatically at a regular interval.
For example, the following `cron.yaml` file creates two periodic tasks. The first one runs every 12 hours and the second one runs at 11 PM UTC every day.
**Example cron.yaml**
```
version: 1
cron:
- name: "backup-job"
url: "/backup"
schedule: "0 */12 * * *"
- name: "audit"
url: "/audit"
schedule: "0 23 * * *"
```
The **name** must be unique for each task. The URL is the path to which the POST request is sent to trigger the job. The schedule is a [CRON expression](http://en.wikipedia.org/wiki/Cron#CRON_expression) that determines when the task runs.
When a task runs, the daemon posts a message to the environment's SQS queue with a header indicating the job that needs to be performed. Any instance in the environment can pick up the message and process the job.
**Note**
If you configure your worker environment with an existing SQS queue and choose an [Amazon SQS FIFO queue](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/FIFO-queues.html), periodic tasks aren't supported.
Elastic Beanstalk uses leader election to determine which instance in your worker environment queues the periodic task. Each instance attempts to become leader by writing to an Amazon DynamoDB table. The first instance that succeeds is the leader, and must continue to write to the table to maintain leader status. If the leader goes out of service, another instance quickly takes its place.
For periodic tasks, the worker daemon sets the following additional headers.
****
| **HTTP headers** |
| --- |
| **Name** | **Value** |
| --- |--- |
| `X-Aws-Sqsd-Taskname` | For periodic tasks, the name of the task to perform. |
| `X-Aws-Sqsd-Scheduled-At` | Time at which the periodic task was scheduled |
| `X-Aws-Sqsd-Sender-Id` | AWS account number of the sender of the message |
## Use Amazon CloudWatch for automatic scaling in worker environment tiers
Together, Amazon EC2 Auto Scaling and CloudWatch monitor the CPU utilization of the running instances in the worker environment. How you configure the automatic scaling limit for CPU capacity determines how many instances the Auto Scaling group runs to appropriately manage the throughput of messages in the Amazon SQS queue. Each EC2 instance publishes its CPU utilization metrics to CloudWatch. Amazon EC2 Auto Scaling retrieves from CloudWatch the average CPU usage across all instances in the worker environment. You configure the upper and lower threshold as well as how many instances to add or terminate according to CPU capacity. When Amazon EC2 Auto Scaling detects that you have reached the specified upper threshold on CPU capacity, Elastic Beanstalk creates new instances in the worker environment. The instances are deleted when the CPU load drops back below the threshold.
**Note**
Messages that have not been processed at the time an instance is terminated are returned to the queue where they can be processed by another daemon on an instance that is still running.
You can also set other CloudWatch alarms, as needed, by using the Elastic Beanstalk console, CLI, or the options file. For more information, see [Using Elastic Beanstalk with Amazon CloudWatch](AWSHowTo.cloudwatch.md) and [Create an Auto Scaling group with Step Scaling Policies](https://docs.aws.amazon.com/autoscaling/ec2/userguide/as-scaling-simple-step.html#policy-creating-asg-console).
## Configuring worker environments
You can manage a worker environment's configuration by editing the **Worker** category on the **Configuration** page in the [environment management console](environments-console.md).
![\[Modify worker configuration page in the Elastic Beanstalk console\]](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/images/aeb-config-worker.png)
**Note**
You can configure the URL path for posting worker queue messages, but you can't configure the IP port. Elastic Beanstalk always posts worker queue messages on port 80. The worker environment application or its proxy must listen to port 80.
**To configure the worker daemon**
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 **Worker** configuration category, choose **Edit**.
The **Modify worker** configuration page has the following options.
In the **Queue** section:
+ **Worker queue** – Specify the Amazon SQS queue from which the daemon reads. If you have one, you can choose an existing queue. If you choose **Autogenerated queue**, Elastic Beanstalk creates a new Amazon SQS queue and a corresponding **Worker queue URL**.
**Note**
When you choose **Autogenerated queue**, the queue that Elastic Beanstalk creates is a [standard](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/standard-queues.html) Amazon SQS queue. When you choose an existing queue, you can provide either a standard or a [FIFO](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/FIFO-queues.html) Amazon SQS queue. Be aware that if you provide a FIFO queue, [periodic tasks](#worker-periodictasks) aren't supported.
+ **Worker queue URL** – If you choose an existing **Worker queue**, this setting displays the URL associated with that Amazon SQS queue.
In the **Messages** section:
+ **HTTP path** – Specify the relative path to the application that will receive the data from the Amazon SQS queue. The data is inserted into the message body of an HTTP POST message. The default value is `/`.
+ **MIME type** – Indicate the MIME type that the HTTP POST message uses. The default value is `application/json`. However, any value is valid because you can create and then specify your own MIME type.
+ **HTTP connections** – Specify the maximum number of concurrent connections that the daemon can make to any application within an Amazon EC2 instance. The default is **50**. You can specify **1** to **100**.
+ **Visibility timeout** – Indicate the amount of time, in seconds, an incoming message from the Amazon SQS queue is locked for processing. After the configured amount of time has passed, the message is again made visible in the queue for another daemon to read. Choose a value that is longer than you expect your application requires to process messages, up to **43200** seconds.
+ **Error visibility timeout** – Indicate the amount of time, in seconds, that elapses before Elastic Beanstalk returns a message to the Amazon SQS queue after an attempt to process it fails with an explicit error. You can specify **0** to **43200** seconds.
In the **Advanced options** section:
+ **Max retries** – Specify the maximum number of times Elastic Beanstalk attempts to send the message to the Amazon SQS queue before moving the message to the [dead-letter queue](#worker-deadletter). The default value is **10**. You can specify **1** to **100**.
**Note**
The **Max retries** option only applies to Amazon SQS queues that are configured with a dead-letter queue. For any Amazon SQS queues that aren't configured with a dead-letter queue, Amazon SQS retains messages in the queue and processes them until the period specified by the **Retention period** option expires.
+ **Connection timeout** – Indicate the amount of time, in seconds, to wait for successful connections to an application. The default value is **5**. You can specify **1** to **60** seconds.
+ **Inactivity timeout** – Indicate the amount of time, in seconds, to wait for a response on an existing connection to an application. The default value is **180**. You can specify **1** to **36000** seconds.
+ **Retention period** – Indicate the amount of time, in seconds, a message is valid and is actively processed. The default value is **345600**. You can specify **60** to **1209600** seconds.
If you use an existing Amazon SQS queue, the settings that you configure when you create a worker environment can conflict with settings you configured directly in Amazon SQS. For example, if you configure a worker environment with a `RetentionPeriod` value that is higher than the `MessageRetentionPeriod` value you set in Amazon SQS, Amazon SQS deletes the message when it exceeds the `MessageRetentionPeriod`.
Conversely, if the `RetentionPeriod` value you configure in the worker environment settings is lower than the `MessageRetentionPeriod` value you set in Amazon SQS, the daemon deletes the message before Amazon SQS can. For `VisibilityTimeout`, the value that you configure for the daemon in the worker environment settings overrides the Amazon SQS `VisibilityTimeout` setting. Ensure that messages are deleted appropriately by comparing your Elastic Beanstalk settings to your Amazon SQS settings.
# Creating links between Elastic Beanstalk environments
As your application grows in size and complexity, you may want to split it into components that have different development and operational lifecycles. By running smaller services that interact with each other over a well defined interface, teams can work independently and deployments can be lower risk. AWS Elastic Beanstalk lets you link your environments to share information between components that depend on one another.
**Note**
Elastic Beanstalk currently supports environment links for all platforms except Multicontainer Docker.
With environment links, you can specify the connections between your application’s component environments as named references. When you create an environment that defines a link, Elastic Beanstalk sets an environment variable with the same name as the link. The value of the variable is the endpoint that you can use to connect to the other component, which can be a web server or worker environment.
For example, if your application consists of a frontend that collects email addresses and a worker that sends a welcome email to the email addresses collected by the frontend, you can create a link to the worker in your frontend and have the frontend automatically discover the endpoint (queue URL) for your worker.
Define links to other environments in an [environment manifest](environment-cfg-manifest.md), a YAML formatted file named `env.yaml` in the root of your application source. The following manifest defines a link to an environment named worker:
**`~/workspace/my-app/frontend/env.yaml`**
```
AWSConfigurationTemplateVersion: 1.1.0.0
EnvironmentLinks:
"WORKERQUEUE": "worker"
```
When you create an environment with an application version that includes the above environment manifest, Elastic Beanstalk looks for an environment named `worker` that belongs to the same application. If that environment exists, Elastic Beanstalk creates an environment property named `WORKERQUEUE`. The value of `WORKERQUEUE` is the Amazon SQS queue URL. The frontend application can read this property in the same manner as an environment variable. See [Environment manifest (`env.yaml`)](environment-cfg-manifest.md) for details.
To use environment links, add an environment manifest to your application source and upload it with the EB CLI, AWS CLI or an SDK. If you use the AWS CLI or an SDK, set the `process` flag when you call `CreateApplicationVersion`:
```
$ aws elasticbeanstalk create-application-version --process --application-name my-app --version-label frontend-v1 --source-bundle S3Bucket="amzn-s3-demo-bucket",S3Key="front-v1.zip"
```
This option tells Elastic Beanstalk to validate the environment manifest and configuration files in your source bundle when you create the application version. The EB CLI sets this flag automatically when you have an environment manifest in your project directory.
Create your environments normally using any client. When you need to terminate environments, terminate the environment with the link first. If an environment is linked to by another environment, Elastic Beanstalk will prevent the linked environment from being terminated. To override this protection, use the `ForceTerminate` flag. This parameter is available in the AWS CLI as `--force-terminate`:
```
$ aws elasticbeanstalk terminate-environment --force-terminate --environment-name worker
```
# Recovering your Elastic Beanstalk environment from an invalid state
This topic provides some background information and resources that explain how to troubleshoot an Elastic Beanstalk environment in an invalid state.
## Addressing the error
Standard operations on an environment in an invalid state will not complete successfully. The failed operation will return an error that includes the following text:
```
The stack stack_id associated with environment environment-ID is in stack-status state.
```
To troubleshoot and resolve this error, see the Knowledge Center article [ Why is my Elastic Beanstalk environment in the invalid state?](https://repost.aws/knowledge-center/elastic-beanstalk-invalid-state).
**Note**
Prior to [December 16, 2024](https://docs.aws.amazon.com/elasticbeanstalk/latest/relnotes/release-2024-12-16-release-notes.html), the failing operation returned the following error instead: `Environment is in an invalid state for this operation. Must be ready.` In this case you had to contact AWS Support to reset the environment status after you completed the corrective actions.
Today you must still resolve the stack issues following the instructions in the referenced [Knowledge Center article](https://repost.aws/knowledge-center/elastic-beanstalk-invalid-state). However, once you successfully complete the corrective actions, Elastic Beanstalk automatically updates the environment's status from invalid to available, and you can resume the standard operations on your environment without further delay.
## Why the error occurs
When you deploy an application in Elastic Beanstalk, the service creates an underlying AWS CloudFormation stack. Elastic Beanstalk calls the CloudFormation service to launch the resources in your environment and propagate configuration changes.
If Elastic Beanstalk performs an operation on an environment without having access to a required resource, the environment’s underlying CloudFormation stack can enter a failed state. Other issues can also lead to this state, although permission issues are the primary cause. As a result of the stack’s failed state, CloudFormation blocks Elastic Beanstalk operation requests from performing further stack updates, causing the failure of Elastic Beanstalk operations, such as UpdateEnvironment and RetrieveEnvironmentInfo.
At this point you must first correct the root cause of the underlying issue to remedy the CloudFormation stack. The Elastic Beanstalk service then detects the CloudFormation stack status change and follows through to reset your environment to an available status. At this point further operations can complete successfully.
Permission issues typically cause this effect on the CloudFormation stack and the Elastic Beanstalk environment, although out-of-band changes can also cause issues.
**Important**
To avoid disruption to your environment, we strongly recommend that you only initiate operations to manage and configure your environment from the Elastic Beanstalk service. Modification of resources by using the console, CLI commands, or SDK of a service other than Elastic Beanstalk is an out-of-band change, which causes *resource drift*. Resource drift affects the status of the CloudFormation stack, which in turn causes the Elastic Beanstalk environment to enter into an invalid state.
For more information about resource drift, see [What is drift?](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-stack-drift.html#what-is-drift) in the *AWS CloudFormation User Guide*.