Customize AWS Elastic Beanstalk with Configuration Files
AWS Elastic Beanstalk can now be customized and configured via YAML configuration files. You can use configuration files to download and install packages, download and extract archives, create files, create users/groups, run commands, start and stop services, and define container settings. In the past, you either had to create custom Amazon Machine Images (AMIs) to configure the Elastic Beanstalk environment, or had to modify your application so it can automatically configure itself on deployment. Custom AMIs needs to be created and maintained, and no longer receive any automated updates to the operating system, software stack, or the AWS Elastic Beanstalk host manager, which makes configuration files a better alternative.
Elastic Beanstalk configurations files are supported on Tomcat 6/7, Python 2.6, and Ruby 1.8.7/1.9.3. Support for PHP and .NET is planned but Amazon has not specified any ETA. If you have existing Elastic Beanstalk environments with Tomcat, you might need to migrate to take advantage of Elastic Beanstalk configuration files. You can verify if your current environment has a legacy container type by logging in to your AWS Console and looking at the Container Type for your environment.
Elastic Beanstalk configuration files can have a filename of your choice with a .config extension. You are allowed to have multiple .config files placed under the .ebextensions directory, which is a top-level directory in your application. For Java WAR files, the .ebextensions directory is at the same level as the WEB-INF directory.
The Elastic Beanstalk configuration file is YAML-based and can have the following keys:
packages - The packages key allows you to download and install pre-packaged applications and components. Supported package managers include apt, yum, rubygems, python, and rpm. Here's an example of adding logwatch using yum.
packages: yum: logwatch: [7.3.6]
sources - The sources key allows you to download and unpack archives. You can reference external locations, or artifacts stored in the source bundle. Supported formats are tar, tar+gzip, tar+bz2 and zip. Here's an example of downloading and unzipping the latest jQuery files from GitHub.
sources: /home/ec2-user/jquery: https://github.com/jquery/jquery/zipball/master
files - The files key allows you to create files, the content of which can be inline or can be pulled from a URL. The files are written to disk in lexicographical order. Here's an example of creating a README file from an external URL.
files: /home/ec2-user/README.md: https://raw.github.com/jquery/jquery/master/README.md
users, groups - The users key allows you to create Linux/UNIX users on the EC2 instance. The groups key allows you to create Linux/UNIX groups and assign group IDs. Here's an example from the AWS documentation.
users: - myuser : groups: - group1 - group2 uid: 50 homedir: "/tmp" groups: - group1 : 45 - group2 : 99 - group3
commands - The commands key allows you to execute shell commands. The commands are processed in lexicographical order by name. They are run before the application and web server are set up, and before the application is extracted. Here's an example or renaming a file we downloaded in an earlier example.
commands: rename-README: command: mv README.md README cwd: /home/ec2-user
container_commands - The container_commands key allows you to execute commands for your container. They are run after the application and web server have been set up and the application has been extracted, but before the application is deployed. container_commands are processed in lexicographical order by name. One instance is chosen to be the leader in an Auto Scaling group. If the leader_only value is true, then the command runs only on the leader. Here's an example of using a custom Tomcat server.xml on the leader.
container_commands: replace-server_xml: command: cp .ebextensions/server.xml /etc/tomcat7/server.xml leader_only: true
services - The services key allows you to define which services should be started or stopped when the instance is launched. The services key also allows you to specify dependencies on sources, packages, and files. Here's an example from the AWS documentation.
services: sysvinit: - myservice: enabled: true ensureRunning: true
option_settings - The option_settings key allows you to define container settings. These get passed in as environment variables to your Amazon EC2 instances. The Python container supports th aws:elasticbeanstalk:application:environment, aws:elasticbeanstalk:container:python and aws:elasticbeanstalk:container:python:staticfiles namespaces. The Java container supports the aws:elasticbeanstalk:application:environment and aws:elasticbeanstalk:container:tomcat:jvmoptions namespaces. The Ruby container supports the aws:elasticbeanstalk:application:environment namespace. Here's an example of setting the JVM max heap size to 512MB in Tomcat.
option_settings: - namespace: aws:elasticbeanstalk:container:tomcat:jvmoptions option_name: Xmx value: 512m
For more information, please visit the Customizing and Configuring AWS Elastic Beanstalk Environments page. Users who are new to YAML might find the Online YAML Parser helpful in creating the configuration file.
Brandon Holt, Preston Briggs, Luis Ceze, Mark Oskin May 21, 2015