How do I use .ebextensions to customize my Elastic Beanstalk environment?

Resolution

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

Set up your .ebextensions directory

Complete the following steps:

1. In the root of your application bundle, create a hidden directory named .ebextensions.
2. Store your configuration files in this directory. Your application source bundle looks similar to the following example:

   ~/workspace/my-application/
   |-- .ebextensions
   |   |-- 01-server-configuration.config
   |   `-- 02-asg-healthcheck.config
   |-- index.php
   `-- styles.css

   Note: Elastic Beanstalk processes configuration files in the .ebextensions directory in alphabetical order. Use numbered prefixes in your file names to control the order of your configurations.

Customize your Elastic Beanstalk environment

To modify your environment configuration, use the option_settings key.

If you create or update an environment with the Elastic Beanstalk console or the Elastic Beanstalk Command Line Interface (EB CLI), then these clients apply recommended values. Recommended values are set at the API level and have the highest precedence. You can't use option_settings to change the configuration setting.

Precedence rules can prevent your option_settings modifications from applying to the environment configuration. To remove settings that Elastic Beanstalk directly applied to the environment during environment creation, use the UpdateEnvironment Elastic Beanstalk API operation. Or, you can use the following update-environment AWS CLI command:

aws elasticbeanstalk update-environment --application-name applicationname --environment-name environmentnamename --options-to-remove Namespace=aws:elasticbeanstalk:application:environment,OptionName==yourpropertyname 

Note: Replace applicationname with your application name, environmentname with your environment name, and yourpropertyname with your property name.

If you can't use option_settings to change your configuration, then use the Resources key to customize resources in your Elastic Beanstalk environment.

Elastic Beanstalk adds the resources that you define in the configuration files to the AWS CloudFormation template that launches your environment. The CloudFormation template supports every CloudFormation resource type. For more information on logical resource names, see Modifying the resources that Elastic Beanstalk creates for your environment.

Configuration files must have the .config file extension and must use either the YAML or JSON format.

If your configuration file uses YAML format, then make sure that your file uses consistent spaces for indentation. Incorrect indentation can cause deployment failures.

Use keys to customize software on Linux or Windows servers. Use each key only one time in each configuration file.

For platforms based on Amazon Linux 2 and Amazon Linux 2023, it's a best practice to use Buildfile, Procfile, and platform hooks to run custom code during instance provisioning. You can still use commands and container_commands in your configuration files. For more information, see How do I use platform hooks to customize my Elastic Beanstalk environment?

When you deploy your application to Elastic Beanstalk, use your .ebextensions configuration files to customize the Amazon Elastic Compute Cloud (Amazon EC2) instances. For configuration file examples, see elastic-beanstalk-samples on the GitHub website.

To use .ebextensions to configure HTTPS for your environment, see Configuring HTTPS for your Elastic Beanstalk environment.

Apply your custom settings to your application

Create an application source bundle that includes your configuration files, and then deploy your updated application.

Note: File archiving tools might not include hidden directories when you create a ZIP file. File browsers might hide folders that start with a period, such as .ebextensions. Include the .ebextensions folder in the root of your application bundle when you create your application source bundle.

Troubleshoot .ebextensions configuration issues

If Elastic Beanstalk doesn't apply your .ebextensions configuration after deployment, then take the following actions:

Check the directory location and file extension

Review recent environment events in the Elastic Beanstalk console. Deployment and configuration messages from Elastic Beanstalk appear on the Events page. Confirm that you configured the .ebextensions directory at the root of your source bundle and that your configuration files use the .config file extension.

Review the deployment logs

Connect to your Amazon EC2 instance and check /var/log/eb-engine.log for errors, startup failures, or deployment issues related to your configuration files. Also check /var/log/cfn-init.log and /var/log/cfn-init-cmd.log for deployment results.

To view deployment logs, see Viewing deployment logs in the console.

To retrieve logs, see To retrieve instance logs in Viewing logs from Amazon EC2 instances in your Elastic Beanstalk environment.

Undo recent configuration changes

If your .ebextensions configuration change caused a deployment failure, then redeploy your application version.

Related information

Troubleshooting your Elastic Beanstalk environment