AWS Elastic Beanstalk - Developer Guide
AWS Elastic Beanstalk
Developer Guide
API Version 2010-12-01
AWS Elastic Beanstalk Developer Guide
AWS Elastic Beanstalk: Developer Guide
Copyright © 2017 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.
Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner
that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not
owned by Amazon are the property of their respective owners, who may or may not be affiliated with, connected to, or sponsored by
Amazon.
AWS Elastic Beanstalk Developer Guide
Table of Contents
What Is AWS Elastic Beanstalk? ............................................................................................................ 1
Storage ..................................................................................................................................... 2
Pricing ...................................................................................................................................... 2
Community ............................................................................................................................... 2
Where to Go Next ...................................................................................................................... 2
Getting Started .................................................................................................................................. 3
Step 1: Sign up for the Service .................................................................................................... 3
Step 2: Create an Application ...................................................................................................... 3
Step 3: View Information About Your Environment ......................................................................... 5
Step 4: Deploy a New Application Version ..................................................................................... 7
Step 5: Change Configuration ...................................................................................................... 8
Step 6: Clean Up ...................................................................................................................... 10
Where to Go Next .................................................................................................................... 11
The EB CLI ...................................................................................................................... 11
AWS SDK for Java ............................................................................................................ 11
AWS Toolkit for Eclipse ..................................................................................................... 11
AWS SDK for .NET ............................................................................................................ 12
AWS Toolkit for Visual Studio ............................................................................................ 12
AWS SDK for Node.js ........................................................................................................ 12
AWS SDK for PHP ............................................................................................................ 12
Boto (AWS SDK for Python) ............................................................................................... 12
AWS SDK for Ruby ........................................................................................................... 13
How Elastic Beanstalk Works ............................................................................................................. 14
Components ............................................................................................................................ 14
Application ...................................................................................................................... 14
Application Version ........................................................................................................... 14
Environment .................................................................................................................... 15
Environment Configuration ................................................................................................ 15
Configuration Template ..................................................................................................... 15
Architectural Overview .............................................................................................................. 15
Web Server Environment Tiers ........................................................................................... 15
Worker Environment Tiers ................................................................................................. 17
Permissions ............................................................................................................................. 17
Elastic Beanstalk Service Role ............................................................................................ 18
Elastic Beanstalk Instance Profile ........................................................................................ 19
Elastic Beanstalk User Policy .............................................................................................. 20
Design Considerations ............................................................................................................... 21
Scalability ........................................................................................................................ 22
Security ........................................................................................................................... 22
Persistent Storage ............................................................................................................ 22
Fault Tolerance ................................................................................................................ 23
Content Delivery .............................................................................................................. 23
Software Updates and Patching ......................................................................................... 23
Connectivity ..................................................................................................................... 23
Where to Go Next .................................................................................................................... 24
Elastic Beanstalk Platforms ................................................................................................................ 25
Supported Platforms ................................................................................................................ 25
Packer Builder .................................................................................................................. 26
Single Container Docker .................................................................................................... 26
Multicontainer Docker ....................................................................................................... 27
Preconfigured Docker ........................................................................................................ 27
Go .................................................................................................................................. 28
Java SE ........................................................................................................................... 28
Java with Tomcat ............................................................................................................. 29
API Version 2010-12-01
iii
AWS Elastic Beanstalk Developer Guide
.NET on Windows Server with IIS ....................................................................................... 29
Node.js ............................................................................................................................ 31
PHP ................................................................................................................................ 32
Python ............................................................................................................................ 32
Ruby ............................................................................................................................... 33
Custom Platforms .................................................................................................................... 35
Creating a Custom Platform .............................................................................................. 36
Using a Sample Custom Platform ....................................................................................... 36
Platform Definition Archive Contents .................................................................................. 40
Platform Hooks ................................................................................................................ 40
Platform Scripts ............................................................................................................... 41
Packer Instance Cleanup .................................................................................................... 41
Platform.yaml Format ....................................................................................................... 42
Tutorials and Samples ....................................................................................................................... 45
Managing Applications ...................................................................................................................... 47
Application Management Console ............................................................................................... 48
Managing Application Versions ................................................................................................... 50
Version Lifecycle ...................................................................................................................... 52
Setting the Application Lifecycle Settings in the Console ....................................................... 53
Create a Source Bundle ............................................................................................................. 54
Creating a Source Bundle from the Command Line ............................................................... 55
Creating a Source Bundle with Git ...................................................................................... 55
Zipping Files in Mac OS X Finder or Windows Explorer .......................................................... 55
Creating a Source Bundle for a .NET Application ................................................................... 58
Testing Your Source Bundle ............................................................................................... 59
Managing Environments .................................................................................................................... 60
The Environment Management Console ...................................................................................... 61
Environment Dashboard .................................................................................................... 62
Environment Management Actions ..................................................................................... 63
Configuration ................................................................................................................... 64
Logs ............................................................................................................................... 65
Health ............................................................................................................................. 66
Monitoring ....................................................................................................................... 66
Alarms ............................................................................................................................ 66
Managed Updates ............................................................................................................ 67
Events ............................................................................................................................. 67
Tags ................................................................................................................................ 68
Creating Environments .............................................................................................................. 68
The Create New Environment Wizard .................................................................................. 71
Clone an Environment ...................................................................................................... 96
Terminate an Environment ................................................................................................ 98
With the AWS CLI ........................................................................................................... 100
With the API .................................................................................................................. 101
Launch Now URL ............................................................................................................ 104
Compose Environments ................................................................................................... 106
Deployments .......................................................................................................................... 108
Deployment Options ....................................................................................................... 110
Blue/Green Deployments ................................................................................................. 113
Deploying a New Application Version ................................................................................ 115
Redeploying a Previous Version ........................................................................................ 116
Configuration Changes ............................................................................................................ 116
Rolling Updates .............................................................................................................. 117
Immutable Updates ........................................................................................................ 120
Tag an Environment ........................................................................................................ 122
Platform Updates ................................................................................................................... 123
Managed Updates ........................................................................................................... 125
Upgrade a Legacy Environment ........................................................................................ 129
API Version 2010-12-01
iv
AWS Elastic Beanstalk Developer Guide
Cancel an Update ...................................................................................................................
Rebuild an Environment ..........................................................................................................
Rebuilding a Running Environment ...................................................................................
Rebuilding a Terminated Environment ...............................................................................
Environment Types .................................................................................................................
Load-balancing, Autoscaling Environment ..........................................................................
Single-instance Environment ............................................................................................
Changing Environment Type ............................................................................................
Worker Environments ..............................................................................................................
The Worker Environment SQS Daemon .............................................................................
Dead Letter Queues ........................................................................................................
Periodic Tasks ................................................................................................................
Use Amazon CloudWatch for Auto Scaling in Worker Environment Tiers .................................
Configuring Worker Environments ....................................................................................
Environment Links ..................................................................................................................
Environment Configuration ..............................................................................................................
Configuration Options .............................................................................................................
Before Environment Creation ...........................................................................................
During Creation ..............................................................................................................
After Creation ................................................................................................................
General Options .............................................................................................................
Platform Specific Options ................................................................................................
Custom Options .............................................................................................................
Precedence ....................................................................................................................
Recommended Values .....................................................................................................
.ebextensions .........................................................................................................................
Option Settings ..............................................................................................................
Server Customization (Linux) ............................................................................................
Server Customization (Windows) ......................................................................................
Custom Resources ...........................................................................................................
Functions .......................................................................................................................
Saved Configurations ..............................................................................................................
env.yaml ...............................................................................................................................
Auto Scaling Group .................................................................................................................
AWS Management Console ..............................................................................................
Auto scaling configuration namespaces .............................................................................
Command Line Interface (CLI) ..........................................................................................
Health Check Setting ......................................................................................................
EC2 Instances .........................................................................................................................
Configuring Your Environment's EC2 Instances in the AWS Management Console .....................
Configuration Files ..........................................................................................................
Custom Image ................................................................................................................
Load Balancer ........................................................................................................................
Configuring Your Environment's Load Balancer in the AWS Management Console ....................
Load Balancer Configuration Namespaces ..........................................................................
Configuring Access Logs ..................................................................................................
Application Load Balancer ...............................................................................................
Database ...............................................................................................................................
Adding a DB Instance to Your Environment ........................................................................
Connecting to the database .............................................................................................
Configuring an Integrated RDS DB Instance .......................................................................
Debugging .............................................................................................................................
Configuring Debugging ...................................................................................................
The aws:elasticbeanstalk:xray Namespace ..........................................................................
VPC ......................................................................................................................................
CW Logs ................................................................................................................................
Configuring CloudWatch logs in the Elastic Beanstalk console ..............................................
API Version 2010-12-01
v
131
132
132
132
134
134
134
134
136
137
139
139
140
140
142
144
145
145
149
154
160
187
194
194
195
197
198
200
210
216
232
234
237
238
238
243
244
246
247
247
250
250
252
253
256
256
257
260
260
261
261
262
264
264
264
265
265
AWS Elastic Beanstalk Developer Guide
The aws:elasticbeanstalk:cloudwatch:logs Namespace ....................................................
SNS Notifications ....................................................................................................................
Configuring an Amazon SNS topic in the Elastic Beanstalk console ........................................
The aws:elasticbeanstalk:sns:topics Namespace ............................................................
Domain Name ........................................................................................................................
Configuring HTTPS .................................................................................................................
Create a Certificate .........................................................................................................
Upload a Certificate ........................................................................................................
Terminate HTTPS at the Load Balancer .............................................................................
Terminate HTTPS at the Instance .....................................................................................
End-to-End Encryption ....................................................................................................
TCP Passthrough ............................................................................................................
Store Keys Securely ........................................................................................................
Monitoring an Environment .............................................................................................................
Monitoring Console .................................................................................................................
Overview .......................................................................................................................
Monitoring Graphs ..........................................................................................................
Customizing the Monitoring Console .................................................................................
Basic Health Reporting ............................................................................................................
Health Colors .................................................................................................................
Elastic Load Balancing Health Check .................................................................................
Single Instance Environment Health Check ........................................................................
Additional Checks ...........................................................................................................
Amazon CloudWatch Metrics ............................................................................................
Enhanced Health Reporting and Monitoring ...............................................................................
The Elastic Beanstalk Health Agent ...................................................................................
Factors in Determining Instance and Environment Health ....................................................
Enhanced Health Roles ....................................................................................................
Enhanced Health Events ..................................................................................................
Enhanced Health Reporting Behavior During Updates, Deployments, and Scaling ....................
Enable Enhanced Health ..................................................................................................
Health Console ...............................................................................................................
Health Colors and Statuses ..............................................................................................
Instance Metrics .............................................................................................................
CloudWatch ...................................................................................................................
API Users .......................................................................................................................
Enhanced Health Log Format ...........................................................................................
Notifications and Troubleshooting ....................................................................................
Manage Alarms ......................................................................................................................
View Events ...........................................................................................................................
Monitor Instances ...................................................................................................................
View Instance Logs .................................................................................................................
Log Location on-Instance ................................................................................................
Log Location in S3 .........................................................................................................
Log Rotation Settings on Linux ........................................................................................
Extending the Default Log Task Configuration ....................................................................
Amazon CloudWatch Logs ...............................................................................................
Integrating AWS Services .................................................................................................................
Architectural Overview ............................................................................................................
CloudFront .............................................................................................................................
CloudTrail ..............................................................................................................................
Elastic Beanstalk Information in CloudTrail History .............................................................
Elastic Beanstalk Information in CloudTrail Logging ............................................................
Understanding Elastic Beanstalk Log File Entries ................................................................
CloudWatch ...........................................................................................................................
CloudWatch Logs ....................................................................................................................
Granting IAM Permissions ................................................................................................
API Version 2010-12-01
vi
265
266
266
267
268
270
271
273
273
275
295
297
298
300
300
301
301
302
303
303
304
304
304
305
306
307
308
310
310
310
311
314
317
319
320
325
327
329
330
333
334
336
337
338
338
339
341
342
342
343
344
344
344
345
345
346
347
AWS Elastic Beanstalk Developer Guide
Streaming CloudWatch Logs ............................................................................................
Setting Up CloudWatch Logs Integration with Configuration Files .........................................
Troubleshooting CloudWatch Logs Integration ...................................................................
DynamoDB .............................................................................................................................
ElastiCache ............................................................................................................................
EFS .......................................................................................................................................
Configuration Files ..........................................................................................................
Sample Applications .......................................................................................................
IAM .......................................................................................................................................
Instance Profiles .............................................................................................................
Service Roles ..................................................................................................................
User Policies ..................................................................................................................
ARN Format ...................................................................................................................
Resources and Conditions ................................................................................................
Example Policies .............................................................................................................
Example Policies Based on Resource Permissions ................................................................
Amazon RDS ..........................................................................................................................
Launching and Connecting to an External RDS Instance in a Default VPC ................................
Launching and Connecting to an External RDS Instance in EC2 Classic ...................................
Storing the Connection String in Amazon S3 .....................................................................
Amazon S3 ............................................................................................................................
Amazon VPC ..........................................................................................................................
What VPC Configurations Do I Need? ................................................................................
Single-Instance Environment in a VPC ...............................................................................
Load-Balancing Environment with Private Instances ............................................................
Bastion Hosts .................................................................................................................
Amazon RDS ..................................................................................................................
Load-Balancing Environment with Public Instances .............................................................
Your Local Development Environment ...............................................................................................
Creating a Project Folder .........................................................................................................
Setting Up Source Control .......................................................................................................
Configuring a Remote Repository .............................................................................................
Installing the EB CLI ...............................................................................................................
Installing the AWS CLI .............................................................................................................
The EB CLI .....................................................................................................................................
Install the EB CLI ....................................................................................................................
Linux .............................................................................................................................
Windows .......................................................................................................................
macOS ..........................................................................................................................
Virtualenv ......................................................................................................................
Configure the EB CLI ...............................................................................................................
Ignoring files with .ebignore ............................................................................................
Using Named Profiles ......................................................................................................
Deploying an Artifact Instead of the Project Folder .............................................................
Configuration Settings and Precedence .............................................................................
Instance Metadata ..........................................................................................................
EB CLI Basics ..........................................................................................................................
eb create .......................................................................................................................
eb status .......................................................................................................................
eb health .......................................................................................................................
eb events ......................................................................................................................
eb logs ..........................................................................................................................
eb open ........................................................................................................................
eb deploy ......................................................................................................................
eb config .......................................................................................................................
eb terminate ..................................................................................................................
Using the EB CLI with AWS CodeBuild .......................................................................................
API Version 2010-12-01
vii
348
350
351
351
352
352
353
353
353
354
358
362
366
368
389
391
398
399
402
406
408
408
409
410
414
418
421
427
431
431
432
432
432
433
434
435
437
439
441
442
443
445
445
445
446
446
446
447
447
448
448
449
449
449
450
450
451
AWS Elastic Beanstalk Developer Guide
Creating an Application ...................................................................................................
Using the EB CLI with Git ........................................................................................................
Associating Elastic Beanstalk environments with Git branches ..............................................
Deploying changes ..........................................................................................................
Using Git submodules .....................................................................................................
Assigning Git tags to your application version ....................................................................
AWS CodeCommit ..................................................................................................................
Prerequisites ..................................................................................................................
Creating an AWS CodeCommit Repository with the EB CLI ...................................................
Deploying from Your AWS CodeCommit Repository ............................................................
Configuring Additional Branches and Environments ............................................................
Using an Existing AWS CodeCommit Repository .................................................................
Monitoring Health ..................................................................................................................
Reading the Output ........................................................................................................
Interactive Health View ...................................................................................................
Interactive Health View Options .......................................................................................
Composing Environments ........................................................................................................
Troubleshooting .....................................................................................................................
Troubleshooting deployments ..........................................................................................
EB CLI Commands ..................................................................................................................
Common Options ...........................................................................................................
eb abort .......................................................................................................................
eb appversion ...............................................................................................................
eb clone .......................................................................................................................
eb codesource ...............................................................................................................
eb config .....................................................................................................................
eb console ...................................................................................................................
eb create .....................................................................................................................
eb deploy .....................................................................................................................
eb events .....................................................................................................................
eb health .....................................................................................................................
eb init ........................................................................................................................
eb labs ........................................................................................................................
eb list ........................................................................................................................
eb local .......................................................................................................................
eb logs ........................................................................................................................
eb open ........................................................................................................................
eb platform ..................................................................................................................
eb printenv ..................................................................................................................
eb restore ...................................................................................................................
eb scale .......................................................................................................................
eb setenv .....................................................................................................................
eb ssh ..........................................................................................................................
eb status .....................................................................................................................
eb swap ........................................................................................................................
eb terminate ................................................................................................................
eb upgrade ...................................................................................................................
eb use ..........................................................................................................................
EB CLI 2.6 (Deprecated) ...........................................................................................................
Differences from Version 3 of EB CLI .................................................................................
Migrating to EB CLI 3 and AWS CodeCommit .....................................................................
Getting Started with Eb ..................................................................................................
Deploying a Branch to an Environment .............................................................................
Eb Common Options .......................................................................................................
EB CLI 2 Commands .......................................................................................................
EB API CLI (deprecated) ...........................................................................................................
Converting Elastic Beanstalk API CLI Scripts .......................................................................
API Version 2010-12-01
viii
451
451
451
451
452
452
453
453
453
454
455
456
457
459
460
461
461
463
463
465
465
466
466
468
470
471
473
474
479
481
482
483
486
486
487
490
491
491
498
498
499
500
501
503
504
505
506
507
508
508
509
509
514
517
517
535
535
AWS Elastic Beanstalk Developer Guide
Getting Set Up ...............................................................................................................
Common Options ...........................................................................................................
Operations .....................................................................................................................
Working with Docker ......................................................................................................................
Docker Platform Configurations ...............................................................................................
Single Container Docker ..................................................................................................
Multicontainer Docker .....................................................................................................
Preconfigured Docker Containers ......................................................................................
Single Container Docker ..........................................................................................................
Sample PHP Application ..................................................................................................
Sample Python Application ..............................................................................................
Sample Dockerfile Application ..........................................................................................
Single Container Docker Configuration ..............................................................................
Multicontainer Docker .............................................................................................................
Multicontainer Docker Platform ........................................................................................
Dockerrun.aws.json File ...................................................................................................
Docker Images ...............................................................................................................
Container Instance Role ...................................................................................................
Amazon ECS Resources Created by Elastic Beanstalk ...........................................................
Using Multiple Elastic Load Balancing Listeners ..................................................................
Failed Container Deployments ..........................................................................................
Multicontainer Docker Configuration .................................................................................
Tutorial - Multicontainer Docker .......................................................................................
Preconfigured Containers .........................................................................................................
Getting Started with Preconfigured Docker Containers ........................................................
Example: Customize and Configure Preconfigured Docker Platforms ......................................
Environment Configuration ......................................................................................................
Docker Images ...............................................................................................................
Configuring Additional Storage Volumes ...........................................................................
Reclaiming Docker Storage Space .....................................................................................
Running Containers Locally ......................................................................................................
Prerequisites for Running Docker Applications Locally .........................................................
Preparing a Docker Application for Use with the EB CLI .......................................................
Running a Docker Application Locally ................................................................................
Cleaning Up After Running a Docker Application Locally ......................................................
Working with Go ............................................................................................................................
The Go Platform ....................................................................................................................
Deploying Simple Go Applications ....................................................................................
Deploying Complex Go Applications ..................................................................................
Execution Order .............................................................................................................
Setting Configuration Options ..........................................................................................
Configuring the Reverse Proxy .........................................................................................
The Docker-based Go Platform ................................................................................................
Set Up Your Local Development Environment ....................................................................
Develop and Test Locally Using Docker .............................................................................
Deploy to Elastic Beanstalk ..............................................................................................
Working with Java ..........................................................................................................................
Getting Started ......................................................................................................................
Launching an Environment with a Sample Java Application ..................................................
Next Steps .....................................................................................................................
Development Environment ......................................................................................................
Installing the Java Development Kit ..................................................................................
Installing a Web Container ...............................................................................................
Downloading Libraries .....................................................................................................
Installing the AWS SDK for Java .......................................................................................
Installing an IDE or Text Editor .........................................................................................
Installing the AWS Toolkit for Eclipse ................................................................................
API Version 2010-12-01
ix
537
539
539
581
581
581
582
582
582
583
583
583
584
587
588
588
589
589
590
590
591
591
595
601
601
603
604
604
607
607
608
608
609
609
611
613
613
613
614
615
616
616
616
616
617
618
619
620
620
625
625
625
625
625
626
626
626
AWS Elastic Beanstalk Developer Guide
The Tomcat Platform ..............................................................................................................
Configuring Your Tomcat Environment in the AWS Management Console ...............................
Configuration Files ..........................................................................................................
Configuring the Proxy Server ...........................................................................................
Using .gitignore ...........................................................................................................
Bundling WAR Files .........................................................................................................
Structuring your Project Folder ........................................................................................
The Java SE Platform ..............................................................................................................
Configuring the Application Process with a Procfile ...........................................................
Building JARs On-Server with a Buildfile .........................................................................
Execution Order .............................................................................................................
Software Configuration Options .......................................................................................
Configuring the Reverse Proxy .........................................................................................
Environment Configuration ......................................................................................................
Setting Environment Properties ........................................................................................
Accessing Environment Properties .....................................................................................
Adding a Database .................................................................................................................
Downloading the JDBC Driver ..........................................................................................
Connecting to a Database (Java SE Platforms) ....................................................................
Connecting to a Database (Tomcat Platforms) ....................................................................
Troubleshooting Database Connections .............................................................................
Eclipse Toolkit ........................................................................................................................
Importing Existing Environments into Eclipse .....................................................................
Managing Environments ..................................................................................................
Managing Multiple AWS Accounts .....................................................................................
Viewing Events ...............................................................................................................
Listing and Connecting to Server Instances ........................................................................
Terminating an Environment ............................................................................................
Resources ..............................................................................................................................
Working with .NET ..........................................................................................................................
Getting Started ......................................................................................................................
Launching an Environment with a Sample .NET Application ..................................................
Next Steps .....................................................................................................................
Development Environment ......................................................................................................
Installing an IDE .............................................................................................................
Installing the AWS Toolkit for Visual Studio .......................................................................
The .NET Platform ..................................................................................................................
Accessing Environment Configuration Settings ...................................................................
Migrating to v1 Elastic Beanstalk Windows Server Platforms ................................................
Deployment Manifest ......................................................................................................
Tutorial - ASP.NET MVC5 .........................................................................................................
Create the Environment ..................................................................................................
Publish Your Application to Elastic Beanstalk .....................................................................
Clean Up Your AWS Resources .........................................................................................
Tutorial - .NET Core ................................................................................................................
Prerequisites ..................................................................................................................
Generate a .NET Core Project ...........................................................................................
Launch an Elastic Beanstalk Environment ..........................................................................
Update the Source Code ..................................................................................................
Deploy Your Application ..................................................................................................
Clean Up .......................................................................................................................
Next Steps .....................................................................................................................
Adding a Database .................................................................................................................
Adding a DB Instance to Your Environment ........................................................................
Downloading a Driver .....................................................................................................
Connecting to a Database ...............................................................................................
The AWS Toolkit for Visual Studio ............................................................................................
API Version 2010-12-01
x
626
627
629
629
631
632
632
634
635
636
636
637
637
638
638
638
639
640
640
641
643
644
645
645
655
656
657
658
658
659
660
660
662
662
662
662
662
664
664
665
669
669
674
678
679
679
680
681
681
684
686
686
687
687
688
688
689
AWS Elastic Beanstalk Developer Guide
Deploy ..........................................................................................................................
Managing Environments ..................................................................................................
Managing Accounts .........................................................................................................
Debug ...........................................................................................................................
Monitor .........................................................................................................................
Deployment Tool ............................................................................................................
Create a Project .............................................................................................................
Test Locally ....................................................................................................................
Create an Elastic Beanstalk Environment ...........................................................................
Terminating an Environment ............................................................................................
Resources ..............................................................................................................................
Working with Node.js ......................................................................................................................
Getting Started ......................................................................................................................
Launching an Environment with a Sample Node.js Application ..............................................
Next Steps .....................................................................................................................
Development Environment ......................................................................................................
Installing Node.js ............................................................................................................
Installing npm ................................................................................................................
Installing the AWS SDK for Node.js ...................................................................................
Installing Express ............................................................................................................
Installing Geddy .............................................................................................................
The Node.js Platform ..............................................................................................................
Configuring Your Node.js Environment in the AWS Management Console ...............................
Configuration Files ..........................................................................................................
Installing Packages with a Package.json File .......................................................................
Locking Dependencies with npm shrinkwrap ......................................................................
Configuring the Proxy Server ...........................................................................................
Tutorial - Express ....................................................................................................................
Prerequisites ..................................................................................................................
Install Express and Generate a Project ...............................................................................
Create an Elastic Beanstalk Environment ...........................................................................
Update the Application ...................................................................................................
Clean Up .......................................................................................................................
Tutorial - Node.js w/ DynamoDB ..............................................................................................
Prerequisites ..................................................................................................................
Launch an Elastic Beanstalk Environment ..........................................................................
Add Permissions to Your Environment's Instances ...............................................................
Deploy the Sample Application ........................................................................................
Create a DynamoDB Table ...............................................................................................
Update the Application's Configuration Files ......................................................................
Configure Your Environment for High Availability ...............................................................
Clean Up .......................................................................................................................
Next Steps .....................................................................................................................
Tutorial - Geddy with Clustering ...............................................................................................
Step 1: Set Up Your Git Repository ...................................................................................
Step 2: Set Up Your Geddy Development Environment ........................................................
Step 3: Configure Elastic Beanstalk ...................................................................................
Step 5: View the Application ............................................................................................
Step 6: Update the Application ........................................................................................
Step 7: Clean Up ............................................................................................................
Adding a Database .................................................................................................................
Adding a DB Instance to Your Environment ........................................................................
Downloading a Driver .....................................................................................................
Connecting to a Database ...............................................................................................
Resources ..............................................................................................................................
Working with PHP ..........................................................................................................................
The PHP Platform ..................................................................................................................
API Version 2010-12-01
xi
689
691
701
701
702
704
705
706
706
715
715
716
717
717
719
719
719
720
720
720
721
721
722
723
724
724
724
726
726
726
727
728
730
730
731
732
733
733
735
735
737
738
738
739
739
739
740
741
741
748
749
749
750
750
751
752
752
AWS Elastic Beanstalk Developer Guide
Configuring your PHP Environment in the AWS Management Console ...................................
Configuration Files ..........................................................................................................
Composer File ................................................................................................................
Update Composer ...........................................................................................................
Extending php.ini ...........................................................................................................
Tutorial - Laravel 5.2 ..............................................................................................................
Prerequisites ..................................................................................................................
Install Composer ............................................................................................................
Install Laravel and Generate a Website ..............................................................................
Create an Elastic Beanstalk Environment and Deploy Your Application ...................................
Add a Database to Your Environment ................................................................................
Clean Up .......................................................................................................................
Next Steps .....................................................................................................................
Tutorial - CakePHP 3.2 ............................................................................................................
Prerequisites ..................................................................................................................
Install Composer ............................................................................................................
Install CakePHP and Generate a Website ...........................................................................
Create an Elastic Beanstalk Environment and Deploy Your Application ...................................
Add a Database to Your Environment ................................................................................
Clean Up .......................................................................................................................
Next Steps .....................................................................................................................
Tutorial - Symfony2 ................................................................................................................
Set Up Your Git Repository ..............................................................................................
Set Up Your Symfony2 Development Environment ..............................................................
Configure Elastic Beanstalk ..............................................................................................
View the Application .......................................................................................................
Update the Application ...................................................................................................
Clean Up .......................................................................................................................
Tutorial - HA Production .........................................................................................................
Prerequisites ..................................................................................................................
Launch a DB Instance in Amazon RDS ...............................................................................
Launch an Elastic Beanstalk Environment ..........................................................................
Configure Security Groups, Environment Properties, and Scaling ...........................................
Deploy the Sample Application ........................................................................................
Clean Up .......................................................................................................................
Next Steps .....................................................................................................................
Tutorial - HA WordPress ..........................................................................................................
Launch a DB Instance in Amazon RDS ...............................................................................
Download WordPress ......................................................................................................
Launch an Elastic Beanstalk Environment ..........................................................................
Configure Security Groups and Environment Properties .......................................................
Install WordPress ............................................................................................................
Updating keys and salts ..................................................................................................
Update the Environment .................................................................................................
Configure Autoscaling .....................................................................................................
Review ..........................................................................................................................
Clean Up .......................................................................................................................
Next Steps .....................................................................................................................
Tutorial - HA Drupal ...............................................................................................................
Launch a DB Instance in Amazon RDS ...............................................................................
Download Drupal ............................................................................................................
Launch an Elastic Beanstalk Environment ..........................................................................
Configure Security Groups and Environment Properties .......................................................
Install Drupal .................................................................................................................
Update the Environment .................................................................................................
Configure Autoscaling .....................................................................................................
Review ..........................................................................................................................
API Version 2010-12-01
xii
753
754
755
755
755
756
756
757
757
758
760
762
763
763
763
764
764
765
766
768
769
769
769
769
771
772
772
773
773
774
774
776
776
778
779
780
780
781
783
784
784
786
786
787
788
788
789
789
790
790
792
794
794
796
796
797
797
AWS Elastic Beanstalk Developer Guide
Clean Up .......................................................................................................................
Next Steps .....................................................................................................................
Adding a Database .................................................................................................................
Adding a DB Instance to Your Environment ........................................................................
Downloading a Driver .....................................................................................................
Connecting to a Database with a PDO or MySQLi ...............................................................
Resources ..............................................................................................................................
Working with Python ......................................................................................................................
Development Environment ......................................................................................................
Common Prerequisites ....................................................................................................
Setting up a virtual Python environment ...........................................................................
Configuring a Python project for Elastic Beanstalk ..............................................................
The Python Platform ..............................................................................................................
Configuring Your Python Environment in the AWS Management Console ...............................
Configuration Files ..........................................................................................................
Requirements File ...........................................................................................................
Tutorial - Flask 0.10 ................................................................................................................
Prerequisites ..................................................................................................................
Set Up a Python Virtual Environment with Flask .................................................................
Create a Flask Application ...............................................................................................
Configure Your Flask Application for Elastic Beanstalk .........................................................
Deploy Your Site With the EB CLI .....................................................................................
Clean Up and Next Steps .................................................................................................
Tutorial - Django 1.9 ...............................................................................................................
Prerequisites ..................................................................................................................
Set Up a Python Virtual Environment with Django ..............................................................
Create a Django Project ...................................................................................................
Configure Your Django Application for Elastic Beanstalk ......................................................
Deploy Your Site With the EB CLI .....................................................................................
Updating Your Application ...............................................................................................
Clean Up and Next Steps .................................................................................................
Adding a Database .................................................................................................................
Adding a DB Instance to Your Environment ........................................................................
Downloading a Driver .....................................................................................................
Connecting to a Database ...............................................................................................
Tools and Resources ................................................................................................................
Working with Ruby .........................................................................................................................
The Ruby Platform .................................................................................................................
Configuring Your Ruby Environment in the AWS Management Console ..................................
Configuration Files ..........................................................................................................
Installing Packages with a Gemfile ....................................................................................
Tutorial - Rails 4.1 ..................................................................................................................
Rails Development Environment Setup ..............................................................................
Install the EB CLI ............................................................................................................
Set Up Your Git Repository ..............................................................................................
Configure the EB CLI .......................................................................................................
Create a Service Role and Instance Profile .........................................................................
Update the Gemfile ........................................................................................................
Deploy the Project ..........................................................................................................
Update the Application ...................................................................................................
Clean Up .......................................................................................................................
Tutorial - Sinatra ....................................................................................................................
Prerequisites ..................................................................................................................
Step 1: Set Up Your Project .............................................................................................
Step 2: Create an Application ...........................................................................................
Step 3: Create an Environment .........................................................................................
Step 4: Deploy a Simple Sinatra Application ......................................................................
API Version 2010-12-01
xiii
798
798
799
799
800
800
801
802
802
802
803
803
804
805
806
806
807
807
808
808
810
810
812
812
812
813
814
815
816
818
821
821
822
822
823
823
824
824
825
826
826
827
827
828
829
829
830
830
831
833
834
834
835
835
836
837
838
AWS Elastic Beanstalk Developer Guide
Step 5: Clean Up ............................................................................................................ 839
Related Resources ........................................................................................................... 840
Adding a Database ................................................................................................................. 840
Adding a DB Instance to Your Environment ........................................................................ 840
Downloading an Adapter ................................................................................................. 841
Connecting to a Database ............................................................................................... 842
Tools ..................................................................................................................................... 842
AWS SDK for Ruby ......................................................................................................... 842
Git Deployment Via EB CLI .............................................................................................. 842
Resources .............................................................................................................................. 842
Troubleshooting ............................................................................................................................. 843
Connectivity ........................................................................................................................... 843
Environment Creation ............................................................................................................. 844
Deployments .......................................................................................................................... 844
Health ................................................................................................................................... 845
Configuration ......................................................................................................................... 845
Docker .................................................................................................................................. 845
FAQ ...................................................................................................................................... 846
Resources ...................................................................................................................................... 847
Sample Applications ............................................................................................................... 847
Appendix ....................................................................................................................................... 849
Customizing AWS Resources .................................................................................................... 849
AWS Resource Types ....................................................................................................... 849
Resource Property Types ................................................................................................. 850
Platform History ..................................................................................................................... 850
Packer Platform History .................................................................................................. 850
Docker Platform History .................................................................................................. 853
Preconfigured Docker Platform History ............................................................................. 868
Go Platform History ........................................................................................................ 897
Tomcat Platform History ................................................................................................. 902
Java SE Platform History ................................................................................................. 923
.NET on Windows Server with IIS Platform History .............................................................. 929
Node.js Platform History ................................................................................................. 958
PHP Platform History ...................................................................................................... 972
Python Platform History ................................................................................................. 993
Ruby Platform History ................................................................................................... 1009
API Version 2010-12-01
xiv
AWS Elastic Beanstalk Developer Guide
What Is AWS Elastic Beanstalk?
Amazon Web Services (AWS) comprises dozens of services, each of which exposes an area of
functionality. While the variety of services offers flexibility for how you want to manage your AWS
infrastructure, it can be challenging to figure out which services to use and how to provision them.
With Elastic Beanstalk, you can quickly deploy and manage applications in the AWS Cloud without
worrying about the infrastructure that runs those applications. AWS Elastic Beanstalk reduces
management complexity without restricting choice or control. You simply upload your application, and
Elastic Beanstalk automatically handles the details of capacity provisioning, load balancing, scaling,
and application health monitoring. Elastic Beanstalk uses highly reliable and scalable services that are
available in the AWS Free Usage Tier.
Elastic Beanstalk supports applications developed in Java, PHP, .NET, Node.js, Python, and Ruby, as well
as different container types for each language. A container defines the infrastructure and software stack
to be used for a given environment. When you deploy your application, Elastic Beanstalk provisions one
or more AWS resources, such as Amazon EC2 instances. The software stack that runs on your Amazon
EC2 instances depends on the container type. For example, Elastic Beanstalk supports two container
types for Node.js: a 32-bit Amazon Linux image and a 64-bit Amazon Linux image. Each runs a software
stack tailored to hosting a Node.js application. You can interact with Elastic Beanstalk by using the AWS
Management Console, the AWS Command Line Interface (AWS CLI), or eb, a high-level CLI designed
specifically for Elastic Beanstalk.
To learn more about the AWS Free Usage Tier and how to deploy a sample web application in it using
AWS Elastic Beanstalk, go to Getting Started with AWS: Deploying a Web Application.
You can also perform most deployment tasks, such as changing the size of your fleet of Amazon EC2
instances or monitoring your application, directly from the Elastic Beanstalk web interface (console).
To use Elastic Beanstalk, you create an application, upload an application version in the form of an
application source bundle (for example, a Java .war file) to Elastic Beanstalk, and then provide some
information about the application. Elastic Beanstalk automatically launches an environment and creates
and configures the AWS resources needed to run your code. After your environment is launched, you can
then manage your environment and deploy new application versions. The following diagram illustrates
the workflow of Elastic Beanstalk.
API Version 2010-12-01
1
AWS Elastic Beanstalk Developer Guide
Storage
After you create and deploy your application, information about the application—including metrics,
events, and environment status—is available through the AWS Management Console, APIs, or Command
Line Interfaces, including the unified AWS CLI. For step-by-step instructions on how to create, deploy,
and manage your application using the AWS Management Console, go to Getting Started Using Elastic
Beanstalk (p. 3). To learn more about an Elastic Beanstalk application and its components, see Elastic
Beanstalk Components (p. 14).
Elastic Beanstalk provides developers and systems administrators an easy, fast way to deploy and
manage their applications without having to worry about AWS infrastructure. If you already know the
AWS resources you want to use and how they work, you might prefer AWS CloudFormation to create
your AWS resources by creating a template. You can then use this template to launch new AWS resources
in the exact same way without having to recustomize your AWS resources. Once your resources are
deployed, you can modify and update the AWS resources in a controlled and predictable way, providing
the same sort of version control over your AWS infrastructure that you exercise over your software. For
more information about AWS CloudFormation, go to AWS CloudFormation Getting Started Guide.
Storage
Elastic Beanstalk does not restrict your choice of persistent storage and database service options. For
more information on AWS storage options, go to Storage Options in the AWS Cloud.
Pricing
There is no additional charge for Elastic Beanstalk. You pay only for the underlying AWS resources that
your application consumes. For details about pricing, see the Elastic Beanstalk service detail page.
Community
Customers have built a wide variety of products, services, and applications on top of AWS. Whether
you are searching for ideas about what to build, looking for examples, or just want to explore, you
can find many solutions at the AWS Customer App Catalog. You can browse by audience, services, and
technology. We also invite you to share applications you build with the community. Developer resources
produced by the AWS community are at http://aws.amazon.com/resources/.
Where to Go Next
This guide contains conceptual information about the Elastic Beanstalk web service, as well as
information about how to use the service to deploy web applications. Separate sections describe how to
use the AWS Management console, command line interface (CLI) tools, and API to deploy and manage
your Elastic Beanstalk environments. This guide also documents how Elastic Beanstalk is integrated with
other services provided by Amazon Web Services.
We recommend that you first read Getting Started Using Elastic Beanstalk (p. 3) to learn how to start
using Elastic Beanstalk. Getting Started steps you through creating, viewing, and updating your Elastic
Beanstalk application, as well as editing and terminating your Elastic Beanstalk environment. Getting
Started also describes different ways you can access Elastic Beanstalk. We also recommend that you
familiarize yourself with Elastic Beanstalk concepts and terminology by reading How Elastic Beanstalk
Works (p. 14).
API Version 2010-12-01
2
AWS Elastic Beanstalk Developer Guide
Step 1: Sign up for the Service
Getting Started Using Elastic
Beanstalk
The following tasks will help you get started with Elastic Beanstalk to create, view, deploy, and update
your application as well as edit and terminate your environment. You'll use the AWS Management
Console, a point-and-click web-based interface, to complete these tasks.
Sections
• Step 1: Sign up for the Service (p. 3)
• Step 2: Create an Application (p. 3)
• Step 3: View Information About Your Environment (p. 5)
• Step 4: Deploy a New Application Version (p. 7)
• Step 5: Change Configuration (p. 8)
• Step 6: Clean Up (p. 10)
• Where to Go Next (p. 11)
Step 1: Sign up for the Service
If you're not already an AWS customer, you'll need to sign up. Signing up allows you to access Elastic
Beanstalk and other AWS services that you will need, such as Amazon Elastic Compute Cloud (Amazon
EC2), Amazon Simple Storage Service (Amazon S3), and Amazon Simple Notification Service (Amazon
SNS).
To sign up for an AWS account
1.
Open the Elastic Beanstalk console.
2.
Follow the instructions shown.
Step 2: Create an Application
Next, you will create and deploy a sample application. For this step, you use a sample application that is
already prepared.
API Version 2010-12-01
3
AWS Elastic Beanstalk Developer Guide
Step 2: Create an Application
Elastic Beanstalk is free to use, but the AWS resources that it provides will be live (and not running in a
sandbox). You will incur the standard usage fees for these resources until you terminate them in the last
task in this tutorial. The total charges will be minimal (typically less than a dollar). For information on
how you might minimize any charges, go to http://aws.amazon.com/free/.
To create a sample application
1.
Open the Elastic Beanstalk Management Console with this preconfigured link: https://
console.aws.amazon.com/elasticbeanstalk/home#/newApplication?applicationName=gettingstarted&environmentType=LoadBalanced
2.
Choose a platform and then choose Review and launch.
3.
Review the available settings and choose Create app.
To run a sample application on AWS resources, Elastic Beanstalk takes the following actions, which takes
about 5 minutes to complete:
• Creates an Elastic Beanstalk application named getting-started.
• Launches an environment named Custom-env with the following AWS resources:
• EC2 instance – An Amazon Elastic Compute Cloud (Amazon EC2) virtual machine configured to run
web apps on the platform that you choose.
Each platform runs a different set of software, configuration files, and scripts to support a specific
language version, framework, web container, or combination thereof. Most platforms use either
Apache or nginx as a reverse proxy that sits in front of your web app, forwards requests to it, serves
static assets, and generates access and error logs.
• Instance security group – An Amazon EC2 security group configured to allow ingress on port 80.
This resource lets HTTP traffic from the load balancer reach the EC2 instance running your web app.
By default, traffic is not allowed on other ports.
API Version 2010-12-01
4
AWS Elastic Beanstalk Developer Guide
Step 3: View Information About Your Environment
• Load balancer – An Elastic Load Balancing load balancer configured to distribute requests to
the instances running your application. A load balancer also eliminates the need to expose your
instances directly to the Internet.
• Load balancer security group – An Amazon EC2 security group configured to allow ingress on port
80. This resource lets HTTP traffic from the Internet reach the load balancer. By default, traffic is not
allowed on other ports.
• Auto Scaling group – An Auto Scaling group configured to replace an instance if it is terminated or
becomes unavailable.
• Amazon S3 bucket – A storage location for your source code, logs, and other artifacts that are
created when you use Elastic Beanstalk.
• Amazon CloudWatch alarms – Two CloudWatch alarms that monitor the load on the instances in
your environment and are triggered if the load is too high or too low. When an alarm is triggered,
your Auto Scaling group scales up or down in response.
• AWS CloudFormation stack – Elastic Beanstalk uses AWS CloudFormation to launch the resources
in your environment and propagate configuration changes. The resources are defined in a template
that you can view in the AWS CloudFormation console.
• Domain name – A domain name that routes to your web app in the form
subdomain.region.elasticbeanstalk.com.
• Creates a new application version named Sample Application, which refers to the default Elastic
Beanstalk sample application file.
• Deploys the sample application code to Custom-env.
During the environment creation process, the console tracks its progress and displays events:
When all of the resources finish launching and the EC2 instances running the application pass health
checks, the environment's health changes to Ok and the website becomes ready to use.
Step 3: View Information About Your Environment
After you create the Elastic Beanstalk application, you can view information about the application you
deployed and its provisioned resources by going to the environment dashboard in the AWS Management
Console. The dashboard shows the health of your application's environment, the running version, and
the environment configuration.
While Elastic Beanstalk creates your AWS resources and launches your application, the environment
will be in a Pending state. Status messages about launch events are displayed in the environment's
dashboard.
API Version 2010-12-01
5
AWS Elastic Beanstalk Developer Guide
Step 3: View Information About Your Environment
If you are not currently viewing the Dashboard, return to it now:
To view the dashboard
1.
Open the Elastic Beanstalk console.
2.
Choose Custom-env
The dashboard shows a subset of useful information about your environment, including its current
health status, the name of the currently deployed application version, its five most recent events, and
the platform configuration on which the application runs.
On the left hand side of the console is a navigation bar that links to other pages, which contain more
detailed information about your environment and provide access to additional features. Explore the
following pages to see the current state of your environment:
• The Configuration page shows the resources provisioned for this environment, such as Amazon
EC2 instances that host your application. This page also lets you configure some of the provisioned
resources.
• The Health page shows the status and detailed health information about the EC2 instances running
your application.
API Version 2010-12-01
6
AWS Elastic Beanstalk Developer Guide
Step 4: Deploy a New Application Version
• The Monitoring page shows the statistics for the environment, such as average latency and CPU
utilization. This page also lets you create alarms for the metrics that you are monitoring.
• The Events page shows any informational or error messages from services that this environment is
using.
Step 4: Deploy a New Application Version
You can deploy a new version of your application at any time, as long as no other update operations are
currently in-progress on your environment.
The application version you are running now is labeled Sample Application.
To update your application version
1.
Download one of the following sample applications that match the configuration for your
environment:
• Go – go-v1.zip
• Java with Tomcat – java-tomcat-v3.zip
• Java SE – java-se-jetty-gradle-v3.zip
• .NET on Windows Server with IIS – dotnet-asp-v1.zip
• Node.js – nodejs-v1.zip
• PHP – php-v1.zip
• Python – python-v1.zip
• Ruby (Passenger Standalone) – ruby-passenger-v2.zip
• Ruby (Puma) – ruby-puma-v2.zip
• Single Container Docker – docker-singlecontainer-v1.zip
• Multicontainer Docker – docker-multicontainer-v2.zip
• Preconfigured Docker (Glassfish) – docker-glassfish-v1.zip
• Preconfigured Docker (Python 3.x) – docker-python-v1.zip
• Preconfigured Docker (Go) – docker-golang-v1.zip
2.
Open the Elastic Beanstalk console.
3.
From the Elastic Beanstalk applications page, choose My First Elastic Beanstalk Application and
then choose Custom-env.
4.
In the Overview section, choose Upload and Deploy.
5.
Choose Browse and upload the sample source bundle that you downloaded.
API Version 2010-12-01
7
AWS Elastic Beanstalk Developer Guide
Step 5: Change Configuration
6.
7.
The console automatically fills in the Version label based on the name of the archive that you
uploaded. For future deployments, you will need to type a unique version label if you use a source
bundle with the same name.
Choose Deploy.
Elastic Beanstalk now deploys your file to your Amazon EC2 instances. You can view the status of
your deployment on the environment's dashboard. The Environment Health status turns grey while
the application version is updated. When the deployment is complete, Elastic Beanstalk performs an
application health check. The status returns to green when the application responds to the health check.
The environment dashboard will show the new Running Version as Sample Application Second Version
(or whatever you provided as the Version label.
Your new application version is also uploaded and added to the table of application versions. To view
the table of application versions, choose My First Elastic Beanstalk Application and then choose
Application Versions.
Step 5: Change Configuration
You can customize your environment to better suit your application. For example, if you have a computeintensive application, you can change the type of Amazon EC2 instance that is running your application.
Some configuration changes are simple and happen quickly. Some changes require Elastic Beanstalk to
delete and recreate AWS resources, which can take several minutes. Elastic Beanstalk will warn you about
possible application downtime when changing configuration settings.
In this task, you change the minimum instance settings for your Auto Scaling group from one to two and
then verify that the change occurred. After the new instance gets created, it will become associated with
your load balancer.
API Version 2010-12-01
8
AWS Elastic Beanstalk Developer Guide
Step 5: Change Configuration
To change your environment configuration
1.
Open the Elastic Beanstalk console.
2.
Navigate to the management page (p. 61) for your environment.
3.
Choose Configuration.
4.
Choose Scaling.
5.
In the Auto Scaling section, change Minimum Instance Count from 1 to 2. This increases the
minimum number of Auto Scaling instances deployed in Amazon EC2.
6.
At the bottom of the page, choose Apply.
The environment update might take a few minutes. When the environment is ready, you can go to the
next task to verify your changes.
To verify changes to load balancers
1.
In the navigation pane, choose Events.
You will see the event Successfully deployed new configuration to environment in the events list.
This confirms that the Auto Scaling minimum instance count has been set to 2. A second instance is
launched automatically.
2.
Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.
3.
In the navigation pane, under LOAD BALANCING, click Load Balancers.
4.
Repeat the next two steps until you identify the load balancer with the desired instance name.
5.
Choose a load balancer in the list of load balancers.
6.
Choose the Instances tab in the Load Balancer: <load balancer name> pane, and then look at the
Name in the Instances table.
API Version 2010-12-01
9
AWS Elastic Beanstalk Developer Guide
Step 6: Clean Up
The information shows that two instances are associated with this load balancer, corresponding to
the increase in EC2 instances.
Step 6: Clean Up
Congratulations! You have successfully deployed a sample application to the cloud, uploaded a new
version, and modified its configuration to add a second Auto Scaling instance. To make sure you are
not charged for any services you don't need, delete any unwanted applications and environments from
Elastic Beanstalk and AWS services.
To completely delete the application
1.
2.
3.
Delete all application versions.
a.
Open the Elastic Beanstalk console.
b.
From the Elastic Beanstalk applications page, choose Custom-env in the My First Elastic
Beanstalk Application application.
c.
Choose Upload and Deploy.
d.
When prompted for an application, choose Application Versions page.
e.
On the Application Versions page, select all application versions that you want to delete, and
then choose Delete.
f.
Confirm the versions that you are deleting, and then click Delete.
g.
Choose Done.
Terminate the environment.
a.
Go back to the environment dashboard by clicking My First Elastic Beanstalk Application and
then Custom-env.
b.
Choose Actions and then choose Terminate Environment.
c.
Confirm that you are terminating Custom-env and then choose Terminate.
Delete the My First Elastic Beanstalk Application Elastic Beanstalk application.
a.
Choose Elastic Beanstalk at the upper left to return to the main dashboard.
b.
From the Elastic Beanstalk applications page, choose Actions for the My First Elastic Beanstalk
Application application and then choose Delete Application.
c.
Confirm that you want to delete this Elastic Beanstalk application by clicking Delete.
API Version 2010-12-01
10
AWS Elastic Beanstalk Developer Guide
Where to Go Next
Where to Go Next
Now that you have learned about Elastic Beanstalk and how to access it, we recommend that you read
How Elastic Beanstalk Works (p. 14) This topic provides information about the Elastic Beanstalk
components, the architecture, and important design considerations for your Elastic Beanstalk
application.
In addition to the AWS Management Console, you can also use the following tools to create and manage
Elastic Beanstalk environments:
Sections
• The EB CLI (p. 11)
• AWS SDK for Java (p. 11)
• AWS Toolkit for Eclipse (p. 11)
• AWS SDK for .NET (p. 12)
• AWS Toolkit for Visual Studio (p. 12)
• AWS SDK for Node.js (p. 12)
• AWS SDK for PHP (p. 12)
• Boto (AWS SDK for Python) (p. 12)
• AWS SDK for Ruby (p. 13)
The EB CLI
The EB CLI is a command line tool for creating and managing environments. See The Elastic Beanstalk
Command Line Interface (EB CLI) (p. 434) for details.
AWS SDK for Java
The AWS SDK for Java provides a Java API you can use to build applications that use AWS infrastructure
services. With the AWS SDK for Java, you can get started in minutes with a single, downloadable package
that includes the AWS Java library, code samples, and documentation.
The AWS SDK for Java requires J2SE Development Kit 5.0 or later. You can download the latest Java
software from http://developers.sun.com/downloads/. The SDK also requires Apache Commons (Codec,
HTTPClient, and Logging), and Saxon-HE third-party packages, which are included in the third-party
directory of the SDK.
For more information on using the AWS SDK for Java, go to the AWS SDK for Java.
AWS Toolkit for Eclipse
With the AWS Toolkit for Eclipse plug-in, you can create new AWS Java web projects that are
preconfigured with the AWS SDK for Java, and then deploy the web applications to Elastic Beanstalk. The
Elastic Beanstalk plug-in builds on top of the Eclipse Web Tools Platform (WTP). The toolkit provides a
Travel Log sample web application template that demonstrates the use of Amazon S3 and Amazon SNS.
To ensure you have all the WTP dependencies, we recommend that you start with the Java EE
distribution of Eclipse, which you can download from http://eclipse.org/downloads/.
For more information on using the Elastic Beanstalk plug-in for Eclipse, go to the AWS Toolkit for Eclipse
web page. To get started creating your Elastic Beanstalk application using Eclipse, see Creating and
Deploying Java Applications on AWS Elastic Beanstalk (p. 619).
API Version 2010-12-01
11
AWS Elastic Beanstalk Developer Guide
AWS SDK for .NET
AWS SDK for .NET
The AWS SDK for .NET enables you to build applications that use AWS infrastructure services. With the
AWS SDK for .NET, you can get started in minutes with a single, downloadable package that includes the
AWS .NET library, code samples, and documentation.
The AWS SDK for .NET requires .NET Framework 2.0 or later. It will work with any of the following Visual
Studio editions:
• Microsoft Visual Studio Professional Edition 2010 and 2012 (recommended)
• Microsoft Visual C# 2008 Express Edition
• Microsoft Visual Web Developer 2008 Express Edition
For more information on using the AWS SDK for .NET, go to the AWS SDK for .NET web page.
AWS Toolkit for Visual Studio
With the AWS Toolkit for Visual Studio plug-in, you can deploy an existing .NET application to Elastic
Beanstalk. You can also create new projects using the AWS templates that are preconfigured with the
AWS SDK for .NET. For prerequisite and installation information, go to AWS Toolkit for Visual Studio. To
get started creating your Elastic Beanstalk application using Visual Studio, see Creating and Deploying
Elastic Beanstalk Applications in .NET Using AWS Toolkit for Visual Studio (p. 659).
AWS SDK for Node.js
The AWS SDK for Node.js enables you to build applications on top of AWS infrastructure services. With
the AWS SDK for Node.js, you can get started in minutes with a single, downloadable package that
includes the AWS Node.js library, code samples, and documentation.
For more information on using the AWS SDK for Node.js, go to the AWS SDK for Node.js (Developer
Preview) web page.
AWS SDK for PHP
The AWS SDK for PHP enables you to build applications on top of AWS infrastructure services. With the
AWS SDK for PHP, you can get started in minutes with a single, downloadable package that includes the
AWS PHP library, code samples, and documentation.
The AWS SDK for PHP requires PHP 5.2 or later.
For more information on using the AWS SDK for PHP, go to the AWS SDK for PHP web page.
Boto (AWS SDK for Python)
With Boto, you can get started in minutes with a single, downloadable package complete with the AWS
Python library, code samples, and documentation. You can build Python applications on top of APIs that
take the complexity out of coding directly against web services interfaces. The all-in-one library provides
Python developer-friendly APIs that hide much of the lower-level tasks associated with programming
for the AWS cloud, including authentication, request retries, and error handling. Practical examples are
provided in Python for how to use the libraries to build applications. For information about Boto, sample
code, documentation, tools, and additional resources, go to http://aws.amazon.com/python/.
API Version 2010-12-01
12
AWS Elastic Beanstalk Developer Guide
AWS SDK for Ruby
AWS SDK for Ruby
You can get started in minutes with a single, downloadable package complete with the AWS Ruby
library, code samples, and documentation. You can build Ruby applications on top of APIs that take the
complexity out of coding directly against web services interfaces. The all-in-one library provides Ruby
developer-friendly APIs that hide much of the lower-level tasks associated with programming for the
AWS cloud, including authentication, request retries, and error handling. Practical examples are provided
in Ruby for how to use the libraries to build applications. For information about the SDK, sample code,
documentation, tools, and additional resources, go to http://aws.amazon.com/ruby/.
API Version 2010-12-01
13
AWS Elastic Beanstalk Developer Guide
Components
How Elastic Beanstalk Works
Topics
• Elastic Beanstalk Components (p. 14)
• Architectural Overview (p. 15)
• Service Roles, Instance Profiles, and User Policies (p. 17)
• Design Considerations (p. 21)
• Where to Go Next (p. 24)
Now that you have a better understanding of what Elastic Beanstalk is, let's take a peek under the hood
and see how Elastic Beanstalk works. The following sections discuss the Elastic Beanstalk components,
the architecture, and important design considerations for your Elastic Beanstalk application.
Elastic Beanstalk Components
The components that comprise Elastic Beanstalk work together to enable you to easily deploy and
manage your application in the cloud. This section discusses those components.
Application
An Elastic Beanstalk application is a logical collection of Elastic Beanstalk components, including
environments, versions, and environment configurations. In Elastic Beanstalk an application is
conceptually similar to a folder.
Application Version
In Elastic Beanstalk, an application version refers to a specific, labeled iteration of deployable code for
a web application. An application version points to an Amazon Simple Storage Service (Amazon S3)
object that contains the deployable code such as a Java WAR file. An application version is part of an
API Version 2010-12-01
14
AWS Elastic Beanstalk Developer Guide
Environment
application. Applications can have many versions and each application version is unique. In a running
environment, you can deploy any application version you already uploaded to the application or you
can upload and immediately deploy a new application version. You might upload multiple application
versions to test differences between one version of your web application and another.
Environment
An environment is a version that is deployed onto AWS resources. Each environment runs only a
single application version at a time, however you can run the same version or different versions in
many environments at the same time. When you create an environment, Elastic Beanstalk provisions
the resources needed to run the application version you specified. For more information about the
environment and the resources that are created, see Architectural Overview (p. 15).
Environment Configuration
An environment configuration identifies a collection of parameters and settings that define how an
environment and its associated resources behave. When you update an environment’s configuration
settings, Elastic Beanstalk automatically applies the changes to existing resources or deletes and deploys
new resources (depending on the type of change).
Configuration Template
A configuration template is a starting point for creating unique environment configurations.
Configuration templates can be created or modified by using the Elastic Beanstalk command line utilities
or API.
Architectural Overview
When you launch an Elastic Beanstalk environment, you choose an environment tier, platform, and
environment type. The environment tier that you choose determines whether Elastic Beanstalk
provisions resources to support a web application that handles HTTP(S) requests or a web application
that handles background-processing tasks. An environment tier whose web application processes web
requests is known as a web server tier. An environment tier whose web application runs background jobs
is known as a worker tier. This topic describes the components, resources, and architecture for each type
of environment tier.
Note
One environment cannot support two different environment tiers because each requires
its own set of resources; a worker environment tier and a web server environment tier each
require an Auto Scaling group, but Elastic Beanstalk supports only one Auto Scaling group per
environment.
Web Server Environment Tiers
This following diagram illustrates an example Elastic Beanstalk architecture for a web server
environment tier and shows how the components in that type of environment tier work together. The
remainder of this section discusses all the components in more detail.
API Version 2010-12-01
15
AWS Elastic Beanstalk Developer Guide
Web Server Environment Tiers
The environment is the heart of the application. In the diagram, the environment is delineated by the
solid blue line. When you create an environment, Elastic Beanstalk provisions the resources required to
run your application. AWS resources created for an environment include one elastic load balancer (ELB in
the diagram), an Auto Scaling group, and one or more Amazon EC2 instances.
Every environment has a CNAME (URL) that points to a load balancer. The environment has a URL such
as myapp.us-west-2.elasticbeanstalk.com. This URL is aliased in Amazon Route 53 to an Elastic Load
Balancing URL—something like abcdef-123456.us-west-2.elb.amazonaws.com—by using a CNAME
record. Amazon Route 53 is a highly available and scalable Domain Name System (DNS) web service. It
provides secure and reliable routing to your infrastructure. Your domain name that you registered with
your DNS provider will forward requests to the CNAME. The load balancer sits in front of the Amazon
EC2 instances, which are part of an Auto Scaling group. (The Auto Scaling group is delineated in the
diagram by a broken black line.) Auto Scaling automatically starts additional Amazon EC2 instances to
accommodate increasing load on your application. If the load on your application decreases, Auto Scaling
stops instances, but always leaves at least one instance running.
The software stack running on the Amazon EC2 instances is dependent on the container type. A container
type defines the infrastructure topology and software stack to be used for that environment. For
example, an Elastic Beanstalk environment with an Apache Tomcat container uses the Amazon Linux
operating system, Apache web server, and Apache Tomcat software. For a list of supported container
types, see Elastic Beanstalk Supported Platforms (p. 25). Each Amazon EC2 server instance that runs
your application uses one of these container types. In addition, a software component called the host
manager (HM) runs on each Amazon EC2 server instance. (In the diagram, the HM is an orange circle in
each EC2 instance.) The host manager is responsible for:
• Deploying the application
•
•
•
•
Aggregating events and metrics for retrieval via the console, the API, or the command line
Generating instance-level events
Monitoring the application log files for critical errors
Monitoring the application server
• Patching instance components
• Rotating your application's log files and publishing them to Amazon S3
The host manager reports metrics, errors and events, and server instance status, which are available via
the AWS Management Console, APIs, and CLIs.
API Version 2010-12-01
16
AWS Elastic Beanstalk Developer Guide
Worker Environment Tiers
The Amazon EC2 instances shown in the diagram are part of one security group. A security group defines
the firewall rules for your instances. By default, Elastic Beanstalk defines a security group, which allows
everyone to connect using port 80 (HTTP). You can define more than one security group. For instance,
you can define a security group for your database server. For more information about Amazon EC2
security groups and how to configure them for your Elastic Beanstalk application, see the Security
Groups (p. 248).
Worker Environment Tiers
AWS resources created for a worker environment tier include an Auto Scaling group, one or more
Amazon EC2 instances, and an IAM role. For the worker environment tier, Elastic Beanstalk also creates
and provisions an Amazon SQS queue if you don’t already have one. When you launch a worker
environment tier, Elastic Beanstalk installs the necessary support files for your programming language
of choice and a daemon on each EC2 instance in the Auto Scaling group. The daemon is responsible for
pulling requests from an Amazon SQS queue and then sending the data to the web application running
in the worker environment tier that will process those messages. If you have multiple instances in your
worker environment tier, each instance has its own daemon, but they all read from the same Amazon
SQS queue.
The following diagram shows the different components and their interactions across environments and
AWS services.
Amazon CloudWatch is used for alarms and health monitoring. For more information, go to Basic Health
Reporting (p. 303).
For details about how the worker environment tier works, see Worker Environments (p. 136).
Service Roles, Instance Profiles, and User Policies
When you create an environment, AWS Elastic Beanstalk prompts you to provide two AWS Identity
and Access Management (IAM) roles: a service role and an instance profile. The service role (p. 18) is
API Version 2010-12-01
17
AWS Elastic Beanstalk Developer Guide
Elastic Beanstalk Service Role
assumed by Elastic Beanstalk to use other AWS services on your behalf. The instance profile (p. 19) is
applied to the instances in your environment and allows them to upload logs to Amazon S3 and perform
other tasks that vary depending on the environment type and platform.
The best way to get a properly configured service role and instance profile is to create an environment
running a sample application (p. 68) in the Elastic Beanstalk console or by using the Elastic Beanstalk
Command Line Interface (EB CLI). When you create an environment, the clients create the required roles
and assign them managed policies (p. 362) that include all of the necessary permissions.
In addition to the two roles that you assign to your environment, you can also create user
policies (p. 20) and apply them to IAM users and groups in your account to allow users to create and
manage Elastic Beanstalk applications and environments. Elastic Beanstalk provides managed policies for
full access and read-only access.
You can create your own instance profiles and user policies for advanced scenarios. If your instances need
to access services that are not included in the default policies, you can add additional policies to the
default or create a new one. You can also create more restrictive user policies if the managed policy is
too permissive. See the AWS Identity and Access Management User Guide for in-depth coverage of AWS
permissions.
Sections
• Elastic Beanstalk Service Role (p. 18)
• Elastic Beanstalk Instance Profile (p. 19)
• Elastic Beanstalk User Policy (p. 20)
Elastic Beanstalk Service Role
A service role is the IAM role that Elastic Beanstalk assumes when calling other services on your behalf.
For example, Elastic Beanstalk uses the service role that you specify when creating an Elastic Beanstalk
environment when it calls Amazon Elastic Compute Cloud (Amazon EC2), Elastic Load Balancing, and
Auto Scaling APIs to gather information about the health of its AWS resources for enhanced health
monitoring (p. 306).
The AWSElasticBeanstalkEnhancedHealth managed policy contains all of the permissions that Elastic
Beanstalk needs to monitor environment health:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"elasticloadbalancing:DescribeInstanceHealth",
"ec2:DescribeInstances",
"ec2:DescribeInstanceStatus",
"ec2:GetConsoleOutput",
"ec2:AssociateAddress",
"ec2:DescribeAddresses",
"ec2:DescribeSecurityGroups",
"sqs:GetQueueAttributes",
"sqs:GetQueueUrl",
"autoscaling:DescribeAutoScalingGroups",
"autoscaling:DescribeAutoScalingInstances",
"autoscaling:DescribeScalingActivities",
"autoscaling:DescribeNotificationConfigurations"
],
"Resource": [
"*"
API Version 2010-12-01
18
AWS Elastic Beanstalk Developer Guide
Elastic Beanstalk Instance Profile
}
]
}
]
This policy also includes Amazon SQS actions to allow Elastic Beanstalk to monitor queue activity for
worker environments.
When you create an environment with the Elastic Beanstalk console, Elastic Beanstalk prompts you to
create a service role named aws-elasticbeanstalk-service-role with the default set of permissions
and a trust policy that allows Elastic Beanstalk to assume the service role. If you enable managed
platform updates (p. 125), Elastic Beanstalk attaches another policy with permissions that enable that
feature.
For more information about service roles, see Managing Elastic Beanstalk Service Roles (p. 358).
Elastic Beanstalk Instance Profile
An instance profile is an IAM role that is applied to instances launched in your Elastic Beanstalk
environment. When creating an Elastic Beanstalk environment, you specify the instance profile that is
used when your instances:
• Write logs to Amazon Simple Storage Service
• In AWS X-Ray integrated environments (p. 262), upload debugging data to X-Ray
• In multicontainer Docker environments, coordinate container deployments with Amazon EC2
Container Service
• In worker environments, read from an Amazon Simple Queue Service (Amazon SQS) queue
• In worker environments, perform leader election with Amazon DynamoDB
• In worker environments, publish instance health metrics to Amazon CloudWatch
The AWSElasticBeanstalkWebTier managed policy contains statements that allow instances in your
environment to upload logs to Amazon S3 and send debugging information to X-Ray:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "BucketAccess",
"Action": [
"s3:Get*",
"s3:List*",
"s3:PutObject"
],
"Effect": "Allow",
"Resource": [
"arn:aws:s3:::elasticbeanstalk-*",
"arn:aws:s3:::elasticbeanstalk-*/*"
]
},
{
"Sid": "XRayAccess",
"Action":[
"xray:PutTraceSegments",
"xray:PutTelemetryRecords"
],
"Effect": "Allow",
"Resource": "*"
},
API Version 2010-12-01
19
AWS Elastic Beanstalk Developer Guide
Elastic Beanstalk User Policy
{
}
]
}
"Sid": "CloudWatchLogsAccess",
"Action": [
"logs:PutLogEvents",
"logs:CreateLogStream"
],
"Effect": "Allow",
"Resource": [
"arn:aws:logs:*:*:log-group:/aws/elasticbeanstalk*"
]
Elastic Beanstalk also provides managed policies named AWSElasticBeanstalkWorkerTier and
AWSElasticBeanstalkMulticontainerDocker for the other use cases. Elastic Beanstalk attaches all of
these policies to the default instance profile, aws-elasticbeanstalk-ec2-role, when you create an
environment with the console or EB CLI.
If your web application requires access to any other AWS services, add statements or managed policies to
the instance profile that allow access to those services.
For more information about instance profiles, see Managing Elastic Beanstalk Instance Profiles (p. 354).
Elastic Beanstalk User Policy
Create IAM users for each person who uses Elastic Beanstalk to avoid using your root account or sharing
credentials. For increased security, only grant these users permission to access services and features that
they need.
Elastic Beanstalk requires permissions not only for its own API actions, but for several other AWS
services as well. Elastic Beanstalk uses user permissions to launch all of the resources in an environment,
including EC2 instances, an Elastic Load Balancing load balancer, and an Auto Scaling group. Elastic
Beanstalk also uses user permissions to save logs and templates to Amazon S3, send notifications to
Amazon SNS, assign instance profiles, and publish metrics to CloudWatch. Elastic Beanstalk requires AWS
CloudFormation permissions to orchestrate resource deployments and updates. It also requires Amazon
RDS permissions to create databases when needed, and Amazon SQS permissions to create queues for
worker environments.
The following policy allows access to the actions used to create and manage Elastic Beanstalk
environments. This policy is available in the IAM console as a managed policy named
AWSElasticBeanstalkFullAccess. You can apply the managed policy to an IAM user or group to grant
permission to use Elastic Beanstalk, or create your own policy that excludes permissions that are not
needed by your users.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"elasticbeanstalk:*",
"ec2:*",
"ecs:*",
"ecr:*",
"elasticloadbalancing:*",
"autoscaling:*",
"cloudwatch:*",
"s3:*",
"sns:*",
API Version 2010-12-01
20
AWS Elastic Beanstalk Developer Guide
Design Considerations
"cloudformation:*",
"dynamodb:*",
"rds:*",
"sqs:*",
"logs:*",
"iam:GetPolicyVersion",
"iam:GetRole",
"iam:PassRole",
"iam:ListRolePolicies",
"iam:ListAttachedRolePolicies",
"iam:ListInstanceProfiles",
"iam:ListRoles",
"iam:ListServerCertificates",
"acm:DescribeCertificate",
"acm:ListCertificates",
"codebuild:CreateProject",
"codebuild:DeleteProject",
"codebuild:BatchGetBuilds",
"codebuild:StartBuild"
},
{
},
{
}
]
}
],
"Resource": "*"
"Effect": "Allow",
"Action": [
"iam:AddRoleToInstanceProfile",
"iam:CreateInstanceProfile",
"iam:CreateRole"
],
"Resource": [
"arn:aws:iam::*:role/aws-elasticbeanstalk*",
"arn:aws:iam::*:instance-profile/aws-elasticbeanstalk*"
]
"Effect": "Allow",
"Action": [
"iam:AttachRolePolicy"
],
"Resource": "*",
"Condition": {
"StringLike": {
"iam:PolicyArn": [
"arn:aws:iam::aws:policy/AWSElasticBeanstalk*",
"arn:aws:iam::aws:policy/service-role/AWSElasticBeanstalk*"
]
}
}
Elastic Beanstalk also provides a read-only managed policy named
AWSElasticBeanstalkReadOnlyAccess. This policy allows a user to view, but not modify or create, Elastic
Beanstalk environments.
For more information about user policies, see Controlling Access to Elastic Beanstalk (p. 362).
Design Considerations
Because applications deployed using Elastic Beanstalk run on Amazon cloud resources, you should keep
several things in mind when designing your application: scalability, security, persistent storage, fault
API Version 2010-12-01
21
AWS Elastic Beanstalk Developer Guide
Scalability
tolerance, content delivery, software updates and patching, and connectivity. For a comprehensive list
of technical AWS whitepapers, covering topics such as architecture, security and economics, go to AWS
Cloud Computing Whitepapers.
Scalability
When you're operating in a physical hardware environment, as opposed to a cloud environment, you
can approach scalability two ways—you can scale up (vertical scaling) or scale out (horizontal scaling).
The scale-up approach requires an investment in powerful hardware as the demands on the business
increase, whereas the scale-out approach requires following a distributed model of investment, so
hardware and application acquisitions are more targeted, data sets are federated, and design is serviceoriented. The scale-up approach could become very expensive, and there's still the risk that demand
could outgrow capacity. Although the scale-out approach is usually more effective, it requires predicting
the demand at regular intervals and deploying infrastructure in chunks to meet demand. This approach
often leads to unused capacity and requires careful monitoring.
By moving to the cloud you can bring the use of your infrastructure into close alignment with demand
by leveraging the elasticity of the cloud. Elasticity is the streamlining of resource acquisition and release,
so that your infrastructure can rapidly scale in and scale out as demand fluctuates. To implement
elasticity, configure your Auto Scaling settings to scale up or down based on metrics from the resources
in your environment (utilization of the servers or network I/O, for instance). You can use Auto Scaling
to automatically add compute capacity when usage rises and remove it when usage drops. Publish
system metrics (CPU, memory, disk I/O, network I/O) to Amazon CloudWatch and configure alarms to
trigger Auto Scaling actions or send notifications. For more instructions on configuring Auto Scaling, see
Configuring Auto Scaling with Elastic Beanstalk (p. 238).
Elastic Beanstalk applications should also be as stateless as possible, using loosely coupled, faulttolerant components that can be scaled out as needed. For more information about designing scalable
application architectures for AWS, read the Architecting for the Cloud: Best Practices whitepaper.
Security
Security on AWS is a shared responsibility. AWS protects the physical resources in your environment and
ensure that the cloud is a safe place for you to run applications. You are responsible for the security of
data coming in and out of your Elastic Beanstalk environment and the security of your application.
Configure SSL to protect information from your clients. You will need a certificate from an external
certification authority such as VeriSign or Entrust. The public key included in the certificate authenticates
your server to the browser and serves as the basis for creating the shared session key used to encrypt the
data in both directions. For instructions on creating, uploading, and assigning an SSL certificate to your
environment, see Configuring HTTPS for your Elastic Beanstalk Environment (p. 270).
When you configure an SSL certificate for your environment, data is encrypted between the client and
your environment's Elastic Load Balancing load balancer. By default, encryption is terminated at the load
balancer and traffic between the load balancer and Amazon EC2 instances is unencrypted.
Persistent Storage
Elastic Beanstalk applications run on Amazon EC2 instances that have no persistent local storage. When
the Amazon EC2 instances terminate, the local file system is not saved, and new Amazon EC2 instances
start with a default file system. You should design your application to store data in a persistent data
source. Amazon Web Services offers a number of persistent storage options that you can leverage for
your application, including:
• Amazon Simple Storage Service (Amazon S3). For more information about Amazon S3, go to the
documentation.
API Version 2010-12-01
22
AWS Elastic Beanstalk Developer Guide
Fault Tolerance
• Amazon Elastic Block Store (Amazon EBS). For more information, go to the documentation and see
also the article Feature Guide: Elastic Block Store.
• Amazon DynamoDB. For more information, go to the documentation. For an example using Amazon
DynamoDB with Elastic Beanstalk, see Example: DynamoDB, CloudWatch, and SNS (p. 225).
• Amazon Relational Database Service (Amazon RDS). For more information, go to the documentation
and see also Amazon RDS for C# Developers.
Fault Tolerance
As a rule of thumb, you should be a pessimist when designing architecture for the cloud. Always design,
implement, and deploy for automated recovery from failure. Use multiple Availability Zones for your
Amazon EC2 instances and for Amazon RDS. Availability Zones are conceptually like logical data centers.
Use Amazon CloudWatch to get more visibility into the health of your Elastic Beanstalk application and
take appropriate actions in case of hardware failure or performance degradation. Configure your Auto
Scaling settings to maintain your fleet of Amazon EC2 instances at a fixed size so that unhealthy Amazon
EC2 instances are replaced by new ones. If you are using Amazon RDS, then set the retention period for
backups, so that Amazon RDS can perform automated backups.
Content Delivery
When users connect to your website, their requests may be routed through a number of individual
networks. As a result users may experience poor performance due to high latency. Amazon CloudFront
can help ameliorate latency issues by distributing your web content (such as images, video, and so on)
across a network of edge locations around the world. End users are routed to the nearest edge location,
so content is delivered with the best possible performance. CloudFront works seamlessly with Amazon
S3, which durably stores the original, definitive versions of your files. For more information about
Amazon CloudFront, see http://aws.amazon.com/cloudfront.
Software Updates and Patching
Elastic Beanstalk periodically updates its platform configurations with new software and patches. Elastic
Beanstalk does not upgrade running environments to new configuration versions automatically, but
you can initiate a platform upgrade (p. 123) to update your running environment in place. Platform
upgrades use rolling updates (p. 117) to keep your application available by applying changes in
batches.
Connectivity
Elastic Beanstalk needs to be able to connect to the instances in your environment to complete
deployments. When you deploy an Elastic Beanstalk application inside an Amazon VPC, the configuration
required to enable connectivity depends on the type of Amazon VPC environment you create:
• For single-instance environments, no additional configuration is required because Elastic Beanstalk
assigns each Amazon EC2 instance a public Elastic IP address that enables the instance to
communicate directly with the Internet.
• For load-balancing, autoscaling environments in an Amazon VPC with both public and private subnets,
you must do the following:
• Create a load balancer in the public subnet to route inbound traffic from the Internet to the Amazon
EC2 instances.
• Create a network address translation (NAT) device to route outbound traffic from the Amazon EC2
instances to the Internet.
• Create inbound and outbound routing rules for the Amazon EC2 instances inside the private subnet.
API Version 2010-12-01
23
AWS Elastic Beanstalk Developer Guide
Where to Go Next
• If using a NAT instance, configure the security groups for the NAT instance and Amazon EC2
instances to enable Internet communication.
• For a load-balancing, autoscaling environment in an Amazon VPC that has one public subnet, no
additional configuration is required because the Amazon EC2 instances are configured with a public IP
address that enables the instances to communicate with the Internet.
For more information about using Elastic Beanstalk with Amazon VPC, see Using Elastic Beanstalk with
Amazon VPC (p. 408).
Where to Go Next
Now that you have learned some Elastic Beanstalk basics, you are ready to start creating and deploying
your applications. If you are a developer, go to one of the following sections:
• Java — Creating and Deploying Java Applications on AWS Elastic Beanstalk (p. 619)
• .NET — Creating and Deploying Elastic Beanstalk Applications in .NET Using AWS Toolkit for Visual
Studio (p. 659)
• Node.js — Deploying Node.js Applications to AWS Elastic Beanstalk (p. 716)
• PHP — Creating and Deploying PHP Applications on AWS Elastic Beanstalk (p. 752)
• Python — Working with Python (p. 802)
• Ruby — Deploying Elastic Beanstalk Applications in Ruby Using EB CLI and Git (p. 824)
If you want to manage and configure your applications and environments using the AWS Management
Console, command line interface, or APIs, see Managing and Configuring AWS Elastic Beanstalk
Applications (p. 47).
API Version 2010-12-01
24
AWS Elastic Beanstalk Developer Guide
Supported Platforms
Elastic Beanstalk Platforms
Topics
• Elastic Beanstalk Supported Platforms (p. 25)
• Custom Platforms (p. 35)
Elastic Beanstalk provides platforms for programming languages (Java, PHP, Python, Ruby, Go), web
containers (Tomcat, Passenger, Puma), and Docker containers, with multiple configurations of each.
Elastic Beanstalk also supports custom platforms that can be based on an AMI that you create and can
include further customizations.
Elastic Beanstalk Supported Platforms
AWS Elastic Beanstalk provides platforms for programming languages (Java, PHP, Python, Ruby, Go), web
containers (Tomcat, Passenger, Puma) and Docker containers, with multiple configurations of each.
Elastic Beanstalk provisions the resources needed to run your application, including one or more Amazon
EC2 instances. The software stack running on the Amazon EC2 instances depends on the configuration.
In a configuration name, the version number refers to the version of the platform configuration.
You can use the solution stack name listed under the configuration name to launch an environment with
the EB CLI (p. 434), Elastic Beanstalk API, or AWS CLI. You can also retrieve solution stack names from
the service with the ListAvailableSolutionStacks API (aws elasticbeanstalk list-available-solution-stacks in
the AWS CLI). This operation returns all of the solution stacks that you can use to create an environment.
Note
You can use solution stacks for the latest platform configurations (the current versions listed on
this page) to create an environment.
In addition, a platform configuration that you used to launch or update an environment remains
available (to the account in use, in the region used) even after it's no longer current, as long as
the environment is active, and up to 30 days after its termination.
All current Linux-based platform configurations run on Amazon Linux 2017.03 (64-bit). You can
customize and configure the software that your application depends on in your Linux platform. Learn
API Version 2010-12-01
25
AWS Elastic Beanstalk Developer Guide
Packer Builder
more at Customizing Software on Linux Servers (p. 200). Detailed release notes are available for recent
releases at aws.amazon.com/releasenotes.
Platforms
• Packer Builder (p. 26)
• Single Container Docker (p. 26)
• Multicontainer Docker (p. 27)
• Preconfigured Docker (p. 27)
• Go (p. 28)
• Java SE (p. 28)
• Java with Tomcat (p. 29)
• .NET on Windows Server with IIS (p. 29)
• Node.js (p. 31)
• PHP (p. 32)
• Python (p. 32)
• Ruby (p. 33)
Packer Builder
Packer is an open-source tool for creating machine images for many platforms, including AMIs for use
with Amazon EC2.
Configuration and Solution
Stack Name
AMI
Packer Version
Elastic Beanstalk Packer Builder
version 2.3.2
2017.03.1
1.0.3
64bit Amazon Linux 2017.03
v2.3.2 running Packer 1.0.3
For information on previous configurations, see Packer Platform History (p. 850).
Single Container Docker
Docker is a container platform that allows you to define your own software stack and store it in an image
that can be downloaded from a remote repository. Use the Single Container Docker platform if you
only need to run a single Docker container on each instance in your environment. The single container
configuration includes an nginx proxy server.
See Deploying Elastic Beanstalk Applications from Docker Containers (p. 581) for more information
about the Docker platform.
Configuration and Solution
Stack Name
AMI
Docker Version
Proxy Server
Single Container Docker 17.03
version 2.7.3
2017.03.1
17.03.1-ce
nginx 1.10.3
64bit Amazon Linux 2017.03
v2.7.3 running Docker 17.03.1-ce
API Version 2010-12-01
26
AWS Elastic Beanstalk Developer Guide
Multicontainer Docker
For information on previous configurations, see Docker Platform History (p. 853).
Multicontainer Docker
Docker is a container platform that allows you to define your own software stack and store it in an image
that can be downloaded from a remote repository. Use the Multicontainer Docker platform if you need
to run multiple containers on each instance. The Multicontainer Docker platform does not include a
proxy server.
See Deploying Elastic Beanstalk Applications from Docker Containers (p. 581) for more information
about the Docker platform.
Configuration and Solution
Stack Name
AMI
Docker Version
ECS Agent
Multicontainer Docker 17.03
version 2.7.4
2017.03.1
17.03.1-ce
1.14.3
64bit Amazon Linux 2017.03
v2.7.4 running Multi-container
Docker 17.03.1-ce (Generic)
For information on previous configurations, see Docker Platform History (p. 853).
Preconfigured Docker
Preconfigured Docker platform configurations use Docker, but do not let you provide your own Docker
images. The preconfigured containers provide application frameworks that are not available on other
platforms, such as Glassfish. They also provide support for Go applications prior to the release of the
full-fledged Go platform.
Configuration and
Solution Stack Name
AMI
Glassfish 4.1 (Docker)
version 2.7.3
2017.03.1
Docker Debian Java
17.03.1Jessie 8
ce
nginx
1.10.3
Glassfish
4.1
amazon/aws-ebglassfish:4.1-jdk8onbuild-3.5.1
2017.03.1
Docker Debian Java
17.03.1Jessie 7
ce
nginx
1.10.3
Glassfish
4.0
amazon/aws-ebglassfish:4.0-jdk7onbuild-3.5.1
none
golang:1.4.2-onbuild
64bit Debian jessie
v2.7.3 running
GlassFish 4.1 Java
8 (Preconfigured Docker)
Glassfish 4.0 (Docker)
version 2.7.3
64bit Debian jessie
v2.7.3 running
GlassFish 4.0 Java
7 (Preconfigured Docker)
Go 1.4 (Docker)
version 2.7.3
Platform
Container
Language
Proxy
OS
Server
2017.03.1
Docker Debian Go
nginx
17.03.1Jessie 1.4.2 1.10.3
ce
API Version 2010-12-01
27
Application Docker Image
Server
AWS Elastic Beanstalk Developer Guide
Go
Configuration and
Solution Stack Name
AMI
Platform
Container
Language
Proxy
OS
Server
Application Docker Image
Server
64bit Debian jessie
v2.7.3 running Go
1.4 (Preconfigured Docker)
Go 1.3 (Docker)
version 2.7.3
64bit Debian jessie
v2.7.3 running Go
1.3 (Preconfigured Docker)
Python 3.4 with
uWSGI 2 (Docker)
version 2.7.3
2017.03.1
Docker Debian Go
nginx
17.03.1Jessie 1.3.3 1.10.3
ce
none
golang:1.3.3-onbuild
2017.03.1
Docker Debian Pythonnginx
17.03.1Jessie 3.4
1.10.3
ce
uWSGI
2.0.8
amazon/awseb-python:3.4.2onbuild-3.5.1
64bit Debian jessie
v2.7.3 running Python
3.4 (Preconfigured Docker)
For information on previous configurations, see Preconfigured Docker Platform History (p. 868).
Go
Elastic Beanstalk supports the following Go configurations.
Configuration and Solution Stack AMI
Name
Go 1.8 version 2.6.0
Language
Proxy Server
2017.03.1 Go 1.8.3
nginx 1.10.3
64bit Amazon Linux 2017.03
v2.6.0 running Go 1.8
For information on previous configurations, see Go Platform History (p. 897).
Java SE
Elastic Beanstalk supports the following Java SE configurations.
Configuration and Solution
Stack Name
AMI
Java 8 version 2.5.4
64bit Amazon Linux 2017.03
v2.5.4 running Java 8
Java 7 version 2.5.4
Language
Tools
AWS
Proxy Server
X‑Ray
2017.03.1
Java
1.8.0_141
Ant 1.9.6, Gradle
2.7, Maven 3.3.3
2.0.0
nginx 1.10.3
2017.03.1
Java
1.7.0_151
Ant 1.9.6, Gradle
2.7, Maven 3.3.3
2.0.0
nginx 1.10.3
API Version 2010-12-01
28
AWS Elastic Beanstalk Developer Guide
Java with Tomcat
Configuration and Solution
Stack Name
AMI
Language
Tools
AWS
Proxy Server
X‑Ray
64bit Amazon Linux 2017.03
v2.5.4 running Java 7
For information on previous configurations, see Java SE Platform History (p. 923).
Java with Tomcat
Elastic Beanstalk supports the following Tomcat configurations.
AWS X‑Ray
Application
Server
Proxy Server
2017.03.1
Java 1.8.0_141
2.0.0
Tomcat 8.0.45
Apache 2.2.32
2017.03.1
Java 1.7.0_151
2.0.0
Tomcat 7.0.79
Apache 2.2.32
2017.03.1
Java 1.6.0_41
2.0.0
Tomcat 7.0.79
Apache 2.2.32
Configuration and
AMI
Solution Stack Name
Java 8 with Tomcat
8 version 2.6.4
Language
64bit Amazon Linux
2017.03 v2.6.4
running Tomcat 8
Java 8
Java 7 with Tomcat
7 version 2.6.4
64bit Amazon Linux
2017.03 v2.6.4
running Tomcat 7
Java 7
Java 6 with Tomcat
7 version 2.6.4
64bit Amazon Linux
2017.03 v2.6.4
running Tomcat 7
Java 6
For information on previous configurations, see Tomcat Platform History (p. 902).
.NET on Windows Server with IIS
You can get started in minutes using the AWS Toolkit for Visual Studio. The toolkit includes the AWS
libraries, project templates, code samples, and documentation. The AWS SDK for .NET supports the
development of applications using .NET Framework 2.0 or later.
Note
This platform does not support worker environments, enhanced health reporting, managed
updates, bundle logs, immutable updates, or log streaming.
To learn how to get started deploying a .NET application using the AWS Toolkit for Visual Studio,
see Creating and Deploying Elastic Beanstalk Applications in .NET Using AWS Toolkit for Visual
Studio (p. 659).
API Version 2010-12-01
29
AWS Elastic Beanstalk Developer Guide
.NET on Windows Server with IIS
For information about the latest security updates, see Microsoft Security Bulletin Summary for 2017.
For information on previous configurations, see .NET on Windows Server with IIS Platform
History (p. 929).
Elastic Beanstalk supports the following .NET configurations.
Configuration basics
Configuration
Solution Stack Name
Framework
Proxy
Server
Windows Server 2016 with
IIS 10.0 version 1.2.0
64bit Windows Server 2016
v1.2.0 running IIS 10.0
.NET Core 2.0, supports 1.1.x,
1.0.x
IIS 10.0
.NET Framework 4.7,
supports 4.x, 2.0, 1.x
Windows Server Core 2016
with IIS 10.0 version 1.2.0
64bit Windows Server Core
2016 v1.2.0 running IIS 10.0
.NET Core 2.0, supports 1.1.x,
1.0.x
IIS 10.0
.NET Framework 4.7,
supports 4.x, 2.0, 1.x
Windows Server 2012 R2
with IIS 8.5 version 1.2.0
64bit Windows Server 2012
R2 v1.2.0 running IIS 8.5
.NET Core 2.0, supports 1.1.x,
1.0.x
IIS 8.5
.NET Framework 4.7,
supports 4.x, 2.0, 1.x
Windows Server 2012 R2
Server Core with IIS 8.5
version 1.2.0
64bit Windows Server Core
2012 R2 v1.2.0 running IIS
8.5
.NET Core 2.0, supports 1.1.x,
1.0.x
Windows Server 2012 with
IIS 8 version 1.2.0
64bit Windows Server 2012
v1.2.0 running IIS 8
.NET Core 2.0, supports 1.1.x,
1.0.x
IIS 8.5
.NET Framework 4.7,
supports 4.x, 2.0, 1.x
IIS 8
.NET Framework 4.7,
supports 4.x, 2.0, 1.x
Windows Server 2008 R2
with IIS 7.5 version 1.2.0
64bit Windows Server 2008
R2 v1.2.0 running IIS 7.5
.NET Core 2.0, supports 1.1.x,
1.0.x
IIS 7.5
.NET Framework 4.7,
supports 4.x, 2.0, 1.x
Windows Server 2012 R2
with IIS 8.5
64bit Windows Server 2012
R2 running IIS 8.5
.NET Framework 4.7,
supports 4.x, 2.0, 1.x
IIS 8.5
Windows Server 2012 R2
Server Core with IIS 8.5
64bit Windows Server Core
2012 R2 running IIS 8.5
.NET Framework 4.7,
supports 4.x, 2.0, 1.x
IIS 8.5
Windows Server 2012 with
IIS 8
64bit Windows Server 2012
running IIS 8
.NET Framework 4.7,
supports 4.x, 2.0, 1.x
IIS 8
Windows Server 2008 R2
with IIS 7.5
64bit Windows Server 2008
R2 running IIS 7.5
.NET Framework 4.7,
supports 4.x, 2.0, 1.x
IIS 7.5
API Version 2010-12-01
30
AWS Elastic Beanstalk Developer Guide
Node.js
More details
Configuration
AMI
version
AWS SDK
for .NET
EC2Config SSM
Agent
Web
Deploy
AWS
X‑Ray
Windows Server 2016 with
IIS 10.0 version 1.2.0
2017.08.09
3.3.103.0
SSM only
2.0.879.0
3.6
1.0.0
Windows Server Core 2016
with IIS 10.0 version 1.2.0
2017.08.09
3.3.103.0
SSM only
2.0.879.0
3.6
1.0.0
Windows Server 2012 R2
with IIS 8.5 version 1.2.0
2017.08.09
3.3.58.0
4.9.2016
2.0.879.0
3.6
1.0.0
Windows Server 2012 R2
Server Core with IIS 8.5
version 1.2.0
2017.08.09
3.3.58.0
4.9.2016
2.0.879.0
3.6
1.0.0
Windows Server 2012 with
IIS 8 version 1.2.0
2017.08.09
3.3.102.0
4.9.2016
2.0.879.0
3.6
1.0.0
Windows Server 2008 R2
with IIS 7.5 version 1.2.0
2017.08.09
3.3.102.0
4.9.1981
2.0.847.0
3.6
1.0.0
Windows Server 2012 R2
with IIS 8.5
2017.08.09
3.3.58.0
4.9.2016
2.0.879.0
3.6
1.0.0
Windows Server 2012 R2
Server Core with IIS 8.5
2017.08.09
3.3.58.0
4.9.2016
2.0.879.0
3.6
1.0.0
Windows Server 2012 with
IIS 8
2017.08.09
3.3.102.0
4.9.2016
2.0.879.0
3.6
1.0.0
Windows Server 2008 R2
with IIS 7.5
2017.08.09
3.3.102.0
4.9.1981
2.0.847.0
3.6
1.0.0
Node.js
The Node.js platform includes a few Node.js versions in a single configuration. The
following table lists them. The default version applies when the NodeVersion option in the
aws:elasticbeanstalk:container:nodejs namespace isn't set. See Node.js Platform Options (p. 190)
for details.
Each Node.js version includes a respective version of npm (the Node.js package manager). The table lists
npm versions in parentheses.
Elastic Beanstalk supports the following Node.js configurations.
Configuration and
Solution Stack Name
AMI
Platform (Package Manager
— npm)
Node.js version 4.2.2
2017.03.18.1.4 (5.0.3), 7.10.1 (4.2.0),
7.6.0 (4.1.2), 6.11.1 (3.10.10),
6.10.0 (3.10.10), 5.12.0 (3.8.6),
4.8.4 (2.15.11), 4.8.0 (2.15.11)
API Version 2010-12-01
31
Proxy Server
Git
AWS
X‑Ray
nginx 1.10.3,
Apache 2.4.27
2.7.4
2.0.0
AWS Elastic Beanstalk Developer Guide
PHP
Configuration and
Solution Stack Name
AMI
64bit Amazon Linux
2017.03 v4.2.2
running Node.js
Platform (Package Manager
— npm)
Proxy Server
Git
AWS
X‑Ray
Default platform: 6.11.1
For information on previous configurations, see Node.js Platform History (p. 958).
Note
When support for the version of Node.js that you are using is removed from the platform
configuration, you must change or remove the version setting prior to doing a platform
upgrade (p. 123). This may occur when a security vulnerability is identified for one or more
versions of Node.js
When this occurs, attempting to upgrade to a new version of the platform that does not support
the configured NodeVersion (p. 190) will fail. To avoid needing to create a new environment,
change the NodeVersion configuration option to a version that is supported by both the old
configuration version and the new one, or remove the option setting (p. 154), and then
perform the platform upgrade.
PHP
Elastic Beanstalk supports the following PHP configurations.
Configuration and
Solution Stack Name
AMI
PHP 7.0 version 2.4.4
Language
Composer
Proxy Server
2017.03.1 PHP 7.0.21
1.4.1
Apache 2.4.27
2017.03.1 PHP 5.6.31
1.4.1
Apache 2.4.27
2017.03.1 PHP 5.5.38
1.4.1
Apache 2.4.27
2017.03.1 PHP 5.4.45
1.4.1
Apache 2.4.27
64bit Amazon Linux
2017.03 v2.4.4 running
PHP 7.0
PHP 5.6 version 2.4.4
64bit Amazon Linux
2017.03 v2.4.4 running
PHP 5.6
PHP 5.5 version 2.4.4
64bit Amazon Linux
2017.03 v2.4.4 running
PHP 5.5
PHP 5.4 version 2.4.4
64bit Amazon Linux
2017.03 v2.4.4 running
PHP 5.4
For information on previous configurations, see PHP Platform History (p. 972).
Python
Elastic Beanstalk supports the following Python configurations.
API Version 2010-12-01
32
AWS Elastic Beanstalk Developer Guide
Ruby
Configuration
and Solution
Stack Name
AMI
Python 3.4
version 2.5.1
Language
Package
Manager
Packager
meld3
AWS Proxy
X‑Ray Server
2017.03.1
Python 3.4.3
pip 7.1.2
setuptools meld3
18.4
1.0.2
2.0.0
Apache
2.4.27
with
mod_wsgi
3.5
2017.03.1
Python 2.7.12
pip 7.1.2
setuptools meld3
18.4
1.0.2
2.0.0
Apache
2.4.27
with
mod_wsgi
3.5
2017.03.1
Python 2.6.9
pip 7.1.2
setuptools meld3
18.4
1.0.2
2.0.0
Apache
2.4.27
with
mod_wsgi
3.5
64bit Amazon
Linux 2017.03
v2.5.1 running
Python 3.4
Python 2.7
version 2.5.1
64bit Amazon
Linux 2017.03
v2.5.1 running
Python 2.7
Python 2.6
version 2.5.1
64bit Amazon
Linux 2017.03
v2.5.1 running
Python
For information on previous configurations, see Python Platform History (p. 993).
Ruby
Elastic Beanstalk supports the following Ruby configurations.
Configuration and
Solution Stack
Name
AMI
Ruby 2.3 with
Puma version 2.4.4
Language
Package Application Server
Manager
Proxy
Server
2017.03.1Ruby
2.3.4-p301
RubyGems
Puma 2.16.0
2.5.1
nginx
1.10.3
2017.03.1Ruby
2.3.4-p301
RubyGems
Passenger 4.0.60
2.5.1
nginx
1.10.2
64bit Amazon Linux
2017.03 v2.4.4
running Ruby 2.3
(Puma)
Ruby 2.3 with
Passenger version
2.4.4
64bit Amazon
Linux 2017.03
v2.4.4 running
Ruby 2.3 (Passenger
Standalone)
API Version 2010-12-01
33
AWS Elastic Beanstalk Developer Guide
Ruby
Configuration and
Solution Stack
Name
AMI
Ruby 2.2 with
Puma version 2.4.4
Language
Package Application Server
Manager
Proxy
Server
2017.03.1Ruby
2.2.7-p470
RubyGems
Puma 2.16.0
2.4.5.1
nginx
1.10.3
2017.03.1Ruby
2.2.7-p470
RubyGems
Passenger 4.0.60
2.4.5.1
nginx
1.10.2
2017.03.1Ruby
2.1.10p492
RubyGems
Puma 2.16.0
2.2.5
nginx
1.10.3
2017.03.1Ruby
2.1.10p492
RubyGems
Passenger 4.0.60
2.2.5
nginx
1.10.2
2017.03.1Ruby
2.0.0-p648
RubyGems
Puma 2.16.0
2.0.14.1
nginx
1.10.3
2017.03.1Ruby
2.0.0-p648
RubyGems
Passenger 4.0.60
2.0.14.1
nginx
1.10.2
64bit Amazon Linux
2017.03 v2.4.4
running Ruby 2.2
(Puma)
Ruby 2.2 with
Passenger version
2.4.4
64bit Amazon
Linux 2017.03
v2.4.4 running
Ruby 2.2 (Passenger
Standalone)
Ruby 2.1 with
Puma version 2.4.4
64bit Amazon Linux
2017.03 v2.4.4
running Ruby 2.1
(Puma)
Ruby 2.1 with
Passenger version
2.4.4
64bit Amazon
Linux 2017.03
v2.4.4 running
Ruby 2.1 (Passenger
Standalone)
Ruby 2.0 with
Puma version 2.4.4
64bit Amazon Linux
2017.03 v2.4.4
running Ruby 2.0
(Puma)
Ruby 2.0 with
Passenger version
2.4.4
64bit Amazon
Linux 2017.03
v2.4.4 running
Ruby 2.0 (Passenger
Standalone)
API Version 2010-12-01
34
AWS Elastic Beanstalk Developer Guide
Custom Platforms
Configuration and
Solution Stack
Name
AMI
Language
Ruby 1.9 with
Passenger version
2.4.4
2017.03.1Ruby
1.9.3-p551
Package Application Server
Manager
Proxy
Server
RubyGems
Passenger 4.0.60
1.8.23.2
nginx
1.10.2
64bit Amazon Linux
2017.03 v2.4.4
running Ruby 1.9.3
For information on previous configurations, see Ruby Platform History (p. 1009).
Custom Platforms
Elastic Beanstalk supports custom platforms that can be based on an Amazon Machine Image (AMI) that
you create (p. 250) from one of the supported operating systems, Ubuntu, RHEL, or Amazon Linux
(see the flavor entry in Platform.yaml File Format (p. 42) for the exact version numbers) and can
include further customizations. Create your own Elastic Beanstalk platform with Packer, which is an
open-source tool for creating machine images for many platforms, including AMIs for use with Amazon
EC2. An Elastic Beanstalk platform comprises an AMI configured to run a set of software that supports
an application, and metadata that can include custom configuration options and default configuration
option settings.
Note
When using the AWS management console to deploy environments to a custom platform, you
must use the new version of the console.
You create a platform by providing Elastic Beanstalk with a Packer template, and the scripts and files
that the template invokes to build an AMI. These components are packaged with a platform definition
file (p. 36), which specifies the template and metadata, into a ZIP archive called a platform definition
archive (p. 40).
When you create a custom platform, you launch a single instance environment without an EIP that runs
Packer, which launches another instance to build an image. You can reuse this environment for multiple
platforms and multiple versions of each platform.
Note
Custom platforms are region-specific. If you use Elastic Beanstalk in multiple regions, you must
create your platforms separately in each region.
In certain circumstances, instances launched by Packer are not cleaned up and have to be
manually terminated. To learn how to manually clean up these instances, see ??? (p. 41).
Users in your account can use your custom platforms by specifying a platform ARN (p. 366) during
environment creation. These ARNs are returned by the eb platform create command that you used to
create the custom platform.
Each time you build your custom platform, Elastic Beanstalk creates a new platform version. Users can
specify a platform by name to get only the latest version of the platform, or include a version number to
get a specific version.
For example, to deploy the latest version of the custom platform with the ARN MyCustomPlatformARN,
which could be version 3.0, your EB CLI command line would look like:
eb deploy -p MyCustomPlatformARN
API Version 2010-12-01
35
AWS Elastic Beanstalk Developer Guide
Creating a Custom Platform
To deploy version 2.1 your EB CLI command line would look like:
eb deploy -p MyCustomPlatformARN --version 2.1
Topics
• Creating a Custom Platform (p. 36)
• Using a Sample Custom Platform (p. 36)
• Platform Definition Archive Contents (p. 40)
• Platform Hooks (p. 40)
• Platform Scripts (p. 41)
• Packer Instance Cleanup (p. 41)
• Platform.yaml File Format (p. 42)
Creating a Custom Platform
To create a custom platform, the root of your application must include a platform.yaml file, which
defines the type of builder used to create the custom platform. The format of this file is described in
the Platform.yaml File Format (p. 42) topic. As an alternative to creating your custom platform from
scratch, you can use one of the sample custom platforms (p. 36).
Using a Sample Custom Platform
One alternative to rolling your own custom platform is to use one of the platform definition archive
samples to bootstrap your custom platform.
Note
Do not use a sample custom platform in production. The goal of the samples is to illustrate
some of the functionality available for a custom platform, but they have not been hardened for
production use.
NodePlatform_Ubuntu.zip
This custom platform is based on Ubuntu 16.04 and supports Node.js 4.4.4. We'll use this custom
platform for the examples in this section.
NodePlatform_RHEL.zip
This custom platform is based on RHEL 7.2 and supports Node.js 4.4.4.
NodePlatform_AmazonLinux.zip
This custom platform is based on Amazon Linux 2016.09.1 and supports Node.js 4.4.4.
TomcatPlatform_Ubuntu.zip
This custom platform is based on Ubuntu 16.04 and supports Tomcat 7/Java 8.
CustomPlatform_NodeSampleApp.zip
A Node.js sample that uses express and ejs to display a static web page
CustomPlatform_TomcatSampleApp.zip
A Tomcat sample that displays a static web page when deployed
Download the sample platform definition archive: NodePlatform_Ubuntu.zip. This file contains a
platform definition file, Packer template, scripts that Packer runs during image creation, and scripts and
configuration files that Packer copies onto the builder instance during platform creation.
API Version 2010-12-01
36
AWS Elastic Beanstalk Developer Guide
Using a Sample Custom Platform
Example NodePlatform_Ubuntu.zip
|-|-|-|--
builder
custom_platform.json
platform.yaml
ReadMe.txt
Contains files used by Packer to create the custom platform
Packer template
Platform definition file
Briefly describes the sample
The platform definition file, platform.yaml, tells Elastic Beanstalk the name of the Packer template,
custom_platform.json.
version: "1.0"
provisioner:
type: packer
template: custom_platform.json
flavor: ubuntu1604
The Packer template tells Packer how to build the AMIs for the platform, using an Ubuntu AMI as a base
for the platform image for HVM instance types. The provisioners section tells Packer to copy all files in
the builder folder within the archive to the instance, and to run the builder.sh script on the instance.
When the scripts complete, Packer creates an image from the modified instance.
Elastic Beanstalk creates three environment variables that can be used to tag AMIs in Packer:
AWS_EB_PLATFORM_ARN
The ARN of the custom platform.
AWS_EB_PLATFORM_NAME
The name of the custom platform.
AWS_EB_PLATFORM_VERSION
The version of the custom platform.
The sample custom_platform.json file uses these values to define the following values that it uses in the
scripts:
• platform_name, which is set by platform.yaml
• platform_version, which is set by platform.yaml
• platform_arn, which is set by the main build script, builder.sh, which is shown at the end of the
sample custom_platform.json file.
Example custom_platform.json
{
"variables": {
"platform_name": "{{env `AWS_EB_PLATFORM_NAME`}}",
"platform_version": "{{env `AWS_EB_PLATFORM_VERSION`}}",
"platform_arn": "{{env `AWS_EB_PLATFORM_ARN`}}"
},
...,
"provisioners": [
{...},
{
"type": "shell",
API Version 2010-12-01
37
AWS Elastic Beanstalk Developer Guide
Using a Sample Custom Platform
}
]
}
"execute_command": "chmod +x {{ .Path }}; {{ .Vars }} sudo {{ .Path }}",
"scripts": [
"builder/builder.sh"
]
The scripts and other files that you include in your platform definition archive will vary greatly
depending on the modifications that you want to make to the instance. The sample platform includes
the following scripts:
• 00-sync-apt.sh – Commented out: apt -y update.
• 01-install-nginx.sh – Installs nginx.
• 02-setup-platform.sh – Installs wget, tree, and git. Copies hooks and logging
configurations (p. 336) to the instance, and creates the following directories:
• /etc/SampleNodePlatform – Where the container configuration file is uploaded during deployment.
• /opt/elasticbeanstalk/deploy/appsource/ – Where the 00-unzip.sh script uploads application
source code during deployment (see the Platform Scripts (p. 41) section for information about
this script).
• /var/app/staging/ – Where application source code is processed during deployment.
• /var/app/current/ – Where application source code runs after processing.
• /var/log/nginx/healthd/ – Where the enhanced health agent (p. 307) writes logs.
• /var/nodejs – Where the Node.js files are uploaded during deployment.
Use the EB CLI to create your first custom platform with the sample platform definition archive.
To create a custom platform
1.
Install the EB CLI (p. 435).
2.
Create a directory in which you will extract the sample custom platform.
~$ mkdir ~/custom-platform
3.
Extract NodePlatform_Ubuntu.zip to the directory.
~$ cd ~/custom-platform
~/custom-platform$ unzip ~/NodePlatform_Ubuntu.zip
4.
Run eb platform init (p. 494) and follow the prompts to initialize a platform repository.
Note
You can shorten eb platform to ebp.
~/custom-platform$ ebp init
This command also creates the directory .elasticbeanstalk in the current directory and adds
the configuration file config.yml to the directory. Don't change or delete this file, because Elastic
Beanstalk relies on it when creating the custom platform.
By default, ebp init uses the name of the current folder as the name of the custom platform, which
would be custom-platform in this example.
5.
Run eb platform create (p. 493) to launch a Packer environment and get the ARN of the custom
platform. You'll need this value later when you create an environment from the custom platform.
API Version 2010-12-01
38
AWS Elastic Beanstalk Developer Guide
Using a Sample Custom Platform
~/custom-platform$ ebp create
...
By default, Elastic Beanstalk creates the instance profile aws-elasticbeanstalk-custom-platformec2-role for custom platforms. If, instead, you want to use an existing instance profile, add the
option -ip INSTANCE_PROFILE to the eb platform create (p. 493) command.
Note
Packer will fail to create a custom platform if you use the Elastic Beanstalk default instance
profile aws-elasticbeanstalk-ec2-role.
The EB CLI shows event output of the Packer environment until the build is complete. You can exit
the event view by pressing Ctrl-C.
6.
You can check the logs for errors using the eb platform logs (p. 495) command.
~/custom-platform$ ebp logs
...
7.
You can check on the process later with eb platform events (p. 494).
~/custom-platform$ ebp events
...
8.
Check the status of your platform with eb platform status (p. 495).
~/custom-platform$ ebp status
...
When the operation completes, you have a platform that you can use to launch an Elastic Beanstalk
environment.
You can use the custom platform when creating a new environment from the console. Learn more at The
Create New Environment Wizard (p. 71).
To launch an environment on your custom platform
1.
Create a new directory for your application.
~$ mkdir custom-platform-app
~$ cd ~/custom-platform-app
2.
Initialize an application repository.
~/custom-platform-app$ eb init
...
3.
Download the sample application NodeSampleApp.zip.
4.
Unzip the sample application.
~/custom-platform-app$ unzip ~/NodeSampleApp.zip
5.
Run eb create -p CUSTOM-PLATFORM-ARN, where CUSTOM-PLATFORM-ARN is the ARN returned by an eb
platform create command, to launch an environment running your custom platform.
~/custom-platform-app$ eb create -p CUSTOM-PLATFORM-ARN
API Version 2010-12-01
39
AWS Elastic Beanstalk Developer Guide
Platform Definition Archive Contents
...
Platform Definition Archive Contents
A platform definition archive is the platform equivalent of an application source bundle (p. 54). The
platform definition archive is a ZIP file that contains a platform definition file, a Packer template, and the
scripts and files used by the Packer template to create your platform.
Note
When you use the EB CLI to create a custom platform, the EB CLI creates a platform definition
archive from the files and folders in your platform repository, so you don't need to create the
archive manually.
The platform definition file is a YAML-formatted file that must be named platform.yaml and be in the
root of your platform definition archive. See Creating a Custom Platform (p. 36) for a list of required
and optional keys supported in a platform definition file.
You don't need to name the Packer template in a specific way, but the name of the file must match the
provisioner template specified in the platform definition file. See the official Packer documentation for
instructions on creating Packer templates.
The other files in your platform definition archive are scripts and files used by the template to customize
an instance before creating an AMI.
Platform Hooks
Elastic Beanstalk uses a standardized directory structure for hooks, which are scripts that are run during
lifecycle events and in response to management operations: when instances in your environment are
launched, or when a user initiates a deployment or uses the restart application server feature.
Hooks are organized into the following folders:
• appdeploy — Scripts run during an application deployment. Elastic Beanstalk performs an application
deployment when new instances are launched and when a client initiates a new version deployment.
• configdeploy — Scripts run when a client performs a configuration update that affects the software
configuration on-instance, for example, by setting environment properties or enabling log rotation to
Amazon S3.
• restartappserver — Scripts run when a client performs a restart app server operation.
• preinit — Scripts run during instance bootstrapping.
• postinit — Scripts run after instance bootstrapping.
The appdeploy, configdeploy, and restartappserver folders contain pre, enact, and post subfolders.
In each phase of an operation, all scripts in the pre folder are run in alphabetical order, then the enact
folder, then the post folder.
When an instance is launched, Elastic Beanstalk runs preinit, postinit, and appdeploy. On subsequent
deployments to running instances, Elastic Beanstalk runs appdeploy hooks. configdeploy hooks are run
when a user updates instance software configuration settings. restartappserver hooks are run only
when the user initiates an application server restart.
When your scripts encounter errors, they can exit with a non-zero status and write to stderr to fail
the operation. The message that you write to stderr will appear in the event that is output when the
operation fails. Elastic Beanstalk also captures this information in the log file /var/log/eb-activity.log
If you don't want to fail the operation, return 0. Messages that you write to stderr or stdout appear in the
deployment logs (p. 336), but won't appear in the event stream unless the operation fails.
API Version 2010-12-01
40
AWS Elastic Beanstalk Developer Guide
Platform Scripts
Platform Scripts
Elastic Beanstalk installs the shell script get-config that you can use to get environment variables and
other information in hooks that run on-instance in environments launched with your custom platform.
This tool is available at /opt/elasticbeanstalk/bin/get-config and can be used in the following ways:
• get-config optionsettings – Returns a JSON object listing the configuration options set on the
environment, organized by namespace.
$ /opt/elasticbeanstalk/bin/get-config optionsettings
{"aws:elasticbeanstalk:container:php:phpini":
{"memory_limit":"256M","max_execution_time":"60","display_errors":"Off","composer_options":"","allow_
{"LogPublicationControl":"false"},"aws:elasticbeanstalk:application:environment":
{"TESTPROPERTY":"testvalue"}}
• get-config environment – Returns a JSON object containing a list of environment properties,
including both user-configured properties and those provided by Elastic Beanstalk.
$ /opt/elasticbeanstalk/bin/get-config environment
{"TESTPROPERTY":"testvalue","RDS_PORT":"3306","RDS_HOSTNAME":"anj9aw1b0tbj6b.cijbpanmxz5u.uswest-2.rds.amazonaws.com","RDS_USERNAME":"testusername","RDS_DB_NAME":"ebdb","RDS_PASSWORD":"testpass
For example, Elastic Beanstalk provides environment properties for connecting to an integrated
RDS DB instance (RDS_HOSTNAME, etc.). These properties appear in the output of get-config
environment but not in the output of get-config optionsettings, because they are not set by the
user.
You can test the previous commands by using SSH to connect to an instance in an Elastic Beanstalk
environment running a Linux-based platform.
See the following files in the sample platform definition archive (p. 36) for an example of get-config
usage:
• builder/platform-uploads/opt/elasticbeanstalk/hooks/configdeploy/enact/02-gen-envvars.sh –
Gets environment properties.
• builder/platform-uploads/opt/SampleNodePlatform/bin/createPM2ProcessFile.js – Parses the
output.
Elastic Beanstalk installs the shell script download-source-bundle that you can use to download your
application source code during the deployment of your custom platform. This tool is available at /opt/
elasticbeanstalk/bin/download-source-bundle. See the sample script 00-unzip.sh, which is in the
appdeploy/pre folder, for an example of how to use download-source-bundle to download application
source code to the /opt/elasticbeanstalk/deploy/appsource folder during deployment.
Packer Instance Cleanup
In certain circumstances, such as killing the Packer builder process before it has finished, instances
launched by Packer are not cleaned up. These instances are not part of the Elastic Beanstalk environment
and can only be viewed and terminated using the Amazon EC2 service.
To manually clean up these instances
1.
Open the https://console.aws.amazon.com/ec2/
2.
Make sure you are in the same region in which you created the instance with Packer.
API Version 2010-12-01
41
AWS Elastic Beanstalk Developer Guide
Platform.yaml Format
3.
Under Resources select N Running Instances, where N indicates the number of running instances.
4.
Click in the query text box.
5.
Select the Name tag.
6.
Type packer.
The query should look like: tag:Name: packer
7.
Select any instances that match the query.
8.
If the Instance State is running, select Actions, Instance State, Stop, then Actions, Instance State,
Terminate.
Platform.yaml File Format
This file has the following format:
version: "version-number"
provisioner:
type: provisioner-type
template: provisioner-template
flavor: provisioner-flavor
metadata:
maintainer: metadata-maintainer
description: metadata-description
operating_system_name: metadata-operating_system_name
operating_system_version: metadata-operating_system_version
programming_language_name: metadata-programming_language_name
programming_language_version: metadata-programming_language_version
framework_name: metadata-framework_name
framework_version: metadata-framework_version
option_definitions:
- namespace: option-def-namespace
option_name: option-def-option_name
description: option-def-description
default_value: option-def-default_value
option_settings:
- namespace: "option-setting-namespace"
option_name: "option-setting-option_name"
value: "option-setting-value"
Where:
version-number
Required. The version of the YAML definition. Must be 1.0.
provisioner-type
Required. The type of builder used to create the custom platform. Must be packer.
provisioner-template
Required. The JSON file containing the settings for provisioner-type.
provisioner-flavor
Optional. The base operating system used for the AMI. One of:
API Version 2010-12-01
42
AWS Elastic Beanstalk Developer Guide
Platform.yaml Format
amazon (default)
Amazon Linux. If not specified, the latest version of Amazon Linux when the platform is created.
ubuntu1604
Ubuntu 16.04 LTS
rhel7
RHEL 7
rhel6
RHEL 6
metadata-maintainer
Optional. Contact information for the person who owns the platform (100 characters).
metadata-description
Optional. Description of the platform (2000 characters).
metadata-operating_system_name
Optional. Name of the platform's operating system (50 characters). This value is available when
filtering the output for the ListPlatformVersions API.
metadata-operating_system_version
Optional. Version of the platform's operating system (20 characters).
metadata-programming_language_name
Optional. Programming language supported by the platform (50 characters)
metadata-programming_language_version
Optional. Version of the platform's language (20 characters).
metadata-framework_name
Optional. Name of the web framework used by the platform (50 characters).
metadata-framework_version
Optional. Version of the platform's web framework (20 characters).
option-def-namespace
Optional. A namespace under aws:elasticbeanstalk:container:custom (100 characters)
option-def-option_name
Optional. The option's name (100 characters). You can define up to 50 custom configuration options
that the platform provides to users.
option-def-description
Optional. Description of the option (1024 characters).
option-def-default_value
Optional. Default value used when the user doesn't specify one.
The following example creates the option NPM_START:
options_definitions:
- namespace: "aws:elasticbeanstalk:container:custom:application"
option_name: "NPM_START"
API Version 2010-12-01
43
AWS Elastic Beanstalk Developer Guide
Platform.yaml Format
description: "Default application startup command"
default_value: "node application.js"
option-setting-namespace
Optional. Namespace of the option.
option-setting-option_name
Optional. Name of the option. You can specify up to 50 options provided by Elastic
Beanstalk (p. 160).
option-setting-value
Optional. Value used when the user doesn't specify one.
The following example creates the option TEST.
option_settings:
- namespace: "aws:elasticbeanstalk:application:environment"
option_name: "TEST"
value: "This is a test"
API Version 2010-12-01
44
AWS Elastic Beanstalk Developer Guide
Tutorials and Samples
Language and framework specific tutorials are spread throughout the AWS Elastic Beanstalk Developer
Guide. New and updated tutorials are added to this list as they are published. The most recent updates
are shown first.
These tutorials are targeted at intermediate users and may not contain instructions for basic steps such
as signing up for AWS. If this is your first time using AWS or Elastic Beanstalk, check out the Getting
Started walkthrough (p. 3) to get your first Elastic Beanstalk environment up and running from scratch.
• PHP and Drupal HA Configuration - Deploying a High-Availability Drupal Website with an External
Amazon RDS Database to Elastic Beanstalk (p. 790)
• PHP and WordPress HA Configuration - Deploying a High-Availability WordPress Website with an
External Amazon RDS Database to Elastic Beanstalk (p. 780)
• Node.js with DynamoDB HA Configuration - Deploying a Node.js Application with DynamoDB to
Elastic Beanstalk (p. 730)
• ASP.NET Core - Deploying an ASP.NET Core Application with AWS Elastic Beanstalk (p. 679)
• PHP 5.6 and MySQL HA Configuration - Deploying a High-Availability PHP Application with an
External Amazon RDS Database to Elastic Beanstalk (p. 773)
• PHP 5.6 and Laravel 5.2 - Deploying a Laravel Application to Elastic Beanstalk (p. 756)
• PHP 5.6 and CakePHP 3.2 - Deploying a CakePHP Application to Elastic Beanstalk (p. 763)
• Python and Flask 0.10 - Deploying a Flask Application to AWS Elastic Beanstalk (p. 807)
• Python and Django 1.9 - Deploying a Django Application to Elastic Beanstalk (p. 812)
• Node.js and Express 4 - Deploying an Express Application to Elastic Beanstalk (p. 726)
• Docker, PHP and nginx - Multicontainer Docker Environments with the AWS Management
Console (p. 595)
• Ruby on Rails - Deploying a Rails Application to Elastic Beanstalk (p. 827)
• Ruby and Sinatra - Deploying a Sinatra Application to AWS Elastic Beanstalk (p. 834)
• .NET Framework (IIS and ASP.NET) - Tutorial: How to Deploy a .NET Sample Application Using AWS
Elastic Beanstalk (p. 669)
You can download the sample applications used by Elastic Beanstalk when you create an environment
without providing a source bundle with the following links:
• Go – go-v1.zip
• Java with Tomcat – java-tomcat-v3.zip
API Version 2010-12-01
45
AWS Elastic Beanstalk Developer Guide
• Java SE – java-se-jetty-gradle-v3.zip
• .NET on Windows Server with IIS – dotnet-asp-v1.zip
• Node.js – nodejs-v1.zip
• PHP – php-v1.zip
• Python – python-v1.zip
• Ruby (Passenger Standalone) – ruby-passenger-v2.zip
• Ruby (Puma) – ruby-puma-v2.zip
• Single Container Docker – docker-singlecontainer-v1.zip
• Multicontainer Docker – docker-multicontainer-v2.zip
• Preconfigured Docker (Glassfish) – docker-glassfish-v1.zip
• Preconfigured Docker (Python 3.x) – docker-python-v1.zip
• Preconfigured Docker (Go) – docker-golang-v1.zip
More involved sample applications that show the use of additional web frameworks, libraries and tools
are available as open source projects on GitHub:
• Load Balanced WordPress (tutorial (p. 780)) – Configuration files for installing WordPress securely
and running it in a load balanced AWS Elastic Beanstalk environment.
• Load Balanced Drupal (tutorial (p. 790)) – Configuration files and instructions for installing Drupal
securely and running it in a load balanced AWS Elastic Beanstalk environment.
• Scorekeep - RESTful web API that uses the Spring framework to provide an interface for creating and
managing users, sessions, and games. The API is bundles with an Angular 1.5 web app that consumes
the API over HTTP.
The application uses features of the Java SE platform to download dependencies and build oninstance, minimizing the size of the souce bundle. The application also includes nginx configuration
files that override the default configuration to serve the frontend web app statically on port 80
through the proxy, and route requests to paths under /api to the API running on localhost:5000.
• Does it Have Snakes? - Tomcat application that shows the use of RDS in a Java EE web application
in AWS Elastic Beanstalk. The project shows the use of Servlets, JSPs, Simple Tag Support, Tag Files,
JDBC, SQL, Log4J, Bootstrap, Jackson, and Elastic Beanstalk configuration files.
• Locust Load Generator - This project shows the use of Java SE platform features to install and run
Locust, a load generating tool written in Python. The project includes configuration files that install
and configure Locust, a build script that configures a DynamoDB table, and a Procfile that runs Locust.
• Share Your Thoughts (tutorial (p. 773)) - PHP application that shows the use of MySQL on Amazon
RDS, Composer, and configuration files.
• A New Startup (tutorial (p. 730)) - Node.js sample application that shows the use of DynamoDB, the
AWS SDK for JavaScript in Node.js, npm package management, and configuration files.
API Version 2010-12-01
46
AWS Elastic Beanstalk Developer Guide
Managing and Configuring AWS
Elastic Beanstalk Applications
The first step in using Elastic Beanstalk is to create an application, which represents your web application
in AWS. In Elastic Beanstalk an application serves as a container for the environments that run your web
app, and versions of your web app's source code, saved configurations, logs and other artifacts that you
create while using Elastic Beanstalk.
To create a new application
1.
Open the Elastic Beanstalk console.
2.
Choose Create New Application.
3.
Enter the name of the application and, optionally, a description. Then click Next.
After creating a new application, the console prompts you to create an environment for it. For
detailed information about all of the options available, see Creating an AWS Elastic Beanstalk
Environment (p. 68).
If you have no further need for an application, you can delete it.
Warning
Deleting an application terminates all associated environments and deletes all application
versions and saved configurations that belong to the application.
To delete an application
1.
Open the Elastic Beanstalk console.
2.
Choose Actions next to the application that you want to delete.
3.
Choose Delete Application
Topics
• The AWS Elastic Beanstalk Application Management Console (p. 48)
• Managing Application Versions (p. 50)
• Configuring Application Version Lifecycle Settings (p. 52)
• Create an Application Source Bundle (p. 54)
API Version 2010-12-01
47
AWS Elastic Beanstalk Developer Guide
Application Management Console
The AWS Elastic Beanstalk Application
Management Console
You can use the AWS Management Console to manage applications, application versions, and saved
configurations.
To access the application management console
1.
Open the Elastic Beanstalk console.
2.
The console displays a list of all environments running in the current region, sorted by application.
Choose an application name to view the management console for that application.
Note
If you have a large number of applications, use the search bar in the upper right corner to
filter the list of applications.
The Environments page shows an overview of all environments associated with the application.
API Version 2010-12-01
48
AWS Elastic Beanstalk Developer Guide
Application Management Console
3.
Choose an environment by name to go to the environment management console (p. 61) for that
environment to configure, monitor, or manage it.
Choose Application Versions to view a list of application versions for your application:
Here you can upload new versions, deploy an existing version to any of the application's
environments, or delete old versions. See Managing Application Versions (p. 50) for more
information about the options on this page.
4.
Choose Saved Configurations to view a list of configurations saved from running environments. A
saved configuration is a collection of settings that you can use to restore an environment's settings
to a previous state or create a new environment with the same settings.
API Version 2010-12-01
49
AWS Elastic Beanstalk Developer Guide
Managing Application Versions
See Using Elastic Beanstalk Saved Configurations (p. 234) for more information.
Managing Application Versions
Elastic Beanstalk creates an application version whenever you upload source code. This usually occurs
when you create a new environment or upload and deploy code using the environment management
console (p. 61) or EB CLI (p. 434). You can also upload a source bundle without deploying it from the
application management console (p. 48).
To create a new application version
1.
Open the Elastic Beanstalk console.
2.
Choose an application.
3.
In the navigation pane, choose Application Versions.
4.
Choose Upload.
API Version 2010-12-01
50
AWS Elastic Beanstalk Developer Guide
Managing Application Versions
5.
Enter a label for this version in the Version label field.
6.
(Optional) Enter a brief description for this version in the Description field.
7.
Choose Browse to specify the location of the source bundle (p. 54).
Note
The file size limit is 512 MB.
8.
Choose Upload.
The file you specified is associated with your application. You can deploy the application version to a new
or existing environment.
Over time, your application can accumulate a large number of application versions. To save storage space
and avoid hitting the application version limit, you can configure Elastic Beanstalk to delete old versions
automatically.
Note
Deleting an application version does not have any affect on environments currently running that
version.
To delete an application version
1.
Open the Elastic Beanstalk console.
2.
Choose an application.
3.
In the navigation pane, choose Application versions.
4.
In the list of application versions, select the check box next to the application version that you want
to delete, and then click Delete.
API Version 2010-12-01
51
AWS Elastic Beanstalk Developer Guide
Version Lifecycle
5.
(Optional) To leave the application source bundle for this application version in your Amazon S3
bucket, uncheck Delete versions from Amazon S3.
6.
Choose Apply.
Lifecycle settings are applied when you create new application versions. For example, if you configure
a maximum of 25 application versions, Elastic Beanstalk deletes the oldest version when you upload a
26th version. If you set a maximum age of 90 days, any versions more than 90 days old are deleted when
you upload a new version.
If you don't choose to delete the source bundle from Amazon S3, Elastic Beanstalk deletes the version
from it's records, but the source bundle is left if your Elastic Beanstalk storage bucket (p. 408). The
application version limit only applies to versions Elastic Beanstalk tracks, so you can delete versions to
stay within the limit, but retain all source bundles in Amazon S3 if needed.
Configuring Application Version Lifecycle Settings
Each time you upload a new version of your application with the Elastic Beanstalk console or the EB CLI,
Elastic Beanstalk creates an application version (p. 50). If you don't delete versions that you no longer
API Version 2010-12-01
52
AWS Elastic Beanstalk Developer Guide
Setting the Application Lifecycle Settings in the Console
use, you will eventually reach the application version limit and be unable to create new versions of that
application.
You can avoid hitting the limit by applying an application version lifecycle policy to your applications. A
lifecycle policy tells Elastic Beanstalk to delete application versions that are old, or to delete application
versions when the total number of versions for an application exceeds a specified number.
Elastic Beanstalk applies an application's lifecycle policy each time you create a new application version,
and deletes up to 100 versions each time the lifecycle policy is applied. Elastic Beanstalk deletes old
versions before creating the new version, and does not count the new version towards the maximum
number of versions defined in the policy.
Elastic Beanstalk does not delete application versions that are currently being used by an environment,
or application versions deployed to environments that were terminated less than six weeks before the
policy was triggered.
The application version limit applies across all applications in a region. If you have several applications,
configure each application with a lifecycle policy appropriate to avoid reaching the limit. Elastic
Beanstalk only applies the policy if the application version creation succeeds, so if you have already
reached the limit, you must delete some versions manually prior to creating a new version.
By default, Elastic Beanstalk leaves the application version's source bundle (p. 54) in Amazon S3 to
prevent loss of data. You can delete the source bundle to save space.
You can set the lifecycle settings through the Elastic Beanstalk CLI and APIs. See eb
appversion (p. 466), CreateApplication (using the ResourceLifecycleConfig parameter), and
UpdateApplicationResourceLifecycle for details.
Setting the Application Lifecycle Settings in the
Console
You can specify the lifecycle settings in the console.
To specify your application lifecycle settings.
1.
Open the Elastic Beanstalk console.
2.
Choose an application.
3.
In the navigation pane, select Application versions.
4.
Select Settings.
API Version 2010-12-01
53
AWS Elastic Beanstalk Developer Guide
Create a Source Bundle
5.
Select Enable for Lifecycle policy to enable lifecycle settings.
6.
Select either Set the application versions limit by total count or Set the application versions limit
by age.
7.
If you selected Set the application versions limit by total count, enter a value from 1 to 1000
for Application Versions to specify the maximum number of application versions to keep before
deleting old versions.
8.
If you selected Set the application versions limit by age, specify the maximum age, in days from 1
to 180, of application versions to keep.
9.
For Retention, specify whether to delete the source bundle from S3 when the application version is
deleted.
10. For Service role, specify the role under which the application version is deleted.
11. Select Save to save your application lifecycle settings.
Create an Application Source Bundle
When you use the AWS Elastic Beanstalk console to deploy a new application or an application version,
you'll need to upload a source bundle. Your source bundle must meet the following requirements:
• Consist of a single ZIP file or WAR file (you can include multiple WAR files inside your ZIP file)
• Not exceed 512 MB
• Not include a parent folder or top-level directory (subdirectories are fine)
API Version 2010-12-01
54
AWS Elastic Beanstalk Developer Guide
Creating a Source Bundle from the Command Line
If you want to deploy a worker application that processes periodic background tasks, your application
source bundle must also include a cron.yaml file. For more information, see Periodic Tasks (p. 139).
If you are deploying your application with the Elastic Beanstalk Command Line Interface (EB CLI), the
AWS Toolkit for Eclipse, or the AWS Toolkit for Visual Studio, the ZIP or WAR file will automatically
be structured correctly. For more information, see The Elastic Beanstalk Command Line Interface (EB
CLI) (p. 434), Creating and Deploying Java Applications on AWS Elastic Beanstalk (p. 619), and The
AWS Toolkit for Visual Studio (p. 689).
Sections
• Creating a Source Bundle from the Command Line (p. 55)
• Creating a Source Bundle with Git (p. 55)
• Zipping Files in Mac OS X Finder or Windows Explorer (p. 55)
• Creating a Source Bundle for a .NET Application (p. 58)
• Testing Your Source Bundle (p. 59)
Creating a Source Bundle from the Command Line
Create a source bundle using the zip command. To include hidden files and folders, use a pattern like the
following.
~/myapp$ zip ../myapp.zip -r * .[^.]*
adding: app.js (deflated 63%)
adding: index.js (deflated 44%)
adding: manual.js (deflated 64%)
adding: package.json (deflated 40%)
adding: restify.js (deflated 85%)
adding: .ebextensions/ (stored 0%)
adding: .ebextensions/xray.config (stored 0%)
This ensures that Elastic Beanstalk configuration files (p. 197) and other files and folders that start with
a period are included in the archive.
For Tomcat web applications, use jar to create a web archive.
~/myapp$ jar -cvf myapp.war .
The above commands include hidden files that may increase your source bundle size unnecessarily. For
more control, use a more detailed file pattern, or create your source bundle with Git (p. 55).
Creating a Source Bundle with Git
If you're using Git to manage your application source code, use the git archive command to create your
source bundle.
$ git archive -v -o myapp.zip --format=zip HEAD
git archive only includes files that are stored in git, and excludes ignored files and git files. This helps
keep your source bundle as small as possible. For more information, go to the git-archive manual page.
Zipping Files in Mac OS X Finder or Windows Explorer
When you create a ZIP file in Mac OS X Finder or Windows Explorer, make sure you zip the files and
subfolders themselves, rather than zipping the parent folder.
API Version 2010-12-01
55
AWS Elastic Beanstalk Developer Guide
Zipping Files in Mac OS X Finder or Windows Explorer
Note
The graphical user interface (GUI) on Mac OS X and Linux-based operating systems does not
display files and folders with names that begin with a period (.). Use the command line instead
of the GUI to compress your application if the ZIP file must include a hidden folder, such as
.ebextensions. For command line procedures to create a ZIP file on Mac OS X or a Linux-based
operating system, see Creating a Source Bundle from the Command Line (p. 55).
Example
Suppose you have a Python project folder labeled myapp, which includes the following files and
subfolders:
myapplication.py
README.md
static/
static/css
static/css/styles.css
static/img
static/img/favicon.ico
static/img/logo.png
templates/
templates/base.html
templates/index.html
As noted in the list of requirements above, your source bundle must be compressed without a parent
folder, so that its decompressed structure does not include an extra top-level directory. In this example,
no myapp folder should be created when the files are decompressed (or, at the command line, no myapp
segment should be added to the file paths).
This sample file structure is used throughout this topic to illustrate how to zip files.
To zip files in Mac OS X Finder
1.
Open your top-level project folder and select all the files and subfolders within it. Do not select the
top-level folder itself.
API Version 2010-12-01
56
AWS Elastic Beanstalk Developer Guide
Zipping Files in Mac OS X Finder or Windows Explorer
2.
Right-click the selected files, and then choose Compress X items, where X is the number of files and
subfolders you've selected.
API Version 2010-12-01
57
AWS Elastic Beanstalk Developer Guide
Creating a Source Bundle for a .NET Application
To zip files in Windows Explorer
1.
Open your top-level project folder and select all the files and subfolders within it. Do not select the
top-level folder itself.
2.
Right-click the selected files, choose Send to, and then choose Compressed (zipped) folder.
Creating a Source Bundle for a .NET Application
If you use Visual Studio, you can use the deployment tool included in the AWS Toolkit for Visual Studio
to deploy your .NET application to Elastic Beanstalk. For more information, see Deploying Elastic
Beanstalk Applications in .NET Using the Deployment Tool (p. 704).
If you need to manually create a source bundle for your .NET application, you cannot simply create a
ZIP file that contains the project directory. You must create a web deployment package for your project
API Version 2010-12-01
58
AWS Elastic Beanstalk Developer Guide
Testing Your Source Bundle
that is suitable for deployment to Elastic Beanstalk. There are several methods you can use to create a
deployment package:
• Create the deployment package using the Publish Web wizard in Visual Studio. For more information,
go to How to: Create a Web Deployment Package in Visual Studio.
Important
When creating the web deployment package, you must start the Site name with Default Web
Site.
• It you have a .NET project, you can create the deployment package using the msbuild command as
shown in the following example.
Important
The DeployIisAppPath parameter must begin with Default Web Site.
C:/> msbuild <web_app>.csproj /t:Package /p:DeployIisAppPath="Default Web Site"
• If you have a website project, you can use the IIS Web Deploy tool to create the deployment package.
For more information, go to Packaging and Restoring a Web site.
Important
The apphostconfig parameter must begin with Default Web Site.
Testing Your Source Bundle
You may want to test your source bundle locally before you upload it to Elastic Beanstalk. Because
Elastic Beanstalk essentially uses the command line to extract the files, it's best to do your tests from the
command line rather than with a GUI tool.
To test the file extraction in Mac OS X or Linux
1.
2.
3.
Open a terminal window (Mac OS X) or connect to the Linux server. Navigate to the directory that
contains your source bundle.
Using the unzip or jar xf command, decompress the archive.
Ensure that the decompressed files appear in the same folder as the archive itself, rather than in a
new top-level folder or directory.
Note
If you use Mac OS X Finder to decompress the archive, a new top-level folder will be
created, no matter how you structured the archive itself. For best results, use the command
line.
To test the file extraction in Windows
1.
2.
3.
4.
Download or install a program that allows you to extract compressed files via the command line. For
example, you can download the free unzip.exe program from http://stahlforce.com/dev/index.php?
tool=zipunzip.
If necessary, copy the executable file to the directory that contains your source bundle. If you've
installed a system-wide tool, you can skip this step.
Using the appropriate command, decompress the archive. If you downloaded unzip.exe using the
link in step 1, the command is unzip <archive-name>.
Ensure that the decompressed files appear in the same folder as the archive itself, rather than in a
new top-level folder or directory.
API Version 2010-12-01
59
AWS Elastic Beanstalk Developer Guide
Managing Environments
AWS Elastic Beanstalk makes it easy to create new environments for your application. You can create
and manage separate environments for development, testing, and production use, and you can deploy
any version (p. 108) 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.
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 (p. 110). You
can deploy to all of the instances in your environment simultaneously, or split a deployment into batches
with rolling deployments.
Configuration changes (p. 116) 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 (p. 117).
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 terminating an environment.
When you launch an environment, you choose a platform configuration. We update platform
configurations periodically to provide performance improvements and new features. You can update
your environment to the latest platform configuration (p. 123) at any time.
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 (p. 136) that
process jobs from an Amazon Simple Queue Service (Amazon SQS) queue.
Topics
• The AWS Elastic Beanstalk Environment Management Console (p. 61)
•
•
•
•
•
Creating an AWS Elastic Beanstalk Environment (p. 68)
Deploying Applications to AWS Elastic Beanstalk Environments (p. 108)
Configuration Changes (p. 116)
Updating Your Elastic Beanstalk Environment's Platform Version (p. 123)
Canceling Environment Configuration Updates and Application Deployments (p. 131)
API Version 2010-12-01
60
AWS Elastic Beanstalk Developer Guide
The Environment Management Console
• Rebuilding AWS Elastic Beanstalk Environments (p. 132)
• Environment Types (p. 134)
• Worker Environments (p. 136)
• Creating Links Between AWS Elastic Beanstalk Environments (p. 142)
The AWS Elastic Beanstalk Environment
Management Console
The AWS Management Console provides a management page for each of your AWS Elastic Beanstalk
environments. From this page, you can manage your environment's configuration and perform common
actions including restarting the web servers running in your environment, cloning the environment, or
rebuilding it from scratch.
Topics
• Environment Dashboard (p. 62)
• Environment Management Actions (p. 63)
• Configuration (p. 64)
• Logs (p. 65)
• Health (p. 66)
• Monitoring (p. 66)
• Alarms (p. 66)
• Managed Updates (p. 67)
• Events (p. 67)
• Tags (p. 68)
API Version 2010-12-01
61
AWS Elastic Beanstalk Developer Guide
Environment Dashboard
To access the environment management console, open the Elastic Beanstalk console in your region and
click on the name of a running environment. Environments are shown in color coded tiles under their
associated application. The color (green, grey or red) indicates the health of the environment.
At the top of the environment console, the name of the application is shown, followed by the name of
the environment and the public DNS name of the running application.
Environment Dashboard
The main view of the environment management console is the Dashboard.
Within the environment management dashboard is an overview, which shows the environment's health,
the application version, and information about the in-use platform, and a list of recent events generated
by the environment.
Click Refresh to update the information shown. The overview contains the following information and
options.
Health
The overall health of the environment. With Enhanced Health Reporting and Monitoring (p. 306)
enabled, the environment status is shown with a Causes button you can click to view more information
about the current status.
For Basic Health Reporting (p. 303) environments, a link to the Monitoring Console (p. 300) is shown.
Running Version
The name of the application version running on your environment. Click Upload and Deploy to upload a
source bundle (p. 54) and deploy it to your environment. This option creates a new application version.
Configuration
Shows the architecture, OS version, and platform running on your environment. Click Change to select
a different configuration. This option is only available if another compatible version of the platform
is available. To be considered compatible, the architecture, OS name, and platform name must be the
same.
Updating the platform version using this option replaces instances running in your environment with
new instances.
API Version 2010-12-01
62
AWS Elastic Beanstalk Developer Guide
Environment Management Actions
Note
When you first use Beanstalk, only the latest version of each platform is available for use. The
Change first becomes available when a new version of the operating system or platform is
released. After upgrading, you have the option to change back to the previous version.
Recent Events
The Recent Events section of the environment management dashboard shows the most recent events
emitted by your environment. This list is updated in real time when your environment is being updated.
Click Show All to open the Events menu.
Environment Management Actions
The environment management console contains an Actions drop down menu that you can use to
perform common operations on your environment. This menu is shown on the right side of the
environment header under the Create New Environment option.
Note
Some actions are only available under certain conditions, and will be greyed out unless these
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. Prior to making 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.
API Version 2010-12-01
63
AWS Elastic Beanstalk Developer Guide
Configuration
Swap Environment 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 will go 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 with no interruption of service. For more information see Blue/Green
Deployments with AWS Elastic Beanstalk (p. 113).
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 application platform. This option is
only available when a newer version of the current environment's platform is available for use.
Abort Current Operation
Stop an in progress environment update. Aborting 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 only available when your environment is being updated.
Restart App Server(s)
Restart the web server running on your environment's instances. This option does not terminate or
restart any AWS resources. If your environment is acting strangely in response to some bad requests,
restarting the application server may 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, equivalent to deploying a new environment from scratch. Any
RDS instances 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 or configure your data tier's
Deletion Policy to create a snapshot automatically prior to 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 running in a data tier and need to retain the data, ensure that a snapshot
is taken prior to terminating your environment. You can create a snapshot manually in the RDS console
or configure your data tier's Deletion Policy to create a snapshot automatically prior to deleting the
instance (this is the default setting when you create a data tier).
Restore Environment
If the environment has been terminated in the last hour, you can restore it from this page. After an hour,
you can restore it from the application overview page (p. 132).
Configuration
The Configuration page shows the current configuration of your environment and its resources,
including EC2 instances, load balancer, notifications and health monitoring settings. Use the settings
API Version 2010-12-01
64
AWS Elastic Beanstalk Developer Guide
Logs
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 AWS Elastic Beanstalk Environment Configuration (p. 144).
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 Your Elastic Beanstalk Environment's Amazon EC2
Instances (p. 336).
API Version 2010-12-01
65
AWS Elastic Beanstalk Developer Guide
Health
Health
The Health page shows live health information about every instance in your environment, if enhanced
health monitoring is enabled. Enhanced health monitoring allows 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 (p. 306).
Monitoring
The Monitoring page shows an overview of health information for your environment, including 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. You can use the options on this page to configure
additional graphs for resource specific metrics, and add alarms for any metric supported by the in-use
health reporting system.
For more information, see Monitoring Environment Health in the AWS Management Console (p. 300).
Alarms
The Alarms page shows information about any alarms that you have configured for your environment.
You can use the options on this page to modify or delete alarms.
API Version 2010-12-01
66
AWS Elastic Beanstalk Developer Guide
Managed Updates
For more information, see Manage Alarms (p. 330).
Managed Updates
The Managed Updates shows information about upcoming and completed managed platform updates
and instance replacement. These features let 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 EC2 instances
during the maintenance window. This can help alleviate issues that occur when your application runs for
extended periods of time.
For more information, see Managed Platform Updates (p. 125).
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.
API Version 2010-12-01
67
AWS Elastic Beanstalk Developer Guide
Tags
For more information, see Viewing an Elastic Beanstalk Environment's Event Stream (p. 333).
Tags
The Tags page shows the tags that you applied to the environment when you created it. These tags are
applied to every resource that Elastic Beanstalk creates to support your application.
For more information, see Tagging Your Elastic Beanstalk Environment's Resources (p. 122).
Creating an AWS Elastic Beanstalk Environment
You can deploy multiple environments when you need to run multiple versions of an application. For
example, you might have development, integration, and production environments.
Note
For instructions on creating and managing environments with the EB CLI, see Managing Elastic
Beanstalk Environments with the EB CLI (p. 446).
API Version 2010-12-01
68
AWS Elastic Beanstalk Developer Guide
Creating Environments
The Create New Environment wizard in the AWS Management Console guides you through the creation
of an environment step by step, with a bevy of options for configuring the resources that Elastic
Beanstalk deploys on your behalf. If you are just getting started, you can use the default values for many
of these options without issue.
Note
Creating an environment requires the permissions in the Elastic Beanstalk full access managed
policy. See Elastic Beanstalk User Policy (p. 20) for details.
Follow this procedure to launch a new environment running the default application. These steps
are simplified to get your environment up and running quickly. See The Create New Environment
Wizard (p. 71) for more detailed instructions with descriptions of all of the available options.
To launch an environment with a sample application (console)
1.
Open the Elastic Beanstalk console.
2.
Choose an application or create a new one (p. 47).
3.
In the upper right corner, choose Create New Environment from the Actions menu.
4.
Choose between Web server and Worker environment types (p. 15). You cannot change an
environment's tier after creation.
API Version 2010-12-01
69
AWS Elastic Beanstalk Developer Guide
Creating Environments
5.
For Platform, choose the platform that matches the language used by your application.
Note
Elastic Beanstalk supports multiple configurations (p. 25) for most platforms listed. By
default, the console selects the latest version of the language, web container or framework
supported by Elastic Beanstalk (p. 25). If your application requires an older version, choose
Configure more options below.
6.
For App code, choose Sample application.
7.
If you would like to further customize your environment, choose Configure more options. The
following options can only be set during environment creation:
• Environment name
• Domain name
• Platform configuration
• VPC
• Tier
The following settings can be changed after environment creation, but require new instances or
other resources to be provisioned and can take a long time to apply:
• Instance type, root volume, key pair, and IAM role
• Internal RDS database
• Load balancer
For details on all available settings, see The Create New Environment Wizard (p. 71).
8.
Choose Create environment.
API Version 2010-12-01
70
AWS Elastic Beanstalk Developer Guide
The Create New Environment Wizard
While Elastic Beanstalk creates your environment, you are redirected to the The AWS Elastic Beanstalk
Environment Management Console (p. 61). Once the environment health turns green, click on 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 (p. 84).
Topics
• The Create New Environment Wizard (p. 71)
• Clone an Environment (p. 96)
• Terminate an Environment (p. 98)
• Creating Elastic Beanstalk Environments with the AWS CLI (p. 100)
• Creating Elastic Beanstalk Environments with the API (p. 101)
• Constructing a Launch Now URL (p. 104)
• Creating and Updating Groups of AWS Elastic Beanstalk Environments (p. 106)
The Create New Environment Wizard
This topic provides more information about pages in the Create New Environment wizard. For basic
instructions, see Creating an AWS Elastic Beanstalk Environment (p. 68).
Topics
• Create a new environment (p. 71)
• Configuration presets (p. 74)
• Environment settings (p. 75)
• Software settings (p. 76)
• Instances (p. 76)
• Capacity (p. 77)
• Load Balancer (p. 79)
• Deployment Settings (p. 81)
• Security (p. 83)
• Monitoring (p. 84)
• Notifications (p. 84)
• Network (p. 84)
• Database (p. 86)
• Worker Details (p. 87)
• The Old New Environment Wizard (p. 88)
Create a new environment
You can use the sample application, upload your own application, or specify the URL for the Amazon S3
bucket that contains your application code.
Choose Create environment to launch an environment right away with a default environment name,
automatically generated domain, and recommended settings. To configure more options before you
launch, choose Configure more options. You can also launch a new environment based on a custom
platform by selecting Custom platform, as shown in the following screenshot. If there are no custom
platforms available, this option is greyed out.
You can create a new environment from two types of platforms:
API Version 2010-12-01
71
AWS Elastic Beanstalk Developer Guide
The Create New Environment Wizard
• Pre-configured platforms (p. 72)
• Custom platforms (p. 72)
Create new environment from pre-configured platform
In most cases you will use a pre-configured platform for your new environment. When the new
environment wizard starts, it selects the Preconfigured platform option by default, as shown in the
following screenshot.
Scroll through the list, select the pre-configured platform to base your environment on, and select
Create environment.
Create new environment from a custom platform
If an off-the-shelf platform does not suit your needs, you can create a new environment from a custom
platform. When the new environment wizard starts, select the Custom platform option, as shown in the
following screenshot.
API Version 2010-12-01
72
AWS Elastic Beanstalk Developer Guide
The Create New Environment Wizard
Note
Depending on the platform configuration you selected, you can upload your application in a ZIP
source bundle (p. 54), a WAR file (p. 626), or a plaintext Docker configuration (p. 582). The
file size limit is 512 MB. If you select Custom platform, the console pops up a window like the
following in which you can specify the custom platform setting.
Once you've selected the platform from which the new environment is created, you can also change the
platform version. Select Configure more options and then Change platform configuration. When the
Change a platform version window appears, select the version to use for your new environment and
select Save.
API Version 2010-12-01
73
AWS Elastic Beanstalk Developer Guide
The Create New Environment Wizard
Now that you have selected the platform to use, the next step is to load your application code. If you
already have code deployed to Elastic Beanstalk, select Existing version and your application in the
Application code section.
If you want to upload new code, select Upload your code, Upload and follow the on-screen instructions.
Once you've loaded your application code into the environment, select Create environement to create
your new environment.
Configuration presets
Elastic Beanstalk provides configuration presets for low-cost development and high availability
use cases. Each preset includes a default environment name and recommended values for several
configuration options (p. 145).
The high availability preset includes a load balancer; the low cost preset does not. Choose this option if
you want a load-balanced environment that can run multiple instances for high availability and scale in
response to load.
The third 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
API Version 2010-12-01
74
AWS Elastic Beanstalk Developer Guide
The Create New Environment Wizard
files (p. 197) that set configuration options. Custom configuration is also selected automatically if you
modify either the low cost or high availability configuration presets.
Environment settings
Set the name and subdomain, and create a description for your environment. Be aware that once you
specify the environment settings, you cannot change them later.
• Name – Enter a name for the environment.
• Domain – (web server environments) Enter a unique URL for your environment. Although the
environment URL is populated with the environment name, you can enter a different name for the
URL. Elastic Beanstalk uses this name to create a unique CNAME for the environment. To check
whether the URL you want is available, click Check Availability.
• Description – Enter a description for this environment.
• Tags – Add tags to the resources in your environment. Restrictions on tag keys and tag values include
the following:
• Keys and values can contain any alphabetic character in any language, any numeric character, white
space, invisible separator, and the following symbols: _ . : / = + \ - @
• Keys and values are case-sensitive
• Values cannot match the environment name
• Values cannot include aws: or elasticbeanstalk:
API Version 2010-12-01
75
AWS Elastic Beanstalk Developer Guide
The Create New Environment Wizard
For more information about using tags, see Tagging Your Amazon EC2 Resources in the Amazon EC2
User Guide for Linux Instances.
Software settings
Configure the instances in your environment to upload rotated logs to Amazon S3, run the AWS X-Ray
daemon for debugging, and set environment properties to pass information to your application. More
platform-specific settings are available on the Configuration page after you create your environment.
• X-Ray Daemon – Run the AWS X-Ray daemon (p. 262) for debugging.
• Application logs – Enable Log storage to upload rotated logs from the instances in your environment
to your Elastic Beanstalk storage bucket in Amazon S3.
• Environment variables – Set properties that are passed to the application on-instance as environment
variables.
The way that properties are passed to applications varies by platform. In general, properties are not
visible if you connect to an instance and run env.
Instances
Configure the Amazon EC2 instances that serve requests in your environment.
API Version 2010-12-01
76
AWS Elastic Beanstalk Developer Guide
The Create New Environment Wizard
• Instance type – Select a server with the characteristics (including memory size and CPU power) that
are most appropriate to your application.
For more information about the Amazon EC2 instance types available for your Elastic Beanstalk
environment, see Instance Families and Types in the Amazon EC2 User Guide for Linux Instances.
• AMI ID – If you have created a custom AMI (p. 250), specify the AMI ID to use on your instances.
• Root volume – Specify the type, size, and input/output operations per second (IOPS) for your root
volume.
• Root volume type – From the list of storage volumes types provided by Amazon EBS, choose the
type to attach to the Amazon EC2 instances in your Elastic Beanstalk environment. Select the
volume type that meets your performance and price requirements. For more information, see
Amazon EBS Volume Types and Amazon EBS Product Details.
• Size – Set the size of your storage volume. The size for magnetic volumes can be between 8 GiB and
1024 GiB; SSD volumes can be between 10 GiB and 16,384 GiB. If you choose Provisioned IOPS
(SSD) as the root volume type for your instances, you must specify the value you want for root
volume size. For other root volumes, if you do not specify your own value, Elastic Beanstalk uses the
default volume size for that storage volume type.
• IOPS – Specify the input/output operations per second that you want. If you selected Provisioned
IOPS (SSD) as your root volume type, you must specify the IOPS. The minimum is 100 and the
maximum is 4,000. The maximum ratio of IOPS to your volume size is 30 to 1. For example, a
volume with 3,000 IOPS must be at least 100 GiB.
Capacity
Configure the compute capacity of your environment and Auto Scaling Group settings to optimize the
number of instances you're using.
API Version 2010-12-01
77
AWS Elastic Beanstalk Developer Guide
The Create New Environment Wizard
• Environment type – Choose Load balanced to run the Amazon EC2 instances in your environment
behind a load balancer, or Single instance to run one instance without a load balancer.
• Availability Zones – Restrict the number of Availability Zones to use for instances.
• Instances – Set the minimum and maximum number of instances to run.
• Placement – Choose AZs that must have instances at all times. If you assign Availability Zones here,
the minimum number of instances must be at least the number of Availability Zones that you choose.
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.
A scaling trigger is an Amazon CloudWatch alarm that lets Auto Scaling know when to scale the number
of instances in your environment. Your environment includes two triggers by default, a high trigger to
scale up, and a low trigger to scale down.
API Version 2010-12-01
78
AWS Elastic Beanstalk Developer Guide
The Create New Environment Wizard
• Metric – Choose the metric that the alarm monitors to identify times when you have too few or too
many running instances for the amount of traffic that your application receives.
• Statistic – Choose how to interpret the metric. Metrics can be measured as an average across all
instances, the maximum or minimum value seen, or a sum value from the numbers submitted by all
instances.
• Unit – Specify the unit of measurement for the values of upper and lower thresholds.
• Period – Specify the amount of time between each metric evaluation.
• Breach duration – Specifiy the amount of time that a metric can meet or exceed a threshold before
triggering the alarm. This value must be a multiple of the value for Period. For example, with a period
of 1 minute and a breach duration of 10 minutes, the threshold must be exceeded on 10 consecutive
evaluations to trigger a scaling operation
• Upper threshold – Specify the minimum value that a statistic can match to be considered in breach.
• Lower threshold – Specify the maximum value that a statistic can match to be considered in breach.
For more information on CloudWatch metrics and alarms, see Amazon CloudWatch Concepts in the
Amazon CloudWatch User Guide.
Load Balancer
Your environment's load balancer is the entry point for all traffic headed for your application. By default,
the load balancer serves HTTP traffic on port 80, but you can also configure a secure listener to accept
secure connections using HTTPS. If you use HTTPS to provide secure connections on port 443, you can
disable the default listener to require users to connect securely.
API Version 2010-12-01
79
AWS Elastic Beanstalk Developer Guide
The Create New Environment Wizard
• ELB listener – The default listener on the load balancer serves HTTP traffic from the Internet or, for an
internal application, networks connected to your VPC.
• Secure ELB listener – The secure listener terminates HTTPS connections using a TLS/SSL certificate
and passes the decrypted traffic to your instances. You can upload certificates with IAM (p. 273), or
create a new certificate with AWS Certificate Managerfor a domain that you own.
Use the remaining options to enable cross-zone load balancing and connection draining.
API Version 2010-12-01
80
AWS Elastic Beanstalk Developer Guide
The Create New Environment Wizard
• Cross-zone load balancing – Ensures traffic is balanced correctly when the number of instances in
each availability zone is not uniform, and prevents issues due to DNS caching on clients.
• Connection draining – Allows time for active connections to complete before deregistering an
instance from the load balancer during scaling operations, updates, and deployments.
You can use configuration files (p. 197) to configure more load balancer options, including advanced
listener configuration, TCP passthrough, application load balancing, and backend authentication. See
Configuring the Load Balancer in your Elastic Beanstalk Environment (p. 252) and Configuring HTTPS
for your Elastic Beanstalk Environment (p. 270) for more information.
Deployment Settings
For single-instance environments, choose a Deployment policy to configure how to deploy new
application versions and changes to the software configuration for instances. All at once completes
deployments as quickly as possible, but can result in downtime. Immutable deployments ensure the
new instance passes health checks before switching over to the new version; otherwise the old version
remains untouched. See Deployment Policies and Settings (p. 110) for more information.
For load-balanced environments, choose a Deployment policy to configure how to deploy new
application versions and changes to the software configuration for instances. All at once completes
deployments as quickly as possible, but can result in downtime. Rolling deployments ensure that
some instances remain in service during the entire deployment process. See Deployment Policies and
Settings (p. 110) for more information.
API Version 2010-12-01
81
AWS Elastic Beanstalk Developer Guide
The Create New Environment Wizard
• Deployment policy – Rolling deployments take one batch of instances out of service at a time to
deploy a new version. Rolling with additional batch launches a new batch first to ensure that capacity
is not affected during the deployment. Immutable performs an immutable update (p. 120) when you
deploy.
• Batch size – The number or percentage of instances to update in each batch.
Rolling updates (p. 117) occur when you change instance launch configuration settings or VPC settings,
which require terminating and replacing the instances in your environment. Other configuration
changes are made in place without affecting capacity. For more information, see Configuration
Changes (p. 116).
• Rolling update type – Time based, where AWS CloudFormation waits for the specified amount of
time after new instances are registered before moving on to the next batch, or health based, where
AWS CloudFormation waits for instances to pass health checks. Immutable performs an immutable
update (p. 120) when a configuration change would normally trigger a rolling update.
• Batch size – The number of instances to replace in each batch.
• Minimum capacity – The minimum number of instances to keep in service at any given time.
• Pause time – For time-based rolling updates, the amount of time to wait for new instances to come up
to speed after they are registered to the load balancer.
The remaining options customize health checks and timeouts.
API Version 2010-12-01
82
AWS Elastic Beanstalk Developer Guide
The Create New Environment Wizard
• 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.
Security
Choose an Amazon EC2 key pair to enable SSH or RDP access to the instances in your environment. If you
have created a custom service role and instance profile, select them from the drop-down lists. If not, use
the default roles, aws-elasticbeanstalk-service-role and aws-elasticbeanstalk-ec2-role.
• Service role – A service role (p. 18) grants Elastic Beanstalk permission to monitor the resources in
your environment.
• EC2 key pair – Assign an SSH key to the instances in your environment to allow you to connect
to them remotely for debugging. For more information about Amazon EC2 key pairs, see Using
Credentials in the Amazon EC2 User Guide for Linux Instances.
• IAM instance profile – An instance profile (p. 19) grants the Amazon EC2 instances in your
environment permissions to access AWS resources.
API Version 2010-12-01
83
AWS Elastic Beanstalk Developer Guide
The Create New Environment Wizard
The Elastic Beanstalk console looks for an instance profile named aws-elasticbeanstalk-ec2-role and
a service role named aws-elasticbeanstalk-service-role. If you don't have these roles, the console
creates them for you. For more information, see Service Roles, Instance Profiles, and User Policies (p. 17).
Monitoring
For load-balanced environments, Health check path tells the load balancer where to send requests for
health checks.
• Health check path – The path to send health check requests to. If not set, the load balancer attempts
to make a TCP connection on port 80 to verify health. Set to a path starting with / to send an HTTP
GET request to that path. You can also include a protocol (HTTP, HTTPS, TCP, or SSL) and port before
the path to check HTTPS connectivity or use a non-default port. For example, HTTPS:443/health.
• Health reporting system – Enhanced health reporting (p. 306) provides additional health
information about the resources in your environment at no additional charge.
Notifications
Specify an email address to receive email notifications (p. 266) for important events from your
environment.
• Email – An email address for notifications.
Network
If you have created a custom VPC (p. 264), use these settings to configure your environment to use it. If
you do not choose a VPC, Elastic Beanstalk uses the default VPC and subnets.
API Version 2010-12-01
84
AWS Elastic Beanstalk Developer Guide
The Create New Environment Wizard
• VPC – The VPC in which to launch your environment's resources.
• Load balancer visibility – Makes your load balancer internal to prevent connections from the Internet.
This option is for applications that serve traffic only from networks connected to the VPC.
• Load balancer subnets – Choose public subnets for your load balancer if your site serves traffic from
the Internet.
API Version 2010-12-01
85
AWS Elastic Beanstalk Developer Guide
The Create New Environment Wizard
• Public IP address – Choose this option if you run your instances and load balancer in the same public
subnets.
• Instance subnets – Choose private subnets for your instances.
• Instance security groups – Choose security groups to assign to your instances, in addition to standard
security groups that Elastic Beanstalk creates.
For more information about Amazon VPC, see Amazon Virtual Private Cloud (Amazon VPC).
Database
Add an Amazon RDS SQL database to your environment for development and testing. Elastic Beanstalk
provides connection information to your instances by setting environment properties for the database
hostname, username, password, table name, and port. When you add a database to your environment,
its lifecycle is tied to your environment lifecycle.
For production environments, you can configure your instances to connect to an external database.
API Version 2010-12-01
86
AWS Elastic Beanstalk Developer Guide
The Create New Environment Wizard
• Engine – Choose the database engine used by your application.
• Engine version – Choose the version of the database engine.
• Instance class – Choose a database instance class. For information about the DB instance classes, see
http://aws.amazon.com/rds/.
• Storage – Specifiy the amount of storage space, in gigabytes, to allocate for your database. For
information about storage allocation, see Features.
• Username – The username for the database administrator. Username requirements vary per database
engine.
• Password – The password for the database administrator. Password requirements vary per database
engine.
• Retention – You can use a snapshot to restore data by launching a new DB instance. Choose Create
snapshot to save a snapshot of the database automatically when you terminate your environment.
• Availability – Choose High (Multi-AZ) to run a second DB instance in a different Availability Zone for
high availability.
For more information about Amazon RDS, see Amazon Relational Database Service (Amazon RDS).
Worker Details
(worker environments) You can create an Amazon SQS queue for your worker application or pull work
items from an existing queue. The worker daemon on the instances in your environment pulls an item
API Version 2010-12-01
87
AWS Elastic Beanstalk Developer Guide
The Create New Environment Wizard
from the queue and relays it in the body of a POST request to a local HTTP path relative to the local
host.
• Worker queue – Choose the queue from which the worker environment tier reads messages that it will
process. If you do not provide a value, then Elastic Beanstalk automatically creates one for you.
• HTTP path – Specifiy the relative path on the local host to which messages from the queue are
forwarded in the form of HTTP POST requests.
• MIME type – Choose The MIME type of the message sent in the HTTP POST request.
• HTTP connections – The maximum number of concurrent connections to the application. Set this to
the number of processes or thread messages that your application can process in parallel.
• Visibility timeout – The amount of time that an incoming message is locked for processing before
being returned to the queue. Set this to the potentially longest amount of time that might be required
to process a message.
The Old New Environment Wizard
To launch a new environment
1.
Open the Elastic Beanstalk console.
2.
From the Elastic Beanstalk console applications page, choose Actions for the application in which
you want to launch a new environment.
API Version 2010-12-01
88
AWS Elastic Beanstalk Developer Guide
The Create New Environment Wizard
3.
Choose Launch New Environment.
4.
Follow the instructions shown to launch an environment.
See the following sections for details on each page of the wizard.
Pages
• New Environment (p. 89)
• Environment Type (p. 89)
• Application Version (p. 90)
• Environment Info (p. 90)
• Additional Resources (p. 90)
• Configuration Details (p. 90)
• Environment Tags (p. 92)
• Worker Details (p. 93)
• RDS Configuration (p. 93)
• VPC Configuration (p. 95)
• Permissions (p. 96)
• Review Information (p. 96)
New Environment
On the New Environment page, select an environment tier. The environment tier setting specifies
whether you want a Web Server or Worker environment. For more information, see Architectural
Overview (p. 15).
Note
After you launch an environment, you cannot change the environment tier. If your application
requires a different environment tier, you must launch a new environment.
Environment Type
On the Environment Type page, select a platform and environment type, and then choose Next.
• The Predefined configuration setting specifies the platform and version that is used for the
environment. For more information, see Elastic Beanstalk Supported Platforms (p. 25).
Note
After you launch an environment with a specific configuration, you cannot change the
configuration. If your application requires a different configuration, you must launch a new
environment.
API Version 2010-12-01
89
AWS Elastic Beanstalk Developer Guide
The Create New Environment Wizard
• The Saved configuration setting lists all environment configurations that you previously saved for this
application, if any. If you have no saved configurations for this application, Elastic Beanstalk does not
display this option in the console.
• The Environment type specifies whether the environment is load balancing and automatically scaling
or is only a single Amazon EC2 instance. For more information, see Environment Types (p. 134).
Application Version
On the Application Version page, you can use the sample application, upload your own, or specify the
URL for the Amazon S3 bucket that contains your application code.
Note
Depending on the platform configuration you selected, you can upload your application in
a ZIP source bundle (p. 54), a WAR file, or a plaintext Docker configuration. You can include
multiple WAR files inside a ZIP file to deploy multiple Tomcat applications to each instance in
your environment. The file size limit is 512 MB.
For load-balancing, automatically scaling environments, choose a Deployment policy to configure how
new application versions and changes to software configurations for instances are deployed. All at once
completes deployments as quickly as possible, but can result in downtime. Rolling deployments ensure
that some instances remain in service during the entire deployment process. The Healthy threshold
option lets you lower the minimum status at which instances can pass health checks during rolling
deployments and configuration updates. See Deployment Policies and Settings (p. 110) for more
information.
Environment Info
On the Environment Information page, enter the details of your environment and choose Next.
• Enter a name for the environment.
• (Web server environments) Enter a unique environment URL. Although the environment URL is
populated with the environment name, you can enter a different name for the URL. Elastic Beanstalk
uses this name to create a unique CNAME for the environment. You can check the availability of the
URL by clicking Check Availability.
• (Optional) Enter a description for this environment.
Additional Resources
(Optional) On the Additional Resources page, select more resources for the environment, and then
choose Next. Note the following:
• If you want to add an Amazon RDS DB to the environment, select Create an RDS Database with this
environment. For more information about Amazon RDS, see Amazon Relational Database Service
(Amazon RDS).
• To create your environment in a custom VPC, select Create this environment inside a VPC. For more
information about Amazon VPC, see Amazon Virtual Private Cloud (Amazon VPC).
Configuration Details
Set configuration details for the environment, and then choose Next.
API Version 2010-12-01
90
AWS Elastic Beanstalk Developer Guide
The Create New Environment Wizard
• Instance type displays the instance types available to your Elastic Beanstalk environment. Select a
server with the characteristics (including memory size and CPU power) that are most appropriate to
your application.
Note
Elastic Beanstalk is free, but the AWS resources that it provisions might not be. For
information on Amazon EC2 usage fees, see Amazon EC2 Pricing.
For more information about the Amazon EC2 instance types that are available for your Elastic
Beanstalk environment, see Instance Families and Types in the Amazon EC2 User Guide for Linux
Instances.
• Select an EC2 key pair to enable SSH or RDP access to the instances in your environment. For more
information about Amazon EC2 key pairs, see Using Credentials in the Amazon EC2 User Guide for
Linux Instances.
API Version 2010-12-01
91
AWS Elastic Beanstalk Developer Guide
The Create New Environment Wizard
• Specify an Email address to receive notifications about important events emitted by your
environment. For more information, see Configuring Amazon SNS Notifications with Elastic
Beanstalk (p. 266).
• For load-balancing, automatically scaling environments, Application health check URL, Cross-zone
load balancing, Connection draining, and Connection draining timeout let you configure the load
balancer's behavior. For more information, see Configuring the Load Balancer in your Elastic Beanstalk
Environment (p. 252).
• Rolling updates type provides options for managing how instances are replaced when you change
settings on the AutoScaling group or VPC. For more information, see Elastic Beanstalk Rolling
Environment Configuration Updates (p. 117).
• Root volume type displays the types of storage volumes provided by Amazon EBS that you can attach
to Amazon EC2 instances in your Elastic Beanstalk environment. Select the volume type that meets
your performance and price requirements. For more information, see Amazon EBS Volume Types and
Amazon EBS Product Details. The size of magnetic volumes can be between 8 GiB and 1,024 GiB, and
SSD volumes can be between 10 GiB and 16,384 GiB.
• With Root volume size, you can specify the size of the storage volume that you selected. You must
specify the root volume size you want if you choose Provisioned IOPS (SSD) as the root volume type
that your instances will use. For other root volumes, if you do not specify your own value, Elastic
Beanstalk uses the default volume size for the storage volume type.
• If you selected Provisioned IOPS (SSD) as your root volume type, you must specify the input/output
operations per second (IOPS) that you want. The minimum is 100 and the maximum is 4,000. The
maximum ratio of IOPS to your volume size is 30 to 1. For example, a volume with 3,000 IOPS must be
at least 100 GiB.
Environment Tags
(Optional) On the Environment Tags page, create tags for the environment, and then choose Next.
Restrictions on tag keys and tag values include the following:
• Keys and values can contain any alphabetic character in any language, any numeric character, white
space, invisible separator, and the following symbols: _ . : / = + \ - @
• Keys and values are case-sensitive
• Values cannot match the environment name
• Values cannot include either aws: or elasticbeanstalk:
For more information about using tags, see Tagging Your Amazon EC2 Resources in the Amazon EC2 User
Guide for Linux Instances.
API Version 2010-12-01
92
AWS Elastic Beanstalk Developer Guide
The Create New Environment Wizard
Worker Details
(worker environments) On the Worker Details page, set the following preliminary worker environment
tier details. Then, choose Next.
• Worker queue specifies the queue from which the worker environment tier reads messages that it will
process. If you do not provide a value, then Elastic Beanstalk automatically creates one for you.
• HTTP path specifies the relative path on the local host to which messages from the queue are
forwarded in the form of HTTP POST requests.
• MIME type specifies the MIME type of the message sent in the HTTP POST request.
• HTTP connections specifies the maximum number of concurrent connections to the application. Set
this to the number of process or thread messages your application can process in parallel.
• Visibility timeout specifies how long an incoming message is locked for processing before being
returned to the queue. Set this to the potentially longest amount of time that might be required to
process a message.
RDS Configuration
If you chose to associate an Amazon RDS DB earlier in the environment configuration process, on the
RDS Configuration page, set the Amazon RDS configuration settings, and then choose Next.
API Version 2010-12-01
93
AWS Elastic Beanstalk Developer Guide
The Create New Environment Wizard
• (Optional) For Snapshot, select whether to create an Amazon RDS DB from an existing snapshot.
• (Optional) For DB engine, select a database engine.
• (Optional) For Instance Class, select a database instance class. For information about the DB instance
classes, see http://aws.amazon.com/rds/.
• For Allocated Storage, type the space needed for your database. You can allocate between 5 GB and
1024 GB. You cannot update the allocated storage for a database to a lower amount after you set it. In
some cases, allocating a larger amount of storage for your DB instance than the size of your database
can improve IO performance. For information about storage allocation, see Features.
• For Master Username, type a name using alphanumeric characters to use to log in to your DB instance
with all database privileges.
• For Master Password, type a password containing 8–16 printable ASCII characters (excluding /, \, and
@).
• For Deletion Policy, select Create snapshot to create a snapshot that you can use later to create
another Amazon RDS database. Select Delete to delete the DB instance when you terminate the
environment. If you select Delete, you lose your DB instance and all the data in it when you terminate
the Elastic Beanstalk instance associated with it. By default, Elastic Beanstalk creates and saves a
snapshot. You can use a snapshot to restore data to use in a new environment, but cannot otherwise
recover lost data.
Note
You may incur charges for storing database snapshots. For more information, see the "Backup
Storage" section of Amazon RDS Pricing.
• For Availability, select one of the following:
• To configure your database in one Availability Zone, select Single Availability Zone. A database
instance launched in one Availability Zone does not have protection from the failure of a single
location.
• To configure your database across multiple Availability Zones, select Multiple Availability Zones.
Running your database instance in multiple Availability Zones helps safeguard your data in the
unlikely event of a database instance component failure or service health disruption in one
Availability Zone.
API Version 2010-12-01
94
AWS Elastic Beanstalk Developer Guide
The Create New Environment Wizard
VPC Configuration
If you chose to create an environment inside a VPC earlier in the environment creation process, set the
VPC configuration settings, and then choose Next.
• Select the VPC ID of the VPC in which you want to launch your environment.
Note
If you do not see the VPC information, then you have not created a VPC in the same region
in which you are launching your environment. To learn how to create a VPC, see Using Elastic
Beanstalk with Amazon VPC (p. 408).
• For a load-balancing, automatically scaling environment, select the subnets for the Elastic Load
Balancing load balancer and the Amazon EC2 instances. If you created a single public subnet, select
the Associate Public IP Address check box, and then select the check boxes for the load balancer
and the Amazon EC2 instances. If you created public and private subnets, be sure the load balancer
(public subnet) and the Amazon EC2 instances (private subnet) are associated with the correct
subnet. By default, Amazon VPC creates a default public subnet using 10.0.0.0/24 and a private
subnet using 10.0.1.0/24. You can view your existing subnets in the Amazon VPC console at https://
console.aws.amazon.com/vpc/.
• For a single-instance environment, select a public subnet for the Amazon EC2 instance. By default,
Amazon VPC creates a default public subnet using 10.0.0.0/24. You can view your existing subnets in
the Amazon VPC console at https://console.aws.amazon.com/vpc/.
• If you are using Amazon RDS, you must select at least two subnets in different Availability Zones. To
learn how to create subnets for your VPC, see Task 1: Create the VPC and Subnets in the Amazon VPC
User Guide.
• If your VPC configuration uses a NAT device, select the security group you created for your instances.
For more information, see Create a Security Group for Your Instances (p. 415). If you do not have a
NAT device or if you did not create a security group, you can use the default security group.
• For a load-balancing, automatically scaling environment, select whether you want to make the load
balancer external or internal. If you do not want your load balancer to be available to the Internet,
select Internal.
API Version 2010-12-01
95
AWS Elastic Beanstalk Developer Guide
Clone an Environment
Permissions
For Permissions window, select an instance profile (p. 19) and service role (p. 18). An instance profile
grants the Amazon EC2 instances in your environment permissions to access AWS resources. A service
role grants Elastic Beanstalk permission to monitor the resources in your environment. For more
information, see Service Roles, Instance Profiles, and User Policies (p. 17).)
If you've created a custom instance profile and service role, select them from the drop-down menus. If
not, choose Next to use the default roles.
The Elastic Beanstalk console looks for an instance profile named aws-elasticbeanstalk-ec2-role and
a service role named aws-elasticbeanstalk-service-role. If you don't have these roles, the console
creates them for you.
Review Information
On the Review Information page, review your application and environment information, and then
choose Launch.
Elastic Beanstalk launches your application in a new environment. It can take several minutes for the new
environment to start while Elastic Beanstalk is provisioning AWS resources. You can view the status of
your deployment on the environment's dashboard. While Elastic Beanstalk creates your AWS resources
and launches your application, the environment displays a gray state. Status messages about launch
events appear in the environment's dashboard. When the deployment is complete, Elastic Beanstalk
performs an application health check. The environment status becomes green when the application
responds to the health check.
Clone an Environment
You can use an existing environment as the basis for a new environment by creating a clone of the
existing environment. For example, you might want to create a clone so that you can use a newer version
of the solution stack used by the original environment's platform. Elastic Beanstalk configures the
clone with the same environment settings used by the original environment. By cloning an existing
environment instead of creating a new environment, you do not have to manually configure option
settings, environment variables, and other settings. Elastic Beanstalk also creates a copy of any AWS
resource associated with the original environment. However, during the cloning process, Elastic Beanstalk
does not copy data from Amazon RDS to the clone. After you have created the clone environment, you
can modify environment configuration settings as needed.
Note
Elastic Beanstalk does not include any unmanaged changes to resources in the clone. Changes
to AWS resources that you make using tools other than the Elastic Beanstalk management
console, command-line tools, or API are considered unmanaged changes.
AWS Management Console
To clone an environment
1.
Open the Elastic Beanstalk console.
2.
From the region list, select the region that includes the environment that you want to work with.
3.
On the Elastic Beanstalk console applications page, click the name of the application, and then the
name of the environment that you want to clone.
API Version 2010-12-01
96
AWS Elastic Beanstalk Developer Guide
Clone an Environment
4.
On the environment dashboard, click Actions, and then do one of the following:
• Click Clone Environment if you want to clone the environment without any changes to the
solution stack version.
• Click Clone with Latest Platform if you want to clone the environment, but with a newer version
of the original environment's solution stack.
5.
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.
6.
In the New Environment section, you can optionally change the Environment name, Environment
URL, Description, and Platform values that Elastic Beanstalk automatically set based on the original
environment.
Note
For Platform, only solution stacks with the same language and web server configuration
are shown. If a newer version of the solution stack used with the original environment
is available, you will be prompted to update, but you cannot choose a different stack,
even if it is for a different version of the same language. For more information, see Elastic
Beanstalk Supported Platforms (p. 25).
API Version 2010-12-01
97
AWS Elastic Beanstalk Developer Guide
Terminate an Environment
7.
When you are ready, click Clone.
Elastic Beanstalk Command Line Interface (EB CLI)
Use the eb clone command to clone a running environment:
~/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 (p. 468).
Terminate an Environment
You can terminate a running environment using the AWS Management Console to avoid incurring
charges for unused AWS resources. For more information about terminating an environment using the
AWS Toolkit for Eclipse, see Terminating an Environment (p. 658).
API Version 2010-12-01
98
AWS Elastic Beanstalk Developer Guide
Terminate an Environment
Note
You can always launch a new environment using the same version later. If you have data from
an environment that you would like to preserve, create a snapshot of your current database
instance before you terminate the environment. You can later use it as the basis for new DB
instance when you create a new environment. For more information, see Creating a DB Snapshot
in the Amazon Relational Database Service User Guide.
AWS Management Console
To terminate an environment
1.
Open the Elastic Beanstalk console.
2.
From the region list, select the region that includes the environment that want to terminate.
3.
From the Elastic Beanstalk console applications page, click the name of the environment that you
want to terminate.
4.
Click Actions and the select Terminate Environment.
5.
Confirm that you are terminating the correct environment and then click Terminate.
Note
When you terminate your environment, the CNAME associated with the terminated
environment becomes available for anyone to use.
API Version 2010-12-01
99
AWS Elastic Beanstalk Developer Guide
With the AWS CLI
It will take a few minutes for Elastic Beanstalk to terminate the AWS resources running in the
environment.
CLI
To terminate an environment
•
$ aws elasticbeanstalk terminate-environment --environment-name my-env
API
To terminate an environment
•
Call TerminateEnvironment with the following parameter:
• EnvironmentName = SampleAppEnv
Example
https://elasticbeanstalk.us-west-2.amazon.com/?EnvironmentName=SampleAppEnv
&Operation=TerminateEnvironment
&AuthParams
Creating Elastic Beanstalk Environments with the
AWS CLI
To create an environment with the AWS CLI
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"
}
2.
Make sure your application version exists.
$ aws elasticbeanstalk describe-application-versions --application-name my-app -version-label v1
3.
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)"
4.
Create environment.
API Version 2010-12-01
100
AWS Elastic Beanstalk Developer Guide
With the API
$ aws elasticbeanstalk create-environment --cname-prefix my-cname --applicationname my-app --template-name v1 --version-label v1 --environment-name v1clone --optionsettings 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.
5.
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
To launch a new environment
1.
Call CheckDNSAvailability with the following parameter:
• CNAMEPrefix = SampleApp
Example
https://elasticbeanstalk.&region_console_default;.amazon.com/?
CNAMEPrefix=sampleapplication
&Operation=CheckDNSAvailability
&AuthParams
2.
Call DescribeApplicationVersions with the following parameters:
• ApplicationName = SampleApp
• VersionLabel = Version2
Example
https://elasticbeanstalk.&region_console_default;.amazon.com/?ApplicationName=SampleApp
&VersionLabel=Version2
&Operation=DescribeApplicationVersions
&AuthParams
API Version 2010-12-01
101
AWS Elastic Beanstalk Developer Guide
With the API
3.
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
https://elasticbeanstalk.&region_console_default;.amazon.com/?ApplicationName=SampleApp
&TemplateName=MyConfigTemplate
&Operation=CreateConfigurationTemplate
&SolutionStackName=64bit%20Amazon%20Linux%202015.03%20v2.0.0%20running%20Ruby
%202.2%20(Passenger%20Standalone)
&AuthParams
4.
Call CreateEnvironment with one of the following sets of parameters.
a.
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 = ElasticBeanstalkProfile
Example
https://elasticbeanstalk.&region_console_default;.amazon.com/?
ApplicationName=SampleApp
&VersionLabel=Version2
&EnvironmentName=SampleAppEnv2
&TemplateName=MyConfigTemplate
&CNAMEPrefix=sampleapplication
&Description=description
&Operation=CreateEnvironment
&OptionSettings.member.1.Namespace=aws%3Aautoscaling%3Alaunchconfiguration
&OptionSettings.member.1.OptionName=IamInstanceProfile
&OptionSettings.member.1.Value=ElasticBeanstalkProfile
&AuthParams
b.
Use the following for a worker environment tier:
• EnvironmentName = SampleAppEnv2
• VersionLabel = Version2
• Description = description
• TemplateName = MyConfigTemplate
• ApplicationName = SampleApp
• Tier = Worker
API Version 2010-12-01
• OptionSettings.member.1.Namespace
= aws:autoscaling:launchconfiguration
102
AWS Elastic Beanstalk Developer Guide
With the API
• OptionSettings.member.1.OptionName = IamInstanceProfile
• OptionSettings.member.1.Value = ElasticBeanstalkProfile
• OptionSettings.member.2.Namespace = aws:elasticbeanstalk:sqsd
• OptionSettings.member.2.OptionName = WorkerQueueURL
• OptionSettings.member.2.Value = sqsd.elasticbeanstalk.us-east-2.amazon.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
https://elasticbeanstalk.&region_console_default;.amazon.com/?
ApplicationName=SampleApp
&VersionLabel=Version2
&EnvironmentName=SampleAppEnv2
&TemplateName=MyConfigTemplate
&Description=description
&Tier=Worker
&Operation=CreateEnvironment
&OptionSettings.member.1.Namespace=aws%3Aautoscaling%3Alaunchconfiguration
&OptionSettings.member.1.OptionName=IamInstanceProfile
&OptionSettings.member.1.Value=ElasticBeanstalkProfile
&OptionSettings.member.2.Namespace=aws%3Aelasticbeanstalk%3Asqsd
&OptionSettings.member.2.OptionName=WorkerQueueURL
&OptionSettings.member.2.Value=sqsd.elasticbeanstalk.&region_console_default;.amazon.com
&OptionSettings.member.3.Namespace=aws%3elasticbeanstalk%3sqsd
&OptionSettings.member.3.OptionName=HttpPath
&OptionSettings.member.3.Value=%2F
&OptionSettings.member.4.Namespace=aws%3Aelasticbeanstalk%3Asqsd
&OptionSettings.member.4.OptionName=MimeType
&OptionSettings.member.4.Value=application%2Fjson
&OptionSettings.member.5.Namespace=aws%3Aelasticbeanstalk%3Asqsd
API Version 2010-12-01
&OptionSettings.member.5.OptionName=HttpConnections
&OptionSettings.member.5.Value=75
103
AWS Elastic Beanstalk Developer Guide
Launch Now URL
&OptionSettings.member.6.Namespace=aws%3Aelasticbeanstalk%3Asqsd
&OptionSettings.member.6.OptionName=ConnectTimeout
&OptionSettings.member.6.Value=10
&OptionSettings.member.7.Namespace=aws%3Aelasticbeanstalk%3Asqsd
&OptionSettings.member.7.OptionName=InactivityTimeout
&OptionSettings.member.7.Value=10
&OptionSettings.member.8.Namespace=aws%3Aelasticbeanstalk%3Asqsd
&OptionSettings.member.8.OptionName=VisibilityTimeout
&OptionSettings.member.8.Value=60
&OptionSettings.member.9.Namespace=aws%3Aelasticbeanstalk%3Asqsd
&OptionSettings.member.9.OptionName=RetentionPeriod
&OptionSettings.member.9.Value=345600
&AuthParams
Constructing a Launch Now URL
You can construct a custom uniform resource locator (URL) so that anyone can quickly deploy and
run a predetermined web application in 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 is built to run on
Elastic Beanstalk. With Launch Now URL, you can use parameters to add the required information to the
Create Application wizard in advance. When you do, anyone can use the URL link to launch an Elastic
Beanstalk environment with your web application source in just a few clicks. This means users don't need
to manually upload or specify the location of the application source bundle or provide any additional
input to the wizard.
A Launch Now URL gives Elastic Beanstalk the minimum information 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 are not 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.
URL Parameters
The URL must contain the following parameters, which are case-sensitive:
• region – Specify an AWS region. For a list of regions supported by Elastic Beanstalk, see AWS Elastic
Beanstalk in the Amazon Web Services General Reference.
• applicationName – Specify the name of your application. Elastic Beanstalk displays the application
name in the AWS Management Console to distinguish it from other applications. By default, the
application name also forms the basis of the environment name and environment URL.
• solutionStackName – Specify the platform and version that will be used for the environment. For
more information, see Elastic Beanstalk Supported Platforms (p. 25).
A Launch Now URL can optionally contain the following parameters. If you do not include the optional
parameters in your Launch Now URL, Elastic Beanstalk uses default values to create and run your
application. When you do not include the sourceBundleUrl parameter, Elastic Beanstalk uses the default
sample application for the specified solutionStackName.
• sourceBundleUrl – Specify the location of your web application source bundle in URL format. For
example, if you uploaded your source bundle to an Amazon Simple Storage Service bucket, you
might specify the value of the sourceBundleUrl parameter as http://s3.amazonaws.com/mybucket/
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.
API Version 2010-12-01
104
AWS Elastic Beanstalk Developer Guide
Launch Now URL
• environmentType – Specify whether the environment is load balancing and autoscaling or just
a single instance. For more information, see Environment Types (p. 134). 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 Worker
Environments (p. 136). 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. To see the instance types that are available in your Elastic
Beanstalk region, see InstanceType (p. 162) in the topic Configuration Options (p. 145). To see the
detailed specifications for each Amazon EC2 instance type, see Instance Types.
• 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 (p. 408).
• withRds – Specify whether to create an Amazon RDS database instance with this environment. For
more information, see Using Elastic Beanstalk with Amazon RDS (p. 398). 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. 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.t1.micro. For a
list of database instance classes supported by Amazon RDS, see DB Instance Class 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, go to Regions and Availability Zones 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 might want to embed the URL on a web page 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/?region=us-west-2#/newApplication?
applicationName=YourCompanySampleApp&solutionStackName=PHP&sourceBundleUrl=http://
s3.amazonaws.com/mybucket/
myobject&environmentType=SingleInstance&tierName=WebServer&instanceType=m1.small&withVpc=true&withRds=t
When users click a Launch Now URL, Elastic Beanstalk displays a page similar to the following.
API Version 2010-12-01
105
AWS Elastic Beanstalk Developer Guide
Compose Environments
To use the Launch Now URL
1.
Click the Launch Now URL.
2.
When the Elastic Beanstalk console opens, on the Application Info page, click Review and Launch
to view the settings Elastic Beanstalk will use to create the application and launch the environment
in which the application runs.
3.
On the Review page, click Launch to create the application.
Creating and Updating Groups of AWS Elastic
Beanstalk Environments
With AWS Elastic Beanstalk's (Elastic Beanstalk's) Compose Environments 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 AWS Elastic Beanstalk
Environments (p. 142).
The Compose Environments API uses an environment manifest (p. 237) 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 AWS Elastic Beanstalk Environments as a Group with the
EB CLI (p. 461) 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 frontAPI Version 2010-12-01
106
AWS Elastic Beanstalk Developer Guide
Compose Environments
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 (p. 50) 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 --source-bundle S3Bucket="my-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",
API Version 2010-12-01
107
AWS Elastic Beanstalk Developer Guide
Deployments
"SourceBundle": {
"S3Bucket": "my-bucket",
"S3Key": "front-v1.zip"
}
}
}
~$ aws elasticbeanstalk create-application-version --application-name media-library -version-label worker-v1 --source-bundle S3Bucket="my-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": "my-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 AWS Elastic Beanstalk Environments (p. 142).
Deploying Applications to AWS Elastic Beanstalk
Environments
You can use the AWS Management Console to upload an updated source bundle (p. 54) and deploy it to
your AWS Elastic Beanstalk environment, or redeploy a previously uploaded version.
Deploying a new version of your application to an environment is typically a fairly quick process. The
new source bundle is deployed to an instance and extracted, and then the web container or application
server picks up the new version and restarts if necessary. During deployment, your application might still
become unavailable to users for a few seconds. You can prevent this by configuring your environment to
use rolling deployments (p. 110) to deploy the new version to instances in batches.
Each deployment is identified by a deployment ID. Deployment IDs start at one and increment by one
with each deployment and instance configuration change. Elastic Beanstalk displays the deployment ID
in both the health console (p. 314) and the EB CLI (p. 457) when it reports instance health status if
you have enabled enhanced health reporting (p. 306). The deployment ID can help you determine the
state of your environment when a rolling update fails.
If you need to ensure that your application source is always deployed to new instances, instead of
updating existing instances, you can configure your environment to use immutable updates (p. 120) for
deployments. In an immutable update, a second AutoScaling group is launched in your environment and
the new version serves traffic alongside the old version until the new instance pass health checks.
API Version 2010-12-01
108
AWS Elastic Beanstalk Developer Guide
Deployments
Supported Deployment Policies
Deployment Policy
Load Balanced
Environments
Single Instance
Environments
Windows Server
Environments
All at Once
✓
✓
✓
Rolling
✓
☓
✓
Rolling with an
Additional Batch
✓
☓
☓
Immutable
✓
✓
☓
To configure deployments
1.
Open the Elastic Beanstalk console.
2.
Navigate to the management page (p. 61) for your environment.
3.
Choose Configuration.
4.
Choose Updates and Deployments.
5.
In the Application Deployments section, choose a Deployment policy (p. 110) and batch settings.
6.
Choose Apply.
For deployments that are dependent 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 (p. 113).
The following table compares deployment methods:
Deployment Methods
Method
Impact of Failed Deployment
Deploy Time
Zero No
Rollback
Code
Downtime
DNS Process
Deployed
Change
To
☓
✓
Re- Existing
deployinstances
✓
✓
Re- Existing
deployinstances
✓
✓
Re- New
deploy&
existing
instances
Immutable
Minimal
✓
✓
Re- New
deployinstances
Blue/ Minimal
green
✓
☓
Swap New
URL instances
All
Downtime
at
once
RollingSingle batch out of service. Any successful
batches prior to failure running new
application version.
RollingMinimal if first batch fails, otherwise similar
with to Rolling.
additional
batch
† Varies depending on batch size.
API Version 2010-12-01
109
†
†
AWS Elastic Beanstalk Developer Guide
Deployment Options
If you deploy often, consider using the Elastic Beanstalk Command Line Interface (p. 434) to manage
your environments. The EB CLI creates a repository alongside your source code and can create a source
bundle, upload it to Elastic Beanstalk, and deploy with a single command.
Deployment Policies and Settings
AWS Elastic Beanstalk provides several options for how deployments (p. 108) are processed, including
deployment policies (All at once, Rolling, Rolling with additional batch, and Immutable) and options
that let you configure batch size and health check behavior during deployments. By default, your
environment uses rolling deployments if you created it with the console or EB CLI, or all at once
deployments if you created it with a different client (API, SDK or AWS CLI).
With rolling deployments, AWS Elastic Beanstalk splits the environment's EC2 instances into batches and
deploys the new version of the application to one batch at a time, leaving 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.
If you need to maintain full capacity during deployments, you can configure your environment to launch
a new batch of instances prior to taking any instances out of service. This option is called 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 (p. 120) 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.
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 (p. 61), 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.
2.
3.
4.
Navigate to the management page (p. 61) for your environment.
Choose Configuration.
5.
6.
In the Updates and Deployments section, choose
.
In the Application Deployments section, choose a Deployment policy, batch settings and health
check options.
Choose Apply.
The Application Deployments section of the Updates and Deployments page has the following options
for rolling updates:
API Version 2010-12-01
110
AWS Elastic Beanstalk Developer Guide
Deployment Options
• 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 (p. 120).
• Batch type – Whether you want to allocate a percentage of the total number of EC2 instances in the
Auto Scaling group or a fixed number to a batch of instances.
• Batch size – The number or percentage of instances to deploy in each batch, up to 100 percent or the
maximum instance count in your environment's Auto Scaling configuration.
The Preferences section contains options related to health checks.
• Healthy threshold – Lowers the threshold at which an instance is considered healthy during rolling
deployments, rolling updates and immutable updates.
• Ignore health check – Prevents a deployment from rolling back when a batch fails to become healthy
within the Command timeout.
• Command timeout – The number of seconds to wait for an instance to become healthy before
cancelling the deployment or, if Ignore health check is set, to continue to the next batch.
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 have connection
API Version 2010-12-01
111
AWS Elastic Beanstalk Developer Guide
Deployment Options
draining (p. 254) enabled, Elastic Beanstalk drains existing connections from the 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 (p. 255) 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 (p. 303), 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 (p. 306) 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 (p. 318)
within 2 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 (p. 110), the deployment
fails. After a failed deployment, check the health of the instances in your environment (p. 314) for
information about the cause of the failure, and 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 (p. 314)
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.
The aws:elasticbeanstalk:command Namespace
You can also use the configuration options (p. 145) in the aws:elasticbeanstalk:command (p. 172)
namespace to configure rolling deployments.
Use the DeploymentPolicy option to set the deployment type. The following values are supported:
• AllAtOnce disables rolling deployments and always deploy to all instances simultaneously.
• Rolling enables standard rolling deployments.
• RollingWithAdditionalBatch launches an extra batch of instances prior to starting the deployment to
maintain full capacity.
• Immutable performs an immutable update (p. 120) for every deployment.
When you enable rolling deployments, set the BatchSize and BatchSizeType options to configure the
size of each batch. For example, to deploy 25% 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
API Version 2010-12-01
112
AWS Elastic Beanstalk Developer Guide
Blue/Green Deployments
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 prior to 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"
EB CLI and Elastic Beanstalk console apply recommended values for the preceding options.
These settings must be removed if you want to use configuration files to configure the same. See
Recommended Values (p. 195) for details.
Blue/Green Deployments with AWS Elastic Beanstalk
Because Elastic Beanstalk performs an in-place update when you update your application versions,
your application may become unavailable to users for a short period of time. It is possible to avoid this
downtime by performing a blue/green deployment, where you deploy the new version to a separate
environment, and then swap CNAMEs of the two environments to redirect traffic to the new version
instantly.
Blue/green deployments require that your environment runs independently of your production database,
if your application uses one. If your environment has an Amazon RDS DB instance attached to it, the
data will not transfer over to your second environment, and will be lost if you terminate the original
environment.
For details on configuring your application to connect to an external (not managed by Elastic Beanstalk)
Amazon RDS instance, see Using Elastic Beanstalk with Amazon RDS (p. 398).
To perform a blue/green deployment
1.
Open the Elastic Beanstalk console.
2.
Clone your current environment (p. 96), or launch a new environment running the desired
configuration.
3.
Deploy the new application version (p. 115) to the new environment.
4.
Test the new version on the new environment.
5.
From the new environment's dashboard, choose Actions and then choose Swap Environment URLs.
API Version 2010-12-01
113
AWS Elastic Beanstalk Developer Guide
Blue/Green Deployments
6.
From the Environment name drop-down list, select the current environment.
7.
Choose Swap.
8.
Elastic Beanstalk swaps the CNAME records of the old and new environment, redirecting traffic from
the old version to the new version and vice-versa.
API Version 2010-12-01
114
AWS Elastic Beanstalk Developer Guide
Deploying a New Application 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 have been propagated and your old DNS records expire. DNS servers do not necessarily
clear old records from their cache based on the time to live (TTL) you set on your DNS records.
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.
2.
Navigate to the management page (p. 61) for your environment.
3.
Choose Upload and Deploy,
4.
Choose Browse to select the application source bundle for the application version you want to
deploy.
API Version 2010-12-01
115
AWS Elastic Beanstalk Developer Guide
Redeploying a Previous Version
5.
For Version label, type a unique version label to represent the new application version.
6.
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.
2.
Choose Actions next to the application name and then choose View application versions.
3.
Select the application version that you want to deploy, and then click Deploy.
4.
Choose an environment and then choose Deploy.
Configuration Changes
When you modify configuration option settings in the Configuration section of the environment
management console (p. 61), AWS Elastic Beanstalk propagates the change to all affected resources.
These resources include the load balancer that distributes traffic to the EC2 instances running your
application, the Auto Scaling group that manages those instances, and the EC2 instances themselves.
API Version 2010-12-01
116
AWS Elastic Beanstalk Developer Guide
Rolling Updates
Many configuration changes can be applied to a running environment without replacing existing
instances. For example, setting a health check URL (p. 255) 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 (p. 162) or VPC settings (p. 170) 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 environment must be terminated and
replaced. To prevent downtime during these processes, Elastic Beanstalk applies these configuration
changes in batches, keeping a minimum number of instances running and serving traffic at all times. This
process is called a rolling update (p. 117).
Immutable updates (p. 120) are an alternative to rolling updates where a temporary Auto Scaling
group is launched outside of your environment with a separate set of instances running on the new
configuration, which are placed behind your environment's load balancer. Old and new instances both
serve traffic until the new instances pass health checks, at which time the new instances are moved into
your environment's Auto Scaling group and the temporary group and old instances are terminated.
Supported Update Types
Rolling Update Setting
Load Balanced
Environments
Single Instance
Environments
Windows Server
Environments
Disabled
✓
✓
✓
Rolling Based on Health
✓
☓
✓
Rolling Based on Time
✓
☓
✓
Immutable
✓
✓
☓
Topics
• Elastic Beanstalk Rolling Environment Configuration Updates (p. 117)
• Immutable Environment Updates (p. 120)
• Tagging Your Elastic Beanstalk Environment's Resources (p. 122)
Elastic Beanstalk Rolling Environment Configuration
Updates
When a configuration change requires instances to be replaced (p. 116), 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 bootsrap 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 (p. 303), a batch is considered healthy as
soon as all instances in it pass ELB health checks.
API Version 2010-12-01
117
AWS Elastic Beanstalk Developer Guide
Rolling Updates
With enhanced health reporting (p. 306), 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 only check 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 does not become healthy within the rolling update timeout (default is 30 minutes), the
update is cancelled. Rolling update timeout is a configuration option (p. 145) that is available
in the aws:autoscaling:updatepolicy:rollingupdate (p. 119) namespace. If your application
does not pass health checks with Ok status but is stable at a different level, you can set the
HealthCheckSuccessThreshold option in the aws:elasticbeanstalk:command namespace (p. 172) 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 rollback to the
previous configuration. A rolling update can fail due to failed health checks or if launching new instances
causes you to exceed the limits on your account. If you hit a limit on the number of 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
AWS Elastic Beanstalk (p. 113) for more information.
Rolling Updates vs Rolling Deployments
Rolling updates occur when you change settings that require new 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 prior to a new batch being provisioned to replace it.
Rolling deployments (p. 110) 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 (p. 162) settings in a
configuration file (p. 197) 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. A separate deployment does not occur in
this case because the new instances are brought up with the new application version.
Any time that 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 (p. 110) (Ignore health check, Healthy threshold and Command timeout) also apply to
health based rolling udates and immutable updates during the deployment phase.
Configuring Rolling Updates
You can enable and configure rolling updates in the Elastic Beanstalk Management Console.
API Version 2010-12-01
118
AWS Elastic Beanstalk Developer Guide
Rolling Updates
To enable rolling updates
1.
2.
3.
4.
Open the Elastic Beanstalk console.
Navigate to the management page (p. 61) for your environment.
Choose Configuration.
5.
In the Updates and Deployments section, choose
.
In the Configuration Updates section, select Rolling configuration updates.
6.
7.
Choose an Update type and batch settings.
Choose Apply.
The Configuration Updates section of the Updates and Deployments page has the following options for
rolling updates:
• Update type – Choose from the following options: 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.
• 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 (p. 120).
• Maximum 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 autoscaling group, rounded up.
• Minimum instances in service – The minimum number of instances to keep running while other
instances are being updated, between 0 and 9999. The default value is either the minimum size of the
autoscaling group or one less than the maximum size of the autoscaling 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 to 1 hour.
The aws:autoscaling:updatepolicy:rollingupdate namespace
You can also use the configuration options (p. 145) in the
aws:autoscaling:updatepolicy:rollingupdate (p. 168) 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:
API Version 2010-12-01
119
AWS Elastic Beanstalk Developer Guide
Immutable Updates
• 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 (p. 120).
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: PT#H#M#S, where each # is the
number of hours, minutes, and/or seconds, respectively.
EB CLI and Elastic Beanstalk console apply recommended values for the preceding options.
These settings must be removed if you want to use configuration files to configure the same. See
Recommended Values (p. 195) for details.
Immutable Environment Updates
Immutable environment updates are an alternative to rolling updates (p. 117) that 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.
API Version 2010-12-01
120
AWS Elastic Beanstalk Developer Guide
Immutable Updates
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 instances with a low on-demand limit, ensure that you have enough capacity to perform an
immutable environment update. If you are near the limit, consider using rolling updates instead.
Immutable updates require enhanced health reporting (p. 306) 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 (p. 308).
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 (p. 110), 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.
If an immutable update fails, the new instances upload bundle logs (p. 336) 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, 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 (p. 116) 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 (p. 113) instead.
Configuring Immutable Updates
You can enable and configure immutable updates in the Elastic Beanstalk Management Console.
To enable immutable updates (console)
1.
Open the Elastic Beanstalk console.
2.
Navigate to the management page (p. 61) for your environment.
3.
Choose Configuration.
4.
5.
In the Updates and Deployments section, choose
.
In the Configuration Updates section, set Rolling update type to Immutable.
API Version 2010-12-01
121
AWS Elastic Beanstalk Developer Guide
Tag an Environment
6.
Choose Apply.
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 (p. 197) 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
EB CLI and Elastic Beanstalk console apply recommended values for the preceding options.
These settings must be removed if you want to use configuration files to configure the same. See
Recommended Values (p. 195) for details.
Tagging Your Elastic Beanstalk Environment's
Resources
When you create an Elastic Beanstalk environment, you can specify tags to apply to resources in the
environment. Tags can help you identify environments in cost allocation reports, especially if you have
many to manage. You can also use tags to manage permissions at the resource level.
Elastic Beanstalk applies three tags by default. elasticbeanstalk:environment-name is the name of the
environment. elasticbeanstalk:environment-id is the environment ID. Name is also the name of the
environment. Name is used in the EC2 dashboard to identify and sort resources.
You can add an additional 47 tags during environment creation. Specify tags on the Environment Tags
page of the create environment wizard (p. 68):
API Version 2010-12-01
122
AWS Elastic Beanstalk Developer Guide
Platform Updates
Constraints
• Key-value pairs must be separated by commas.
• Keys and values can contain any alphabetic character in any language, any numeric character, white
space, invisible separator, and the following symbols: _ . : / + - @
• Keys can contain up to 128 characters. Values can contain up to 256 characters.
• Keys and values are case sensitive.
• Values cannot match the environment name.
• Values cannot include either aws: or elasticbeanstalk:.
If you use the EB CLI to create environments, use the --tags option with eb create (p. 474) to add
tags:
~/workspace/my-app$ eb create --tags mytag1=value1,mytag2=value2
With the AWS CLI or other API-based clients, use the --tags parameter on the create-environment
command:
$ aws elasticbeanstalk create-environment --tags Key=mytag1,Value=value1
Key=mytag2,Value=value2 --application-name my-app --environment-name my-env --cname-prefix
my-app --version-label v1 --template-name my-saved-config
Saved configurations (p. 147) include user-defined tags. When you apply a saved configuration that
contains tags during environment creation, those tags will be applied to the new environment, as long as
you don't specify any new tags. If you add tags to an environment using one of the preceding methods,
any tags defined in the saved configuration will be discarded.
You can use cost allocation reports to track your usage of AWS resources. The reports include both
tagged and untagged resources, but they aggregate costs according to tags. For information about how
cost allocation reports use tags, see Use Cost Allocation Tags for Custom Billing Reports in the AWS
Billing and Cost Management User Guide.
Updating Your Elastic Beanstalk Environment's
Platform Version
Elastic Beanstalk regularly releases updates for the Linux and Windows Server based platforms (p. 25)
that run applications on an Elastic Beanstalk environment. A platform consists of a software component
API Version 2010-12-01
123
AWS Elastic Beanstalk Developer Guide
Platform Updates
(an AMI running a specific version of an OS, tools, and Elastic Beanstalk-specific scripts), and a
configuration component (the default settings (p. 145) applied to environments created with the
platform). New platform versions provide updates to existing software components and support for new
features and configuration options.
For platforms which support multiple incompatible major versions of the included web container,
programming language, or framework, a separate configuration of the platform is provided for each. For
example, the Java with Tomcat (p. 626) platform supports separate configurations for Tomcat 7 and
Tomcat 8. Each configuration of a platform is versioned separately, but updates are generally released
for all configurations of a given platform at the same time.
When a new version of your environment's platform configuration is available, Elastic Beanstalk shows a
message in the environment management console (p. 61) and makes the Change button available. If
you've previously created an environment using an older version of the same configuration, or upgraded
your environment from an older configuration, you can also use the Change button to revert to a
previous configuration version.
To update your environment's platform
1.
Navigate to the management page (p. 61) for your environment.
2.
In the Overview section, under Configuration, click Change.
3.
Choose a Platform Version. The newest platform version is selected automatically, but you can
update to any version that you have used in the past if you choose.
API Version 2010-12-01
124
AWS Elastic Beanstalk Developer Guide
Managed Updates
4.
Choose Save.
Configurations are specific to major language and tool versions. When a configuration is updated, the
language and tools will not change major versions. For example, Java 7 with Tomcat 7 and Java 8 with
Tomcat 8 are two different configurations of the Java with Tomcat platform. You cannot perform a
platform update between configurations, only between versions of the same configuration, such as Java
8 with Tomcat 8 version 1.4.5 and Java 8 with Tomcat 8 version 2.0.0.
Linux-based Elastic Beanstalk platforms are semantically versioned with three numbers, major, minor,
and patch. For example, Java 8 with Tomcat 8 version 2.1.0 has a major version of 2, a minor version of
1, and a patch version of 0. Major versions are only used for backwards incompatible changes. Minor
versions add support for new Elastic Beanstalk features, and patch versions fix bugs, update OS and
software components, and provide access to updated packages in the Amazon Linux yum repository.
You can configure your environment to apply minor and patch version updates automatically during
a configurable weekly maintenance window with Managed Platform Updates (p. 125). 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.
Windows Server-based platforms are not semantically versioned and do not support managed platform
updates. You can only launch the latest version of each Windows Server platform configuration and
cannot roll back after an upgrade.
Managed Platform Updates
Elastic Beanstalk regularly releases platform updates (p. 123) 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 (p. 127). 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 is not available for the .NET on Windows Server platform.
API Version 2010-12-01
125
AWS Elastic Beanstalk Developer Guide
Managed Updates
You can configure your environment to automatically apply patch version updates (p. 127), or both
patch and minor version updates. Managed platform updates don't support major version updates,
which may introduce changes that are backwards incompatible.
When you enable managed platform updates, you can also configure AWS 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.
Use the Elastic Beanstalk environment management console to enable managed platform updates.
To enable managed platform updates
1.
Open the Elastic Beanstalk console.
2.
Navigate to the management page (p. 61) for your environment.
3.
Choose Configuration.
4.
Choose Managed Updates.
5.
Select Enable managed updates.
6.
Choose a maintenance window and then choose Update level.
7.
(optional) Select Instance replacement to enable weekly instance replacement.
8.
Choose Apply.
Managed platform updates depend on enhanced health reporting (p. 306) to determine that your
application is healthy enough to consider the platform update successful. See Enabling AWS Elastic
Beanstalk Enhanced Health Reporting (p. 311) for instructions.
Sections
• Permissions Required to Perform Managed Platform Updates (p. 127)
• The Managed Update Maintenance Window (p. 127)
• Minor and Patch Version Updates (p. 127)
• Immutable Environment Updates (p. 127)
• Managing Managed Updates (p. 127)
• Managed Action Option Namespaces (p. 129)
API Version 2010-12-01
126
AWS Elastic Beanstalk Developer Guide
Managed Updates
Permissions Required to Perform Managed Platform Updates
Elastic Beanstalk needs permission to initiate a platform update on your behalf. If you use the default
service role (p. 18), the console adds the required permissions when you enable managed platform
updates. If you don't use the default service role or manage your environments with a different client,
add the AWSElasticBeanstalkService managed profile to your service role (p. 361).
Note
If you use configuration files (p. 197) to extend your environment to include additional
resources, you might need to add additional permissions to your environment's service role.
Typically you need to add additional 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 (p. 127) page.
The Managed Update Maintenance Window
When AWS releases a new version of your environment's platform configuration, 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, but the update might not complete until after the windows ends.
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 backwards 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 (p. 120) 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, prior to confirming that instances running
the new configuration 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 configuration.
Managed platform updates always perform immutable updates, even when you apply them outside
of the maintenance window. If you change the platform configuration from the Dashboard, Elastic
Beanstalk applies the update policy that you've chosen for configuration updates.
Managing Managed Updates
The Elastic Beanstalk environment management console shows detailed information about managed
updates on the Managed Updates page.
To view information about managed updates (console)
1.
Open the Elastic Beanstalk console.
API Version 2010-12-01
127
AWS Elastic Beanstalk Developer Guide
Managed Updates
2.
Navigate to the management page (p. 61) for your environment.
3.
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.
2.
Navigate to the management page (p. 61) for your environment.
3.
Choose Managed Updates.
4.
Choose Apply now.
5.
Choose Apply.
API Version 2010-12-01
128
AWS Elastic Beanstalk Developer Guide
Upgrade a Legacy Environment
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 (p. 62),
or by using a different client, Elastic Beanstalk uses the update type that you have selected for
configuration changes (p. 116).
If you don't have a managed update scheduled, your environment may already be running the latest
version. Other reasons for not having an update scheduled include:
• a minor version (p. 127) 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 goes into
pending status prior to execution.
Managed Action Option Namespaces
You can use configuration options (p. 145) in the aws:elasticbeanstalk:managedactions (p. 176)
and aws:elasticbeanstalk:managedactions:platformupdate (p. 176) 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 (p. 197) enables managed platform updates for patch version
updates with a maintenance window starting at 10:00 AM UTC each Tuesday:
Example .ebextensions/managed-platform-update.config
option_settings:
aws:elasticbeanstalk:managedactions:
ManagedActionsEnabled: true
PreferredStartTime: "Tue:10:00"
aws:elasticbeanstalk:managedactions:platformupdate:
UpdateLevel: patch
InstanceRefreshEnabled: true
Migrating Your Application from a Legacy Container
Type
If you have deployed an Elastic Beanstalk application that uses a legacy container type, you should
migrate your application to a new environment using a non-legacy container type so that you can
API Version 2010-12-01
129
AWS Elastic Beanstalk Developer Guide
Upgrade a Legacy Environment
get access to new features. If you are unsure whether you are running your application using a legacy
container type, you can check in the Elastic Beanstalk console. For instructions, see To check if you are
using a legacy container type (p. 130).
What new features are legacy containers missing?
Legacy platforms do not support the following features:
• Configuration files, as described in the Advanced Environment Customization with Configuration Files
(.ebextensions) (p. 197) topic
• ELB health checks, as described in the Basic Health Reporting (p. 303) topic
• Instance Profiles, as described in the Managing Elastic Beanstalk Instance Profiles (p. 354) topic
• VPCs, as described in the Using Elastic Beanstalk with Amazon VPC (p. 408) topic
• Data Tiers, as described in the Configuring Databases with Elastic Beanstalk (p. 260) topic
• Worker Tiers, as described in the Architectural Overview (p. 15) topic
• Single Instance Environments, as described in the Environment Types (p. 134) topic
• Tags, as described in the Tagging Your Elastic Beanstalk Environment's Resources (p. 122) topic
• Rolling Updates, as described in the Elastic Beanstalk Rolling Environment Configuration
Updates (p. 117) topic
Why are some container types marked legacy?
Some older platform configurations do not support the latest Elastic Beanstalk features. These
configurations are marked (legacy) on the environment configuration page in the AWS Management
Console.
To check if you are using a legacy container type
1.
Open the Elastic Beanstalk console.
2.
From the Elastic Beanstalk console applications page, click the environment that you want to verify.
3.
In the Overview section of the environment dashboard, view the Configuration name.
Your application is using a legacy container type if you see (legacy) next to the configuration.
To migrate your application
1.
Deploy your application to a new environment. For instructions, go to Creating an AWS Elastic
Beanstalk Environment (p. 68).
2.
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
API Version 2010-12-01
130
AWS Elastic Beanstalk Developer Guide
Cancel an Update
EC2 security group using the AWS Management Console, see Security Groups (p. 248). 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 in the Amazon Relational
Database Service User Guide.
3.
Swap your environment URL. For instructions, go to Blue/Green Deployments with AWS Elastic
Beanstalk (p. 113).
4.
Terminate your old environment. For instructions, go to Terminate an Environment (p. 98).
Note
If you use AWS Identity and Access Management (IAM) then you will need to update your
policies to include AWS CloudFormation and Amazon RDS (if applicable). For more information,
see Using Elastic Beanstalk with AWS Identity and Access Management (p. 353).
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 (p. 117). For more information about batched application version deployments, see
Deployment Policies and Settings (p. 110).
To cancel an update
•
On the environment dashboard, click Actions, and then click Abort Current Operation.
API Version 2010-12-01
131
AWS Elastic Beanstalk Developer Guide
Rebuild an Environment
Rebuilding AWS Elastic Beanstalk Environments
Your 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.
To rebuild a running environment (console)
1.
Open the Elastic Beanstalk console.
2.
3.
4.
Navigate to the management page (p. 61) for your environment.
Choose Actions, and then choose Rebuild environment.
Choose Rebuild.
Rebuilding a running environment creates new resources that have the same configuration as the old
resources; however, the resource IDs are different, and any data on the old resources is not restored. For
example, rebuilding an environment with an Amazon RDS database instance creates a new database with
the same configuration, but does not apply a snapshot to the new database.
To rebuild a running environment with the Elastic Beanstalk API, use the RebuildEnvironment 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
API Version 2010-12-01
132
AWS Elastic Beanstalk Developer Guide
Rebuilding a Terminated Environment
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 (p. 268) 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 (p. 61), and use the Restore environment
action (p. 63) 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.
2.
3.
Choose your application.
Choose Actions, and then choose Restore terminated environment.
4.
5.
Choose a terminated environment.
Choose Restore.
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
API Version 2010-12-01
133
AWS Elastic Beanstalk Developer Guide
Environment Types
See eb restore (p. 498) for more information.
To rebuild a terminated environment with the Elastic Beanstalk API, use the RebuildEnvironment action
with the AWS CLI or the AWS SDK.
$ aws elasticbeanstalk rebuild-environment --environment-id e-vdnftxubwq
Environment Types
In Elastic Beanstalk, you can create a load-balancing, autoscaling 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-balancing, autoscaling environment when the application is
ready for production.
Note
A worker environment tier for a web application that processes background tasks does not
include a load balancer. However, a worker environment does effectively scale out by adding
instances to the autoscaling group to process data from the Amazon SQS queue when the load
necessitates it.
Load-balancing, Autoscaling Environment
A load-balancing and autoscaling environment uses the Elastic Load Balancing and Auto Scaling services
to provision the Amazon EC2 instances that are required for your deployed application. Auto Scaling
automatically starts additional instances to accommodate increasing load on your application. If the load
on your application decreases, 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-balancing, autoscaling 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 singleinstance environment doesn't have a load balancer, which can help you reduce costs compared to a loadbalancing, autoscaling environment. Although a single-instance environment does use the 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 (p. 134).
Changing Environment Type
You can change your environment type to a single-instance or load-balancing, autoscaling 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 in order to save costs. When your application is ready for production, you
can change the environment type to a load-balancing, autoscaling environment so that it can scale to
meet the demands of your customers.
API Version 2010-12-01
134
AWS Elastic Beanstalk Developer Guide
Changing Environment Type
To change an environment's type
1.
Open the Elastic Beanstalk console.
2.
Navigate to the management page (p. 61) for your environment.
3.
Choose Configuration.
4.
Click
for the Scaling settings.
5.
In the Environment Type section, select the type of environment that you want.
6.
If your environment is in a VPC, select subnets to place ELB and EC2 instances in. Each availability
zone that your application runs in must have both. See Using Elastic Beanstalk with Amazon
VPC (p. 408) for details.
API Version 2010-12-01
135
AWS Elastic Beanstalk Developer Guide
Worker Environments
7.
Click Save.
Note that it can take several minutes for the environment to update while Elastic Beanstalk
provisions AWS resources.
Worker Environments
If your 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 may only
take 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 500ms.
One option is to spawn a worker process locally, return success, and process the task asynchronously.
This works, as long as 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 queue, and run the process that performs them on a
separate set of instances. The worker instances only take items from the queue when they have capacity
to run them, preventing them from becoming overwhelmed.
Elastic Beanstalk simplifies this process by managing the Amazon SQS queue and running a daemon
process (p. 137) 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/ 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 (p. 140) to post to a different path, use a MIME
type other than application/JSON, connect to an existing queue, or customize connections, timeouts,
and retries.
API Version 2010-12-01
136
AWS Elastic Beanstalk Developer Guide
The Worker Environment SQS Daemon
With periodic tasks (p. 139), you can also configure the worker daemon to queue messages based on
a cron schedule. Each periodic tasks 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.
Sections
• The Worker Environment SQS Daemon (p. 137)
• Dead Letter Queues (p. 139)
• Periodic Tasks (p. 139)
• Use Amazon CloudWatch for Auto Scaling in Worker Environment Tiers (p. 140)
• Configuring Worker Environments (p. 140)
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 (p. 25).
Feature
Release Date
Description
Enhanced Health
Reporting (p. 306)
August 11, 2015
Monitor environment health
with more detail and accuracy.
Periodic Tasks (p. 139)
February 17, 2015
Run cron jobs that you configure
in a cron.yaml file in your
application source code.
API Version 2010-12-01
137
AWS Elastic Beanstalk Developer Guide
The Worker Environment SQS Daemon
Feature
Release Date
Description
Dead Letter Queues (p. 139)
May 27, 2014
Send failed jobs to a dead letter
queue for troubleshooting.
Changed the default visibility
timeout from 30 seconds to 300
seconds.
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 SQS
queue so that the message will be deleted from the queue. If the application returns any response other
than 200 OK, then Elastic Beanstalk waits to put the message back in the queue after the configured
ErrorVisibilityTimeout period. If there is no response, then 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 in the Amazon Simple Queue Service
Developer Guide.
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.11
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-FirstReceived-At
UTC time, in ISO 8601 format, when the message was first received.
X-Aws-Sqsd-ReceiveCount
SQS message receive count
X-Aws-SqsdAttr-message-
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.
attribute-name
Content-Type
Mime type configuration; by default, application/json
API Version 2010-12-01
138
AWS Elastic Beanstalk Developer Guide
Dead Letter Queues
Dead Letter Queues
Elastic Beanstalk worker environments support Amazon Simple Queue Service (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.
A dead letter queue is enabled by default for a worker environment if you specify an autogenerated
Amazon SQS queue at the time you create your worker environment tier. 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.
You cannot disable dead letter queues. Messages that cannot be delivered will always eventually be
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.
Note
The Elastic Beanstalk MaxRetries option is equivalent to the SQS MaxReceiveCount option. If
your worker environment does not 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.
For more information about the lifecycle of an SQS message, go to Message Lifecycle.
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, one that runs every 12 hours and a
second that runs at 11pm 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 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.
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 a 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.
API Version 2010-12-01
139
AWS Elastic Beanstalk Developer Guide
Use Amazon CloudWatch for Auto
Scaling in Worker Environment Tiers
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-SqsdScheduled-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 Auto Scaling in Worker
Environment Tiers
Together, Auto Scaling and CloudWatch monitor the CPU utilization of the running instances in the
worker environment. How you configure the autoscaling limit for CPU capacity determines how many
instances the autoscaling group runs to appropriately manage the throughput of messages in the SQS
queue. Each EC2 instance publishes its CPU utilization metrics to CloudWatch. 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 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 AWS Management Console, CLI, or
the options file. For more information, go to Using Elastic Beanstalk with Amazon CloudWatch (p. 345)
and Use Auto Scaling Policies and Amazon CloudWatch Alarms for Dynamic Scaling.
Configuring Worker Environments
You can manage a worker environment's configuration by editing Worker Configuration on the
Configuration page in the environment management console (p. 61).
API Version 2010-12-01
140
AWS Elastic Beanstalk Developer Guide
Configuring Worker Environments
To configure the worker daemon
1.
Open the Elastic Beanstalk console.
2.
Navigate to the management page (p. 61) for your environment.
3.
Choose Configuration.
4.
Choose Worker Configuration.
The Worker Details page has the following options:
• Worker queue – Specify the Amazon SQS queue from which the daemon reads. You can choose an
existing queue, if you have one. If you choose Autogenerated queue, Elastic Beanstalk creates a new
Amazon SQS queue and a corresponding Worker queue URL.
• Worker queue URL – If you choose an existing Worker queue, then this setting displays the URL
associated with that Amazon SQS queue.
• 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.
• 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. The default value is
10. You can specify a value between 1 and 1000.
• HTTP connections – Specify the maximum number of concurrent connections that the daemon can
make to any application(s) within an Amazon EC2 instance. The default is 50. You can specify a value
between 1 and 100.
API Version 2010-12-01
141
AWS Elastic Beanstalk Developer Guide
Environment Links
• 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 a value between 1 and 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 a value between 1 and 36000
seconds.
• 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 a value between 0 and 43200.
• Retention period – Indicate the amount of time, in seconds, a message is valid and will be actively
processed. The default value is 345600. You can specify a value between 60 and 1209600.
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, then Amazon SQS will delete 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, then the daemon will delete 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 AWS 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. This allows you to manage and scale each
component independently providing you with greater agility. One of the challenges of this approach is
the requirement for sharing connection information between components. This can be solved with AWS
Elastic Beanstalk environment links.
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.
API Version 2010-12-01
142
AWS Elastic Beanstalk Developer Guide
Environment Links
Define links to other environments in an environment manifest (p. 237), 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 Using Elastic Beanstalk Saved
Configurations (p. 234) 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="my-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
API Version 2010-12-01
143
AWS Elastic Beanstalk Developer Guide
AWS Elastic Beanstalk Environment
Configuration
When you create an AWS Elastic Beanstalk environment, Elastic Beanstalk provisions and configures
all of the AWS resources required to run and support your application. In addition to configuring your
environment's metadata and update behavior, you can customize these resources by providing values for
configuration options (p. 145). For example, you may want to add an Amazon SQS queue and an alarm
on queue depth, or you might want to add an Amazon ElastiCache cluster.
Most of the configuration options have default values that are applied automatically by Elastic
Beanstalk. You can override these defaults with configuration files, saved configurations, command line
options, or by directly calling the Elastic Beanstalk API. The EB CLI and Elastic Beanstalk console also
apply recommended values for some options.
You can easily customize your environment at the same time that you deploy your application version by
including a configuration file with your source bundle. When customizing the software on your instance,
it is more advantageous to use a configuration file than to create a custom AMI because you do not need
to maintain a set of AMIs.
When deploying your applications, you may want to customize and configure the software that your
application depends on. These files could be either dependencies required by the application—for
example, additional packages from the yum repository—or they could be configuration files such as a
replacement for httpd.conf to override specific settings that are defaulted by AWS Elastic Beanstalk.
Topics
• Configuration Options (p. 145)
• Advanced Environment Customization with Configuration Files (.ebextensions) (p. 197)
• Using Elastic Beanstalk Saved Configurations (p. 234)
• Environment Manifest (env.yaml) (p. 237)
• Configuring Auto Scaling with Elastic Beanstalk (p. 238)
• Configuring the EC2 Instances in your Elastic Beanstalk Environment (p. 247)
• Configuring the Load Balancer in your Elastic Beanstalk Environment (p. 252)
API Version 2010-12-01
144
AWS Elastic Beanstalk Developer Guide
Configuration Options
• Configuring Databases with Elastic Beanstalk (p. 260)
• Configuring AWS X-Ray Debugging (p. 262)
• Configuring VPC with Elastic Beanstalk (p. 264)
• Configuring CloudWatch Logs with Elastic Beanstalk (p. 265)
• Configuring Amazon SNS Notifications with Elastic Beanstalk (p. 266)
• Your Elastic Beanstalk Environment's Domain Name (p. 268)
• Configuring HTTPS for your Elastic Beanstalk Environment (p. 270)
Configuration Options
This section lists the namespaces, options and values that can be specified in configuration files
(.ebextensions (p. 197)), saved configurations, and option settings applied directly to an environment
when it is created or updated using the Elastic Beanstalk console, the EB CLI, the AWS CLI, or an SDK.
Configuration option settings can be composed in text format and saved prior to environment creation,
applied during environment creation using any supported client, and added, modified or removed
after environment creation. For a detailed breakdown of all of the available methods for working with
configuration options at each of these three stages, read the following topics:
• Setting Configuration Options Before Environment Creation (p. 145)
• Setting Configuration Options During Environment Creation (p. 149)
• Setting Configuration Options After Environment Creation (p. 154)
For a complete list of namespaces and options, including default and supported values for each, see
General Options for All Environments (p. 160) and Platform Specific Options (p. 187).
Topics
• Setting Configuration Options Before Environment Creation (p. 145)
• Setting Configuration Options During Environment Creation (p. 149)
• Setting Configuration Options After Environment Creation (p. 154)
• General Options for All Environments (p. 160)
• Platform Specific Options (p. 187)
• Custom Options (p. 194)
• Precedence (p. 194)
• Recommended Values (p. 195)
Setting Configuration Options Before Environment
Creation
AWS Elastic Beanstalk supports a large number of configuration options (p. 145) that let you modify
the settings that are applied to resources in your environment. Several of these options have default
values that can be overridden to customize your environment. Other options can be configured to enable
additional features.
Elastic Beanstalk supports two methods of saving configuration option settings. Configuration files
in YAML or JSON format can be included in your application's source code in a directory named
API Version 2010-12-01
145
AWS Elastic Beanstalk Developer Guide
Before Environment Creation
.ebextensions and deployed as part of your application source bundle. You create and manage
configuration files locally.
Saved configurations are templates that you create from a running environment or JSON options file
and store in Elastic Beanstalk. Existing saved configurations can also be extended to create a new
configuration.
Note
Settings defined in configuration files and saved configurations have lower precedence than
settings configured during or after environment creation, including recommended values
applied by the Elastic Beanstalk console and EB CLI (p. 434). See Precedence (p. 194) for
details.
Options can also be specified in a JSON document and provided directly to Elastic Beanstalk when
you create or update an environment with the EB CLI or AWS CLI. Options provided directly to Elastic
Beanstalk in this manner override all other methods.
For a full list of available options, see Configuration Options (p. 145).
Methods
• Configuration Files (.ebextensions) (p. 146)
• Saved Configurations (p. 147)
• JSON Document (p. 149)
• EB CLI Configuration (p. 149)
Configuration Files (.ebextensions)
Use .ebextensions to configure options that are required to make your application work, and provide
default values for other options that can be overridden at a higher level of precedence (p. 194).
Options specified in .ebextensions have the lowest level of precedence and are overridden by settings at
any other level.
To use configuration files, create a folder named .ebextensions at the top level of your project's source
code. Add a file with the extension .config and specify options in the following manner:
option_settings:
- namespace: namespace
option_name: option name
value: option value
- namespace: namespace
option_name: option name
value: option value
For example, the following configuration file sets the application's health check url to /health:
healthcheckurl.config
option_settings:
- namespace: aws:elasticbeanstalk:application
option_name: Application Healthcheck URL
value: /health
In JSON:
{
API Version 2010-12-01
146
AWS Elastic Beanstalk Developer Guide
Before Environment Creation
"option_settings" :
[
{
"namespace" : "aws:elasticbeanstalk:application",
"option_name" : "Application Healthcheck URL",
"value" : "/health"
}
]
}
This configures the Elastic Load Balancing load balancer in your Elastic Beanstalk environment to make
an HTTP request to the path /health to each EC2 instance to determine if it is healthy or not.
Note
YAML relies on consistent indentation. Match the indentation level when replacing content in an
example configuration file and make sure that your text editor uses spaces, not tab characters,
to indent.
Include the .ebextensions directory in your Application Source Bundle (p. 54) and deploy it to a new or
existing Elastic Beanstalk environment.
Configuration files support several sections in addition to option_settings for customizing the software
and files that run on the servers in your environment. For more information, see Customizing Software
on Linux Servers (p. 200) and Customizing Software on Windows Servers (p. 210).
Saved Configurations
Create a saved configuration to save settings that you have applied to an existing environment during
or after environment creation by using the AWS Management Console, EB CLI, or AWS CLI. Saved
configurations belong to an application and can be applied to new or existing environments for that
application.
Clients
• Elastic Beanstalk Console (p. 147)
• EB CLI (p. 147)
• AWS CLI (p. 148)
Elastic Beanstalk Console
To create a saved configuration (Elastic Beanstalk console)
1.
Open the Elastic Beanstalk console.
2.
Navigate to the management page (p. 61) for your environment.
3.
Click Actions and then click Save Configuration.
4.
Enter a configuration name and description and then click Save.
Saved configurations are stored in the Elastic Beanstalk S3 bucket in a folder named after your
application. For example, configurations for an application named my-app in the us-west-2 region for
account number 0123456789012 can be found at s3://elasticbeanstalk-us-west-2-0123456789012/
resources/templates/my-app.
EB CLI
The EB CLI (p. 434) also provides subcommands for interacting with saved configurations under eb
config (p. 471):
API Version 2010-12-01
147
AWS Elastic Beanstalk Developer Guide
Before Environment Creation
To create a saved configuration (EB CLI)
1.
Save the attached environment's current configuration:
~/project$ eb config save --cfg my-app-v1
The EB CLI saves the configuration to ~/project/.elasticbeanstalk/saved_configs/my-appv1.cfg.yml
2.
Modify the saved configuration locally if needed.
3.
Upload the saved configuration to S3:
~/project$ eb config put my-app-v1
AWS CLI
Create a saved configuration from a running environment with aws elasticbeanstalk createconfiguration-template
To create a saved configuration (AWS CLI)
1.
Identify your Elastic Beanstalk environment's environment ID with describe-environments:
$ aws elasticbeanstalk describe-environments --environment-name my-env
{
"Environments": [
{
"ApplicationName": "my-env",
"EnvironmentName": "my-env",
"VersionLabel": "89df",
"Status": "Ready",
"Description": "Environment created from the EB CLI using \"eb create\"",
"EnvironmentId": "e-vcghmm2zwk",
"EndpointURL": "awseb-e-v-AWSEBLoa-1JUM8159RA11M-43V6ZI1194.uswest-2.elb.amazonaws.com",
"SolutionStackName": "64bit Amazon Linux 2015.03 v2.0.2 running Multicontainer Docker 1.7.1 (Generic)",
"CNAME": "my-env-nfptuqaper.elasticbeanstalk.com",
"Health": "Green",
"AbortableOperationInProgress": false,
"Tier": {
"Version": " ",
"Type": "Standard",
"Name": "WebServer"
},
"HealthStatus": "Ok",
"DateUpdated": "2015-10-01T00:24:04.045Z",
"DateCreated": "2015-09-30T23:27:55.768Z"
}
]
}
2.
Save the environment's current configuration with create-configuration-template:
$ aws elasticbeanstalk create-configuration-template --environment-id e-vcghmm2zwk -application-name my-app --template-name v1
Elastic Beanstalk saves the configuration to your Elastic Beanstalk bucket in Amazon S3.
API Version 2010-12-01
148
AWS Elastic Beanstalk Developer Guide
During Creation
JSON Document
If you use the AWS CLI to create and update environments, you can also provide configuration options
in JSON format. A library of configuration files in JSON is useful if you use the AWS CLI to create and
manage environments.
For example, the following JSON document sets the application's health check url to /health:
~/ebconfigs/healthcheckurl.json
[
]
{
}
"Namespace": "aws:elasticbeanstalk:application",
"OptionName": "Application Healthcheck URL",
"Value": "/health"
EB CLI Configuration
In addition to supporting saved configurations and direct environment configuration with eb
config commands, the EB CLI has a configuration file with an option named default_ec2_keyname
that you can use to specify an Amazon EC2 key pair for SSH access to the instances in your
environment. The EB CLI uses this option to set the EC2KeyName configuration option in the
aws:autoscaling:launchconfiguration namespace.
~/workspace/my-app/.elasticbeanstalk/config.yml
branch-defaults:
master:
environment: my-env
develop:
environment: my-env-dev
deploy:
artifact: ROOT.war
global:
application_name: my-app
default_ec2_keyname: my-keypair
default_platform: Tomcat 8 Java 8
default_region: us-west-2
profile: null
sc: git
Setting Configuration Options During Environment
Creation
When you create an AWS Elastic Beanstalk environment by using the AWS Management Console, EB
CLI, AWS CLI, an SDK, or the Elastic Beanstalk API, you can provide values for configuration options to
customize your environment and the AWS resources that are launched within it.
For anything other than a one-off configuration change, you can store configuration files (p. 145)
locally, in your source bundle, or in Amazon S3.
This topic includes procedures for all of the methods of setting configuration options during
environment creation.
Clients
API Version 2010-12-01
149
AWS Elastic Beanstalk Developer Guide
During Creation
• In the AWS Management Console (p. 150)
• With the EB CLI (p. 151)
• With the AWS CLI (p. 152)
In the AWS Management Console
When you create an Elastic Beanstalk environment in the AWS Management Console, you can provide
configuration options using configuration files, saved configurations, and forms in the Create New
Environment wizard.
Methods
• Using Configuration Files (.ebextensions) (p. 150)
• Using a Saved Configuration (p. 150)
• Using the New Environment Wizard (p. 150)
Using Configuration Files (.ebextensions)
Include .config files in your application source bundle (p. 54) in a folder named .ebextensions.
~/workspace/my-app-v1.zip
|-- .ebextensions
|
|-- environmentvariables.config
|
`-- healthcheckurl.config
|-- index.php
`-- styles.css
Upload the source bundle to Elastic Beanstalk normally during environment creation (p. 68).
The Elastic Beanstalk console applies recommended values (p. 195) for some configuration options and
has form fields for others. Options configured by the Elastic Beanstalk console are applied directly to the
environment and override settings in configuration files.
Using a Saved Configuration
When you create a new environment using the Elastic Beanstalk console, one of the first steps is to
choose a configuration. The configuration can be a Predefined configuration (p. 25), typically the latest
version of a platform such as PHP or Tomcat, or it can be a Saved configuration.
To apply a saved configuration during environment creation (AWS Management Console)
1.
2.
3.
Open the Elastic Beanstalk console.
Choose an application.
Choose Saved Configurations.
4.
5.
Choose an saved configuration and then choose Launch environment.
Proceed through the wizard to create your environment.
Saved configurations are application specific. See Saved Configurations (p. 147) for details on creating
saved configurations.
Using the New Environment Wizard
Most of the standard configuration options are presented on the Configuration Details and Permissions
pages of the wizard. If you create an Amazon RDS database or configure a VPC for your environment,
additional configuration options are available on the pages for those resources.
API Version 2010-12-01
150
AWS Elastic Beanstalk Developer Guide
During Creation
To set configuration options during environment creation (AWS Management Console)
1.
2.
3.
4.
Open the Elastic Beanstalk console.
Choose or create (p. 47) an application.
Choose Create New Environment.
Proceed through the wizard to the Configuration Details page.
5.
6.
Fill in the fields on this page to set the corresponding configuration options.
Proceed through the wizard to create your environment.
Any options that you set in the new environment wizard are set directly on the environment and override
any option settings in saved configurations or configuration files (.ebextensions) that you apply. You
can remove settings after the environment is created using the EB CLI (p. 156) or AWS CLI (p. 158) to
allow the settings in saved configurations or configuration files to surface.
With the EB CLI
Methods
• Using Configuration Files (.ebextensions) (p. 151)
• Using Saved Configurations (p. 151)
• Using Command Line Options (p. 152)
Using Configuration Files (.ebextensions)
Include .config files in your project folder under .ebextensions to deploy them with your application
code.
~/workspace/my-app/
|-- .ebextensions
|
|-- environmentvariables.config
|
`-- healthcheckurl.config
|-- .elasticbeanstalk
|
`-- config.yml
|-- index.php
`-- styles.css
Create your environment and deploy your source code to it with eb create:
~/workspace/my-app$ eb create my-env
Using Saved Configurations
To apply a saved configuration when you create an environment with eb create (p. 474), use the --cfg
option:
~/workspace/my-app$ eb create --cfg savedconfig
The saved configuration can be stored in your project folder or in your Elastic Beanstalk storage
location on Amazon S3. In the above example, the EB CLI first looks for a saved configuration file
named savedconfig.cfg.yml in the folder .elasticbeanstalk/saved_configs/. Do not include the file
extensions (.cfg.yml) when applying a saved configuration with --cfg.
~/workspace/my-app/
|-- .ebextensions
API Version 2010-12-01
151
AWS Elastic Beanstalk Developer Guide
During Creation
|
|-|
|
|
|-`--
`-- healthcheckurl.config
.elasticbeanstalk
|-- saved_configs
|
`-- savedconfig.cfg.yml
`-- config.yml
index.php
styles.css
If the EB CLI does not find the configuration locally, it looks in the Elastic Beanstalk storage location
in Amazon S3. For details on creating, editing and uploading saved configurations, see Saved
Configurations (p. 147).
Using Command Line Options
The EB CLI eb create command has several options (p. 474) that you can use to set configuration
options during environment creation. These options can be used to add an RDS database to your
environment, configure a VPC, or override recommended values (p. 195).
For example, the EB CLI will use the t2.micro instance type by default. To choose a different instance
type, use the --instance_type option:
$ eb create my-env --instance_type t2.medium
To create an Amazon RDS database instance and attach it to your environment, use the --database
options:
$ eb create --database.engine postgres --database.username dbuser
If you leave out the environment name, database password or any other parameters that are required to
create your environment, the EB CLI prompts you to enter them.
See eb create (p. 474) for a full list of available options and usage examples.
With the AWS CLI
When you use the create-environment command to create an Elastic Beanstalk environment with the
AWS CLI, the AWS CLI does not apply any recommended values (p. 195). All configuration options
defined in configuration files in the source bundle that you specify
Methods
• Using Configuration Files (.ebextensions) (p. 152)
• Using a Saved Configuration (p. 153)
• Using Command Line Options (p. 153)
Using Configuration Files (.ebextensions)
To apply configuration files to an environment that you create with the AWS CLI, include them in the
application source bundle that you upload to Amazon S3.
~/workspace/my-app-v1.zip
|-- .ebextensions
|
|-- environmentvariables.config
|
`-- healthcheckurl.config
|-- index.php
`-- styles.css
API Version 2010-12-01
152
AWS Elastic Beanstalk Developer Guide
During Creation
To upload an application source bundle and create an environment with the AWS CLI
1.
If you don't already have an Elastic Beanstalk bucket in Amazon S3, create one with createstorage-location:
$ aws elasticbeanstalk create-storage-location
{
"S3Bucket": "elasticbeanstalk-us-west-2-0123456789012"
}
2.
Upload your application source bundle to Amazon S3:
$ aws s3 cp sourcebundle.zip s3://elasticbeanstalk-us-west-2-0123456789012/my-app/
sourcebundle.zip
3.
Create the application version:
$ aws elasticbeanstalk create-application-version --application-name my-app -version-label v1 --description MyAppv1 --source-bundle S3Bucket="elasticbeanstalk-uswest-2-0123456789012",S3Key="my-app/sourcebundle.zip" --auto-create-application
4.
Create the environment:
$ aws elasticbeanstalk create-environment --application-name my-app --environment-name
my-env --version-label v1 --solution-stack-name "64bit Amazon Linux 2015.03 v2.0.0
running Tomcat 8 Java 8"
Using a Saved Configuration
To apply a saved configuration to an environment during creation, use the --template-name parameter:
$ aws elasticbeanstalk create-environment --application-name my-app --environment-name myenv --template-name savedconfig --version-label v1
When you specify a saved configuration, do not also specify a solution stack name. Saved configurations
already specify a solution stack and Elastic Beanstalk will return an error if you try to use both options.
Using Command Line Options
Use the --option-settings parameter to specify configuration options in JSON format:
$ aws elasticbeanstalk create-environment --application-name my-app --environment-name myenv --version-label v1 --template-name savedconfig --option-settings '[
{
"Namespace": "aws:elasticbeanstalk:application",
"OptionName": "Application Healthcheck URL",
"Value": "/health"
}
]
To load the JSON from a file, use the file:// prefix:
$ aws elasticbeanstalk create-environment --application-name my-app --environmentname my-env --version-label v1 --template-name savedconfig --option-settings file://
healthcheckurl.json
API Version 2010-12-01
153
AWS Elastic Beanstalk Developer Guide
After Creation
Elastic Beanstalk applies option settings that you specify with the --option-settings option directly
to your environment. If the same options are specified in a saved configuration or configuration file, -option-settings overrides those values.
Setting Configuration Options After Environment
Creation
You can modify the option settings on a running environment by applying saved configurations,
uploading a new source bundle with configuration files (.ebextensions), or a JSON document. The EB
CLI and Elastic Beanstalk console also have client specific functionality for setting and updating options
configuration options.
When you set or change a configuration option, you may trigger a full environment
update, depending on the severity of the change. For example, changes to options in the
aws:autoscaling:launchconfiguration (p. 162), such as InstanceType, require that the EC2
instances in your environment must be reprovisioned. This will trigger a rolling update (p. 117). Other
configuration changes can be applied without any interruption or reprovisioning.
You can remove option settings from an environment with EB CLI or AWS CLI commands. Removing an
option that has been set directly on an environment at an API level allows settings in configuration files,
which are otherwise masked by settings applied directly to an environment, to surface and take effect.
Settings in saved configurations and configuration files can be overridden by setting the same option
directly on the environment with one of the other configuration methods, but can only be removed
completely by applying an updated saved configuration or configuration file. When an option is not set
in a saved configuration, configuration file, or directly on an environment, the default value applies, if
there is one. See Precedence (p. 194) for details.
Clients
• The Elastic Beanstalk console (p. 154)
• The EB CLI (p. 156)
• The AWS CLI (p. 158)
The Elastic Beanstalk console
You can update configuration option settings in the AWS Management Console by deploying an
application source bundle that contains configuration files, applying a saved configuration, or modifying
the environment directly with the Configuration page in the environment management console.
Methods
• Using Configuration Files (.ebextensions) (p. 154)
• Using a Saved Configuration (p. 155)
• Using the Environment Management Console (p. 155)
Using Configuration Files (.ebextensions)
Update configuration files in your source directory, create a new source bundle, and deploy the new
version to your Elastic Beanstalk environment to apply the changes.
To deploy an updated source bundle to your environment (Elastic Beanstalk console)
1.
Open the Elastic Beanstalk console.
API Version 2010-12-01
154
AWS Elastic Beanstalk Developer Guide
After Creation
2.
Navigate to the management page (p. 61) for your environment.
3.
Choose Upload and Deploy
4.
Choose Browse and open the application source bundle.
5.
Choose Deploy.
Changes made to configuration files will not override option settings in saved configurations or settings
applied directly to the environment at the API level. See Precedence (p. 194) for details.
Using a Saved Configuration
Apply a saved configuration to a running environment to apply option settings that it defines.
To apply a saved configuration to a running environment (Elastic Beanstalk console)
1.
Open the Elastic Beanstalk console.
2.
Choose the name of your application.
3.
Choose Saved Configurations.
4.
Select the saved configuration and then choose Load.
5.
Select an environment and then choose Load.
Settings defined in a saved configuration override settings in configuration files, and are overridden by
settings configured using the environment management console.
See Saved Configurations (p. 147) for details on creating saved configurations.
Using the Environment Management Console
The Elastic Beanstalk console presents several configuration options on the Configuration page for each
environment.
Changing configuration options on a running environment (Elastic Beanstalk console)
1.
Open the Elastic Beanstalk console.
2.
Navigate to the management page (p. 61) for your environment.
3.
Choose Configuration
4.
5.
In the section that contains the option that you want to modify, choose
.
Modify settings and choose Apply.
Changes made to configuration options in the environment management console are applied directly to
the environment, overriding settings for the same options in configuration files or saved configurations.
See Precedence (p. 194) for details.
API Version 2010-12-01
155
AWS Elastic Beanstalk Developer Guide
After Creation
The EB CLI
You can update configuration option settings with the EB CLI by deploying source code that contains
configuration files, applying settings from a saved configuration, or modifying the environment
configuration directly with the eb config command.
Methods
• Using Configuration Files (.ebextensions) (p. 156)
• Using a Saved Configuration (p. 156)
• Using eb config (p. 156)
• Using eb setenv (p. 158)
Using Configuration Files (.ebextensions)
Include .config files in your project folder under .ebextensions to deploy them with your application
code.
~/workspace/my-app/
|-- .ebextensions
|
|-- environmentvariables.config
|
`-- healthcheckurl.config
|-- .elasticbeanstalk
|
`-- config.yml
|-- index.php
`-- styles.css
Deploy your source code with eb deploy:
~/workspace/my-app$ eb deploy
Using a Saved Configuration
You can use the eb config command to apply a saved configuration to a running environment. Use the
--cfg option with the name of the saved configuration to apply its settings to your environment:
$ eb config --cfg v1
In this example, v1 is the name of a previously created saved configuration file (p. 147).
Settings applied to an environment with this command override settings that were applied during
environment creation, and settings defined in configuration files in your application source bundle.
Using eb
config
The EB CLI's eb config command lets you set and remove option settings directly on an environment by
using a text editor.
When you run eb config, the EB CLI shows settings applied to your environment from all sources,
including configuration files, saved configurations, recommended values, options set directly on the
environment, and API defaults.
Note
eb config does not show environment properties. To set environment properties that you can
read from within your application, use eb setenv (p. 158)
API Version 2010-12-01
156
AWS Elastic Beanstalk Developer Guide
After Creation
The following example shows settings applied in the aws:autoscaling:launchconfiguration
namespace, including two recommended values (for IamInstanceProfile and InstanceType applied by
the EB CLI during environment creation, an option set directly on the environment during creation based
on repository configuration (EC2KeyName), and API defaults for the other values.
ApplicationName: tomcat
DateUpdated: 2015-09-30 22:51:07+00:00
EnvironmentName: tomcat
SolutionStackName: 64bit Amazon Linux 2015.03 v2.0.1 running Tomcat 8 Java 8
settings:
...
aws:autoscaling:launchconfiguration:
BlockDeviceMappings: null
EC2KeyName: my-key
IamInstanceProfile: aws-elasticbeanstalk-ec2-role
ImageId: ami-538a9563
InstanceType: t2.micro
...
To set or change configuration options with eb
1.
config
Run eb config to view your environment's configuration.
~/workspace/my-app/$ eb config
2.
Change any of the setting values using the default text editor
aws:autoscaling:launchconfiguration:
BlockDeviceMappings: null
EC2KeyName: my-key
IamInstanceProfile: aws-elasticbeanstalk-ec2-role
ImageId: ami-538a9563
InstanceType: t2.medium
3.
4.
Save the temporary configuration file and exit.
The EB CLI updates your environment configuration.
Setting configuration options with eb config overrides settings from all other sources.
You can also remove options from your environment with eb config.
To remove configuration options (EB CLI)
1.
Run eb config to view your environment's configuration.
~/workspace/my-app/$ eb config
2.
Replace any value shown with the string null. You can also delete the entire line containing the
option that you want to remove.
aws:autoscaling:launchconfiguration:
BlockDeviceMappings: null
EC2KeyName: my-key
IamInstanceProfile: aws-elasticbeanstalk-ec2-role
ImageId: ami-538a9563
InstanceType: null
3.
4.
Save the temporary configuration file and exit.
The EB CLI updates your environment configuration.
API Version 2010-12-01
157
AWS Elastic Beanstalk Developer Guide
After Creation
Removing options from your environment with eb config allows settings for the same options to
surface from configuration files in your application source bundle. See Precedence (p. 194) for details.
Using eb
setenv
To set environment properties with the EB CLI, use eb setenv:
~/workspace/my-app/$ eb setenv ENVVAR=TEST
INFO: Environment update is starting.
INFO: Updating environment my-env's configuration settings.
INFO: Environment health has transitioned from Ok to Info. Command is executing on all
instances.
INFO: Successfully deployed new configuration to environment.
This command sets environment properties in the aws:elasticbeanstalk:application:environment
namespace (p. 171). Environment properties set with eb setenv are available to your application after
a short update process.
View environment properties set on your environment with eb printenv:
~/workspace/my-app/$ eb printenv
Environment Variables:
ENVVAR = TEST
The AWS CLI
You can update configuration option settings with the AWS CLI by deploying a source bundle that
contains configuration files, applying a remotely stored saved configuration, or modifying the
environment directly with the aws elasticbeanstalk update-environment command.
Methods
• Using Configuration Files (.ebextensions) (p. 158)
• Using a Saved Configuration (p. 159)
• Using Command Line Options (p. 159)
Using Configuration Files (.ebextensions)
To apply configuration files to a running environment with the AWS CLI, include them in the application
source bundle that you upload to Amazon S3.
~/workspace/my-app-v1.zip
|-- .ebextensions
|
|-- environmentvariables.config
|
`-- healthcheckurl.config
|-- index.php
`-- styles.css
To upload an application source bundle and apply it to a running environment (AWS CLI)
1.
If you don't already have an Elastic Beanstalk bucket in Amazon S3, create one with createstorage-location:
$ aws elasticbeanstalk create-storage-location
{
"S3Bucket": "elasticbeanstalk-us-west-2-0123456789012"
API Version 2010-12-01
158
AWS Elastic Beanstalk Developer Guide
After Creation
}
2.
Upload your application source bundle to Amazon S3:
$ aws s3 cp sourcebundlev2.zip s3://elasticbeanstalk-us-west-2-0123456789012/my-app/
sourcebundlev2.zip
3.
Create the application version:
$ aws elasticbeanstalk create-application-version --application-name my-app -version-label v2 --description MyAppv2 --source-bundle S3Bucket="elasticbeanstalk-uswest-2-0123456789012",S3Key="my-app/sourcebundlev2.zip"
4.
Update the environment:
$ aws elasticbeanstalk update-environment --environment-name my-env --version-label v2
Using a Saved Configuration
You can apply a saved configuration to a running environment with the --template-name option on the
aws elasticbeanstalk update-environment command.
The saved configuration must be in your Elastic Beanstalk bucket in a path named after your application
under resources/templates. For example, the v1 template for the my-app application in the us-west-2
region for account 0123456789012 is located at s3://elasticbeanstalk-us-west-2-0123456789012/
resources/templates/my-app/v1
To apply a saved configuration to a running environment (AWS CLI)
•
Specify saved configuration in an update-environment call with the --template-name option.
$ aws elasticbeanstalk update-environment --environment-name my-env --template-name v1
Elastic Beanstalk places saved configurations in this location when you create them with aws
elasticbeanstalk create-configuration-template. You can also modify saved configurations locally
and place them in this location yourself.
Using Command Line Options
To change configuration options with a JSON document (AWS CLI)
1.
2.
Define your option settings in JSON format in a local file.
Run update-environment with the --option-settings option:
$ aws elasticbeanstalk update-environment --environment-name my-env --option-settings
file://~/ebconfigs/as-zero.json
In this example, as-zero.json defines options that configures the environment with a minimum and
maximum of zero instances. This stops the instances in the environment without terminating it:
~/ebconfigs/as-zero.json
[
{
API Version 2010-12-01
159
AWS Elastic Beanstalk Developer Guide
General Options
},
{
},
{
]
}
"Namespace": "aws:autoscaling:asg",
"OptionName": "MinSize",
"Value": "0"
"Namespace": "aws:autoscaling:asg",
"OptionName": "MaxSize",
"Value": "0"
"Namespace": "aws:autoscaling:updatepolicy:rollingupdate",
"OptionName": "RollingUpdateEnabled",
"Value": "false"
Note
Setting configuration options with update-environment overrides settings from all other
sources.
You can also remove options from your environment with update-environment.
To remove configuration options (AWS CLI)
•
Run update-environment command with the --settings-to-remove option:
$ aws elasticbeanstalk update-environment --environment-name my-env --options-to-remove
Namespace=aws:autoscaling:launchconfiguration,OptionName=InstanceType
Removing options from your environment with update-environment allows settings for the same options
to surface from configuration files in your application source bundle. If an option is not configured using
any of these methods, the API default value applies, if one exists. See Precedence (p. 194) for details.
General Options for All Environments
Namespaces
• aws:autoscaling:asg (p. 161)
• aws:autoscaling:launchconfiguration (p. 162)
• aws:autoscaling:scheduledaction (p. 166)
• aws:autoscaling:trigger (p. 167)
• aws:autoscaling:updatepolicy:rollingupdate (p. 168)
• aws:ec2:vpc (p. 170)
• aws:elasticbeanstalk:application (p. 171)
• aws:elasticbeanstalk:application:environment (p. 171)
• aws:elasticbeanstalk:cloudwatch:logs (p. 171)
• aws:elasticbeanstalk:command (p. 172)
• aws:elasticbeanstalk:environment (p. 173)
• aws:elasticbeanstalk:environment:process:default (p. 173)
• aws:elasticbeanstalk:environment:process:process_name (p. 174)
• aws:elasticbeanstalk:healthreporting:system (p. 175)
• aws:elasticbeanstalk:hostmanager (p. 176)
• aws:elasticbeanstalk:managedactions (p. 176)
API Version 2010-12-01
160
AWS Elastic Beanstalk Developer Guide
General Options
• aws:elasticbeanstalk:managedactions:platformupdate (p. 176)
• aws:elasticbeanstalk:monitoring (p. 177)
• aws:elasticbeanstalk:sns:topics (p. 177)
• aws:elasticbeanstalk:sqsd (p. 177)
• aws:elb:healthcheck (p. 179)
• aws:elb:loadbalancer (p. 179)
• aws:elb:listener (p. 180)
• aws:elb:listener:listener_port (p. 181)
• aws:elb:policies (p. 181)
• aws:elb:policies:policy_name (p. 182)
• aws:elbv2:listener:default (p. 183)
• aws:elbv2:listener:listener_port (p. 184)
• aws:elbv2:listenerrule:rule_name (p. 184)
• aws:elbv2:loadbalancer (p. 185)
• aws:rds:dbinstance (p. 186)
aws:autoscaling:asg
Configure your environment's Auto Scaling group.
Namespace: aws:autoscaling:asg
Name
Description
Default
Valid Values
Availability
Zones
Availability Zones (AZs) are distinct
locations within a region that are
engineered to be isolated from failures in
other AZs and provide inexpensive, lowlatency network connectivity to other AZs
in the same region. Choose the number
of AZs for your instances.
Any
Any
Cooldown
Cooldown periods help to prevent Auto
Scaling from initiating additional scaling
activities before the effects of previous
activities are visible.
360
0 to 10000
Custom
Availability
Zones
Define the AZs for your instances.
None
us-east-1a
Any 1
Any 2
Any 3
us-east-1b
us-east-1c
us-east-1d
us-east-1e
eu-central-1
MinSize
Minimum number of instances you want
in your Auto Scaling group.
1
1 to 10000
MaxSize
Maximum number of instances you want
in your Auto Scaling group.
4
1 to 10000
API Version 2010-12-01
161
AWS Elastic Beanstalk Developer Guide
General Options
aws:autoscaling:launchconfiguration
Configure your environment's EC2 instances.
Namespace: aws:autoscaling:launchconfiguration
Name
Description
Default
EC2KeyName
A key pair enables you to securely log
into your EC2 instance.
None
IamInstanceProfile
An instance profile enables AWS Identity
and Access Management (IAM) users
and AWS services to access temporary
security credentials to make AWS API
calls. Specify the profile name or the
ARN.
Valid Values
None
Example: ElasticBeanstalkProfile
Example:
arn:aws:iam::123456789012:instanceprofile/ElasticBeanstalkProfile
ImageId
You can override the default Amazon
Machine Image (AMI) by specifying your
own custom AMI ID.
None
Example: ami-cbab67a2
InstanceType
The instance type used to run your
application in an Elastic Beanstalk
environment.
t1.micro
The instance types available
depend on platform, solution stack
(configuration) and region. To get
a list of available instance types for
your solution stack of choice, use the
DescribeConfigurationOptions action in
the API, describe-configuration-options
command in the AWS CLI.
For example, the following command lists
the available instance types for version
1.4.3 of the PHP 5.6 stack in the current
region:
$ aws elasticbeanstalk describeconfiguration-options --options
Namespace=aws:autoscaling:launchconfiguration,OptionName=InstanceType
--solution-stack-name "64bit Amazon
Linux 2015.03 v1.4.3 running PHP
5.6"
MonitoringInterval
Interval at which you want Amazon
CloudWatch metrics returned.
API Version 2010-12-01
162
5 minute
1 minute
5 minute
AWS Elastic Beanstalk Developer Guide
General Options
Name
Description
Default
SecurityGroups Lists the Amazon EC2 security groups to
assign to the EC2 instances in the Auto
Scaling group in order to define firewall
rules for the instances.
You can provide a single string of commaseparated values that contain the name
of existing Amazon EC2 security groups
or references to AWS::EC2::SecurityGroup
resources created in the template. If you
use Amazon VPC with Elastic Beanstalk so
that your instances are launched within
a virtual private cloud (VPC), specify
security group IDs instead of a security
group name.
API Version 2010-12-01
163
elasticbeanstalkdefault
Valid Values
AWS Elastic Beanstalk Developer Guide
General Options
Name
Description
Default
Used to lock down SSH access to an
SSHSourceRestriction
environment. For instance, you can lock
down SSH access to the EC2 instances so
that only a bastion host can access the
instances in the private subnet.
This string takes the following form:
protocol, fromPort, toPort,
source_restriction
protocol
The protocol for the ingress rule.
fromPort
The starting port number.
toPort
The ending port number.
source_restriction
The CIDR range or the name of
a security group to allow traffic
from. To specify a security group
from another account (EC2-Classic
only, must be in the same region),
include the account ID prior to
the security group name (e.g.,
other_account_id/
security_group_name).
Example: tcp, 22, 22,
54.240.196.185/32
Example: tcp, 22, 22, my-securitygroup
Example (EC2-Classic): tcp, 22, 22,
0123456789012/their-security-group
API Version 2010-12-01
164
None
Valid Values
AWS Elastic Beanstalk Developer Guide
General Options
Name
Description
Default
BlockDeviceMappings
Attach additional Amazon EBS volumes
or instance store volumes on all of the
instances in the autoscaling group.
Valid Values
None
When you map instance store volumes
you only map the device name to a
volume name; when you map Amazon
EBS volumes, you can specify the
following fields, separated by a colon:
• snapshot ID
• size, in GB
• delete on terminate (true or false)
• storage type (gp2, standard, st1, sc1,
or io1)
• IOPS (only for io1 volumes).
The following example attaches three
Amazon EBS volumes, one blank 100GB
gp2 volume and one snapshot, one blank
20GB io1 volume with 2000 provisioned
IOPS, and an instance store volume
ephemeral0. Multiple instance store
volumes can be attached if the instance
type supports it.
/dev/sdj=:100:true:gp2,/
dev/sdh=snap-51eef269,/dev/
sdi=:20:true:io1:2000,/dev/
sdb=ephemeral0
RootVolumeType
Volume type (magnetic, general purpose
SSD or privisioned IOPS SSD) to use for
the root Amazon EBS volume attached to
your environment's EC2 instances.
Varies per platform.
standard for
magnetic storage
gp2 for general
purpose SSD
io1 for
provisioned IOPS
SSD
RootVolumeSizeStorage capacity of the root Amazon EBS
volume in whole GB.
Required if you set RootVolumeType to
provisioned IOPS SSD.
For example, "64".
API Version 2010-12-01
165
Varies per platform
for magnetic storage
and general purpose
SSD. None for
provisioned IOPS SSD.
10 to 16384 GB for
general purpose
and provisioned
IOPS SSD.
8 to 1024 GB for
magnetic.
AWS Elastic Beanstalk Developer Guide
General Options
Name
Description
RootVolumeIOPS
Desired input/output operations per
second (IOPS) for a provisioned IOPS SSD
root volume.
Default
Valid Values
None
100 to 20000
The maximum ratio of IOPS to volume
size is 30 to 1. For example, a volume
with 3000 IOPS must be at least 100 GB.
aws:autoscaling:scheduledaction
Configure scheduled actions for your environment's Auto Scaling group.
Namespace: aws:autoscaling:scheduledaction
Name
Description
Default
Valid Values
DesiredCapacity
The number of instances that you want
running in the autoscaling group.
None
1 to 10000
EndTime
A date and time in the future (in the
UTC/GMT time zone) when you want the
scheduled scaling action to stop.
None
A unique date and
time across all
scheduled scaling
actions.
If you don't specify an EndTime, the
recurrence is ongoing until you configure
it with an end date and time.
Example: 2015-04-28T04:07:2Z
For more information on the ISO-8601
timestamp format, visit http://
www.w3.org/TR/NOTE-datetime.
MaxSize
The maximum number of instances that
you want in the autoscaling group for
the duration of the scheduled action.
None
0 to 10000
MinSize
The minimum number of instances that
you want in the autoscaling group for
the duration of the scheduled action.
None
0 to 10000
Recurrence
The frequency with which you want the
scheduled action to occur. If you do not
specify a recurrence, then the scaling
action will occur only once, as specified
by the StartTime.
None
A CRON expression.
A date and time in the future (in the
UTC/GMT time zone) when you want the
scheduled scaling action to start.
None
StartTime
API Version 2010-12-01
166
For more
information about
CRON, see Cron.
A unique date
and time across
all scheduled
actions in ISO
8601 time format.
For example,
2015-04-28T04:07:02Z.
For more
information about
AWS Elastic Beanstalk Developer Guide
General Options
Name
Description
Default
Valid Values
ISO 8601 time
format, go to Date
and Time Formats.
Suspend
Whether to temporarily stop the
scheduled action.
false
True
False
Note
When you configure a scheduled scaling action, include a resource name with a unique value
as the name for the scheduled scaling action. All option settings that share this resource name
apply to the same scheduled action. For example:
option_settings:
- namespace: aws:autoscaling:scheduledaction
resource_name: ScheduledAction01
option_name: MinSize
value: 2
- namespace: aws:autoscaling:scheduledaction
resource_name: ScheduledAction01
option_name: MaxSize
value: 5
- namespace: aws:autoscaling:scheduledaction
resource_name: ScheduledAction01
option_name: StartTime
value: "2015-05-14T19:25:00Z"
aws:autoscaling:trigger
Configure scaling triggers for your environment's Auto Scaling group.
Namespace: aws:autoscaling:trigger
Name
Description
Default
Valid Values
BreachDuration
Amount of time, in minutes, a metric
can be beyond its defined limit (as
specified in the UpperThreshold and
LowerThreshold) before the trigger fires.
5
1 to 600
LowerBreachScaleIncrement
How many Amazon EC2 instances to
remove when performing a scaling
activity.
-1
LowerThreshold
If the measurement falls below this
number for the breach duration, a
trigger is fired.
2000000
0 to 20000000
MeasureName
Metric used for your Auto Scaling
trigger.
NetworkOut
CPUUtilization
NetworkIn
NetworkOut
DiskWriteOps
DiskReadBytes
API Version 2010-12-01
167
AWS Elastic Beanstalk Developer Guide
General Options
Name
Description
Default
Valid Values
DiskReadOps
DiskWriteBytes
Latency
RequestCount
HealthyHostCount
UnhealthyHostCount
Period
Specifies how frequently Amazon
CloudWatch measures the metrics for
your trigger.
5
Statistic
Statistic the trigger should use, such as
Average.
Average
Minimum
Maximum
Sum
Average
Unit
Unit for the trigger measurement, such
as Bytes.
Bytes
Seconds
Percent
Bytes
Bits
Count
Bytes/Second
Bits/Second
Count/Second
None
UpperBreachScaleIncrement
How many Amazon EC2 instances to add
when performing a scaling activity.
1
UpperThreshold
6000000
If the measurement is higher than this
number for the breach duration, a
trigger is fired.
aws:autoscaling:updatepolicy:rollingupdate
Configure rolling updates your environment's Auto Scaling group.
API Version 2010-12-01
168
0 to 20000000
AWS Elastic Beanstalk Developer Guide
General Options
Namespace: aws:autoscaling:updatepolicy:rollingupdate
Name
Description
Default
Valid Values
MaxBatchSize
The number of
instances included
in each batch of the
rolling update.
One-third of the
minimum size of
the autoscaling
group, rounded to
the next highest
integer.
1 to 10000
MinInstancesInService
The minimum number
of instances that must
be in service within
the autoscaling group
while other instances
are terminated.
The minimum size
of the AutoScaling
group or one
less than the
maximum size of
the autoscaling
group, whichever is
lower.
0 to 9999
RollingUpdateEnabled
If true, enables
rolling updates for
an environment.
Rolling updates are
useful when you
need to make small,
frequent updates to
your Elastic Beanstalk
software application
and you want to avoid
application downtime.
false
true
false
Setting this value to
true automatically
enables the
MaxBatchSize,
MinInstancesInService,
and PauseTime
options. Setting any
of those options also
automatically sets the
RollingUpdateEnabled
option value to true.
Setting this option to
false disables rolling
updates.
RollingUpdateType
Time-based rolling
updates apply a
PauseTime between
batches. Health-based
rolling updates wait for
new instances to pass
health checks before
moving on to the next
batch. Immutable
updates (p. 120) launch
a full set of instances
API Version 2010-12-01
169
Time
Time
Health
Immutable
AWS Elastic Beanstalk Developer Guide
General Options
Name
Description
Default
Valid Values
in a new AutoScaling
group.
PauseTime
The amount of time the
Elastic Beanstalk service
will wait after it has
completed updates to
one batch of instances
before it continues on
to the next batch.
Automatically
computed based on
instance type and
container.
PT0S* (0 seconds) to
PT1H (1 hour)
Timeout
Maximum amount of
time to wait for all
instances in a batch of
instances to pass health
checks before canceling
the update.
PT30M (30 minutes)
PT5M* (5 minutes) to
PT1H (1 hour)
*ISO8601 duration
format: PT#H#M#S
where each # is the
number of hours,
minutes, and/or
seconds, respectively.
aws:ec2:vpc
Configure your environment to launch resources in a custom VPC. If you don't configure settings in this
namespace, Elastic Beanstalk launches resources in the default VPC.
Namespace: aws:ec2:vpc
Name
Description
Default
VPCId
The ID for your VPC.
None
Subnets
The IDs of the Auto Scaling group subnet or subnets. If
you have multiple subnets, specify the value as a single
comma-delimited string of subnet IDs (for example,
"subnet-11111111,subnet-22222222").
None
ELBSubnets
The IDs of the subnet or subnets for the elastic load
balancer. If you have multiple subnets, specify the value
as a single comma-delimited string of subnet IDs (for
example, "subnet-11111111,subnet-22222222").
None
ELBScheme
Specify internal if you want to create an internal load
balancer in your VPC so that your Elastic Beanstalk
application cannot be accessed from outside your VPC.
None
DBSubnets
Contains the IDs of the database subnets. This is
only used if you want to add an Amazon RDS DB
Instance as part of your application. If you have
multiple subnets, specify the value as a single
comma-delimited string of subnet IDs (for example,
"subnet-11111111,subnet-22222222").
None
AssociatePublicIpAddress
Specifies whether to launch instances with public IP
addresses in your VPC. Instances with public IP addresses
API Version 2010-12-01
170
None
Valid
Values
internal
true
AWS Elastic Beanstalk Developer Guide
General Options
Name
Description
Default
do not require a NAT device to communicate with the
Internet. You must set the value to true if you want to
include your load balancer and instances in a single public
subnet.
Valid
Values
false
aws:elasticbeanstalk:application
Configure a health check path for your application.
Namespace: aws:elasticbeanstalk:application
Name
Description
Default Valid Values
Application
Healthcheck URL
The path to which to send health check
requests. If not set, the load balancer
attempts to make a TCP connection
on port 80 to verify health. Set to a
path starting with / to send an HTTP
GET request to that path. You can also
include a protocol (HTTP, HTTPS, TCP, or
SSL) and port prior to the path to check
HTTPS connectivity or use a non-default
port.
None
/ (HTTP GET to root path)
/health
HTTPS:443/
HTTPS:443/health
etc
EB CLI and Elastic Beanstalk console apply recommended values for the preceding options.
These settings must be removed if you want to use configuration files to configure the same. See
Recommended Values (p. 195) for details.
aws:elasticbeanstalk:application:environment
Configure environment properties for your application.
Namespace: aws:elasticbeanstalk:application:environment
Name
Description
Default
Valid Values
Any environment
variable name.
Pass in key-value pairs.
None
Any environment
variable value.
Note
The combined size of all environment properties defined for an environment is limited to 4096
bytes. The format of environment properties is KEY1=VALUE1, KEY2=VALUE2, which means
that both the value and key of each variable are included in the total. When a platform has
one or more predefined environment properties, such as JDBC_CONNECTION_STRING, those
properties are also included in the total.
aws:elasticbeanstalk:cloudwatch:logs
Configure log streaming for your application.
API Version 2010-12-01
171
AWS Elastic Beanstalk Developer Guide
General Options
Namespace: aws:elasticbeanstalk:cloudwatch:logs
Name
Description
Default
Valid
Values
StreamLogs
Whether to create groups in CloudWatch logs for proxy
and deployment logs, and stream logs from each instance
in your environment.
false
true
DeleteOnTerminate
Whether to delete the log groups when the environment
is terminated. If false, the logs are kept RetentionDays
days.
false
false
true
false
RetentionInDaysThe number of days to keep log events before they expire. 7
1, 3, 5,
7, 14,
30, 60,
90, 120,
150, 180,
365, 400,
545, 731,
1827,
3653
aws:elasticbeanstalk:command
Configure rolling deployments for your application code.
Namespace: aws:elasticbeanstalk:command
Name
Description
Default
Valid
Values
DeploymentPolicy
Choose a deployment policy (p. 110) for
application version deployments.
AllAtOnce
AllAtOnce
Rolling
RollingWithAdditionalB
Immutable
Timeout
Number of seconds to wait for an
instance to complete executing
commands.
"600"
"1" to
"3600"
BatchSizeType
The type of number that is specified in
BatchSize.
Percentage
Percentage
Percentage or fixed number of Amazon
EC2 instances in the Auto Scaling group
on which to simultaneously perform
deployments. Valid values vary per
BatchSizeType setting.
100
Do not cancel a deployment due to failed
health checks.
false
BatchSize
IgnoreHealthCheck
API Version 2010-12-01
172
Fixed
1 to 100
(Percentage).
1 to
aws:autoscaling:asg::MaxS
(Fixed)
true
false
AWS Elastic Beanstalk Developer Guide
General Options
Name
Description
Default
Valid
Values
HealthCheckSuccessThreshold
Lower the threshold for instances to pass
health checks.
Ok
Ok
Warning
Degraded
Severe
aws:elasticbeanstalk:environment
Configure your environment's architecture and service role.
Namespace: aws:elasticbeanstalk:environment
Name
Description
Default
Valid Values
EnvironmentType
Set to SingleInstance to launch one EC2
instance with no load balancer.
LoadBalanced
SingleInstance
The name of an IAM role that Elastic Beanstalk
uses to manage resources for the environment.
None
Any role name.
classic
classic
ServiceRole
LoadBalanced
For example, aws-elasticbeanstalk-servicerole.
LoadBalancerType Choose between a classic load balancer and an
application load balancer.
application
aws:elasticbeanstalk:environment:process:default
Configure your environment's default process.
Namespace: aws:elasticbeanstalk:environment:process:default
Name
Description
Default
Valid Values
DeregistrationDelay
Time to wait for active
requests to complete
before deregistering.
20
0 to 3600
HealthCheckInterval
The interval at which
Elastic Load Balancing
will check the health
of your application's
Amazon EC2 instances.
15
15 to 300
HealthCheckPath
Path to which to send
HTTP requests for
health checks.
/
A routable path.
API Version 2010-12-01
173
AWS Elastic Beanstalk Developer Guide
General Options
Name
Description
Default
Valid Values
HealthCheckTimeout
Time to wait for a
response during a
health check.
5
1 to 60
HealthyThresholdCount
Consecutive successful
requests before Elastic
Load Balancing changes
the instance health
status.
3
1 to 10
MatcherHTTPCode
HTTP code that
indicates that an
instance is healthy.
None
200 to 399
Port
Port on which the
process listens.
80
1 to 65535
Protocol
Protocol that the
process uses.
HTTP
HTTP
Set to true to enable
sticky sessions.
'false'
StickinessEnabled
HTTPS
'false'
'true'
StickinessLBCookieDuration
Lifetime of the sticky
session cookie in
seconds.
86400
1 to 604800
StickinessType
lb_cookie
lb_cookie
5
2 to 10
Set to lb_cookie to
use cookies for sticky
sessions.
UnhealthyThresholdCountConsecutive
unsuccessful requests
before Elastic Load
Balancing changes the
instance health status.
aws:elasticbeanstalk:environment:process:process_name
Configure additional processes for your environment.
Namespace: aws:elasticbeanstalk:environment:process:process_name
Name
Description
Default
Valid Values
DeregistrationDelay
Time to wait for active
requests to complete
before deregistering.
20
0 to 3600
HealthCheckInterval
The interval at which
Elastic Load Balancing
will check the health
of your application's
Amazon EC2 instances.
15
15 to 300
API Version 2010-12-01
174
AWS Elastic Beanstalk Developer Guide
General Options
Name
Description
Default
Valid Values
HealthCheckPath
Path to which to send
HTTP requests for
health checks.
/
A routable path.
HealthCheckTimeout
Time to wait for a
response during a
health check.
5
1 to 60
HealthyThresholdCount
Consecutive successful
requests before Elastic
Load Balancing changes
the instance health
status.
3
1 to 10
MatcherHTTPCode
HTTP code that
indicates that an
instance is healthy.
None
200 to 399
Port
Port on which the
process listens.
80
1 to 65535
Protocol
Protocol that the
process uses.
HTTP
HTTP
Set to true to enable
sticky sessions.
'false'
StickinessEnabled
HTTPS
'false'
'true'
StickinessLBCookieDuration
Lifetime of the sticky
session cookie in
seconds.
86400
1 to 604800
StickinessType
lb_cookie
lb_cookie
5
2 to 10
Set to lb_cookie to
use cookies for sticky
sessions.
UnhealthyThresholdCountConsecutive
unsuccessful requests
before Elastic Load
Balancing changes the
instance health status.
aws:elasticbeanstalk:healthreporting:system
Configure enhanced health reporting for your environment.
Namespace: aws:elasticbeanstalk:healthreporting:system
Name
Description
Default
Valid Values
SystemType
Health reporting system (basic (p. 303) or
enhanced (p. 306)). Enhanced health reporting
requires a service role (p. 18) and a version 2
platform configuration (p. 25).
basic
basic
API Version 2010-12-01
175
enhanced
AWS Elastic Beanstalk Developer Guide
General Options
Name
Description
Default
Valid Values
ConfigDocument
A JSON document describing the environment and
instance metrics to publish to CloudWatch.
None
aws:elasticbeanstalk:hostmanager
Configure the EC2 instances in your environment to upload rotated logs to Amazon S3.
Namespace: aws:elasticbeanstalk:hostmanager
Name
Description
LogPublicationControl Copy the log files for your application's Amazon
EC2 instances to the Amazon S3 bucket associated
with your application.
Default
Valid Values
false
true
false
aws:elasticbeanstalk:managedactions
Configure managed platform updates for your environment.
Namespace: aws:elasticbeanstalk:managedactions
Name
Description
Default
Valid Values
ManagedActionsEnabled
Enable managed platform
updates (p. 129).
true
true
false
When you set this to true,
you must also specify a
PreferredStartTime and
UpdateLevel (p. 176).
PreferredStartTime
Configure a maintenance window
for managed actions in UTC.
None
Day and time in
day:hour:minute
For example, "Tue:10:00".
format.
aws:elasticbeanstalk:managedactions:platformupdate
Configure managed platform updates for your environment.
Namespace: aws:elasticbeanstalk:managedactions:platformupdate
Name
Description
Default
Valid Values
UpdateLevel
The highest level of update to
apply with managed platform
updates. Platforms are versioned
major.minor.patch. For example,
2.0.8 has a major version of 2, a
minor version of 0, and a patch
version of 8.
None
patch for
API Version 2010-12-01
176
patch version
updates only.
minor for both
minor and
AWS Elastic Beanstalk Developer Guide
General Options
Name
Description
Default
Valid Values
patch version
updates.
InstanceRefreshEnabled
Enable weekly instance
replacement.
false
true
false
Requires ManagedActionsEnabled
to be set to true.
aws:elasticbeanstalk:monitoring
Configure your environment to terminate EC2 instances that fail health checks.
Namespace: aws:elasticbeanstalk:monitoring
Name
Description
Default
Valid Values
Automatically Terminate
Unhealthy Instances
Terminate an instance if it fails
health checks.
true
true
false
aws:elasticbeanstalk:sns:topics
Configure notifications for your environment.
Namespace: aws:elasticbeanstalk:sns:topics
Name
Description
Default
Notification
Endpoint
Endpoint where you want to be
notified of important events
affecting your application.
None
Notification
Protocol
Protocol used to send notifications to
your endpoint.
email
Valid Values
http
https
email
email-json
sqs
Notification
Topic ARN
Amazon Resource Name for the topic
you subscribed to.
None
Notification
Topic Name
Name of the topic you subscribed to.
None
aws:elasticbeanstalk:sqsd
Configure the Amazon SQS queue for a worker environment.
API Version 2010-12-01
177
AWS Elastic Beanstalk Developer Guide
General Options
Namespace: aws:elasticbeanstalk:sqsd
Name
Description
Default
Valid Values
WorkerQueueURL The URL of the queue from which the
daemon in the worker environment
tier reads messages
automaticallyIf you don't specify a value,
generated
then Elastic Beanstalk
automatically creates a
queue.
HttpPath
The relative path to the application
to which HTTP POST messages are
sent
/
MimeType
The MIME type of the message sent
in the HTTP POST request
application/application/json
json
application/x-www-formurlencoded
application/xml
text/plain
Custom MIME type.
HttpConnections
The maximum number of concurrent
connections to any application(s)
within an Amazon EC2 instance
15
1 to 100
ConnectTimeout
The amount of time, in seconds, to
wait for successful connections to an
application
5
1 to 60
InactivityTimeout The amount of time, in seconds, to
wait for a response on an existing
connection to an application
The message is reprocessed until
the daemon receives a 200 OK
response from the application in
the worker environment tier or the
RetentionPeriod expires.
180
1 to 36000
VisibilityTimeout
300
0 to 43200
ErrorVisibilityTimeout
The amount of time, in seconds,
that elapses before Elastic Beanstalk
returns a message to the Amazon
SQS queue after a processing
attempt fails with an explicit error.
2 seconds
0 to 43200 seconds
RetentionPeriod
345600
60 to 1209600
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, then the message is
again made visible in the queue for
any other daemon to read.
The amount of time, in seconds, a
message is valid and will be actively
processed
API Version 2010-12-01
178
AWS Elastic Beanstalk Developer Guide
General Options
Name
Description
Default
Valid Values
MaxRetries
The maximum number of attempts
that Elastic Beanstalk attempts
to send the message to the web
application that will process it before
moving the message to the dead
letter queue.
10
1 to 100
aws:elb:healthcheck
Configure healtchecks for a classic load balancer.
Namespace: aws:elb:healthcheck
Name
Description
Default
Valid
Values
HealthyThreshold Consecutive successful requests before Elastic Load
Balancing changes the instance health status.
3
2 to 10
Interval
The interval at which Elastic Load Balancing will check the
health of your application's Amazon EC2 instances.
10
5 to 300
Timeout
Number of seconds Elastic Load Balancing will wait for a
response before it considers the instance nonresponsive.
5
2 to 60
UnhealthyThreshold
Consecutive unsuccessful requests before Elastic Load
Balancing changes the instance health status.
5
2 to 10
(deprecated)
Target
TCP:80
Target in
the format
PROTOCOL:PORT/
Destination on backend instance to which to send
health checks. Use Application Healthcheck URL in the
aws:elasticbeanstalk:application (p. 171) namespace
instead.
PATH
aws:elb:loadbalancer
Configure your environment's classic load balancer.
Several of the options in this namespace have been deprecated in favor of listener-specific options in the
aws:elb:listener (p. 180) namespace. The deprecated options only let you configure two listeners (one
secure and one unsecure) on standard ports.
Namespace: aws:elb:loadbalancer
Name
Description
Default
Valid Values
CrossZone
Configure the load balancer to route traffic
evenly across all instances in all Availability
Zones rather than only within each zone.
false
true
SecurityGroups
Assign one or more security groups that you
created to the load balancer.
None
One or more
security
group IDs.
ManagedSecurityGroup
Assign an existing security group to your
environment’s load balancer, instead of
None
A security
group ID.
API Version 2010-12-01
179
false
AWS Elastic Beanstalk Developer Guide
General Options
Name
Description
Default
Valid Values
80
OFF
creating a new one. To use this setting, update
the SecurityGroups setting in this namespace
to include your security group’s ID, and
remove the automatically created security
group’s ID, if one exists.
To allow traffic from the load balancer to your
environment’s EC2 instances, Elastic Beanstalk
adds a rule to the instances’ security group
that allows inbound traffic from the managed
security group.
(deprecated)
LoadBalancerHTTPPort
Port to listen on for the unsecure listener.
80
(deprecated)
Protocol to use on the unsecure listener.
LoadBalancerPortProtocol
HTTP
(deprecated)
Port to listen on for the secure listener.
LoadBalancerHTTPSPort
OFF
HTTP
TCP
OFF
443
8443
(deprecated)
Protocol to use on the secure listener.
LoadBalancerSSLPortProtocol
HTTPS
(deprecated)
SSLCertificateId
None
ARN of an SSL certificate to bind to the secure
listener.
HTTPS
SSL
aws:elb:listener
Configure the default listener (port 80) on a classic load balancer.
Namespace: aws:elb:listener
Name
Description
Default
Valid Values
ListenerProtocol
The protocol used by the listener.
HTTP
HTTP TCP
InstancePort
The port that this listener uses to
communicate with the EC2 instances.
The same as
InstanceProtocol
The protocol that this listener uses to
communicate with the EC2 instances.
HTTP when
HTTP or
ListenerProtocol
HTTPS when
is HTTP
ListenerProtocol
is HTTP or
TCP when
HTTPS
ListenerProtocol
is TCP
TCP or
SSL when
ListenerProtocol
is TCP or SSL
API Version 2010-12-01
180
1 to 65535
listener_port.
AWS Elastic Beanstalk Developer Guide
General Options
Name
Description
Default
Valid Values
PolicyNames
A comma-separated list of policy names to
apply to the port for this listener. We suggest
that you use the LoadBalancerPorts option
of the aws:elb:policies (p. 181) namespace
instead.
None
ListenerEnabled
Specifies whether this listener is enabled. If
you specify false, the listener is not included
in the load balancer.
true
true
false
aws:elb:listener:listener_port
Configure additional listeners on a classic load balancer.
Namespace: aws:elb:listener:listener_port
Name
Description
Default
Valid Values
ListenerProtocol
The protocol used by the listener.
HTTP
HTTP HTTPS
TCP SSL
InstancePort
The port that this listener uses to
communicate with the EC2 instances.
The same as
InstanceProtocol
The protocol that this listener uses to
communicate with the EC2 instances.
HTTP when
HTTP or
ListenerProtocol
HTTPS when
is HTTP or
ListenerProtocol
HTTPS
is HTTP or
HTTPS
TCP when
ListenerProtocol
TCP or
is TCP or SSL SSL when
ListenerProtocol
is TCP or SSL
PolicyNames
A comma-separated list of policy names to
apply to the port for this listener. We suggest
that you use the LoadBalancerPorts option
of the aws:elb:policies (p. 181) namespace
instead.
None
SSLCertificateId
ARN of an SSL certificate to bind to the
listener.
None
ListenerEnabled
Specifies whether this listener is enabled. If
you specify false, the listener is not included
in the load balancer.
true if
true false
1 to 65535
listener_port.
any other
option is
set. false
otherwise.
aws:elb:policies
Modify the default stickiness and global load balancer policies for a classic load balancer.
API Version 2010-12-01
181
AWS Elastic Beanstalk Developer Guide
General Options
Namespace: aws:elb:policies
Name
Description
Default
Valid Values
ConnectionDrainingEnabled
Specifies whether the load balancer
maintains existing connections to instances
that have become unhealthy or deregistered
to complete in-progress requests.
false
true
ConnectionDrainingTimeout
The maximum number of seconds that the
load balancer maintains existing connections
to an instance during connection draining
before forcibly closing the connections.
20
1 to 3600
ConnectionSettingIdleTimeout
Number of seconds that the load balancer
waits for any data to be sent or received over
the connection. If no data has been sent or
received after this time period elapses, the
load balancer closes the connection.
60
1 to 3600
LoadBalancerPorts
A comma-separated list of the listener
ports that the default policy (AWSEB-ELBStickinessPolicy) applies to.
None
You can use
:all to indicate
all listener ports
Stickiness Cookie
Expiration
The amount of time, in seconds, that each
cookie is valid. Uses the default policy
(AWSEB-ELB-StickinessPolicy) .
0
0 to 1000000
Stickiness Policy
Binds a user's session to a specific server
instance so that all requests coming from
the user during the session are sent to the
same server instance. Uses the default policy
(AWSEB-ELB-StickinessPolicy) .
false
true false
Default
Valid Values
false
aws:elb:policies:policy_name
Create additional load balancer policies for a classic load balancer.
Namespace: aws:elb:policies:policy_name
Name
Description
CookieName
The name of the application-generated
None
cookie that controls the session lifetimes of
a AppCookieStickinessPolicyType policy.
This policy can be associated only with HTTP/
HTTPS listeners.
InstancePorts
A comma-separated list of the instance ports
that this policy applies to.
None
A list of ports,
or :all
LoadBalancerPorts
A comma-separated list of the listener ports
that this policy applies to.
None
A list of ports,
or :all
ProxyProtocol
For a ProxyProtocolPolicyType policy,
specifies whether to include the IP address
and port of the originating request for TCP
None
true false
API Version 2010-12-01
182
AWS Elastic Beanstalk Developer Guide
General Options
Name
Description
Default
Valid Values
None
messages. This policy can be associated only
with TCP/SSL listeners.
PublicKey
The contents of a public key for a
PublicKeyPolicyType policy to use
when authenticating the back-end
server or servers. This policy cannot
be applied directly to back-end servers
or listeners; it must be part of a
BackendServerAuthenticationPolicyType
policy.
PublicKeyPolicyNames
A comma-separated list of policy names
(from the PublicKeyPolicyType policies) for
a BackendServerAuthenticationPolicyType
policy that controls authentication to a backend server or servers. This policy can be
associated only with back-end servers that
are using HTTPS/SSL.
None
SSLProtocols
A comma-separated list of SSL protocols to
be enabled for a SSLNegotiationPolicyType
policy that defines the ciphers and protocols
that will be accepted by the load balancer.
This policy can be associated only with
HTTPS/SSL listeners.
None
SSLReferencePolicy
The name of a predefined security
None
policy that adheres to AWS security best
practices and that you want to enable for
a SSLNegotiationPolicyType policy that
defines the ciphers and protocols that will be
accepted by the load balancer. This policy can
be associated only with HTTPS/SSL listeners.
Stickiness Cookie
Expiration
The amount of time, in seconds, that each
cookie is valid.
0
0 to 1000000
Stickiness Policy
Binds a user's session to a specific server
instance so that all requests coming from the
user during the session are sent to the same
server instance.
false
true false
aws:elbv2:listener:default
Configure the default listener (port 80) on an application load balancer.
Namespace: aws:elbv2:listener:default
Name
Description
Default
Valid Values
DefaultProcess
Name of the
process (p. 173) to
which to forward traffic
when no rules match.
default
A process name.
API Version 2010-12-01
183
AWS Elastic Beanstalk Developer Guide
General Options
Name
Description
ListenerEnabled
Set to false to disable
true
the listener. You can use
this option to disable
the default listener on
port 80.
true
List of rules (p. 184)
to apply to the listener
Comma separated list
of rule names.
Rules
Default
Valid Values
false
None
aws:elbv2:listener:listener_port
Configure additional listeners on an application load balancer.
Namespace: aws:elbv2:listener:listener_port
Name
Description
Default
Valid Values
DefaultProcess
Name of the
process (p. 173) where
traffic is forwarded
when no rules match.
default
A process name.
ListenerEnabled
Set to false to disable
true
the listener. You can use
this option to disable
the default listener on
port 80.
true
Protocol of traffic to
process.
HTTP
HTTP
Rules
List of rules (p. 184)
to apply to the listener
None
Comma separated list
of rule names.
SSLCertificateArns
The ARN of the SSL
certificate to bind to
the listener.
None
The ARN of a certificate
stored in IAM or ACM.
SSLPolicy
Specify a security policy
to apply to the listener.
None (ELB default)
The name of a load
balancer security policy.
Protocol
false
HTTPS
aws:elbv2:listenerrule:rule_name
Add listener rules to an application load balancer.
Namespace: aws:elbv2:listenerrule:rule_name
Name
Description
Default
PathPatternsList of path patterns to match. For example, /
img/*.
API Version 2010-12-01
184
None
Valid Values
AWS Elastic Beanstalk Developer Guide
General Options
Name
Description
Default
Priority
Precedence of this rule when multiple rules
1
match. The lower number takes precedence. No
two rules can have the same priority.
1 to 1000
Process
Name of the process (p. 173) to which to
forward traffic when this rule matches the
request.
A process name.
default
Valid Values
aws:elbv2:loadbalancer
Configure an application load balancer.
Namespace: aws:elbv2:loadbalancer
Name
Description
Default
Valid Values
AccessLogsS3Bucket
Amazon S3 bucket in which to store
access logs. The bucket must be in the
same region as the environment and
allow the load balancer write access.
None
A bucket name.
AccessLogsS3Enabled
Enable access log storage.
false
true
false
AccessLogsS3Prefix
Prefix to prepend to access log names.
By default, the load balancer uploads
logs to a directory names AWSLogs in
the bucket you specify. Specify a prefix
to place the AWSLogs directory inside
another directory.
IdleTimeout
Time to wait for a request to complete
None
before closing connections to client and
instance.
ManagedSecurityGroup
Assign an existing security group to
your environment’s load balancer,
instead of creating a new one. To use
this setting, update the SecurityGroups
setting in this namespace to include
your security group’s ID, and remove
the automatically created security
group’s ID, if one exists.
To allow traffic from the load balancer
to your environment’s EC2 instances,
Elastic Beanstalk adds a rule to the
instances’ security group that allows
inbound traffic from the managed
security group.
SecurityGroups
List of security groups to attach to the
load balancer.
API Version 2010-12-01
185
None
1 to 3600
The
A security group ID.
security
group
that
Elastic
Beanstalks
creates
for your
load
balancer.
The
security
group
that
Comma separated list
of security group IDs.
AWS Elastic Beanstalk Developer Guide
General Options
Name
Description
Default
Valid Values
Elastic
Beanstalks
creates
for your
load
balancer.
aws:rds:dbinstance
Configure an attached Amazon RDS DB instance.
Namespace: aws:rds:dbinstance
Name
Description
DBAllocatedStorage
The allocated database storage size, specified
in gigabytes.
Default
Valid Values
MySQL: 5
MySQL: 5-1024
Oracle: 10
Oracle: 10-1024
sqlserver-se:
sqlserver: cannot
be modified
200
sqlserver-ex: 30
sqlserver-web:
30
DBDeletionPolicyDecides whether to delete or snapshot the DB
instance on environment termination.
Delete
Delete
Snapshot
Warning
Deleting a DB instance results in
permanent data loss.
DBEngine
The name of the database engine to use for
this instance.
mysql
mysql
oracle-se1
oracle-se
oracle-ee
sqlserver-ee
sqlserver-ex
sqlserver-web
sqlserver-se
postgres
DBEngineVersionThe version number of the database engine.
5.5
DBInstanceClass The database instance type.
db.t1.micro
API Version 2010-12-01
186
Go to DB Instance
Class in the
Amazon Relational
AWS Elastic Beanstalk Developer Guide
Platform Specific Options
Name
Description
Default
Valid Values
Database Service
User Guide.
DBPassword
The name of master user password for the
database instance.
None
DBSnapshotIdentifier
The identifier for the DB snapshot to restore
from.
None
DBUser
ebroot
The name of master user for the DB Instance.
MultiAZDatabaseSpecifies whether a database instance MultiAZ deployment needs to be created. For more
information about Multi-AZ deployments
with Amazon Relational Database Service
(RDS), go to Regions and Availability Zones in
the Amazon Relational Database Service User
Guide.
false
true
false
Platform Specific Options
Platforms
• Docker Platform Options (p. 187)
• Go Platform Options (p. 187)
• Java SE Platform Options (p. 188)
• Java with Tomcat Platform Options (p. 188)
• .NET Platform Options (p. 189)
• Node.js Platform Options (p. 190)
• PHP Platform Options (p. 191)
• Python Platform Options (p. 192)
• Ruby Platform Options (p. 193)
Docker Platform Options
Elastic Beanstalk does not provide any Docker-specific configuration options.
Go Platform Options
Map a path in your web application to a directory in the source bundle that contains static files. Each
option that you define in this namespace maps a different path.
Namespace: aws:elasticbeanstalk:container:golang:staticfiles
Name
Description
Default
Valid Values
Application path.
Source directory.
n/a
n/a
Example: /images
Example: myimages
API Version 2010-12-01
187
AWS Elastic Beanstalk Developer Guide
Platform Specific Options
Java SE Platform Options
Map a path in your web application to a directory in the source bundle that contains static files. Each
option that you define in this namespace maps a different path.
Namespace: aws:elasticbeanstalk:container:java:staticfiles
Name
Description
Default
Valid Values
Application path.
Source directory.
n/a
n/a
Example: /images
Example: myimages
Run the AWS X-Ray daemon to relay trace information from your X-Ray integrated (p. 262) Java 8
application.
Namespace: aws:elasticbeanstalk:xray
Name
Description
Default
Valid Values
XRayEnabled
Set to true to run the AWS X-Ray daemon
on the instances in your environment.
false
true
false
Java with Tomcat Platform Options
Namespace: aws:elasticbeanstalk:application:environment
Name
Description
JDBC_CONNECTION_STRINGThe connection string to an external database.
Default
Valid
Values
n/a
n/a
Note
The combined size of all environment properties defined for an environment is limited to 4096
bytes. The format of environment properties is KEY1=VALUE1, KEY2=VALUE2, which means
that both the value and key of each variable are included in the total. When a platform has
one or more predefined environment properties, such as JDBC_CONNECTION_STRING, those
properties are also included in the total.
Namespace: aws:elasticbeanstalk:container:tomcat:jvmoptions
Name
Description
Default
Valid
Values
JVM Options
Pass command-line options to the JVM at
startup.
n/a
n/a
Xmx
Maximum JVM heap sizes.
256m
n/a
XX:MaxPermSize
Section of the JVM heap that is used to store
class definitions and associated metadata.
64m
n/a
Xms
Initial JVM heap sizes.
256m
n/a
API Version 2010-12-01
188
AWS Elastic Beanstalk Developer Guide
Platform Specific Options
Note
You can extend the number of parameters and specify the parameter
names in the aws:elasticbeanstalk:container:tomcat:jvmoptions and
aws:elasticbeanstalk:application:environment namespaces.
Namespace: aws:elasticbeanstalk:environment:proxy
Name
Description
Default
Valid Values
GzipCompression
Set to 'false' to disable response
compression.
'true'
'true'
ProxyServer
apache
'false'
Set to nginx to use nginx as a proxy instead of
Apache 2.2.
apache
nginx
Map a path in your web application to a directory in the source bundle that contains static files. Each
option that you define in this namespace maps a different path.
Namespace: aws:elasticbeanstalk:environment:proxy:staticfiles
Name
Description
Default
Valid Values
Application path.
Source directory. If ProxyServer is set to
"none", then the static file mappings will
not take affect.
n/a
n/a
Example: /images
Example: myimages
Run the AWS X-Ray daemon to relay trace information from your X-Ray integrated (p. 262) Tomcat 8
application.
Namespace: aws:elasticbeanstalk:xray
Name
Description
Default
Valid Values
XRayEnabled
Set to true to run the AWS X-Ray daemon
on the instances in your environment.
false
true
false
.NET Platform Options
Namespace: aws:elasticbeanstalk:application:environment
Name
Description
Default
Valid Values
PARAM1 - PARAM5
Pass in key-value pairs.
n/a
n/a
Note
The combined size of all environment properties defined for an environment is limited to 4096
bytes. The format of environment properties is KEY1=VALUE1, KEY2=VALUE2, which means
that both the value and key of each variable are included in the total. When a platform has
one or more predefined environment properties, such as JDBC_CONNECTION_STRING, those
properties are also included in the total.
API Version 2010-12-01
189
AWS Elastic Beanstalk Developer Guide
Platform Specific Options
Namespace: aws:elasticbeanstalk:container:dotnet:apppool
Name
Description
Default
Valid Values
Target Runtime
You can choose the version of .NET Framework
for your application.
4.0
2.0
Enable 32-bit applications.
False
Enable 32-bit
Applications
4.0
True
False
Run the AWS X-Ray daemon to relay trace information from your X-Ray integrated (p. 262) .NET
application.
Namespace: aws:elasticbeanstalk:xray
Name
Description
Default
Valid Values
XRayEnabled
Set to true to run the AWS X-Ray daemon
on the instances in your environment.
false
true
false
Node.js Platform Options
Namespace: aws:elasticbeanstalk:container:nodejs
Name
Description
Default
Valid Values
NodeCommandCommand used to start the Node.js
application. If an empty string is specified,
app.js is used, then server.js, then "npm
start" in that order.
""
n/a
NodeVersion
varies
varies
Version of Node.js. For example, 4.4.6
Supported Node.js versions vary between
versions of the Node.js platform configuration.
See Node.js (p. 31) on the supported platforms
page for a list of the currently supported
versions.
Note
When support for the version of
Node.js that you are using is removed
from the platform configuration, you
must change or remove the version
setting prior to doing a platform
upgrade (p. 123). This may occur when
a security vulnerability is identified for
one or more versions of Node.js
When this occurs, attempting to
upgrade to a new version of the
platform that does not support the
configured NodeVersion (p. 190)
fails. To avoid needing to create
a new environment, change the
API Version 2010-12-01
190
AWS Elastic Beanstalk Developer Guide
Platform Specific Options
Name
Description
Default
Valid Values
GzipCompression
Specifies if gzip compression is enabled.
If ProxyServer is set to "none", then gzip
compression will be disabled.
false
true
ProxyServer
nginx
NodeVersion configuration option to
a version that is supported by both
the old configuration version and
the new one, or remove the option
setting (p. 154), and then perform
the platform upgrade.
Specifies which web server should be used to
proxy connections to Node.js. If ProxyServer
is set to "none", then static file mappings will
not take affect and gzip compression will be
disabled.
false
apache
nginx
none
Map a path in your web application to a directory in the source bundle that contains static files. Each
option that you define in this namespace maps a different path.
Namespace: aws:elasticbeanstalk:container:nodejs:staticfiles
Name
Description
Default
Valid Values
Application path.
Source directory. If ProxyServer is set to
"none", then the static file mappings will
not take affect.
n/a
n/a
Example: /images
Example: myimages
Run the AWS X-Ray daemon to relay trace information from your X-Ray integrated (p. 262) Node.js
application.
Namespace: aws:elasticbeanstalk:xray
Name
Description
Default
Valid Values
XRayEnabled
Set to true to run the AWS X-Ray daemon
on the instances in your environment.
false
true
false
PHP Platform Options
Namespace: aws:elasticbeanstalk:container:php:phpini
Name
Description
Default
Valid Values
document_root (p. 752)
Specify the child directory of your project
/
that is treated as the public-facing web root.
A blank string is treated
as /, or specify a string
starting with /
memory_limit (p. 752)
Amount of memory allocated to the PHP
environment.
n/a
API Version 2010-12-01
191
256M
AWS Elastic Beanstalk Developer Guide
Platform Specific Options
Name
Description
Default
Valid Values
zlib.output_compression
Specifies
(p. 752)
whether or not PHP should use
compression for output.
Off
On
allow_url_fopen (p. 752)
Specifies if PHP's file functions are allowed
to retrieve data from remote locations, such
as websites or FTP servers.
On
display_errors (p. 752)
Specifies if error messages should be part of
the output.
Off
max_execution_timeSets
(p. 752)
the maximum time, in seconds, a script
is allowed to run before it is terminated by
the environment.
60
composer_options (p.
Sets
752)
custom options to use when installing
dependencies using Composer through
composer.phar install. For more information
including available options, go to http://
getcomposer.org/doc/03-cli.md#install.
n/a
Off
On
Off
On
Off
0 to
9223372036854775807
(PHP_INT_MAX)
n/a
Python Platform Options
Namespace: aws:elasticbeanstalk:application:environment
Name
Description
DJANGO_SETTINGS_MODULESpecifies which settings file to use.
Default
Valid Values
n/a
n/a
Note
The combined size of all environment properties defined for an environment is limited to 4096
bytes. The format of environment properties is KEY1=VALUE1, KEY2=VALUE2, which means
that both the value and key of each variable are included in the total. When a platform has
one or more predefined environment properties, such as JDBC_CONNECTION_STRING, those
properties are also included in the total.
Namespace: aws:elasticbeanstalk:container:python
Name
Description
Default
Valid
Values
WSGIPath
The file that contains the WSGI application. This file must
have an "application" callable.
application.pyn/a
NumProcesses The number of daemon processes that should be started
for the process group when running WSGI applications.
1
n/a
NumThreads The number of threads to be created to handle requests
in each daemon process within the process group when
running WSGI applications.
15
n/a
Map a path in your web application to a directory in the source bundle that contains static files. Each
option that you define in this namespace maps a different path.
API Version 2010-12-01
192
AWS Elastic Beanstalk Developer Guide
Platform Specific Options
Namespace: aws:elasticbeanstalk:container:python:staticfiles
Name
Description
Default
Valid
Values
Application path.
Source directory.
n/a
n/a
Example: /images
Example: myimages
Run the AWS X-Ray daemon to relay trace information from your X-Ray integrated (p. 262) Python
application.
Namespace: aws:elasticbeanstalk:xray
Name
Description
Default
Valid Values
XRayEnabled
Set to true to run the AWS X-Ray daemon
on the instances in your environment.
false
true
false
Ruby Platform Options
Namespace: aws:elasticbeanstalk:application:environment
Name
Description
Default
Valid
Values
RAILS_SKIP_MIGRATIONS
Specifies whether to run `rake
db:migrate` on behalf of the users'
applications; or whether it should be
skipped. This is only applicable to Rails 3
applications.
false
true
false
RAILS_SKIP_ASSET_COMPILATION
Specifies whether the container should run
`rake assets:precompile` on behalf of
the users' applications; or whether it should
be skipped. This is also only applicable to
Rails 3 applications.
false
BUNDLE_WITHOUT
A colon (:) separated list of groups to
ignore when installing dependencies from a
Gemfile.
test:development
n/a
RACK_ENV
Specifies what environment stage an
application can be run in. Examples
of common environments include
development, production, test.
production
n/a
RAILS_ENV
Specifies what environment stage an
application can be run in. Examples
of common environments include
development, production, test.
production
n/a
Note
true
false
The combined size of all environment properties defined for an environment is limited to 4096
bytes. The format of environment properties is KEY1=VALUE1, KEY2=VALUE2, which means
API Version 2010-12-01
193
AWS Elastic Beanstalk Developer Guide
Custom Options
that both the value and key of each variable are included in the total. When a platform has
one or more predefined environment properties, such as JDBC_CONNECTION_STRING, those
properties are also included in the total.
Custom Options
Use the aws:elasticbeanstalk:customoption namespace to define options and values that can be read
in Resources blocks in other configuration files. Use custom options to collect user specified settings in a
single configuration file.
For example, you may have a complex configuration file that defines a resource that can be configured
by the user launching the environment. If you use Fn::GetOptionSetting to retrieve the value of a
custom option, you can put the definition of that option in a different configuration file, where it is more
easily discovered and modified by the user.
Also, because they are configuration options, custom options can be set at the API level to override
values set in a configuration file. See Precedence (p. 194) for more information.
Custom options are defined like any other option:
option_settings:
aws:elasticbeanstalk:customoption:
option name: option value
For example, the following configuration file creates an option named ELBAlarmEmail and sets the value
to [email protected]:
option_settings:
aws:elasticbeanstalk:customoption:
ELBAlarmEmail: [email protected]
Elsewhere, a configuration file defines an SNS topic that reads the option with Fn::GetOptionSetting to
populate the value of the Endpoint attribute:
Resources:
MySNSTopic:
Type: AWS::SNS::Topic
Properties:
Subscription:
- Endpoint:
Fn::GetOptionSetting:
OptionName: ELBAlarmEmail
DefaultValue: [email protected]
Protocol: email
You can find more example snippets using Fn::GetOptionSetting at Adding and Customizing Elastic
Beanstalk Environment Resources (p. 216).
Precedence
During environment creation, configuration options are applied from multiple sources with the following
precedence, from highest to lowest:
• Settings applied directly to the environment – Settings specified during a create environment
or update environment operation on the Elastic Beanstalk API by any client, including the AWS
API Version 2010-12-01
194
AWS Elastic Beanstalk Developer Guide
Recommended Values
Management Console, EB CLI, AWS CLI, and SDKs. The AWS Management Console and EB CLI also
apply recommended values (p. 195) for some options that apply at this level unless overridden.
• Saved Configurations – Settings for any options that are not applied directly to the environment are
loaded from a saved configuration, if specified.
• Configuration Files (.ebextensions) – Settings for any options that are not applied directly to the
environment, and also not specified in a saved configuration, are loaded from configuration files in the
.ebextensions folder at the root of the application source bundle.
Configuration files are executed in alphabetical order. For example, .ebextensions/01run.config is
executed before .ebextensions/02do.config.
• Default Values – If a configuration option has a default value, it only applies when the option is not
set at any of the above levels.
If the same configuration option is defined in more than one location, the setting with the highest
precedence is applied. When a setting is applied from a saved configuration or settings applied directly
to the environment, the setting is stored as part of the environment's configuration. These settings can
be removed with the AWS CLI (p. 160) or with the EB CLI (p. 157).
Settings in configuration files are not applied directly to the environment and cannot be removed
without modifying the configuration files and deploying a new application version. If a setting applied
with one of the other methods is removed, the same setting will be loaded from configuration files in the
source bundle.
For example, say you set the minimum number of instances in your environment to 5 during
environment creation, using either the AWS Management Console, a command line option, or a saved
configuration. The source bundle for your application also includes a configuration file that sets the
minimum number of instances to 2.
When you create the environment, Elastic Beanstalk sets the MinSize option in the aws:autoscaling:asg
namespace to 5. If you then remove the option from the environment configuration, the value in the
configuration file is loaded, and the minimum number of instances is set to 2. If you then remove the
configuration file from the source bundle and redeploy, Elastic Beanstalk uses the default setting of 1.
Recommended Values
The Elastic Beanstalk Command Line Interface (EB CLI) and Elastic Beanstalk console provide
recommended values for some configuration options. These values can be different from the default
values and are set at the API level when your environment is created. Recommended values allow Elastic
Beanstalk to improve the default environment configuration without making backwards incompatible
changes to the API.
For example, both the EB CLI and Elastic Beanstalk console set the configuration option for EC2 instance
type (InstanceType in the aws:autoscaling:launchconfiguration namespace). Each client provides a
different way of overriding the default setting. In the console you can choose a different instance type
from a drop down menu on the Configuration Details page of the Create New Environment wizard.
With the EB CLI, you can use the --instance_type parameter for eb create (p. 474).
Because the recommended values are set at the API level, they will override values for the same options
that you set in configuration files or saved configurations. The following options are set:
Elastic Beanstalk console
• Namespace: aws:autoscaling:launchconfiguration
Option Names: IamInstanceProfile, EC2KeyName, InstanceType
• Namespace: aws:autoscaling:updatepolicy:rollingupdate
API Version 2010-12-01
195
AWS Elastic Beanstalk Developer Guide
Recommended Values
Option Names: RollingUpdateType and RollingUpdateEnabled
• Namespace: aws:elasticbeanstalk:application
Option Name: Application Healthcheck URL
• Namespace: aws:elasticbeanstalk:command
Option Name: DeploymentPolicy, BatchSize and BatchSizeType
• Namespace: aws:elasticbeanstalk:environment
Option Name: ServiceRole
• Namespace: aws:elasticbeanstalk:healthreporting:system
Option Name: SystemType and HealthCheckSuccessThreshold
• Namespace: aws:elasticbeanstalk:sns:topics
Option Name: Notification Endpoint
• Namespace: aws:elasticbeanstalk:sqsd
Option Name: HttpConnections
• Namespace: aws:elb:loadbalancer
Option Name: CrossZone
• Namespace: aws:elb:policies
Option Names: ConnectionDrainingTimeout and ConnectionDrainingEnabled
EB CLI
• Namespace: aws:autoscaling:launchconfiguration
Option Names: IamInstanceProfile, InstanceType
• Namespace: aws:autoscaling:updatepolicy:rollingupdate
Option Names: RollingUpdateType and RollingUpdateEnabled
• Namespace: aws:elasticbeanstalk:command
Option Name: BatchSize and BatchSizeType
• Namespace: aws:elasticbeanstalk:environment
Option Name: ServiceRole
• Namespace: aws:elasticbeanstalk:healthreporting:system
Option Name: SystemType
• Namespace: aws:elb:loadbalancer
Option Name: CrossZone
• Namespace: aws:elb:policies
Option Names: ConnectionDrainingEnabled
If you use the Elastic Beanstalk console or EB CLI to create environments, and you want to set these
options using configuration files or saved configurations, you can remove the options settings with the
AWS CLI (p. 160) or EB CLI (p. 157) after the environment is created.
API Version 2010-12-01
196
AWS Elastic Beanstalk Developer Guide
.ebextensions
Advanced Environment Customization with
Configuration Files (
)
.ebextensions
You can add AWS Elastic Beanstalk configuration files (.ebextensions) to your web application's source
code to configure your environment and customize the AWS resources that it contains. Configuration
files are YAML formatted documents with a .config file extension that you place in a folder named
.ebextensions and deploy in your application source bundle.
The option_settings section of a configuration file defines values for configuration options (p. 145).
Configuration options let you configure your Elastic Beanstalk environment, the AWS resources in it,
and the software that runs your application. Configuration files are only one of several ways to set
configuration options.
The resources section lets you further customize the resources in your application's environment, and
define additional AWS resources beyond the functionality provided by configuration options. You can
use resources to add and configure any resources supported by AWS CloudFormation, which Elastic
Beanstalk uses to create environments.
The other sections of a configuration file (packages, sources, files, users, groups, commands,
container_commands, and services) let you configure the EC2 instances that are launched in your
environment. Whenever a server is launched in your environment, Elastic Beanstalk runs the operations
defined in these sections to prepare the operating system and storage system for your application.
One configuration file can contain multiple sections, or you can split your configuration into multiple
files. Configuration files are processed in alphabetical order, so you can split your configuration activities
into multiple stages.
To use configuration files, add them to a folder named .ebextensions in your source bundle and deploy
it to your environment.
If you are deploying a single application, put your .ebextensions folder in the root of your app source:
~/workspace/my-app/
|-- .ebextensions
|
|-- environmentvariables.config
|
`-- healthcheckurl.config
|-- .elasticbeanstalk
|
`-- config.yml
|-- index.php
`-- styles.css
If you are deploying multiple applications or an ASP.NET Core application, put your .ebextensions folder
in the root of the source bundle, side by side with the application bundles and manifest file:
~/workspace/source-bundle/
|-- .ebextensions
|
|-- environmentvariables.config
|
`-- healthcheckurl.config
|-- AspNetCore101HelloWorld.zip
|-- AspNetCoreHelloWorld.zip
|-- aws-windows-deployment-manifest.json
`-- VS2015AspNetWebApiApp.zip
The process varies slightly depending on the client that you use to manage your environments. See the
following sections for details:
• Elastic Beanstalk Console (p. 150)
API Version 2010-12-01
197
AWS Elastic Beanstalk Developer Guide
Option Settings
• EB CLI (p. 151)
• AWS CLI (p. 152)
When you are developing or testing new configuration files, launch a clean environment running
the default application and deploy to that. Poorly formatted configuration files will cause a new
environment launch to fail unrecoverably.
Topics
• Option Settings (p. 198)
• Customizing Software on Linux Servers (p. 200)
• Customizing Software on Windows Servers (p. 210)
• Adding and Customizing Elastic Beanstalk Environment Resources (p. 216)
• Functions (p. 232)
Option Settings
You can use the option_settings key to modify the Elastic Beanstalk configuration and define variables
that can be retrieved from your application using environment variables. Some namespaces allow you
to extend the number of parameters, and specify the parameter names. For a list of namespaces and
configuration options, see Configuration Options (p. 145).
Option settings can also be applied directly to an environment during environment creation or an
environment update. Settings applied directly to the environment override the settings for the same
options in configuration files. If you remove settings from an environment's configuration, settings in
configuration files will take effect. See Precedence (p. 194) for details.
Syntax
The standard syntax for option settings is an array of objects, each having a namespace, option_name and
value key.
option_settings:
- namespace: namespace
option_name: option name
value: option value
- namespace: namespace
option_name: option name
value: option value
The namespace key is optional. If you do not specify a namespace, the default used is
aws:elasticbeanstalk:application:environment:
option_settings:
- option_name: option name
value: option value
- option_name: option name
value: option value
Elastic Beanstalk also supports a shorthand syntax for option settings that lets you specify options as
key-value pairs underneath the namespace:
option_settings:
namespace:
API Version 2010-12-01
198
AWS Elastic Beanstalk Developer Guide
Option Settings
option name: option value
Examples
The following examples set a Tomcat platform-specific option in the
aws:elasticbeanstalk:container:tomcat:jvmoptions namespace and an environment property named
MYPARAMETER. In standard YAML format:
Example .ebextensions/options.config
option_settings:
- namespace: aws:elasticbeanstalk:container:tomcat:jvmoptions
option_name: Xmx
value: 256m
- option_name: MYPARAMETER
value: parametervalue
In shorthand format:
Example .ebextensions/options.config
option_settings:
aws:elasticbeanstalk:container:tomcat:jvmoptions:
Xmx: 256m
aws:elasticbeanstalk:application:environment:
MYPARAMETER: parametervalue
In JSON:
Example .ebextensions/options.config
{
}
"option_settings": [
{
"namespace": "aws:elasticbeanstalk:container:tomcat:jvmoptions",
"option_name": "Xmx",
"value": "256m"
},
{
"option_name": "MYPARAMETER",
"value": "parametervalue"
}
]
Accessing Environment Variables
The parameters specified in the option_settings section of the configuration file are passed in as
environment variables to the EC2 instances. For coding examples, see the following sections:
• Java (p. 638)
• .NET (p. 662)
• Node.js (p. 723)
• PHP (p. 754)
• Python (p. 805)
• Ruby (p. 825)
API Version 2010-12-01
199
AWS Elastic Beanstalk Developer Guide
Server Customization (Linux)
Customizing Software on Linux Servers
You may want to customize and configure the software that your application depends on. These files
could be either dependencies required by the application—for example, additional packages from the
yum repository—or they could be configuration files such as a replacement for httpd.conf to override
specific settings that are defaulted by Elastic Beanstalk.
Note
YAML relies on consistent indentation. Match the indentation level when replacing content in an
example configuration file and make sure that your text editor uses spaces, not tab characters,
to indent.
This section describes the type of information you can include in a configuration file to customize
the software on your EC2 instances running Linux. For general information about customizing
and configuring your Elastic Beanstalk environments, see AWS Elastic Beanstalk Environment
Configuration (p. 144). For information about customizing software on your EC2 instances running
Windows, see Customizing Software on Windows Servers (p. 210).
Configuration files support the following keys that affect the Linux server your application runs on.
Keys
• Packages (p. 200)
• Groups (p. 201)
• Users (p. 202)
• Sources (p. 202)
• Files (p. 203)
• Commands (p. 205)
• Services (p. 206)
• Container Commands (p. 207)
• Example: Using Custom Amazon CloudWatch Metrics (p. 208)
Keys are processed in the order that they are listed above.
Packages
You can use the packages key to download and install prepackaged applications and components.
Syntax
packages:
name of package manager:
package name: version
Supported Package Formats
Elastic Beanstalk currently supports the following package managers: yum, rubygems, python, and rpm.
Packages are processed in the following order: rpm, yum, and then rubygems and python. There is no
ordering between rubygems and python, and packages within each package manager are not guaranteed
to be installed in any order. Use a package manager supported by your operating system.
Note
Elastic Beanstalk supports two underlying package managers for Python, pip and easy_install.
However, in the syntax of the configuration file, you must specify the package manager name
as python. When you use a configuration file to specify a Python package manager, Elastic
Beanstalk uses Python 2.7. If your application relies on a different version of Python, you
API Version 2010-12-01
200
AWS Elastic Beanstalk Developer Guide
Server Customization (Linux)
can specify the packages to install in a requirements.txt file. For more information, see
Configuration Files (p. 806).
Specifying Versions
Within each package manager, each package is specified as a package name and a list of versions. The
version can be a string, a list of versions, or an empty string or list. An empty string or list indicates that
you want the latest version. For rpm manager, the version is specified as a path to a file on disk or a URL.
Relative paths are not supported.
If you specify a version of a package, Elastic Beanstalk attempts to install that version even if a newer
version of the package is already installed on the instance. If a newer version is already installed, the
deployment fails. Some package managers support multiple versions, but others may not. Please check
the documentation for your package manager for more information. If you do not specify a version and
a version of the package is already installed, Elastic Beanstalk does not install a new version—it assumes
that you want to keep and use the existing version.
Example Snippet
The following snippet specifies a version URL for rpm, requests the latest version from yum, and version
0.10.2 of chef from rubygems.
packages:
yum:
libmemcached: []
ruby-devel: []
gcc: []
rpm:
epel: http://download.fedoraproject.org/pub/epel/5/i386/epel-release-5-4.noarch.rpm
rubygems:
chef: '0.10.2'
Groups
You can use the groups key to create Linux/UNIX groups and to assign group IDs. To create a group, add
a new key-value pair that maps a new group name to an optional group ID. The groups key can contain
one or more group names. The following table lists the available keys.
Syntax
groups:
name of group: {}
name of group:
gid: "group id"
Options
gid
A group ID number.
If a group ID is specified, and the group already exists by name, the group creation will fail. If
another group has the specified group ID, the operating system may reject the group creation.
Example Snippet
The following snippet specifies a group named groupOne without assigning a group ID and a group
named groupTwo that specified a group ID value of 45.
API Version 2010-12-01
201
AWS Elastic Beanstalk Developer Guide
Server Customization (Linux)
groups:
groupOne: {}
groupTwo:
gid: "45"
Users
You can use the users key to create Linux/UNIX users on the EC2 instance.
Syntax
users:
name of user:
groups:
- name of group
uid: "id of the user"
homeDir: "user's home directory"
Options
uid
A user ID. The creation process fails if the user name exists with a different user ID. If the user ID is
already assigned to an existing user, the operating system may reject the creation request.
groups
A list of group names. The user is added to each group in the list.
homeDir
The user's home directory.
Users are created as noninteractive system users with a shell of /sbin/nologin. This is by design and
cannot be modified.
Example Snippet
users:
myuser:
groups:
- group1
- group2
uid: "50"
homeDir: "/tmp"
Sources
You can use the sources key to download an archive file from a public URL and unpack it in a target
directory on the EC2 instance.
Syntax
sources:
target directory: location of archive file
API Version 2010-12-01
202
AWS Elastic Beanstalk Developer Guide
Server Customization (Linux)
Supported Formats
Supported formats are tar, tar+gzip, tar+bz2, and zip. You can reference external locations such as
Amazon Simple Storage Service (Amazon S3) (e.g., http://s3.amazonaws.com/mybucket/myobject) as
long as the URL is publicly accessible.
Example Snippet
The following example downloads a public .zip file from an Amazon S3 bucket and unpacks it into /etc/
myapp:
sources:
/etc/myapp: http://s3.amazonaws.com/mybucket/myobject
Files
You can use the files key to create files on the EC2 instance. The content can be either inline in the
configuration file, or the content can be pulled from a URL. The files are written to disk in lexicographic
order.
You can use the files key to download private files from Amazon S3 by providing an instance profile for
authorization.
Syntax
files:
"target file location on disk":
mode: "six-digit octal value"
owner: name of owning user for file
group: name of owning group for file
source: URL
authentication: authentication name:
"target file location on disk":
mode: "six-digit octal value"
owner: name of owning user for file
group: name of owning group for file
content: |
this is my content
encoding: encoding format
authentication: authentication name:
Options
content
String content to add to the file. Specify either content or source, but not both.
source
URL of a file to download. Specify either content or source, but not both.
encoding
The encoding format of the string specified with the content option.
Valid values: plain | base64
group
Linux group that owns the file.
API Version 2010-12-01
203
AWS Elastic Beanstalk Developer Guide
Server Customization (Linux)
owner
Linux user that owns the file.
mode
A six-digit octal value representing the mode for this file (e.g, 000444). The first three digits are used
for symlinks and the last three digits are used for setting permissions on the file.
authentication
The name of a AWS CloudFormation authentication method to use. You can add authentication
methods to the autoscaling group metadata with the Resources key. See below for an example.
Example Snippet
files:
"/home/ec2-user/myfile" :
mode: "000755"
owner: root
group: root
source: http://foo.bar/myfile
"/home/ec2-user/myfile2" :
mode: "000755"
owner: root
group: root
content: |
# this is my file
# with content
Example using a symlink. This creates a link /tmp/myfile2.txt that points at the existing file /tmp/
myfile1.txt.
files:
"/tmp/myfile2.txt" :
mode: "120400"
content: "/tmp/myfile1.txt"
The following example uses the Resources key to add an authentication method named S3Auth and uses
it to download a private file from an Amazon S3 bucket:
Resources:
AWSEBAutoScalingGroup:
Metadata:
AWS::CloudFormation::Authentication:
S3Auth:
type: "s3"
buckets: ["elasticbeanstalk-us-west-2-123456789012"]
roleName:
"Fn::GetOptionSetting":
Namespace: "aws:autoscaling:launchconfiguration"
OptionName: "IamInstanceProfile"
DefaultValue: "aws-elasticbeanstalk-ec2-role"
files:
"/tmp/data.json" :
mode: "000755"
owner: root
group: root
authentication: "S3Auth"
API Version 2010-12-01
204
AWS Elastic Beanstalk Developer Guide
Server Customization (Linux)
source: https://s3-us-west-2.amazonaws.com/elasticbeanstalk-us-west-2-123456789012/
data.json
Commands
You can use the commands key to execute commands on the EC2 instance. The commands are processed
in alphabetical order by name, and they run before the application and web server are set up and the
application version file is extracted.
By default, commands run in the root directory. To run commands from another directory, use the cwd
option.
Syntax
commands:
command name:
command: command to run
cwd: working directory
env:
variable name: variable value
test: conditions for command
ignoreErrors: true
Options
command
Either an array or a string specifying the command to run. If you use an array, you do not need to
escape space characters or enclose command parameters in quotes.
env
(Optional) Sets environment variables for the command. This property overwrites, rather than
appends, the existing environment.
cwd
(Optional) The working directory. If not specified, commands run from the root directory (/).
test
(Optional) A command that must return the value true (exit code 0) in order for Elastic Beanstalk to
process the command, such as a shell script, contained in the command key.
ignoreErrors
(Optional) A boolean value that determines if other commands should run if the command
contained in the command key fails (returns a nonzero value). Set this value to true if you want to
continue running commands even if the command fails. Set it to false if you want to stop running
commands if the command fails. The default value is false.
Example Snippet
The following example snippet runs a python script.
commands:
python_install:
command: myscript.py
cwd: /home/ec2-user
env:
myvarname: myvarvalue
test: "[ -x /usr/bin/python ]"
API Version 2010-12-01
205
AWS Elastic Beanstalk Developer Guide
Server Customization (Linux)
Services
You can use the services key 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 so
that if a restart is needed due to files being installed, Elastic Beanstalk takes care of the service restart.
Syntax
services:
sysvinit:
name of service:
enabled: "true"
ensureRunning: "true"
files:
- "file name"
sources:
- "directory"
packages:
name of package manager:
"package name[: version]"
commands:
- "name of command"
Options
ensureRunning
Set to true to ensure that the service is running after Elastic Beanstalk finishes.
Set to false to ensure that the service is not running after Elastic Beanstalk finishes.
Omit this key to make no changes to the service state.
enabled
Set to true to ensure that the service is started automatically upon boot.
Set to false to ensure that the service is not started automatically upon boot.
Omit this key to make no changes to this property.
files
A list of files. If Elastic Beanstalk changes one directly via the files block, the service is restarted.
sources
A list of directories. If Elastic Beanstalk expands an archive into one of these directories, the service
is restarted.
packages
A map of the package manager to a list of package names. If Elastic Beanstalk installs or updates
one of these packages, the service is restarted.
commands
A list of command names. If Elastic Beanstalk runs the specified command, the service is restarted.
Example Snippet
The following is an example snippet:
services:
API Version 2010-12-01
206
AWS Elastic Beanstalk Developer Guide
Server Customization (Linux)
sysvinit:
myservice:
enabled: true
ensureRunning: true
Container Commands
You can use the container_commands key to execute commands that affect your application source code.
Container commands run after the application and web server have been set up and the application
version archive has been extracted, but before the application version is deployed. Non-container
commands and other customization operations are performed prior to the application source code being
extracted.
Container commands are run from the staging directory, where your source code is extracted prior to
being deployed to the application server. Any changes you make to your source code in the staging
directory with a container command will be included when the source is deployed to its final location.
You can use leader_only to only run the command on a single instance, or configure a test to only
run the command when a test command evaluates to true. Leader-only container commands are
only executed during environment creation and deployments, while other commands and server
customization operations are performed every time an instance is provisioned or updated. Leader-only
container commands are not executed due to launch configuration changes, such as a change in the AMI
Id or instance type.
Syntax
container_commands:
name of container_command:
command: "command to run"
leader_only: true
name of container_command:
command: "command to run"
Options
command
A string or array of strings to run.
env
(Optional) Set environment variables prior to running the command, overriding any existing value.
cwd
(Optional) The working directory. By default, this is the staging directory of the unzipped
application.
leader_only
(Optional) Only run the command on a single instance chosen by Elastic Beanstalk. Leader-only
container commands are run before other container commands. A command can be leader-only or
have a test, but not both (leader_only takes precedence).
test
(Optional) Run a test command that must return the true in order to run the container command. A
command can be leader-only or have a test, but not both (leader_only takes precedence).
ignoreErrors
(Optional) Do not fail deployments if the container command returns a value other than 0 (success).
Set to true to enable.
API Version 2010-12-01
207
AWS Elastic Beanstalk Developer Guide
Server Customization (Linux)
Example Snippet
The following is an example snippet.
container_commands:
collectstatic:
command: "django-admin.py collectstatic --noinput"
01syncdb:
command: "django-admin.py syncdb --noinput"
leader_only: true
02migrate:
command: "django-admin.py migrate"
leader_only: true
99customize:
command: "scripts/customize.sh"
Example: Using Custom Amazon CloudWatch Metrics
Amazon CloudWatch is a web service that enables you to monitor, manage, and publish various metrics,
as well as configure alarm actions based on data from metrics. You can define custom metrics for
your own use, and Elastic Beanstalk will push those metrics to Amazon CloudWatch. Once Amazon
CloudWatch contains your custom metrics, you can view those in the Amazon CloudWatch console.
The Amazon CloudWatch Monitoring Scripts for Linux are available to demonstrate how to produce
and consume Amazon CloudWatch custom metrics. The scripts comprise a fully functional example that
reports memory, swap, and disk space utilization metrics for an Amazon Elastic Compute Cloud (Amazon
EC2) Linux instance. For more information about the Amazon CloudWatch Monitoring Scripts, go to
Amazon CloudWatch Monitoring Scripts for Linux in the Amazon CloudWatch Developer Guide.
Note
Elastic Beanstalk Enhanced Health Reporting (p. 306) has native support for publishing a wide
range of instance and environment metrics to CloudWatch. See Publishing Amazon CloudWatch
Custom Metrics for an Environment (p. 320) for details.
Topics
• .ebextensions Configuration File (p. 208)
• Permissions (p. 209)
• Viewing Metrics in the CloudWatch Console (p. 210)
.ebextensions Configuration File
This example uses commands and option settings in an .ebextensions configuration file to download,
install, and run monitoring scripts provided by Amazon CloudWatch.
To use this sample, save it to a file named cloudwatch.config in a directory named .ebextensions at
the top level of your project directory, then deploy your application using the AWS Management Console
(include the .ebextensions directory in your source bundle (p. 54)) or the EB CLI (p. 434).
For more information about configuration files, see Advanced Environment Customization with
Configuration Files (.ebextensions) (p. 197).
.ebextensions/cloudwatch.config
packages:
yum:
perl-DateTime: []
perl-Sys-Syslog: []
perl-LWP-Protocol-https: []
API Version 2010-12-01
208
AWS Elastic Beanstalk Developer Guide
Server Customization (Linux)
perl-Switch: []
perl-URI: []
perl-Bundle-LWP: []
sources:
/opt/cloudwatch: http://aws-cloudwatch.s3.amazonaws.com/downloads/
CloudWatchMonitoringScripts-1.2.1.zip
container_commands:
01-setupcron:
command: |
echo '*/5 * * * * root perl /opt/cloudwatch/aws-scripts-mon/mon-put-instance-data.pl
`{"Fn::GetOptionSetting" : { "OptionName" : "CloudWatchMetrics", "DefaultValue" : "--memutil --disk-space-util --disk-path=/" }}` >> /var/log/cwpump.log 2>&1' > /etc/cron.d/cwpump
02-changeperm:
command: chmod 644 /etc/cron.d/cwpump
03-changeperm:
command: chmod u+x /opt/cloudwatch/aws-scripts-mon/mon-put-instance-data.pl
option_settings:
"aws:autoscaling:launchconfiguration" :
IamInstanceProfile : "aws-elasticbeanstalk-ec2-role"
"aws:elasticbeanstalk:customoption" :
CloudWatchMetrics : "--mem-util --mem-used --mem-avail --disk-space-util --disk-spaceused --disk-space-avail --disk-path=/ --auto-scaling"
After you verify the configuration file works, you can conserve disk usage by changing the command
redirect from a log file (>> /var/log/cwpump.log 2>&1') to /dev/null (> /dev/null).
Permissions
In order to publish custom Amazon CloudWatch metrics, the instances in your environment need
permission to use CloudWatch. You can grant permissions to your environment's instances by adding
them to the environment's instance profile (p. 19). You can add permissions to the instance profile before
or after deploying your application.
To grant permissions to publish CloudWatch metrics
1.
Open the IAM console at https://console.aws.amazon.com/iam/.
2.
In the navigation pane, choose Roles.
3.
Choose your environment's instance profile role. By default, when you create an environment with
the AWS Management Console or EB CLI (p. 434), this is aws-elasticbeanstalk-ec2-role.
4.
Choose the Permissions tab.
5.
Under Inline Policies, in the Permissions section, choose Create Role Policy.
6.
Choose Custom Policy, and then choose Select.
7.
Complete the following fields, and then choose Apply Policy:
Policy Name
The name of the policy.
Policy Document
Copy and paste the following text into the policy document:
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
API Version 2010-12-01
209
AWS Elastic Beanstalk Developer Guide
Server Customization (Windows)
"cloudwatch:PutMetricData",
"ec2:DescribeTags"
}
]
}
],
"Effect": "Allow",
"Resource": [
"*"
]
For more information about managing policies, see Working with Policies in the IAM User Guide.
Viewing Metrics in the CloudWatch Console
After deploying the CloudWatch configuration file to your environment, check the Amazon CloudWatch
console to view your metrics. Custom metrics will have the prefix Linux System.
Customizing Software on Windows Servers
You may want to customize and configure the software that your application depends on. These files
could be either dependencies required by the application—for example, additional packages or services
that need to be run. For general information on customizing and configuring your Elastic Beanstalk
environments, see AWS Elastic Beanstalk Environment Configuration (p. 144).
Note
YAML relies on consistent indentation. Match the indentation level when replacing content in an
example configuration file and make sure that your text editor uses spaces, not tab characters,
to indent.
Configuration files support the following keys that affect the Windows server on which your application
runs.
API Version 2010-12-01
210
AWS Elastic Beanstalk Developer Guide
Server Customization (Windows)
Keys are processed in the following order.
Note
Older (non-versioned) versions of .NET platform configurations do not process configuration
files in the correct order. Learn more at Migrating to v1 Elastic Beanstalk Windows Server
Platforms (p. 664).
Keys
• Packages (p. 211)
• Sources (p. 211)
• Files (p. 212)
• Commands (p. 213)
• Services (p. 214)
• Container Commands (p. 215)
Packages
Use the packages key to download and install prepackaged applications and components.
Syntax
packages:
name of package manager:
package name: version
Supported Package Formats
Elastic Beanstalk supports MSI packages.
Specifying Versions
Packages are specified as a package name and a URL to the software.
Elastic Beanstalk invokes the package manager associated with your configuration to install the package
you specify, even if a newer version of the package is already installed on the instance. Some package
managers allow you to install an older version; some do not. It is your responsibility to ensure that if you
attempt to install an earlier version of a package, your package manager supports that feature. If you
specify the same version of a package that is already installed, the deployment fails.
Example
The following example specifies a URL to download mysql.
packages:
msi:
mysql: http://dev.mysql.com/get/Downloads/Connector-Net/mysql-connector-net-6.6.5.msi/
from/http://cdn.mysql.com/
Sources
Use the sources key to download an archive file from a public URL and unpack it in a target directory on
the EC2 instance.
API Version 2010-12-01
211
AWS Elastic Beanstalk Developer Guide
Server Customization (Windows)
Syntax
sources:
target directory: location of archive file
Supported Formats
Elastic Beanstalk currently supports .zip format. You can reference external locations such as Amazon
Simple Storage Service (Amazon S3) (e.g., http://s3.amazonaws.com/mybucket/myobject) as long as the
URL is publically accessible.
Example
The following example downloads a public .zip file from an Amazon S3 bucket and unpacks it into c:/
myproject/myapp.
sources:
"c:/myproject/myapp": http://s3.amazonaws.com/mybucket/myobject.zip
Files
Use the files key to create files on the EC2 instance. The content can be either inline in the
configuration file, or from a URL. The files are written to disk in lexicographic order. To download private
files from Amazon S3, provide an instance profile for authorization.
Syntax
files:
"target file location on disk":
source: URL
authentication: authentication name:
"target file location on disk":
content: |
this is my content
encoding: encoding format
Options
content
(Optional) A string.
source
(Optional) The URL from which the file is loaded. This option cannot be specified with the content
key.
encoding
(Optional) The encoding format. This option is only used for a provided content key value. The
default value is plain.
Valid values: plain | base64
authentication
(Optional) The name of a AWS CloudFormation authentication method to use. You can add
authentication methods to the autoscaling group metadata with the Resources key.
API Version 2010-12-01
212
AWS Elastic Beanstalk Developer Guide
Server Customization (Windows)
Example
files:
"c:\\targetdirectory\\targetfile.txt":
source: http://foo.bar/myfile
"c:/targetdirectory/targetfile.txt":
content: |
# this is my file
# with content
Note
If you use a backslash (\) in your file path, you must precede that with another backslash (the
escape character) as shown in the previous example.
Commands
Use the commands key to execute commands on the EC2 instance. The commands are processed in
alphabetical order by name, and they run before the application and web server are set up and the
application version file is extracted.
Syntax
commands:
command name:
command: command to run
Options
command
Either an array or a string specifying the command to run. If you use an array, you do not need to
escape space characters or enclose command parameters in quotes.
cwd
(Optional) The working directory. By default, Elastic Beanstalk attempts to find the directory
location of your project. If not found, it uses c:\Windows\System32 as the default.
env
(Optional) Sets environment variables for the command. This property overwrites, rather than
appends, the existing environment.
ignoreErrors
(Optional) A boolean value that determines if other commands should run if the command
contained in the command key fails (returns a nonzero value). Set this value to true if you want to
continue running commands even if the command fails. Set it to false if you want to stop running
commands if the command fails. The default value is false.
test
(Optional) A command that must return the value true (exit code 0) in order for Elastic Beanstalk to
process the command contained in the command key.
waitAfterCompletion
(Optional) Seconds to wait after the command completes before running the next command. If
the system requires a reboot after the command completes, the system reboots after the specified
API Version 2010-12-01
213
AWS Elastic Beanstalk Developer Guide
Server Customization (Windows)
number of seconds elapses. If the system reboots as a result of a command, Elastic Beanstalk will
recover to the point after the command in the configuration file. The default value is 60 seconds. You
can also specify forever, but the system must reboot before you can run another command.
Example
The following example saves the output of the set command to the specified file. If there is a
subsequent command, Elastic Beanstalk runs that command immediately after this command completes.
If this command requires a reboot, Elastic Beanstalk reboots the instance immediately after the
command completes.
commands:
test:
command: set > c:\\myapp\\set.txt
waitAfterCompletion: 0
Services
Use the services key to define which services should be started or stopped when the instance is
launched. The services key also enables you to specify dependencies on sources, packages, and files so
that if a restart is needed due to files being installed, Elastic Beanstalk takes care of the service restart.
Syntax
services:
windows:
name of service:
files:
- "file name"
sources:
- "directory"
packages:
name of package manager:
"package name[: version]"
commands:
- "name of command"
Options
ensureRunning
(Optional) Set to true to ensure that the service is running after Elastic Beanstalk finishes.
Set to false to ensure that the service is not running after Elastic Beanstalk finishes.
Omit this key to make no changes to the service state.
enabled
(Optional) Set to true to ensure that the service is started automatically upon boot.
Set to false to ensure that the service is not started automatically upon boot.
Omit this key to make no changes to this property.
files
A list of files. If Elastic Beanstalk changes one directly via the files block, the service is restarted.
API Version 2010-12-01
214
AWS Elastic Beanstalk Developer Guide
Server Customization (Windows)
sources
A list of directories. If Elastic Beanstalk expands an archive into one of these directories, the service
is restarted.
packages
A map of the package manager to a list of package names. If Elastic Beanstalk installs or updates
one of these packages, the service is restarted.
commands
A list of command names. If Elastic Beanstalk runs the specified command, the service is restarted.
Example
services:
windows:
myservice:
enabled: true
ensureRunning: true
Container Commands
Use the container_commands key to execute commands that affect your application source code.
Container commands run after the application and web server have been set up and the application
version archive has been extracted, but before the application version is deployed. Non-container
commands and other customization operations are performed prior to the application source code being
extracted.
Container commands are run from the staging directory, where your source code is extracted prior to
being deployed to the application server. Any changes you make to your source code in the staging
directory with a container command will be included when the source is deployed to its final location.
Use the leader_only option to only run the command on a single instance, or configure a test to
only run the command when a test command evaluates to true. Leader-only container commands
are only executed during environment creation and deployments, while other commands and server
customization operations are performed every time an instance is provisioned or updated. Leader-only
container commands are not executed due to launch configuration changes, such as a change in the AMI
Id or instance type.
Syntax
container_commands:
name of container_command:
command: command to run
Options
command
A string or array of strings to run.
env
(Optional) Set environment variables prior to running the command, overriding any existing value.
cwd
(Optional) The working directory. By default, this is the staging directory of the unzipped
application.
API Version 2010-12-01
215
AWS Elastic Beanstalk Developer Guide
Custom Resources
leader_only
(Optional) Only run the command on a single instance chosen by Elastic Beanstalk. Leader-only
container commands are run before other container commands. A command can be leader-only or
have a test, but not both (leader_only takes precedence).
test
(Optional) Run a test command that must return the true in order to run the container command. A
command can be leader-only or have a test, but not both (leader_only takes precedence).
ignoreErrors
(Optional) Do not fail deployments if the container command returns a value other than 0 (success).
Set to true to enable.
waitAfterCompletion
(Optional) Seconds to wait after the command completes before running the next command. If
the system requires a reboot after the command completes, the system reboots after the specified
number of seconds elapses. If the system reboots as a result of a command, Elastic Beanstalk will
recover to the point after the command in the configuration file. The default value is 60 seconds. You
can also specify forever, but the system must reboot before you can run another command.
Example
The following example saves the output of the set command to the specified file. Elastic Beanstalk runs
the command on one instance, and reboots the instance immediately after the command completes.
container_commands:
foo:
command: set > c:\\myapp\\set.txt
leader_only: true
waitAfterCompletion: 0
Adding and Customizing Elastic Beanstalk
Environment Resources
You may also want to customize your environment resources that are part of your Elastic Beanstalk
environment. For example, you may want to add an Amazon SQS queue and an alarm on queue depth,
or you might want to add an Amazon ElastiCache cluster. You can easily customize your environment at
the same time that you deploy your application version by including a configuration file with your source
bundle.
You can use the Resources key in a configuration file (p. 197) to create and customize AWS resources
in your environment. Resources defined in configuration files are added to the AWS CloudFormation
template used to launch your environment. All AWS CloudFormation resources types are supported.
For example, the following configuration file adds an Auto Scaling lifecycle hook to the default Auto
Scaling group created by Elastic Beanstalk:
~/my-app/.ebextensions/as-hook.config
Resources:
hookrole:
Type: AWS::IAM::Role
Properties:
API Version 2010-12-01
216
AWS Elastic Beanstalk Developer Guide
Custom Resources
AssumeRolePolicyDocument: {
"Version" : "2012-10-17",
"Statement": [ {
"Effect": "Allow",
"Principal": {
"Service": [ "autoscaling.amazonaws.com" ]
},
"Action": [ "sts:AssumeRole" ]
} ]
}
Policies: [ {
"PolicyName": "SNS",
"PolicyDocument": {
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Resource": "*",
"Action": [
"sqs:SendMessage",
"sqs:GetQueueUrl",
"sns:Publish"
]
}
]
}
} ]
hooktopic:
Type: AWS::SNS::Topic
Properties:
Subscription:
- Endpoint: "[email protected]"
Protocol: email
lifecyclehook:
Type: AWS::AutoScaling::LifecycleHook
Properties:
AutoScalingGroupName: { "Ref" : "AWSEBAutoScalingGroup" }
LifecycleTransition: autoscaling:EC2_INSTANCE_TERMINATING
NotificationTargetARN: { "Ref" : "hooktopic" }
RoleARN: { "Fn::GetAtt" : [ "hookrole", "Arn"] }
This example defines three resources, hookrole, hooktopic and lifecyclehook. The first two resources
are an IAM role, which grants Auto Scaling permission to publish messages to Amazon SNS, and an SNS
topic, which relays messages from the Auto Scaling group to an email address. Elastic Beanstalk creates
these resources with the specified properties and types.
The final resource, lifecyclehook, is the lifecycle hook itself:
lifecyclehook:
Type: AWS::AutoScaling::LifecycleHook
Properties:
AutoScalingGroupName: { "Ref" : "AWSEBAutoScalingGroup" }
LifecycleTransition: autoscaling:EC2_INSTANCE_TERMINATING
NotificationTargetARN: { "Ref" : "hooktopic" }
RoleARN: { "Fn::GetAtt" : [ "hookrole", "Arn"] }
The lifecycle hook definition uses a few intrinsic functions to populate values for the hook's properties.
{ "Ref" : "AWSEBAutoScalingGroup" } retrieves the name of the Auto Scaling group created by Elastic
Beanstalk for the environment. AWSEBAutoScalingGroup is one of the standard resource names (p. 231)
provided by Elastic Beanstalk.
For AWS::IAM::Role, Ref only returns the name of the role, not the ARN. To get the ARN for the RoleARN
parameter, you use another intrinsic function, Fn::GetAtt instead, which can get any attribute from
API Version 2010-12-01
217
AWS Elastic Beanstalk Developer Guide
Custom Resources
a resource. RoleARN: { "Fn::GetAtt" : [ "hookrole", "Arn"] } gets the Arn attribute from the
hookrole resource.
{ "Ref" : "hooktopic" } gets the ARN of the Amazon SNS topic created earlier in the configuration
file. The value returned by Ref varies per resource type and can be found in the AWS CloudFormation
User Guide topic for the AWS::SNS::Topic resource type.
Example Snippets: ElastiCache
The following samples add an Amazon ElastiCache cluster to EC2-Classic and EC2-VPC (both default and
custom VPC) platforms. For more information about these platforms and how you can determine which
ones EC2 supports for your region and your AWS account, see http://docs.aws.amazon.com/AWSEC2/
latest/UserGuide/ec2-supported-platforms.html. Then refer to the section in this topic that applies to
your platform.
• EC2-Classic Platforms (p. 218)
• EC2-VPC (Default) (p. 219)
• EC2-VPC (Custom) (p. 221)
EC2-Classic Platforms
This sample adds an Amazon ElastiCache cluster to an environment with instances launched into the
EC2-Classic platform. All of the properties that are listed in this example are the minimum required
properties that must be set for each resource type. You can download the example at ElastiCache
Example.
Note
This example creates AWS resources, which you may be charged for. For more information about
AWS pricing, go to http://aws.amazon.com/pricing/. Some services are part of the AWS Free
Usage Tier. If you are a new customer, you may test drive these services for free. Go to http://
aws.amazon.com/free/ for more information.
To use this example, do the following:
1. Create an .ebextensions directory in the top-level directory of your source bundle.
2. Create two configuration files with the .config extension and place them in your .ebextensions
directory. One configuration file defines the resources, and the other configuration file defines the
options.
3. Deploy your application to Elastic Beanstalk.
YAML relies on consistent indentation. Match the indentation level when replacing content in an
example configuration file and make sure that your text editor uses spaces, not tab characters, to
indent.
Create a configuration file (e.g., elasticache.config) that defines the resources. In this example,
we create the ElastiCache cluster by specifying the name of the ElastiCache cluster resource
(MyElastiCache), declaring its type, and then configuring the properties for the cluster. The example
references the name of the ElastiCache security group resource that gets created and defined in this
configuration file. Next, we create an ElastiCache security group. We define the name for this resource,
declare its type, and add a description for the security group. Finally, we set the ingress rules for the
ElastiCache security group to allow access only from instances inside the ElastiCache security group
(MyCacheSecurityGroup) and the Elastic Beanstalk security group (AWSEBSecurityGroup). The parameter
name, AWSEBSecurityGroup, is a fixed resource name provided by Elastic Beanstalk. You must add
AWSEBSecurityGroup to your ElastiCache security group ingress rules in order for your Elastic Beanstalk
application to connect to the instances in your ElastiCache cluster.
API Version 2010-12-01
218
AWS Elastic Beanstalk Developer Guide
Custom Resources
#This sample requires you to create a separate configuration file that defines the custom
option settings for CacheCluster properties.
Resources:
MyElastiCache:
Type: AWS::ElastiCache::CacheCluster
Properties:
CacheNodeType:
Fn::GetOptionSetting:
OptionName : CacheNodeType
DefaultValue: cache.m1.small
NumCacheNodes:
Fn::GetOptionSetting:
OptionName : NumCacheNodes
DefaultValue: 1
Engine:
Fn::GetOptionSetting:
OptionName : Engine
DefaultValue: memcached
CacheSecurityGroupNames:
- Ref: MyCacheSecurityGroup
MyCacheSecurityGroup:
Type: AWS::ElastiCache::SecurityGroup
Properties:
Description: "Lock cache down to webserver access only"
MyCacheSecurityGroupIngress:
Type: AWS::ElastiCache::SecurityGroupIngress
Properties:
CacheSecurityGroupName:
Ref: MyCacheSecurityGroup
EC2SecurityGroupName:
Ref: AWSEBSecurityGroup
For more information about the resources used in this example configuration file, see the following
references:
• AWS::ElastiCache::CacheCluster
• AWS::ElastiCache::SecurityGroup
• AWS::ElastiCache:SecurityGroupIngress
Create a separate configuration file called options.config and define the custom option settings.
option_settings:
"aws:elasticbeanstalk:customoption":
CacheNodeType : cache.m1.small
NumCacheNodes : 1
Engine : memcached
These lines tell Elastic Beanstalk to get the values for the CacheNodeType, NumCacheNodes,
and Engine properties from the CacheNodeType, NumCacheNodes, and Engine values in a
config file (options.config in our example) that contains an option_settings section with an
aws:elasticbeanstalk:customoption section that contains a name-value pair that contains the actual
value to use. In the example above, this means cache.m1.small, 1, and memcached would be used for the
values. For more information about Fn::GetOptionSetting, see Functions (p. 232).
EC2-VPC (Default)
This sample adds an Amazon ElastiCache cluster to an environment with instances launched into the
EC2-VPC platform. Specifically, the information in this section applies to a scenario where EC2 launches
API Version 2010-12-01
219
AWS Elastic Beanstalk Developer Guide
Custom Resources
instances into the default VPC. All of the properties in this example are the minimum required properties
that must be set for each resource type. For more information about default VPCs, see Your Default VPC
and Subnets.
Note
This example creates AWS resources, which you may be charged for. For more information about
AWS pricing, go to http://aws.amazon.com/pricing/. Some services are part of the AWS Free
Usage Tier. If you are a new customer, you may test drive these services for free. Go to http://
aws.amazon.com/free/ for more information.
To use this example, do the following:
1. Create an .ebextensions directory in the top-level directory of your source bundle.
2. Create two configuration files with the .config extension and place them in your .ebextensions
directory. One configuration file defines the resources, and the other configuration file defines the
options.
3. Deploy your application to Elastic Beanstalk.
YAML relies on consistent indentation. Match the indentation level when replacing content in an
example configuration file and make sure that your text editor uses spaces, not tab characters, to
indent.
Now name the resources configuration file elasticache.config. To create the ElastiCache cluster, this
example specifies the name of the ElastiCache cluster resource (MyElastiCache), declares its type, and
then configures the properties for the cluster. The example references the ID of the security group
resource that we create and define in this configuration file.
Next, we create an EC2 security group. We define the name for this resource, declare its type, add a
description, and set the ingress rules for the security group to allow access only from instances inside
the Elastic Beanstalk security group (AWSEBSecurityGroup). (The parameter name, AWSEBSecurityGroup,
is a fixed resource name provided by Elastic Beanstalk. You must add AWSEBSecurityGroup to your
ElastiCache security group ingress rules in order for your Elastic Beanstalk application to connect to the
instances in your ElastiCache cluster.)
The ingress rules for the EC2 security group also define the IP protocol and port numbers on which the
cache nodes can accept connections. For Redis, the default port number is 6379.
#This sample requires you to create a separate configuration file that defines the custom
option settings for CacheCluster properties.
Resources:
MyCacheSecurityGroup:
Type: "AWS::EC2::SecurityGroup"
Properties:
GroupDescription: "Lock cache down to webserver access only"
SecurityGroupIngress :
- IpProtocol : "tcp"
FromPort :
Fn::GetOptionSetting:
OptionName : "CachePort"
DefaultValue: "6379"
ToPort :
Fn::GetOptionSetting:
OptionName : "CachePort"
DefaultValue: "6379"
SourceSecurityGroupName:
Ref: "AWSEBSecurityGroup"
MyElastiCache:
Type: "AWS::ElastiCache::CacheCluster"
Properties:
API Version 2010-12-01
220
AWS Elastic Beanstalk Developer Guide
Custom Resources
CacheNodeType:
Fn::GetOptionSetting:
OptionName : "CacheNodeType"
DefaultValue : "cache.t1.micro"
NumCacheNodes:
Fn::GetOptionSetting:
OptionName : "NumCacheNodes"
DefaultValue : "1"
Engine:
Fn::GetOptionSetting:
OptionName : "Engine"
DefaultValue : "redis"
VpcSecurityGroupIds:
Fn::GetAtt:
- MyCacheSecurityGroup
- GroupId
Outputs:
ElastiCache:
Description : "ID of ElastiCache Cache Cluster with Redis Engine"
Value :
Ref : "MyElastiCache"
For more information about the resources used in this example configuration file, see the following
references:
• AWS::ElastiCache::CacheCluster
• AWS::EC2::SecurityGroup
Next, name the options configuration file options.config and define the custom option settings.
option_settings:
"aws:elasticbeanstalk:customoption":
CacheNodeType : cache.t1.micro
NumCacheNodes : 1
Engine : redis
CachePort : 6379
These lines tell Elastic Beanstalk to get the values for the CacheNodeType, NumCacheNodes, Engine, and
CachePort properties from the CacheNodeType, NumCacheNodes, Engine, and CachePort values in a config
file (options.config in our example). That file includes an aws:elasticbeanstalk:customoption section
(under option_settings) that contains name-value pairs with the actual values to use. In the preceding
example, cache.t1.micro, 1, redis, and 6379 would be used for the values. For more information about
Fn::GetOptionSetting, see Functions (p. 232).
EC2-VPC (Custom)
If you create a custom VPC on the EC2-VPC platform and specify it as the VPC into which EC2 launches
instances, the process of adding an Amazon ElastiCache cluster to your environment differs from that of
a default VPC. The main difference is that you must create a subnet group for the ElastiCache cluster. All
of the properties in this example are the minimum required properties that must be set for each resource
type.
Note
This example creates AWS resources, which you may be charged for. For more information about
AWS pricing, go to http://aws.amazon.com/pricing/. Some services are part of the AWS Free
Usage Tier. If you are a new customer, you may test drive these services for free. Go to http://
aws.amazon.com/free/ for more information.
API Version 2010-12-01
221
AWS Elastic Beanstalk Developer Guide
Custom Resources
To use this example, do the following:
1. Create an .ebextensions directory in the top-level directory of your source bundle.
2. Create two configuration files with the .config extension and place them in your .ebextensions
directory. One configuration file defines the resources, and the other configuration file defines the
options.
3. Deploy your application to Elastic Beanstalk.
YAML relies on consistent indentation. Match the indentation level when replacing content in an
example configuration file and make sure that your text editor uses spaces, not tab characters, to
indent.
Now name the resources configuration file elasticache.config. To create the ElastiCache cluster, this
example specifies the name of the ElastiCache cluster resource (MyElastiCache), declares its type, and
then configures the properties for the cluster. The properties in the example reference the name of the
subnet group for the ElastiCache cluster as well as the ID of security group resource that we create and
define in this configuration file.
Next, we create an EC2 security group. We define the name for this resource, declare its type,
add a description, the VPC ID, and set the ingress rules for the security group to allow access only
from instances inside the Elastic Beanstalk security group (AWSEBSecurityGroup). (The parameter
name, AWSEBSecurityGroup, is a fixed resource name provided by Elastic Beanstalk. You must add
AWSEBSecurityGroup to your ElastiCache security group ingress rules in order for your Elastic Beanstalk
application to connect to the instances in your ElastiCache cluster.)
The ingress rules for the EC2 security group also define the IP protocol and port numbers on which the
cache nodes can accept connections. For Redis, the default port number is 6379. Finally, this example
creates a subnet group for the ElastiCache cluster. We define the name for this resource, declare its type,
and add a description and ID of the subnet in the subnet group.
Note
We recommend that you use private subnets for the ElastiCache cluster. For more information
about a VPC with a private subnet, see http://docs.aws.amazon.com/AmazonVPC/latest/
UserGuide/VPC_Scenario2.html.
#This sample requires you to create a separate configuration file that defines the custom
option settings for CacheCluster properties.
Resources:
MyElastiCache:
Type: "AWS::ElastiCache::CacheCluster"
Properties:
CacheNodeType:
Fn::GetOptionSetting:
OptionName : "CacheNodeType"
DefaultValue : "cache.t1.micro"
NumCacheNodes:
Fn::GetOptionSetting:
OptionName : "NumCacheNodes"
DefaultValue : "1"
Engine:
Fn::GetOptionSetting:
OptionName : "Engine"
DefaultValue : "redis"
CacheSubnetGroupName:
Ref: "MyCacheSubnets"
VpcSecurityGroupIds:
- Ref: "MyCacheSecurityGroup"
MyCacheSecurityGroup:
Type: "AWS::EC2::SecurityGroup"
API Version 2010-12-01
222
AWS Elastic Beanstalk Developer Guide
Custom Resources
Properties:
GroupDescription: "Lock cache down to webserver access only"
VpcId:
Fn::GetOptionSetting:
OptionName : "VpcId"
SecurityGroupIngress :
- IpProtocol : "tcp"
FromPort :
Fn::GetOptionSetting:
OptionName : "CachePort"
DefaultValue: "6379"
ToPort :
Fn::GetOptionSetting:
OptionName : "CachePort"
DefaultValue: "6379"
SourceSecurityGroupId:
Ref: "AWSEBSecurityGroup"
MyCacheSubnets:
Type: "AWS::ElastiCache::SubnetGroup"
Properties:
Description: "Subnets for ElastiCache"
SubnetIds:
Fn::GetOptionSetting:
OptionName : "CacheSubnets"
Outputs:
ElastiCache:
Description : "ID of ElastiCache Cache Cluster with Redis Engine"
Value :
Ref : "MyElastiCache"
For more information about the resources used in this example configuration file, see the following
references:
• AWS::ElastiCache::CacheCluster
• AWS::EC2::SecurityGroup
• AWS::ElastiCache::SubnetGroup
Next, name the options configuration file options.config and define the custom option settings.
Note
In the following example, replace the example CacheSubnets and VpcId values with your own
subnets and VPC.
option_settings:
"aws:elasticbeanstalk:customoption":
CacheNodeType : cache.t1.micro
NumCacheNodes : 1
Engine : redis
CachePort : 6379
CacheSubnets:
- subnet-1a1a1a1a
- subnet-2b2b2b2b
- subnet-3c3c3c3c
VpcId: vpc-4d4d4d4d
These lines tell Elastic Beanstalk to get the values for the CacheNodeType, NumCacheNodes, Engine,
CachePort, CacheSubnets, and VpcId properties from the CacheNodeType, NumCacheNodes, Engine,
CachePort, CacheSubnets, and VpcId values in a config file (options.config in our example). That file
includes an aws:elasticbeanstalk:customoption section (under option_settings) that contains namevalue pairs with sample values. In the example above, cache.t1.micro, 1, redis, 6379, subnet-1a1a1a1a,
API Version 2010-12-01
223
AWS Elastic Beanstalk Developer Guide
Custom Resources
subnet-2b2b2b2b, subnet-3c3c3c3c, and vpc-4d4d4d4d would be used for the values. For more
information about Fn::GetOptionSetting, see Functions (p. 232).
Example Snippet: SQS, CloudWatch, and SNS
This example adds an Amazon SQS queue and an alarm on queue depth to the environment. The
properties that you see in this example are the minimum required properties that you must set for each
of these resources. You can download the example at SQS, SNS, and CloudWatch.
Note
This example creates AWS resources, which you may be charged for. For more information about
AWS pricing, go to http://aws.amazon.com/pricing/. Some services are part of the AWS Free
Usage Tier. If you are a new customer, you may test drive these services for free. Go to http://
aws.amazon.com/free/ for more information.
To use this example, do the following:
1. Create an .ebextensions directory in the top-level directory of your source bundle.
2. Create two configuration files with the .config extension and place them in your .ebextensions
directory. One configuration file defines the resources, and the other configuration file defines the
options.
3. Deploy your application to Elastic Beanstalk.
YAML relies on consistent indentation. Match the indentation level when replacing content in an
example configuration file and make sure that your text editor uses spaces, not tab characters, to
indent.
Create a configuration file (e.g., sqs.config) that defines the resources. In this example, we create an
SQS queue and define the VisbilityTimeout property in the MySQSQueue resource. Next, we create an
SNS Topic and specify that email gets sent to [email protected] when the alarm is fired. Finally,
we create a CloudWatch alarm if the queue grows beyond 10 messages. In the Dimensions property,
we specify the name of the dimension and the value representing the dimension measurement. We use
Fn::GetAtt to return the value of QueueName from MySQSQueue.
#This sample requires you to create a separate configuration file to define the custom
options for the SNS topic and SQS queue.
Resources:
MySQSQueue:
Type: AWS::SQS::Queue
Properties:
VisibilityTimeout:
Fn::GetOptionSetting:
OptionName: VisibilityTimeout
DefaultValue: 30
AlarmTopic:
Type: AWS::SNS::Topic
Properties:
Subscription:
- Endpoint:
Fn::GetOptionSetting:
OptionName: AlarmEmail
DefaultValue: "[email protected]"
Protocol: email
QueueDepthAlarm:
Type: AWS::CloudWatch::Alarm
Properties:
AlarmDescription: "Alarm if queue depth grows beyond 10 messages"
Namespace: "AWS/SQS"
MetricName: ApproximateNumberOfMessagesVisible
API Version 2010-12-01
224
AWS Elastic Beanstalk Developer Guide
Custom Resources
Dimensions:
- Name: QueueName
Value : { "Fn::GetAtt" : [ "MySQSQueue", "QueueName"] }
Statistic: Sum
Period: 300
EvaluationPeriods: 1
Threshold: 10
ComparisonOperator: GreaterThanThreshold
AlarmActions:
- Ref: AlarmTopic
InsufficientDataActions:
- Ref: AlarmTopic
Outputs :
QueueURL:
Description : "URL of newly created SQS Queue"
Value : { Ref : "MySQSQueue" }
QueueARN :
Description : "ARN of newly created SQS Queue"
Value : { "Fn::GetAtt" : [ "MySQSQueue", "Arn"]}
QueueName :
Description : "Name newly created SQS Queue"
Value : { "Fn::GetAtt" : [ "MySQSQueue", "QueueName"]}
For more information about the resources used in this example configuration file, see the following
references:
• AWS::SQS::Queue
• AWS::SNS::Topic
• AWS::CloudWatch::Alarm
Create a separate configuration file called options.config and define the custom option settings.
option_settings:
"aws:elasticbeanstalk:customoption":
VisibilityTimeout : 30
AlarmEmail : "[email protected]"
These lines tell Elastic Beanstalk to get the values for the VisibilityTimeout and Subscription Endpoint
properties from the VisibilityTimeout and Subscription Endpoint values in a config file (options.config
in our example) that contains an option_settings section with an aws:elasticbeanstalk:customoption
section that contains a name-value pair that contains the actual value to use. In the example above,
this means 30 and "[email protected]" would be used for the values. For more information about
Fn::GetOptionSetting, see Functions (p. 232)
Example: DynamoDB, CloudWatch, and SNS
This configuration file sets up the DynamoDB table as a session handler for a PHP-based application
using the AWS SDK for PHP 2. To use this example, you must have an IAM instance profile, which is
added to the instances in your environment and used to access the DynamoDB table.
You can download the sample that we'll use in this step at DynamoDB Session Support Example. The
sample contains the following files:
• The sample application, index.php
• A configuration file, dynamodb.config, to create and configure a DynamoDB table and other AWS
resources as well as install software on the EC2 instances that host the application in an Elastic
Beanstalk environment
API Version 2010-12-01
225
AWS Elastic Beanstalk Developer Guide
Custom Resources
• An configuration file, options.config, that overrides the defaults in dynamodb.config with specific
settings for this particular installation
index.php
<?php
// Include the SDK using the Composer autoloader
require '../vendor/autoload.php';
use Aws\DynamoDb\DynamoDbClient;
// Grab the session table name and region from the configuration file
list($tableName, $region) = file(__DIR__ . '/../sessiontable');
$tableName = rtrim($tableName);
$region = rtrim($region);
// Create a DynamoDB client and register the table as the session handler
$dynamodb = DynamoDbClient::factory(array('region' => $region));
$handler = $dynamodb->registerSessionHandler(array('table_name' => $tableName, 'hash_key'
=> 'username'));
// Grab the instance ID so we can display the EC2 instance that services the request
$instanceId = file_get_contents("http://169.254.169.254/latest/meta-data/instance-id");
?>
<h1>Elastic Beanstalk PHP Sessions Sample</h1>
<p>This sample application shows the integration of the Elastic Beanstalk PHP
container and the session support for DynamoDB from the AWS SDK for PHP 2.
Using DynamoDB session support, the application can be scaled out across
multiple web servers. For more details, see the
<a href="http://aws.amazon.com/php/">PHP Developer Center</a>.</p>
<form id="SimpleForm" name="SimpleForm" method="post" action="index.php">
<?php
echo 'Request serviced from instance ' . $instanceId . '<br/>';
echo '<br/>';
if (isset($_POST['continue'])) {
session_start();
$_SESSION['visits'] = $_SESSION['visits'] + 1;
echo 'Welcome back ' . $_SESSION['username'] . '<br/>';
echo 'This is visit number ' . $_SESSION['visits'] . '<br/>';
session_write_close();
echo '<br/>';
echo '<input type="Submit" value="Refresh" name="continue" id="continue"/>';
echo '<input type="Submit" value="Delete Session" name="killsession" id="killsession"/>';
} elseif (isset($_POST['killsession'])) {
session_start();
echo 'Goodbye ' . $_SESSION['username'] . '<br/>';
session_destroy();
echo 'Username: <input type="text" name="username" id="username" size="30"/><br/>';
echo '<br/>';
echo '<input type="Submit" value="New Session" name="newsession" id="newsession"/>';
} elseif (isset($_POST['newsession'])) {
session_start();
$_SESSION['username'] = $_POST['username'];
$_SESSION['visits'] = 1;
echo 'Welcome to a new session ' . $_SESSION['username'] . '<br/>';
session_write_close();
echo '<br/>';
echo '<input type="Submit" value="Refresh" name="continue" id="continue"/>';
echo '<input type="Submit" value="Delete Session" name="killsession" id="killsession"/>';
} else {
echo 'To get started, enter a username.<br/>';
API Version 2010-12-01
226
AWS Elastic Beanstalk Developer Guide
Custom Resources
echo '<br/>';
echo 'Username: <input type="text" name="username" id="username" size="30"/><br/>';
echo '<input type="Submit" value="New Session" name="newsession" id="newsession"/>';
}
?>
</form>
.ebextensions/dynamodb.config
Resources:
SessionTable:
Type: AWS::DynamoDB::Table
Properties:
KeySchema:
HashKeyElement:
AttributeName:
Fn::GetOptionSetting:
OptionName : SessionHashKeyName
DefaultValue: "username"
AttributeType:
Fn::GetOptionSetting:
OptionName : SessionHashKeyType
DefaultValue: "S"
ProvisionedThroughput:
ReadCapacityUnits:
Fn::GetOptionSetting:
OptionName : SessionReadCapacityUnits
DefaultValue: 1
WriteCapacityUnits:
Fn::GetOptionSetting:
OptionName : SessionWriteCapacityUnits
DefaultValue: 1
SessionWriteCapacityUnitsLimit:
Type: AWS::CloudWatch::Alarm
Properties:
AlarmDescription: { "Fn::Join" : ["", [{ "Ref" : "AWSEBEnvironmentName" }, " write
capacity limit on the session table." ]]}
Namespace: "AWS/DynamoDB"
MetricName: ConsumedWriteCapacityUnits
Dimensions:
- Name: TableName
Value: { "Ref" : "SessionTable" }
Statistic: Sum
Period: 300
EvaluationPeriods: 12
Threshold:
Fn::GetOptionSetting:
OptionName : SessionWriteCapacityUnitsAlarmThreshold
DefaultValue: 240
ComparisonOperator: GreaterThanThreshold
AlarmActions:
- Ref: SessionAlarmTopic
InsufficientDataActions:
- Ref: SessionAlarmTopic
SessionReadCapacityUnitsLimit:
Type: AWS::CloudWatch::Alarm
Properties:
AlarmDescription: { "Fn::Join" : ["", [{ "Ref" : "AWSEBEnvironmentName" }, " read
capacity limit on the session table." ]]}
Namespace: "AWS/DynamoDB"
MetricName: ConsumedReadCapacityUnits
Dimensions:
- Name: TableName
API Version 2010-12-01
227
AWS Elastic Beanstalk Developer Guide
Custom Resources
Value: { "Ref" : "SessionTable" }
Statistic: Sum
Period: 300
EvaluationPeriods: 12
Threshold:
Fn::GetOptionSetting:
OptionName : SessionReadCapacityUnitsAlarmThreshold
DefaultValue: 240
ComparisonOperator: GreaterThanThreshold
AlarmActions:
- Ref: SessionAlarmTopic
InsufficientDataActions:
- Ref: SessionAlarmTopic
SessionThrottledRequestsAlarm:
Type: AWS::CloudWatch::Alarm
Properties:
AlarmDescription: { "Fn::Join" : ["", [{ "Ref" : "AWSEBEnvironmentName" }, ":
requests are being throttled." ]]}
Namespace: AWS/DynamoDB
MetricName: ThrottledRequests
Dimensions:
- Name: TableName
Value: { "Ref" : "SessionTable" }
Statistic: Sum
Period: 300
EvaluationPeriods: 1
Threshold:
Fn::GetOptionSetting:
OptionName: SessionThrottledRequestsThreshold
DefaultValue: 1
ComparisonOperator: GreaterThanThreshold
AlarmActions:
- Ref: SessionAlarmTopic
InsufficientDataActions:
- Ref: SessionAlarmTopic
SessionAlarmTopic:
Type: AWS::SNS::Topic
Properties:
Subscription:
- Endpoint:
Fn::GetOptionSetting:
OptionName: SessionAlarmEmail
DefaultValue: "[email protected]"
Protocol: email
files:
"/var/app/sessiontable":
mode: "000444"
content: |
`{"Ref" : "SessionTable"}`
`{"Ref" : "AWS::Region"}`
"/var/app/composer.json":
mode: "000744"
content:
{
"require": {
"aws/aws-sdk-php": "*"
}
}
container_commands:
"1-install-composer":
command: "cd /var/app; curl -s http://getcomposer.org/installer | php"
API Version 2010-12-01
228
AWS Elastic Beanstalk Developer Guide
Custom Resources
"2-install-dependencies":
command: "cd /var/app; php composer.phar install"
"3-cleanup-composer":
command: "rm -Rf /var/app/composer.*"
In the sample configuration file, we first create the DynamoDB table and configure the primary key
structure for the table and the capacity units to allocate sufficient resources to provide the requested
throughput. Next, we create CloudWatch alarms for WriteCapacity and ReadCapacity. We create an SNS
topic that sends email to "[email protected]" if the alarm thresholds are breached.
After we create and configure our AWS resources for our environment, we need to customize the EC2
instances. We use the files key to pass the details of the DynamoDB table to the EC2 instances in our
environment as well as add a "require" in the composer.json file for the AWS SDK for PHP 2. Finally, we
run container commands to install composer, the required dependencies, and then remove the installer.
.ebextensions/options.config
option_settings:
"aws:elasticbeanstalk:customoption":
SessionHashKeyName
SessionHashKeyType
SessionReadCapacityUnits
SessionReadCapacityUnitsAlarmThreshold
SessionWriteCapacityUnits
SessionWriteCapacityUnitsAlarmThreshold
SessionThrottledRequestsThreshold
SessionAlarmEmail
:
:
:
:
:
:
:
:
username
S
1
240
1
240
1
[email protected]
Replace the SessionAlarmEmail value with the email where you want alarm notifications sent. The
options.config file contains the values used for some of the variables defined in dynamodb.config. For
example, dynamodb.config contains the following lines:
Subscription:
- Endpoint:
Fn::GetOptionSetting:
OptionName: SessionAlarmEmail
DefaultValue: "[email protected]"
These lines that tell Elastic Beanstalk to get the value for the Endpoint property from the
SessionAlarmEmail value in a config file (options.config in our sample application) that contains an
option_settings section with an aws:elasticbeanstalk:customoption section that contains a name-value
pair that contains the actual value to use. In the example above, this means SessionAlarmEmail would
be assigned the value [email protected]
For more information about the CloudFormation resources used in this example, see the following
references:
• AWS::DynamoDB::Table
• AWS::CloudWatch::Alarm
• AWS::SNS::Topic
Syntax
When defining the values for the properties for your resource, there are three different methods you can
use to define the values for the properties for a resource:
• Pass the value
API Version 2010-12-01
229
AWS Elastic Beanstalk Developer Guide
Custom Resources
• Pass a list of values
• Pass the option name and the value
There are two different functions you can use to retrieve the values for the properties:
• Use Fn::GetAtt to return the value of an attribute from a resource. For more information, see
Fn::GetAtt.
• Use Ref to return the value of a specified parameter or resource. For more information, see Ref.
Resources:
<name of resource>:
Type: <resource type identifier>
Properties:
# Example syntax of a property that takes in the actual value
<property name>: <literal string>
# Example syntax of a property that takes a list of strings
<property name>: ["<literal string>", "<literal string>"]
# Example syntax of a property that takes the option name and the value
<property name>:
- Name: <option name>
Value: <literal string>
# Example syntax showing how to use Fn::GetAtt to return the value of an attribute
from a resource in the configuration file
<property name>:
- Name: <option name>
Value : { "Fn::GetAtt" : [ "<logicalNameOfResource>", "<attributeName>"] }
# Example syntax showing how to use Ref to return the value of a specified parameter
or resource. You can use Ref for single property values and lists.
<property name>:
Ref: <parameter reference>
Options
This table shows the available keys and descriptions for the Resources key.
Key
Description
<name of resource>
The name for what you want to create your resource. Each resource must
have a logical name unique within the configuration file. This is the name
you use elsewhere in the configuration file to reference the resource.
This table shows the available keys and descriptions for each resource name you provide.
Key
Description
Type
This is the resource type identifier. For a list of resource type identifiers, see
AWS Resource Types Reference (p. 849).
Properties
Optional. A Properties section is declared for each resource immediately
after the resource Type declaration. Property values can be literal strings,
lists of strings, parameter references, pseudo references, or the value
API Version 2010-12-01
230
AWS Elastic Beanstalk Developer Guide
Custom Resources
Key
Description
returned by a function. If a resource does not require any properties to be
declared, you can omit the Properties section of that resource.
Elastic Beanstalk Resource Names
Elastic Beanstalk provides fixed resource names for the AWS resources that it creates for you when you
deploy your application. You will need to know these resource names when you reference them in your
configuration file. You can use Ref and Fn::GetAtt to retrieve information about these resources in
your configuration files. The value of Ref and the attributes available are determined by the type of the
resource in CloudFormation.
Resource Name
Description
AWSEBAutoScalingGroup
The Auto Scaling group attached to your environment.
Type: AWS::AutoScaling::AutoScalingGroup
AWSEBAutoScalingLaunchConfiguration The launch configuration attached to your environment's
Auto Scaling group.
Type: AWS::AutoScaling::LaunchConfiguration
Your environment.
AWSEBEnvironmentName
Type: AWS::ElasticBeanstalk::Environment
Your environment's load balancer (if applicable).
AWSEBLoadBalancer
Type: AWS::ElasticLoadBalancing::LoadBalancer
AWSEBLoadBalancerSecurityGroup
In a custom VPC only, the name of the security group that
Elastic Beanstalk creates for the load balancer. In a default
VPC or EC2 classic, Elastic Load Balancing assigns a default
security group to the load balancer.
Type: AWS::EC2::SecurityGroup
AWSEBRDSDatabase
The Amazon RDS DB instance attached to your environment
(if applicable).
Type: AWS::RDS::DBInstance
AWSEBSecurityGroup
The security group attached to your Auto Scaling group.
Type: AWS::EC2::SecurityGroup
AWSEBWorkerQueue
In a worker environment, the Amazon SQS queue from
which the daemon pulls requests that need to be processed.
Type: AWS::SQS::Queue
AWSEBWorkerDeadLetterQueue
In a worker environment, the Amazon SQS queue that stores
messages that cannot be delivered or otherwise were not
successfully processed by the daemon.
Type: AWS::SQS::Queue
API Version 2010-12-01
231
AWS Elastic Beanstalk Developer Guide
Functions
Resource Name
Description
AWSEBWorkerCronLeaderRegistry
In a worker environment, the Amazon DynamoDB table
that is the internal registry used by the daemon for periodic
tasks.
Type: AWS::DynamoDB::Table
Example Snippets
The following is a list of example configuration files that you can use to customize your Elastic Beanstalk
environments:
• DynamoDB, CloudWatch, and SNS
• Elastic Load Balancing and CloudWatch
• ElastiCache
• RDS and CloudWatch
• SQS, SNS, and CloudWatch
Functions
You can use functions in your configuration files to populate values for resource properties with
information from other resources or from Elastic Beanstalk configuration option settings. Elastic
Beanstalk supports AWS CloudFormation functions (Ref, Fn::GetAtt, Fn::Join), and one Elastic
Beanstalk-specific function, Fn::GetOptionSetting.
Functions
• Ref (p. 232)
• Fn::GetAtt (p. 233)
• Fn::Join (p. 233)
• Fn::GetOptionSetting (p. 233)
Ref
Use Refto retrieve the default string representation of an AWS resource. The value returned by
Refdepends on the resource type, and sometimes depends on other factors as well. For example, a
security group (AWS::EC2::SecurityGroup) returns either the name or ID of the security group, depending
on if the security group is in a default VPC, EC2 classic, or a custom VPC.
{ "Ref" : "resource name" }
Note
For details on each resource type, including the return value(s) of Ref, see AWS Resource Types
Reference in the AWS CloudFormation User Guide.
From the sample Auto Scaling lifecycle hook (p. 216):
Resources:
lifecyclehook:
Type: AWS::AutoScaling::LifecycleHook
API Version 2010-12-01
232
AWS Elastic Beanstalk Developer Guide
Functions
Properties:
AutoScalingGroupName: { "Ref" : "AWSEBAutoScalingGroup" }
You can also use Ref to retrieve the value of a AWS CloudFormation parameter defined elsewhere in the
same file or in a different configuration file.
Fn::GetAtt
Use Fn::GetAtt to retrieve the value of an attribute on an AWS resource.
{ "Fn::GetAtt" : [ "resource name", "attribute name"] }
From the sample Auto Scaling lifecycle hook (p. 216):
Resources:
lifecyclehook:
Type: AWS::AutoScaling::LifecycleHook
Properties:
RoleARN: { "Fn::GetAtt" : [ "hookrole", "Arn"] }
See Fn::GetAtt for more information.
Fn::Join
Use Fn::Join to combine strings with a delimiter. The strings can be hard-coded or use the output from
Fn::GetAtt or Ref.
{ "Fn::Join" : [ "delimiter", [ "string1", "string2" ] ] }
See Fn::Join fore more information.
Fn::GetOptionSetting
Use Fn::GetOptionSetting to retrieve the value of a configuration option (p. 145) setting applied to
the environment.
"Fn::GetOptionSetting":
Namespace: "namespace"
OptionName: "option name"
DefaultValue: "default value"
From the storing private keys (p. 298) example:
Resources:
AWSEBAutoScalingGroup:
Metadata:
AWS::CloudFormation::Authentication:
S3Auth:
type: "s3"
buckets: ["elasticbeanstalk-us-west-2-123456789012"]
roleName:
"Fn::GetOptionSetting":
Namespace: "aws:autoscaling:launchconfiguration"
OptionName: "IamInstanceProfile"
DefaultValue: "aws-elasticbeanstalk-ec2-role"
API Version 2010-12-01
233
AWS Elastic Beanstalk Developer Guide
Saved Configurations
Using Elastic Beanstalk Saved Configurations
You can save your environment's configuration as an object in Amazon S3 that can be applied to other
environments during environment creation, or applied to a running environment. Saved configurations
are YAML formatted templates that define an environment's platform configuration (p. 25), tier (p. 15),
configuration option (p. 145) settings, and tags.
Create a saved configuration from the current state of your environment in the Elastic Beanstalk
Management Console:
To save an environment's configuration
1.
Open the Elastic Beanstalk console.
2.
3.
Navigate to the management page (p. 61) for your environment.
Choose Actions and then choose Save Configuration.
4.
Type a configuration name and description and then choose Save.
The saved configuration includes any settings that you have applied to the environment with the console
or any other client that uses the Elastic Beanstalk API. You can then apply the saved configuration to
your environment at a later date to restore it to its previous state, or apply it to a new environment
during environment creation (p. 71).
You can download a configuration using the EB CLI the section called “eb config” (p. 471) command,
as shown in the following example, NAME is the name of your saved configuration.
eb config get NAME
To apply a saved configuration during environment creation (AWS Management Console)
1.
2.
3.
Open the Elastic Beanstalk console.
Choose an application.
Choose Saved Configurations.
API Version 2010-12-01
234
AWS Elastic Beanstalk Developer Guide
Saved Configurations
4.
Choose an saved configuration and then choose Launch environment.
5.
Proceed through the wizard to create your environment.
Saved configurations do not include settings applied with configuration files (p. 197) in your
application's source code. If the same setting is applied in both a configuration file and saved
configuration, the setting in the saved configuration takes precedence. Likewise, options specified in
the AWS Management Console override options in saved configurations. For more information, see
Precedence (p. 194).
Saved configurations are stored in the Elastic Beanstalk S3 bucket in a folder named after your
application. For example, configurations for an application named my-app in the us-west-2 region for
account number 0123456789012 can be found at s3://elasticbeanstalk-us-west-2-0123456789012/
resources/templates/my-app/.
View the contents of a saved configuration by opening it in a text editor. The following example
configuration shows the configuration of a web server environment launched with the Elastic Beanstalk
Management Console:
EnvironmentConfigurationMetadata:
Description: Saved configuration from a multicontainer Docker environment created with
the Elastic Beanstalk Management Console
DateCreated: '1452824453000'
DateModified: '1452824453000'
SolutionStack: 64bit Amazon Linux 2015.09 v2.0.6 running Multi-container Docker 1.7.1
(Generic)
OptionSettings:
aws:elasticbeanstalk:command:
BatchSize: '30'
BatchSizeType: Percentage
aws:elasticbeanstalk:sns:topics:
Notification Endpoint: [email protected]
aws:elb:policies:
ConnectionDrainingEnabled: true
ConnectionDrainingTimeout: '20'
aws:elb:loadbalancer:
CrossZone: true
aws:elasticbeanstalk:environment:
ServiceRole: aws-elasticbeanstalk-service-role
aws:elasticbeanstalk:application:
Application Healthcheck URL: /
aws:elasticbeanstalk:healthreporting:system:
SystemType: enhanced
aws:autoscaling:launchconfiguration:
IamInstanceProfile: aws-elasticbeanstalk-ec2-role
InstanceType: t2.micro
EC2KeyName: workstation-uswest2
aws:autoscaling:updatepolicy:rollingupdate:
RollingUpdateType: Health
RollingUpdateEnabled: true
EnvironmentTier:
Type: Standard
Name: WebServer
AWSConfigurationTemplateVersion: 1.1.0.0
Tags:
Cost Center: WebApp Dev
You can modify the contents of a saved configuration and save it in the same location in Amazon S3. Any
properly formatted saved configuration stored in the right location can be applied to an environment
with the Elastic Beanstalk Management Console.
The following keys are supported:
API Version 2010-12-01
235
AWS Elastic Beanstalk Developer Guide
Saved Configurations
• AWSConfigurationTemplateVersion (required) – The configuration template version (1.1.0.0).
AWSConfigurationTemplateVersion: 1.1.0.0
• SolutionStack – The full name of the solution stack (p. 25) used to create the environment:
SolutionStack: 64bit Amazon Linux 2015.09 v2.0.6 running Multi-container Docker 1.7.1
(Generic)
• OptionSettings – Configuration option (p. 145) settings to apply to the environment. For example,
the following entry sets the instance type to t2.micro:
OptionSettings:
aws:autoscaling:launchconfiguration:
InstanceType: t2.micro
• Tags – Up to seven tags to apply to resources created within the environment.
Tags:
Cost Center: WebApp Dev
• EnvironmentTier – The type of environment to create. For a web server environment, you can exclude
this section (web server is the default). For a worker environment, use the following:
EnvironmentTier:
Name: Worker
Type: SQS/HTTP
• CName – The CNAME for the environment. Include a + character at the end of the name to enable
groups:
CName: front-A08G28LG+
• EnvironmentName – The name of the environment to create. Include a + character at the end of the
name to enable groups:
EnvironmentName: front+
With groups enabled, you must specify a group name when you create the environments. Elastic
Beanstalk appends the group name to the environment name with a hyphen. For example, with the
environment name front+ and the group name dev, Elastic Beanstalk will create the environment with
the name front-dev.
• EnvironmentLinks – A map of variable names and environment names of dependencies. The following
example makes the worker+ environment a dependency and tells Elastic Beanstalk to save the link
information to a variable named WORKERQUEUE.
EnvironmentLinks:
"WORKERQUEUE" : "worker+"
The value of the link variable varies depending on the type of the linked environment. For a web server
environment, the link is the environment's CNAME. For a worker environment, the link is the name of
the environment's Amazon SQS queue.
The CName, EnvironmentName and EnvironmentLinks keys can be used to create environment
groups (p. 106) and links to other environments (p. 142). These features are currently supported when
using the EB CLI, AWS CLI or an SDK. When using these features, you can include the saved configuration
API Version 2010-12-01
236
AWS Elastic Beanstalk Developer Guide
env.yaml
in your source code as an environment manifest (p. 237) instead of referencing a saved configuration
stored in Amazon S3. See the corresponding topics for more information.
See the following topics for alternate methods of creating and applying saved configurations:
• Setting Configuration Options Before Environment Creation (p. 145)
• Setting Configuration Options During Environment Creation (p. 149)
• Setting Configuration Options After Environment Creation (p. 154)
Environment Manifest (
)
env.yaml
You can include a YAML formatted environment manifest in the root of your application source bundle
to configure the environment name, solution stack and environment links (p. 142) to use when creating
your environment. An environment manifest uses the same format as Saved Configurations (p. 234).
This file format includes support for environment groups. To use groups, specify the environment name
in the manifest with a + symbol at the end. When you create or update the environment, specify the
group name with --group-name (AWS CLI) or --env-group-suffix (EB CLI). For more information on
groups, see Creating and Updating Groups of AWS Elastic Beanstalk Environments (p. 106).
The following example manifest defines an web server environment with a link to a worker environment
component that it is dependent upon. The manifest uses groups to allow creating multiple environments
with the same source bundle:
~/myapp/frontend/env.yaml
AWSConfigurationTemplateVersion: 1.1.0.0
SolutionStack: 64bit Amazon Linux 2015.09 v2.0.6 running Multi-container Docker 1.7.1
(Generic)
OptionSettings:
aws:elasticbeanstalk:command:
BatchSize: '30'
BatchSizeType: Percentage
aws:elasticbeanstalk:sns:topics:
Notification Endpoint: [email protected]
aws:elb:policies:
ConnectionDrainingEnabled: true
ConnectionDrainingTimeout: '20'
aws:elb:loadbalancer:
CrossZone: true
aws:elasticbeanstalk:environment:
ServiceRole: aws-elasticbeanstalk-service-role
aws:elasticbeanstalk:application:
Application Healthcheck URL: /
aws:elasticbeanstalk:healthreporting:system:
SystemType: enhanced
aws:autoscaling:launchconfiguration:
IamInstanceProfile: aws-elasticbeanstalk-ec2-role
InstanceType: t2.micro
EC2KeyName: workstation-uswest2
aws:autoscaling:updatepolicy:rollingupdate:
RollingUpdateType: Health
RollingUpdateEnabled: true
Tags:
Cost Center: WebApp Dev
CName: front-A08G28LG+
EnvironmentName: front+
EnvironmentLinks:
"WORKERQUEUE" : "worker+"
API Version 2010-12-01
237
AWS Elastic Beanstalk Developer Guide
Auto Scaling Group
For more information on the saved configuration format and supported keys, see Using Elastic Beanstalk
Saved Configurations (p. 234)
Configuring Auto Scaling with Elastic Beanstalk
Auto Scaling is a web service designed to automatically launch or terminate Amazon EC2 instances in
an autoscaling group based on parameters that you define. Elastic Beanstalk supports Auto Scaling
for load-balancing, autoscaling environments. Automatically increasing or decreasing the number of
Amazon EC2 instances helps you seamlessly deal with traffic changes to your application. The triggers
that you define for an autoscaling group instruct Elastic Beanstalk to scale computing resources in
response to metrics such as bandwidth usage or CPU utilization. You can also schedule scaling actions to
occur at specific times. Auto Scaling works with Amazon CloudWatch to retrieve metrics for the server
instances running your application.
Auto Scaling also monitors the health of each Amazon EC2 instance that it launches. If any instance
terminates unexpectedly, Auto Scaling detects the termination and launches a replacement instance.
This capability enables you to maintain a fixed, desired number of Amazon EC2 instances automatically.
Note
Autoscaling settings can impact rolling updates. If you configured rolling updates, a rolling
update cannot happen if the minimum number of instances in service for rolling updates is
larger than the maximum size of the autoscaling group. You must change the value of either
the Minimum instances in service setting for rolling updates or the Maximum instance count
setting for the autoscaling group.
For more information about Auto Scaling, go to the Auto Scaling documentation.
AWS Management Console
You can configure how Auto Scaling works by editing Scaling on the environment's Configuration page
in the environment management console (p. 61).
API Version 2010-12-01
238
AWS Elastic Beanstalk Developer Guide
AWS Management Console
API Version 2010-12-01
239
AWS Elastic Beanstalk Developer Guide
AWS Management Console
The following section discusses how to configure Auto Scaling parameters for your application.
Launch Configuration
You can edit the launch configuration in the Auto Scaling section of the page to control how your Elastic
Beanstalk application provisions Auto Scaling resources.
The Minimum instance count and Maximum instance count boxes let you specify the minimum and
maximum size of the Auto Scaling group that your Elastic Beanstalk application uses.
Note
To maintain a fixed number of Amazon EC2 instances, set the Minimum instance count and
Maximum instance count boxes to the same value.
The Availability Zones box lets you specify the number of Availability Zones in which you want Elastic
Beanstalk to launch instances. We recommend that you choose multiple Availability Zones so that
instances can be launched in another Availability Zone if one zone becomes unavailable. For example, if
you have a minimum of 3 instances, then you should choose 3 Availability Zones.
The Custom Availability Zones box lets you specify which Availability Zones you want Elastic Beanstalk
to launch instance(s) in across a region. If you do not select any custom Availability Zones, then Elastic
Beanstalk will choose the Availability Zones for you. The number of Availability Zones must be less than
or equal to the number of custom Availability Zones you select. For example, if you select Any 2, then
you must select at least two custom Availability Zones.
Note
Here are some things to keep in mind when working with Availability Zones:
• It is important to launch instances in more than one Availability Zone in order to build faulttolerant applications. If one Availability Zone goes down, your instances will still be running in
another Availability Zones.
• If you purchased Reserved Instances, you need to specify the same Availability Zone(s) that
you specified when you purchased your Reserved Instances. Reserved Instances let you make
a low, one-time, upfront payment for an instance, reserve it for a one- or three-year term, and
pay a significantly lower hourly rate for that instance. For more information about Reserved
Instances, see Reserved Instances in the Amazon EC2 User Guide for Linux Instances.
• You can create custom Availability Zones only in a default VPC or non-VPC environment.
The Scaling cooldown (seconds) box specifies how long Auto Scaling will wait before resuming any
scaling activities after it launches an instance so that the new instance has time to begin handling traffic.
If, by the time the cooldown period elapses, your environment has the appropriate level of resources to
keep the CloudWatch alarm from continuing to fire, then no new instances will be launched.
Triggers
You can edit the Scaling Trigger section of the page to set metrics-based parameters for scaling actions
for your Elastic Beanstalk application. A trigger is an Auto Scaling mechanism that you define to tell
the system when to increase (scale out) the number of instances and when to decrease (scale in) the
number of instances. You can configure triggers to fire on Amazon EC2 or Elastic Load Balancing metrics
published to Amazon CloudWatch, such as an Amazon EC2 instance's CPU utilization, and determine
whether the conditions you specified have been met. When the upper or lower thresholds of the
conditions for the metric have been breached for the specified period of time, the trigger launches a
long-running process called a scaling activity. For more information about Amazon EC2 metrics, see
Amazon Elastic Compute Cloud Dimensions and Metrics in the Amazon CloudWatch User Guide. For
more information about Elastic Load Balancing metrics, see Monitor Your Load Balancer Using Amazon
CloudWatch in the Elastic Load Balancing User Guide.
API Version 2010-12-01
240
AWS Elastic Beanstalk Developer Guide
AWS Management Console
Auto Scaling triggers work by watching a specific Amazon CloudWatch metric for an instance. Triggers
include CPU utilization, network traffic, disk activity, and instance health. Use the Trigger measurement
setting to specify a metric for your trigger.
The following list describes the trigger parameters you can configure using the AWS Management
Console.
• Use Trigger statistic to specify which statistic the trigger should use—Minimum, Maximum, Sum, or
Average.
• Use Unit of measurement to specify the unit for the trigger measurement.
• For Measurement period, specify how frequently Amazon CloudWatch measures the metrics for
your trigger. Breach duration is the amount of time a metric can extend beyond its defined limit (as
specified for Upper threshold and Lower threshold) before the trigger fires.
• Upper breach scale increment and Lower breach scale increment specify how many Amazon EC2
instances to add or remove when performing a scaling activity.
Time-based Scaling
Time-based scaling enables you to plan scaling actions that launch or terminate Amazon EC2 instances in
each autoscaling group. You can schedule scaling actions, as needed. To see the list of an environment's
scheduled scaling actions, including expired ones, see the Time-based Scaling section of the Scaling
page in the AWS Management Console. An environment can have up to 120 scheduled scaling actions,
not including expired actions (actions that ended in the past).
If your Elastic Beanstalk application has predictable needs for scaling out or scaling in at specific times,
you can schedule scaling actions on a recurring basis. You can also schedule a scaling action for a
planned one-time future event. Instead of creating an entirely new scheduled action, you can reuse an
expired scheduled action by changing the start time to a time and date in the future. (Elastic Beanstalk
keeps a history of the most recent 150 expired scheduled actions.)
The table in the Time-based Scaling section displays the following information.
• The Name column shows the name that you assigned the scheduled action when you created it. You
cannot change the name of a scaling action after you create it.
• The Limits column displays the minimum, maximum, and desired number of instances that you
specified for the autoscaling group when you created or most recently changed the scheduled action.
• In the Next occurrence column, you can see the next time the scheduled action will take effect. For a
recurrent scaling action, the next occurrence is based on the recurrence that you specified with a CRON
expression.
In the Time-based Scaling section of the page, if you click Add scheduled action, the New scheduled
action window displays the following options:
API Version 2010-12-01
241
AWS Elastic Beanstalk Developer Guide
AWS Management Console
• Use Name to specify a name for the scheduled scaling action that differentiates it from other scaling
actions and that you can use to find it later. You must use alphanumeric characters with no spaces. The
name has a limit of 255 characters.
• For Instances, indicate the Min (minimum) and Max (maximum) number of instances for the
autoscaling group.
• The Desired capacity box lets you specify the number of instances that you want running in the
autoscaling group. The desired capacity must be less than or equal to the value you defined as the
maximum number of instances and larger than or equal to the value you defined as the minimum.
• For Occurrence, choose whether the scaling action should occur only once or on a recurring basis.
• If you choose One-time, configure the following settings:
• Start time – Specify a date and time in the future to run the action.
• If you choose Recurrent, configure the following settings:
• Recurrence – Use a CRON expression to specify the frequency with which you want the scheduled
action to occur. For example, if you want to schedule a recurrent action that take effect every
Tuesday at 6:30 AM UTC, you can use the CRON expression “30 6 * * 2”. For more information
about CRON syntax, see Cron.
• Start time (optional) – Specify a date and time in the future to activate the scheduled action.
If you don't specify a start time, the scheduled action is active immediately. The console
automatically selects the top of the next hour by default.
API Version 2010-12-01
242
AWS Elastic Beanstalk Developer Guide
Auto scaling configuration namespaces
• End time (optional) – Specify a date and time in the future when you want to stop the scheduled
action. If you don’t specify an end time, the scaling action recurs until you configure it with an end
date and time.
Use ISO 8601 time format to specify start and end times in UTC. For example, 2015-04-28T04:07:02Z.
For more information about ISO 8601 time format, go to Date and Time Formats. The dates must be
unique across all scheduled actions.
You can’t suspend a scheduled action using the Elastic Beanstalk management console, but you can
configure option settings with the EB CLI to do so. When you suspend a scheduled scaling action, Elastic
Beanstalk ignores the scheduled action and does nothing. Suspending an action lets you stop the
scheduled action without deleting it so that you can resume the action later, if necessary.
Auto scaling configuration namespaces
Elastic Beanstalk provides additional configuration options (p. 145) in the following namespaces that
allow you to further customize auto scaling in your environment:
• aws:autoscaling:asg (p. 161) – Configure your environment's auto scaling group.
• aws:autoscaling:launchconfiguration (p. 162) – Configure your environment's EC2 instances.
• aws:autoscaling:scheduledaction (p. 166) – Configure scheduled actions for your environment's
auto scaling group.
• aws:autoscaling:trigger (p. 167) – Configure scaling triggers for your environment's auto scaling
group.
Examples: configuring time-based scaling actions
This section provides examples of option setting files that configure scheduled scaling actions. Include
these files in the .ebextensions directory in your application source bundle. For more information about
deploying configuration files with your application, see Advanced Environment Customization with
Configuration Files (.ebextensions) (p. 197).
Example scheduled-scale-up-specific-time.config
This configuration file instructs Elastic Beanstalk to scale out from five instances to 10 instances at
2015-12-12T00:00:00Z.
option_settings:
- namespace: aws:autoscaling:scheduledaction
resource_name: ScheduledScaleUpSpecificTime
option_name: MinSize
value: '5'
- namespace: aws:autoscaling:scheduledaction
resource_name: ScheduledScaleUpSpecificTime
option_name: MaxSize
value: '10'
- namespace: aws:autoscaling:scheduledaction
resource_name: ScheduledScaleUpSpecificTime
option_name: DesiredCapacity
value: '5'
- namespace: aws:autoscaling:scheduledaction
resource_name: ScheduledScaleUpSpecificTime
option_name: StartTime
value: '2015-12-12T00:00:00Z'
Here is an example to a shorter syntax that specifies the same configuration:
API Version 2010-12-01
243
AWS Elastic Beanstalk Developer Guide
Command Line Interface (CLI)
option_settings:
ScheduledScaleUpSpecificTime.aws:autoscaling:scheduledaction:
MinSize: '5'
MaxSize: '10'
DesiredCapacity: '5'
StartTime: '2015-12-12T00:00:00Z'
Example scheduled-scale-down-specific-time.config
This configuration file instructs Elastic Beanstalk to scale in at 2015-12-12T07:00:00Z.
option_settings:
ScheduledScaleDownSpecificTime.aws:autoscaling:scheduledaction:
MinSize: '1'
MaxSize: '1'
DesiredCapacity: '4'
StartTime: '2015-12-12T07:00:00Z'
Example scheduled-periodic-scale-up.config
This configuration file instructs Elastic Beanstalk to scale out every day at 9AM. The action is scheduled
to begin May 14, 2015 and end January 12, 2016.
option_settings:
ScheduledPeriodicScaleUp.aws:autoscaling:scheduledaction:
MinSize: '5'
MaxSize: '10'
DesiredCapacity: '5'
StartTime: '2015-05-14T07:00:00Z'
EndTime: '2016-01-12T07:00:00Z'
Recurrence: 0 9 * * *
Example scheduled-weekend-scale-down.config
This configuration file instructs Elastic Beanstalk to scale in every Friday at 6PM. If you know that your
application doesn’t receive as much traffic over the weekend, you can create a similar scheduled action.
option_settings:
ScheduledWeekendScaleDown.aws:autoscaling:scheduledaction:
MinSize: '1'
MaxSize: '4'
DesiredCapacity: '1'
StartTime: '2015-12-12T07:00:00Z'
EndTime: '2016-01-12T07:00:00Z'
Recurrence: 0 18 * * 5
Command Line Interface (CLI)
You can use the EB CLI to edit the environment settings for autoscaling.
To edit an application's environment settings using EB CLI
1.
Update an application's environment settings.
$ eb config my-env
2.
Add the following to the option settings file that opens in your text editor.
AWSEBAutoScalingScaleDownPolicy.aws:autoscaling:trigger:
API Version 2010-12-01
244
AWS Elastic Beanstalk Developer Guide
Command Line Interface (CLI)
LowerBreachScaleIncrement: '-1'
AWSEBAutoScalingScaleUpPolicy.aws:autoscaling:trigger:
UpperBreachScaleIncrement: '1'
AWSEBCloudwatchAlarmHigh.aws:autoscaling:trigger:
UpperThreshold: '6000000'
AWSEBCloudwatchAlarmLow.aws:autoscaling:trigger:
BreachDuration: '5'
EvaluationPeriods: '1'
LowerThreshold: '2000000'
MeasureName: NetworkOut
Period: '5'
Statistic: Average
Unit: Bytes
aws:autoscaling:asg:
Availability Zones: Any
Cooldown: '360'
Custom Availability Zones: null
MaxSize: '4'
MinSize: '1'
aws:autoscaling:launchconfiguration:
BlockDeviceMappings: null
EC2KeyName: null
IamInstanceProfile: aws-elasticbeanstalk-ec2-role
ImageId: ami-13de5b0e
InstanceType: t1.micro
MonitoringInterval: 5 minute
RootVolumeIOPS: null
RootVolumeSize: null
RootVolumeType: null
SSHSourceRestriction: tcp,22,22,0.0.0.0/0
SecurityGroups: awseb-e-um3yfrzq22-stack-AWSEBSecurityGroup-10MV688E4994W
You can also specify custom Availability Zones using EB CLI.
To update an application's environment settings with custom Availability Zones using EB CLI
1.
Update an application's environment settings with custom Availability Zones for autoscaling.
$ eb config
2.
Add the following to the option settings file that opens in your text editor.
aws:autoscaling:asg:
Availability Zones: Any
Cooldown: '360'
Custom Availability Zones: 'us-west-2a,us-west-2b'
MaxSize: '4'
MinSize: '1'
You can use EB CLI to create a scheduled action to scale out or scale in the number of instances in each
autoscaling group in your environment.
To create a new scheduled scaling action using EB CLI
1.
Run eb config
$ eb config
2.
Add the following to the option settings file that opens in your text editor to create a one-time
scheduled scaling action.
API Version 2010-12-01
245
AWS Elastic Beanstalk Developer Guide
Health Check Setting
Note
In the following examples, ScheduledScaleUpSpecificTime and
ScheduledScaleUpRecurring are the names you want to give each respective scheduled
action. Settings are grouped according to the scheduled scaling action name.
ScheduledScaleUpSpecificTime.aws:autoscaling:scheduledaction:
DesiredCapacity: '5'
EndTime: null
MaxSize: '10'
MinSize: '5'
Recurrence: null
StartTime: '2015-12-12T00:00:00Z'
Suspend: 'false'
Add the following to the option settings file that opens in your text editor to create a recurring
scheduled scaling action.
ScheduledScaleUpRecurring.aws:autoscaling:scheduledaction:
DesiredCapacity: '5'
EndTime: '2016-01-12T07:00:00Z'
MaxSize: '10'
MinSize: '5'
Recurrence: '0 9 * * *'
StartTime: '2015-12-12T00:00:00Z'
Suspend: 'false'
EB CLI and Elastic Beanstalk console apply recommended values for the preceding options.
These settings must be removed if you want to use configuration files to configure the same. See
Recommended Values (p. 195) for details.
Auto Scaling Health Check Setting
By default, the Auto Scaling created for your environment uses Amazon EC2 status checks. If an instance
in your environment fails an EC2 status check, it is taken down and replaced by Auto Scaling.
EC2 status checks only cover an instance's health, not the health of your application, server, or any
Docker containers running on the instance. If your application crashes, but the instance that it runs on
is still healthy, it may be kicked out of the load balancer, but it won't be replaced automatically by Auto
Scaling.
Note
Configuring a health check URL (p. 255) in the Load Balancing configuration section of the
Elastic Beanstalk console does not affect the health check behavior of an environment's Auto
Scaling group.
You may want instances in your environment to stay up when the application crashes for troubleshooting
and recovery purposes. If Auto Scaling replaced the instance as soon as the application crashed, you may
not realize that anything went wrong, even if it crashed quickly after starting up.
If you would like Auto Scaling to restart instances whose application has stopped responding, you can
configure the Auto Scaling group to use Elastic Load Balancing health checks with an .ebextensions
configuration file.
Note
Enabling this option can cause your environment to continually terminate and replace instances
if the Elastic Load Balancing health check fails soon after an instance starts. If this happens,
change the health check type back to EC2 in the Auto Scaling management console, or reverse
the configuration change and redeploy your environment.
API Version 2010-12-01
246
AWS Elastic Beanstalk Developer Guide
EC2 Instances
To set the Auto Scaling health check to ELB during environment launch
1.
Create a .ebextensions directory in your project folder.
2.
Create a config file in the .ebextensions folder with the following content:
.ebextensions/autoscaling.config
Resources:
AWSEBAutoScalingGroup:
Type: "AWS::AutoScaling::AutoScalingGroup"
Properties:
HealthCheckType: ELB
HealthCheckGracePeriod: 300
The grace period setting sets the number of seconds that an instance can fail the health check
without being terminated and replaced. Instances may recover even after being kicked out of the
load balancer, so give the instance an amount of time that is appropriate for your application.
3.
Deploy or update your environment.
By default, the Elastic Load Balancing health check is configured to attempt a TCP connection to
your instance over port 80. This confirms that the web server running on the instance is accepting
connections, but you may want to customize the check to make sure that your application is in a good
state, not just the web server.
You can tell Elastic Load Balancing to use a different port or to make an HTTP GET request to a path that
your application uses by changing the Elastic Load Balancing configuration for your environment. See
Configuring the Load Balancer in your Elastic Beanstalk Environment (p. 252) for details.
Configuring the EC2 Instances in your Elastic
Beanstalk Environment
The Auto Scaling Group in your environment manages the EC2 instances that run your application.
Changes to the Auto Scaling Group's launch configuration require replacement of all instances (p. 116)
and will trigger a rolling update (p. 117) or immutable update (p. 120), depending on which one is
configured.
Sections
• Configuring Your Environment's EC2 Instances in the AWS Management Console (p. 247)
• Configuration Files (p. 250)
• Creating a Custom Amazon Machine Image (AMI) (p. 250)
Configuring Your Environment's EC2 Instances in the
AWS Management Console
You can modify your Elastic Beanstalk environment's Auto Scaling Group configuration in the Elastic
Beanstalk console.
To configure EC2 Instances (console)
1.
Open the Elastic Beanstalk console.
API Version 2010-12-01
247
AWS Elastic Beanstalk Developer Guide
Configuring Your Environment's EC2
Instances in the AWS Management Console
2.
Navigate to the management page (p. 61) for your environment.
3.
Choose Configuration.
4.
Choose Instances.
The following settings are available:
Options
• Instance Type (p. 248)
• Security Groups (p. 248)
• EC2 Key Pair (p. 249)
• Instance Profile (p. 249)
• Monitoring Interval (p. 249)
• Custom AMI ID (p. 249)
• Root Volume (Boot Device) (p. 250)
Instance Type
The Instance type setting determines the type of EC2 instance launched to run your application. Choose
an instance that is powerful enough to run your application under load, but not so powerful that it is idle
most of the time. For development purposes, the t2 family of instances provides a moderate amount of
power with the ability to burst for short periods of time.
For large scale, high availability applications, use a pool of instances to ensure that capacity is not
greatly affected if any single instance goes down. Start with an instance type that allows you to run five
instances under moderate load during normal hours. If any instance fails, the rest of the instances can
absorb the rest of the traffic. The capacity buffer also allows time for the environment to scale up as
traffic begins to rise during peak hours.
For more information about EC2 instance families and types, see Instance Types in the Amazon Elastic
Compute Cloud User Guide.
Security Groups
The security groups attached to your instances determine which traffic is allowed to reach the instances
(ingress), and which traffic is allowed to leave the instances (egress). Elastic Beanstalk creates a security
group that allows traffic from the load balancer on the standard ports for HTTP (80) and HTTPS (443).
API Version 2010-12-01
248
AWS Elastic Beanstalk Developer Guide
Configuring Your Environment's EC2
Instances in the AWS Management Console
You can specify additional security groups that you have created to allow traffic on other ports or from
other sources. For example, you can create a security group for SSH access that allows ingress on port 22
from a restricted IP address range or, for additional security, from a bastion host to which only you have
access.
Note
To allow traffic between environment A's instances and environment B's instances, you can add
a rule to the security group that Elastic Beanstalk attached to environment B, and specify the
security group that Elastic Beanstalk attached to environment A. This allows ingress from, or
egress to, environment A's instances. However, doing so creates a dependency between the two
security groups. If you later try to terminate environment A, Elastic Beanstalk will not be able to
delete the environment's security group, because environment B's security group is dependent
on it.
A safer approach would be to create a separate security group, attach it to environment A, and
specify it in a rule of environment B's security group.
For more information on Amazon EC2 security groups, see Amazon EC2 Security Groups in the Amazon
Elastic Compute Cloud User Guide.
EC2 Key Pair
You can securely log in to the Amazon EC2 instances provisioned for your Elastic Beanstalk application
with an Amazon EC2 key pair. For instructions on creating a key pair for Amazon EC2, see the Amazon
Elastic Compute Cloud Getting Started Guide.
Choose an EC2 key pair from the drop down menu to assign it to your environment's instances. When
you assign a key pair, the public key is stored on the instance to authenticate the private key, which you
store locally. The private key is never stored in AWS.
For more information on connecting to Amazon EC2 instances, see Connect to Your Instance and
Connecting to Linux/UNIX Instances from Windows using PuTTY in the Amazon Elastic Compute Cloud
User Guide.
Instance Profile
An instance profile (p. 19) is an IAM role that is applied to instances launched in your Elastic Beanstalk
environment. EC2 instances assume the instance profile role to sign requests to AWS and access APIs, for
example, to upload logs to Amazon S3.
The first time you create an environment in the AWS Management Console, Elastic Beanstalk prompts
you to create an instance profile with a default set of permissions. You can add permissions to this profile
to provide your instances access to other AWS services. For details, see Managing Elastic Beanstalk
Instance Profiles (p. 354)
Monitoring Interval
By default, the instances in your environment publish basic health metrics (p. 303) to CloudWatch at 5
minute intervals at no additional cost.
For more detailed reporting, you can set the Monitoring interval to 1 minute to increase the frequency
with which the resources in your environment publish basic health metrics (p. 305) to CloudWatch.
Amazon CloudWatch service charges apply for one-minute interval metrics. See Amazon CloudWatch for
more information.
Custom AMI ID
The Amazon Machine Image (AMI) is the Amazon Linux or Windows Server machine image that AWS
Elastic Beanstalk uses to launch EC2 instances in your environment. Elastic Beanstalk provides machine
images that contain the tools and resources required to run your application.
API Version 2010-12-01
249
AWS Elastic Beanstalk Developer Guide
Configuration Files
Elastic Beanstalk selects a default AMI for your environment based on the region, platform, and instance
type that you choose. If you have created a custom AMI (p. 250), replace the default AMI ID with yours.
Root Volume (Boot Device)
Each instance in your environment is configured with a root volume. The root volume is the Amazon
EBS block device attached to the instance to store the operating system, libraries, scripts, and your
application source code. By default, all platforms use general purpose SSD block devices for storage.
You can modify Root volume type to use use magnetic storage or provisioned IOPS SSD volume types,
and increase the volume size if needed. For provisioned IOPS volumes, you must also select the number
of IOPS to provision. Select the volume type that meets your performance and price requirements.
For more information, see Amazon EBS Volume Types and Amazon EBS Product Details.
Configuration Files
You can use the configuration options (p. 145) in the
aws:autoscaling:launchconfiguration (p. 162) namespace to configure your Auto Scaling Group,
including additional options that are not available in the console.
The following configuration file (p. 197) configures the basic options shown above an an additional
option, BlockDeviceMappings, which isn't available in the console.
option_settings:
aws:autoscaling:launchconfiguration:
InstanceType: m1.small
SecurityGroups: my-securitygroup
EC2KeyName: my-keypair
MonitoringInterval: "1 minute"
ImageId: "ami-cbab67a2"
IamInstanceProfile: "ElasticBeanstalkProfile"
BlockDeviceMappings: "/dev/sdj=:100,/dev/sdh=snap-51eef269,/dev/sdb=ephemeral0"
BlockDeviceMappings lets you configure additional block devices for your instances. For more
information about block device mappings, see Block Device Mapping in the Amazon Elastic Cloud
Computer User Guide.
EB CLI and Elastic Beanstalk console apply recommended values for the preceding options.
These settings must be removed if you want to use configuration files to configure the same. See
Recommended Values (p. 195) for details.
Creating a Custom Amazon Machine Image (AMI)
When you create an AWS Elastic Beanstalk environment, you can specify an Amazon Machine Image
(AMI) to use instead of the standard Elastic Beanstalk AMI included in your platform configuration's
solution stack. A custom AMI can improve provisioning times when instances are launched in your
environment if you need to install a lot of software that isn't included in the standard AMIs.
Using configuration files (p. 197) is great for configuring and customizing your environment quickly
and consistently. Applying configurations, however, can start to take a long time during environment
creation and updates. If you do a lot of server configuration in configuration files, you can reduce this
time by making a custom AMI that already has the software and configuration that you need.
A custom AMI also allows you to make changes to low level components, such as the Linux kernel, that
are difficult to implement or take a long time to apply in configuration files. To create a custom AMI,
API Version 2010-12-01
250
AWS Elastic Beanstalk Developer Guide
Custom Image
launch an Elastic Beanstalk platform AMI in Amazon EC2, customize the software and configuration to
your needs, and then stop the instance and save an AMI from it.
To identify the base Elastic Beanstalk AMI
1.
Open the Elastic Beanstalk console.
2.
Create an Elastic Beanstalk environment running your application. For more information on how to
launch an Elastic Beanstalk application, go to the Getting Started Using Elastic Beanstalk (p. 3).
3.
Navigate to the management page (p. 61) for your environment.
4.
Choose Configuration
5.
Next to Instances, choose
.
6.
Note the value in the Custom AMI ID box.
7.
Terminate the environment.
The value in the Custom AMI ID field is the stock Elastic Beanstalk AMI for the platform version, EC2
instance architecture and region in which you created your environment. If you need to create AMIs for
multiple platforms, architectures or regions, repeat this process to identify the correct base AMI for each
combination.
Note
Do not create an AMI from an instance that has been launched in an Elastic Beanstalk
environment. Elastic Beanstalk makes changes to instances during provisioning that can cause
issues in the saved AMI. Saving an image from an instance in an Elastic Beanstalk environment
will also bake in the version of your application that was deployed to the instance.
It is also possible to create a custom AMI from a community AMI that was not published by Elastic
Beanstalk. You can use the latest Amazon Linux AMI as a starting point. When you launch an
environment with a non-Beanstalk Linux AMI, Elastic Beanstalk attempts to install platform software
(language, framework, proxy server, etc.) and additional components to support features such as
Enhanced Health Reporting (p. 306).
Note
Non-Beanstalk AMIs are not supported for Elastic Beanstalk Windows Server platforms.
Although you can use a non-Beanstalk AMI with Elastic Beanstalk, the increase in provisioning time that
results from Elastic Beanstalk installing missing components can reduce or eliminate the benefits of
creating a custom AMI in the first place. Other Linux distributions may work with some troubleshooting
but are not officially supported. If your application requires a specific Linux distribution, one alternative
is to create a Docker image and run it on Elastic Beanstalk's single container Docker platform (p. 582) or
multicontainer Docker platform (p. 587).
To create a custom AMI
1.
Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.
2.
Choose Launch Instance.
3.
Choose Community AMIs
4.
Enter the AMI ID of the Elastic Beanstalk or Amazon Linux AMI that you will customize to create a
custom AMI and press Enter.
5.
Choose Select to select the AMI.
6.
Select an instance type and choose Next: Configure Instance Details.
7.
(Linux platforms) Expand the Advanced Details section and paste the following text in the User
Data field:
#cloud-config
API Version 2010-12-01
251
AWS Elastic Beanstalk Developer Guide
Load Balancer
repo_releasever: repository version number
repo_upgrade: none
The repository version number is the year and month version in the AMI name. For example, AMIs
based on the March 2015 release of Amazon Linux have a repository version number 2015.03. For
Elastic Beanstalk image, this matches the date shown in the solution stack name for your platform
configuration (p. 25).
Note
These settings configure the lock-on-launch feature, which causes the AMI to use a fixed,
specific repository version when it launches, and disables the automatic installation of
security updates. Both are required to use a custom AMI with Elastic Beanstalk.
8.
Proceed through the wizard to launch the EC2 instance. When prompted, select an key pair that you
have access to so that you can connect to the instance for the next steps.
9.
Connect to the instance with SSH or RDP.
10. Perform any desired customizations.
11. (Windows platforms) Run the EC2Config service Sysprep. For information about EC2Config, go to
Configuring a Windows Instance Using the EC2Config Service. Ensure that Sysprep is configured to
generate a random password that can be retrieved from the AWS Management Console.
12. In the Amazon EC2 console, stop the EC2 instance and then choose Create Image (EBS AMI) from
the Instance Actions menu.
13. To avoid incurring additional AWS charges, terminate the EC2 instance.
14. To use your custom AMI, specify your custom AMI ID in the Custom AMI ID field in Instances section
of the Configuration page of the Elastic Beanstalk Environment Management Console. Existing
instances will be replaced with new instances launched from the new custom AMI.
When you create a new environment with the custom AMI, you should use the same platform
configuration that you used as a base to create the AMI. If you later apply a platform update (p. 123) to
an environment using a custom AMI, Elastic Beanstalk attempts to apply the library and configuration
updates during the bootstrapping process.
Configuring the Load Balancer in your Elastic
Beanstalk Environment
If you've enabled load balancing (p. 134), your environment is equipped with an Elastic Load Balancing
load balancer to distribute traffic among the the instances in your environment.
By default, your load balancer is configured to listen for HTTP traffic on port 80 and forward it to
instances on the same port. To support secure connections, you can configure your load balancer with a
listener on port 443 and a TLS certificate.
Elastic Load Balancing uses a health check to determine whether the EC2 instances running your
application are healthy. The health check determines an instance's health status by making a request to
a specified URL at a set interval; if the URL returns an error message, or fails to return within a specified
timeout period, the health check fails.
If your application performs better by serving multiple requests from the same client on a single server,
you can configure your load balancer to use sticky sessions. With sticky sessions, the load balancer adds
a cookie to HTTP responses that identifies the EC2 instance that served the request. When a subsequent
request is received from the same client, the load balancer uses the cookie to send the request to the
same instance.
API Version 2010-12-01
252
AWS Elastic Beanstalk Developer Guide
Configuring Your Environment's Load
Balancer in the AWS Management Console
When an instance is removed from the load balancer because it has become unhealthy or the
environment is scaling down, connection draining gives the instance time to complete requests prior to
closing the connection between the instance and the load balancer. You can change the amount of time
given to instances to send a response, or disable connection draining completely.
Note
Connection draining is enabled by default when you create an environment with the console or
EB CLI. For other clients, you must enable it with configuration options (p. 256).
Advanced load balancer settings are available through configuration options (p. 256) that you can set
with configuration files in your source code or directly on an environment by using the Elastic Beanstalk
API. You can use these options to configure listeners on arbitrary ports, modify additional sticky session
settings, and configure the load balancer to connect to EC2 instances securely. You can also configure a
load balancer to upload access logs (p. 256) to Amazon S3.
Topics
• Configuring Your Environment's Load Balancer in the AWS Management Console (p. 253)
• Load Balancer Configuration Namespaces (p. 256)
• Configuring Access Logs (p. 256)
• Configuring an Application Load Balancer (p. 257)
Configuring Your Environment's Load Balancer in the
AWS Management Console
Load balancer settings are available in the Network Tier section of the Configuration (p. 155) page in
the Environment Management Console (p. 61):
Ports and Cross-Zone Load Balancing
The basic settings for your load balancer let you configure the standard listener on port 80, a secure
listener on port 443 or port 8443, cross-zone load balancing.
API Version 2010-12-01
253
AWS Elastic Beanstalk Developer Guide
Configuring Your Environment's Load
Balancer in the AWS Management Console
You can change the listener protocol from HTTP to TCP if you want the load balancer to forward
requests as-is. This prevents the load balancer from rewriting headers (including X-Forwarded-For) and
does not work with sticky sessions.
For HTTPS, you can add a secure listener with the secure listener port and protocol options. You must
also select a certificate to use to decrypt the connections. You can also disable the standard listener if
you only want to accept secure connections.
To turn on the secure listener port
1.
Create and upload a certificate and key to AWS Identity and Access Management (IAM).
For more information about creating and uploading certificates, see the Managing Server
Certificates section of Using AWS Identity and Access Management.
2.
Open the Elastic Beanstalk console.
3.
Navigate to the management page (p. 61) for your environment.
4.
Choose Configuration.
5.
Specify the secure listener port by selecting a port from the Secure Listener Port list.
6.
For SSL Certificate ID, choose the ARN of your SSL certificate. For example,
arn:aws:iam::123456789012:server-certificate/abc/certs/build).
7.
(Optional) Set Listener port to OFF to disable the standard listener.
8.
Choose Apply.
For more detail on configuring HTTPS and working with certificates, see Configuring HTTPS for your
Elastic Beanstalk Environment (p. 270).
Connection Draining
Use these settings to turn connection draining on or off and set the Draining timeout to anything up to
3600 seconds.
API Version 2010-12-01
254
AWS Elastic Beanstalk Developer Guide
Configuring Your Environment's Load
Balancer in the AWS Management Console
Sessions
Use these settings to enable session sticking and configure the length of a session up to a maximum of
1000000 seconds.
Health Check
Specify an Application health check URL to configure the load balancer to make an HTTP GET request
to a specific route. For example, type / to send requests to the application root, or /health to send
requests to a resource at /health. If you don't configure a health check URL, the load balancer attempts
to establish a TCP connection with the instance.
Note
Configuring a health check URL does not affect the health check behavior of an environment's
Auto Scaling group. Instances that fail an Elastic Load Balancing health check will not
automatically be replaced by Auto Scaling unless you configure Auto Scaling to do so manually.
See Auto Scaling Health Check Setting (p. 246) for details.
The remaining options let you customize the number of seconds between each health check (Health
check interval), the number of seconds to wait for the health check to return (Health check timeout),
and the number of health checks that must pass (Healthy check count threshold) or fail (Unhealthy
check count threshold) before Elastic Load Balancing marks an instance as healthy or unhealthy.
For more information on health checks and how they influence your environment's overall health, see
Basic Health Reporting (p. 303).
API Version 2010-12-01
255
AWS Elastic Beanstalk Developer Guide
Load Balancer Configuration Namespaces
Load Balancer Configuration Namespaces
Elastic Beanstalk provides additional configuration options (p. 145) in the following namespaces that
allow you to further customize the load balancer in your environment:
• aws:elb:healthcheck (p. 179) – Configure the thresholds, check interval and timeout for ELB health
checks.
• aws:elasticbeanstalk:application (p. 171) – Configure the health check URL.
• aws:elb:loadbalancer (p. 179) – Enable cross-zone load balancing. Assign security groups to the
load balancer and override the default security group that Elastic Beanstalk creates. This namespace
also includes deprecated options for configuring the standard and secure listeners that have been
replaced by options in the the aws:elb:listener namespace.
• aws:elb:listener (p. 180) – Configure the default listener on port 80, a secure listener on 443, or
additional listeners for any protocol on any port.
• aws:elb:policies (p. 181) – Configure additional settings for your load balancer. You can use
options in this namespace to configure listeners on arbitrary ports, modify additional sticky session
settings, and configure the load balancer to connect to EC2 instances securely.
aws:elb:listener
You can use aws:elb:listener namespaces to configure additional listeners on your load balancer. If
you specify aws:elb:listener as the namespace, settings apply to the default listener on port 80. If you
specify a port (for example, aws:elb:listener:443), a listener is configured on that port.
The following example configuration file creates an HTTPS listener on port 443, assigns a certificate
that the load balancer uses to terminate the secure connection, and disables the default listener on port
80. The load balancer forwards the decrypted requests to the EC2 instances in your environment on
HTTP:80.
Example .ebextensions/loadbalancer-terminatehttps.config
option_settings:
aws:elb:listener:443:
ListenerProtocol: HTTPS
SSLCertificateId: arn:aws:iam::123456789012:server-certificate/elastic-beanstalk-x509
InstancePort: 80
InstanceProtocol: HTTP
aws:elb:listener:80:
ListenerEnabled: false
EB CLI and Elastic Beanstalk console apply recommended values for the preceding options.
These settings must be removed if you want to use configuration files to configure the same. See
Recommended Values (p. 195) for details.
Configuring Access Logs
You can use configuration files (p. 197) to configure your environment's load balancer to upload access
logs to an Amazon S3 bucket. See the following example configuration files on GitHub for instructions:
• loadbalancer-accesslogs-existingbucket.config – Configure the load balancer to upload access
logs to an existing Amazon S3 bucket.
• loadbalancer-accesslogs-newbucket.config – Configure the load balancer to upload access logs to a
new bucket.
API Version 2010-12-01
256
AWS Elastic Beanstalk Developer Guide
Application Load Balancer
Configuring an Application Load Balancer
When you launch a load-balanced environment, you can choose to use an application load balancer
instead of a classic load balancer. An application load balancer inspects traffic to identify the request's
path so that it can direct requests for different paths to different destinations.
By default, an application load balancer performs the same function as a classic load balancer. The
default listener accepts HTTP requests on port 80 and distributes them to the instances in your
environment. You can add a secure listener on port 443 with a certificate to decrypt HTTPS traffic,
configure health check behavior, and push access logs from the load balancer to an Amazon Simple
Storage Service (Amazon S3) bucket.
Note
Unlike a classic load balancer, an application load balancer cannot have non-HTTP TCP or SSL/
TLS listeners, and cannot use backend authentication to authenticate HTTPS connections
between the load balancer and backend instances.
In an AWS Elastic Beanstalk environment, you can use an application load balancer to direct traffic for
certain paths to a different port on your web server instances. With a classic load balancer, all traffic to
a listener is routed to a single port on the backend instances. With an application load balancer, you can
configure multiple rules on the listener to route requests to certain paths to different backend ports.
For example, you could run a login process separate from your main application. While your main
application accepts the majority of requests and listens on port 80, your login process listens on port
5000 and accepts requests to the /login path. With an application load balancer, you can configure a
single listener with two rules to route traffic to either port 80 or port 5000, depending on the path in the
request. One rule routes traffic to /login to port 5000, while the default rule routes all other traffic to
port 80.
An application load balancer rule maps a request to a target group. In Elastic Beanstalk, a target group is
represented by a process, which you can configure with a protocol, port, and health check settings. The
process represents the process running on the instances in your environment. The default process is a
listener on port 80 of the reverse proxy (nginx or Apache) that runs in front of your application.
Note
Outside of Elastic Beanstalk, a target group maps to a group of instances, and a listener can use
rules and target groups to route traffic to different instances based on the path. Within Elastic
Beanstalk, all of your instances in your environment are identical, so the distinction is made
between processes listening on different ports.
Instead of a single health check path for the entire environment, each process has a separate health
check path that is monitored by the load balancer and Elastic Beanstalk enhanced health monitoring.
To use an application load balancer, your environment must be in a default or custom VPC, and must
have a service role with the standard set of permissions. If you have an older service role, you may need
to update the permissions (p. 357) on it to include elasticloadbalancing:DescribeTargetHealth and
elasticloadbalancing:DescribeLoadBalancers. For more information about application load balancers,
see What Is an Application Load Balancer? in the Application Load Balancer Guide.
Note
The application load balancer health check does not take into account the Elastic Beanstalk
health check path, but instead uses the path provided in the .ebextensions like the one in the
example .ebextensions/alb-default-process.config (p. 259).
Getting Started
Note
You can set the load balancer type only during environment creation using the EB CLI, the
Elastic Beanstalk APIs, or using .ebextensions like the one in the example .ebextensions/
application-load-balancer.config (p. 258); the console does not support this functionality.
API Version 2010-12-01
257
AWS Elastic Beanstalk Developer Guide
Application Load Balancer
The EB CLI prompts you to choose a load balancer type when you run eb create:
$ eb create
Enter Environment Name
(default is my-app): test-env
Enter DNS CNAME prefix
(default is my-app): test-env-DLW24ED23SF
Select a load balancer type
1) classic
2) application
(default is 1): 2
You can also specify a load balancer type with the --elb-type option:
$ eb create test-env --elb-type application
Application Load Balancer Namespaces
Settings related to application load balancers are spread across the following namespaces:
• aws:elasticbeanstalk:environment (p. 173) – Choose between an application load balancer and
classic load balancer.
• aws:elbv2:loadbalancer (p. 185) – Configure access logs and other settings that apply to the
application load balancer as a whole.
• aws:elbv2:listener (p. 184) – Configure listeners on the application load balancer. These settings
map to the settings in aws:elb:listener for classic load balancers.
• aws:elbv2:listenerrule (p. 184) – Configure rules that route traffic to different processes,
depending on the request path. Rules are unique to application load balancers.
• aws:elasticbeanstalk:environment:process (p. 173) – Configure health checks and specify the
port and protocol for the processes that run on your environment's instances. The port and protocol
settings map to the instance port and instance protocol settings in aws:elb:listener for a listener
on a classic load balancer. Health check settings map to the settings in aws:elb:healthcheck and
aws:elasticbeanstalk:application namespaces.
Example .ebextensions/application-load-balancer.config
To get started with an application load balancer, use a configuration file (p. 197) to set the load
balancer type to application:
option_settings:
aws:elasticbeanstalk:environment:
LoadBalancerType: application
Note
You can only set the load balancer type during environment creation.
Example .ebextensions/alb-access-logs.config
The following configuration file enables access log uploads for an environment with an application load
balancer:
option_settings:
API Version 2010-12-01
258
AWS Elastic Beanstalk Developer Guide
Application Load Balancer
aws:elbv2:loadbalancer:
AccessLogsS3Bucket: my-bucket
AccessLogsS3Enabled: 'true'
AccessLogsS3Prefix: beanstalk-alb
Example .ebextensions/alb-default-process.config
The following configuration file modifies health check and stickiness settings on the default process:
option_settings:
aws:elasticbeanstalk:environment:process:default:
DeregistrationDelay: '20'
HealthCheckInterval: '15'
HealthCheckPath: /
HealthCheckTimeout: '5'
HealthyThresholdCount: '3'
UnhealthyThresholdCount: '5'
MatcherHTTPCode: null
Port: '80'
Protocol: HTTP
StickinessEnabled: 'true'
StickinessLBCookieDuration: '43200'
Example .ebextensions/alb-secure-listener.config
The following configuration file adds a secure listener and matching process on port 443:
option_settings:
aws:elbv2:listener:443:
DefaultProcess: https
ListenerEnabled: 'true'
Protocol: HTTPS
SSLCertificateArns: arn:aws:acm:us-east-2:0123456789012:certificate/21324896-0fa4-412bbf6f-f362d6eb6dd7
aws:elasticbeanstalk:environment:process:https:
Port: '443'
Protocol: HTTPS
Example .ebextensions/alb-admin-rule.config
The following configuration file adds a secure listener with a rule that routes traffic with a request path
of /admin to a process named admin that listens on port 4443:
option_settings:
aws:elbv2:listener:443:
DefaultProcess: https
ListenerEnabled: 'true'
Protocol: HTTPS
Rules: admin
SSLCertificateArns: arn:aws:acm:us-east-2:0123456789012:certificate/21324896-0fa4-412bbf6f-f362d6eb6dd7
aws:elasticbeanstalk:environment:process:admin:
HealthCheckPath: /admin
Port: '4443'
Protocol: HTTPS
aws:elbv2:listenerrule:admin:
PathPatterns: /admin/*
Priority: 1
Process: admin
API Version 2010-12-01
259
AWS Elastic Beanstalk Developer Guide
Database
Configuring Databases with Elastic Beanstalk
Elastic Beanstalk provides integration with Amazon RDS to help you add a database instance to your
Elastic Beanstalk environment. You can use Elastic Beanstalk to add a MySQL, PostgreSQL, Oracle,
or SQL Server database to your environment during or after environment creation. When you add a
database instance to your environment, Elastic Beanstalk provides connection information to your
application by setting environment properties for the database hostname, port, username, password,
and database name.
A database instance that is part of your environment is tied to the lifecycle of your environment,
and cannot be removed from your environment once added. If you terminate the environment, the
database instance is terminated as well. You can configure Elastic Beanstalk to save a snapshot of the
database when you terminate your environment, and restore a database from a snapshot when you
add a DB instance to an environment. You may incur charges for storing database snapshots. For more
information, see the Backup Storage section of Amazon RDS Pricing.
For a production environment, you may want to launch a database instance outside of your
environment (p. 398) and configure your application to connect to it outside of the functionality
provided by Elastic Beanstalk. Using a database instance external to your environment requires
additional security group and connection string configuration, but it also lets you connect to the
database from multiple environments, use database types not supported with integrated databases,
perform blue/green deployments, and tear down your environment without affecting the database
instance.
Sections
• Adding a DB Instance to Your Environment (p. 260)
• Connecting to the database (p. 261)
• Configuring an Integrated RDS DB Instance (p. 261)
Adding a DB Instance to Your Environment
You can add a DB instance to your environment in the Elastic Beanstalk console.
To add a DB instance to your environment
1.
Open the Elastic Beanstalk console.
2.
Navigate to the management page (p. 61) for your environment.
3.
Choose Configuration.
4.
Under Data Tier, choose Create a new RDS database.
5.
Choose a DB engine, enter a user name and password, and then choose Apply.
You can configure the following options:
• DB engine – Choose a database engine.
API Version 2010-12-01
260
AWS Elastic Beanstalk Developer Guide
Connecting to the database
• Instance Class – Choose the DB instance class. For information about the DB instance classes, see
http://aws.amazon.com/rds/.
• Allocated Storage – Choose the amount of storage to provision for your database. You can increase
allocated storage later, but you cannot decrease it. For information about storage allocation, see
Features.
• Master Username – Type a username using alphanumeric characters.
• Master Password – Type a password containing 8 to 16 printable ASCII characters (excluding /, \, and
@).
• Deletion Policy – Choose Create snapshot to create a snapshot of the database when you terminate
your environment.
• Snapshot – To restore a database from an existing snapshot, choose a snapshot.
• Availability – Choose Multiple Availability Zones to run a warm backup in a second AZ for high
availability.
Adding a DB instance takes about 10 minutes. When the environment update is complete, the DB
instance's hostname and other connection information are available to your application through the
following environment properties:
• RDS_HOSTNAME – The hostname of the DB instance.
Amazon RDS console label – Endpoint is the hostname.
• RDS_PORT – The port on which the DB instance accepts connections. The default value varies between
DB engines.
Amazon RDS console label – Port
• RDS_DB_NAME – The database name, ebdb.
Amazon RDS console label – DB Name
• RDS_USERNAME – The user name that you configured for your database.
Amazon RDS console label – Username
• RDS_PASSWORD – The password that you configured for your database.
Connecting to the database
Use the connectivity information to connect to your DB from inside your application through
environment variables. For more information about using Amazon RDS with your applications, see the
following topics.
• Java SE – Connecting to a Database (Java SE Platforms) (p. 640)
• Java with Tomcat – Connecting to a Database (Tomcat Platforms) (p. 641)
• Node.js – Connecting to a Database (p. 750)
•
•
•
•
.NET – Connecting to a Database (p. 688)
PHP – Connecting to a Database with a PDO or MySQLi (p. 800)
Python – Connecting to a Database (p. 823)
Ruby – Connecting to a Database (p. 842)
Configuring an Integrated RDS DB Instance
You can view and modify configuration settings for your DB instance in the Data Tier section on the
environment's Configuration page in the environment management console (p. 61).
API Version 2010-12-01
261
AWS Elastic Beanstalk Developer Guide
Debugging
To configure your environment's DB instance
1.
Open the Elastic Beanstalk console.
2.
Navigate to the management page (p. 61) for your environment.
3.
Choose Configuration.
4.
Under Data Tier, choose RDS.
You can modify the Master Password, Allocated Storage, Instance Class, Deletion Policy, and
Availability after database creation. Changing the instance class requires Elastic Beanstalk to reprovision
the DB instance.
Do not modify settings on the DB instance outside of the functionality provided by Elastic Beanstalk (for
example, in the Amazon RDS console).
Configuring AWS X-Ray Debugging
You can use the AWS Elastic Beanstalk console or a configuration file to run the AWS X-Ray daemon on
the instances in your environment. AWS X-Ray is an AWS service that gathers data about the requests
that your application serves, and uses it to construct a service map that you can use to identify issues
with your application and opportunities for optimization.
API Version 2010-12-01
262
AWS Elastic Beanstalk Developer Guide
Debugging
AWS X-Ray provides an SDK that you can use to instrument your application code, and a daemon
application that relays debugging information from the SDK to the X-Ray API.
Supported platforms
You can use the AWS X-Ray SDK with the following Elastic Beanstalk platform configurations:
• Java 8 - version 2.3.0 and later
• Java 8 with Tomcat 8 - version 2.4.0 and later
• Node.js - version 3.2.0 and later
• Python - version 2.5.0 and later
• Windows Server - all configurations starting December 9th, 2016
On supported platforms, you can use a configuration option to run the X-Ray daemon on the instances
in your environment. You can enable the daemon in the console (p. 264) or by using a configuration
file (p. 264).
Note
To be able to upload data to X-Ray, the X-Ray daemon requires IAM permissions in the
AWSXrayWriteOnlyAccess managed policy. These permissions are included in the Elastic
Beanstalk instance profile (p. 19). If you don't use the default instance profile, see Giving the
Daemon Permission to Send Data to X-Ray.
Debugging with AWS X-Ray requires the use of the AWS X-Ray SDK. See the AWS X-Ray Developer Guide
for instructions and sample applications.
If you use a platform configuration that doesn't include the daemon, you can still run it with a script in
a configuration file. For more information, see Downloading and Running the X-Ray Daemon Manually
(Advanced) in the AWS X-Ray Developer Guide.
Sections
• Configuring Debugging (p. 264)
API Version 2010-12-01
263
AWS Elastic Beanstalk Developer Guide
Configuring Debugging
• The aws:elasticbeanstalk:xray Namespace (p. 264)
Configuring Debugging
You can enable the AWS X-Ray daemon on a running environment in the Elastic Beanstalk console.
To enable debugging in the Elastic Beanstalk console
1.
Open the Elastic Beanstalk console.
2.
Navigate to the management page (p. 61) for your environment.
3.
Choose Configuration.
4.
In the Software Configuration section, choose the settings icon (
5.
For X-Ray Daemon, choose Enabled.
6.
Choose Apply.
).
You can also enable this option during environment creation. For more information, see The Create New
Environment Wizard (p. 71).
The aws:elasticbeanstalk:xray Namespace
You can use the XRayEnabled option in the aws:elasticbeanstalk:xray namespace to enable
debugging.
To enable debugging automatically when you deploy your application, set the option in a configuration
file (p. 197) in your source code, as follows.
Example .ebextensions/debugging.config
option_settings:
aws:elasticbeanstalk:xray:
XRayEnabled: true
Configuring VPC with Elastic Beanstalk
Amazon Virtual Private Cloud (Amazon VPC) enables you to define a virtual network in your own isolated
section within the Amazon Web Services (AWS) cloud, known as a virtual private cloud (VPC). Using VPC,
you can deploy a new class of web applications on Elastic Beanstalk, including internal web applications
(such as your recruiting application), web applications that connect to an on-premise database (using
a VPN connection), as well as private web service back ends. Elastic Beanstalk launches your AWS
resources, such as instances, into your VPC. Your VPC closely resembles a traditional network, with
the benefits of using AWS's scalable infrastructure. You have complete control over your VPC; you can
select the IP address range, create subnets, and configure routes and network gateways. To protect the
resources in each subnet, you can use multiple layers of security, including security groups and network
access control lists. For more information about Amazon VPC, go to the Amazon VPC User Guide.
You can view your environment's VPC configuration by viewing the VPC settings on the environment's
Configuration page. If you do not see the VPC settings on the Configuration page, your current
environment is not inside a VPC either because you are using a legacy container or you created the
Elastic Beanstalk environment outside a VPC. To learn how to migrate to a nonlegacy container to
use Amazon VPC with Elastic Beanstalk, see Migrating Your Application from a Legacy Container
API Version 2010-12-01
264
AWS Elastic Beanstalk Developer Guide
CW Logs
Type (p. 129). To learn how to create your VPC and launch your Elastic Beanstalk environment inside your
VPC, see Using Elastic Beanstalk with Amazon VPC (p. 408).
Configuring CloudWatch Logs with Elastic
Beanstalk
You can configure your AWS Elastic Beanstalk environment to stream Amazon CloudWatch (CloudWatch)
logs from Amazon EC2 instances created by Elastic Beanstalk.
When you configure CloudWatch logs, Elastic Beanstalk creates CloudWatch log groups for proxy and
deployment logs on the Amazon EC2 instances and transfers these log files to CloudWatch logs in real
time.
Configuring CloudWatch logs in the Elastic Beanstalk
console
The Elastic Beanstalk console contains three settings:
• Whether to enable streaming CloudWatch logs
• Whether to delete the log groups when the environment is terminated
• The number of days to keep log events before they expire
The aws:elasticbeanstalk:cloudwatch:logs Namespace
Use the options in the aws:elasticbeanstalk:cloudwatch:logs (p. 171) namespace to configure
CloudWatch logs. These options can be set by using configuration files, a CLI or an SDK.
StreamLogs – Set this option to true to create groups in CloudWatch logs for proxy and deployment logs,
and stream logs from each instance in your environment.
DeleteOnTerminate – Set this option to true to delete the log groups when the environment is
terminated. If false, the logs are kept RetentionInDays days..
RetentionInDays – Set this option to the number of days to keep log events before they expire.
API Version 2010-12-01
265
AWS Elastic Beanstalk Developer Guide
SNS Notifications
Configuring Amazon SNS Notifications with Elastic
Beanstalk
You can configure your AWS Elastic Beanstalk environment to use Amazon Simple Notification
Service (Amazon SNS) to notify you of important events affecting your application. Specify an email
address during or after environment creation to receive emails from AWS when an error occurs or your
environment's health changes.
Note
Elastic Beanstalk uses Amazon Simple Notification Service for notifications. For details on
Amazon SNS pricing, see https://aws.amazon.com/sns/pricing/.
When you configure notifications for your environment, Elastic Beanstalk creates an Amazon SNS topic
for your environment. When a notable event (p. 333) occurs, Elastic Beanstalk sends a message to the
topic. Amazon SNS relays messages it receives to the topic's subscribers.
Notable events include environment creation errors and all changes in environment and instance
health (p. 306). Events for Auto Scaling operations (adding and removing instances from the
environment) and other informational events do not trigger notifications.
The Elastic Beanstalk console lets you enter an email address during or after environment creation to
create an Amazon SNS topic and subscribe to it. Elastic Beanstalk manages the lifecycle of the topic, and
deletes it when your environment is terminated or you remove your email address in the environment
management console (p. 61).
The aws:elasticbeanstalk:sns:topics configuration option namespace provides options for
configuring an Amazon SNS topic in configuration files, or by using a CLI or SDK. These methods let you
configure the type of subscriber as well as the endpoint, so that the subscriber can be an SQS queue or
HTTP URL.
Amazon SNS notifications can only be turned on or off. Depending on the size and composition of
your environment, the frequency of notifications sent to the topic can be high. For notifications that
are only sent under specific circumstances, you can configure your environment to publish custom
metrics (p. 320) and set Amazon CloudWatch alarms (p. 330) to notify you when those metrics reach
an unhealthy threshold.
Configuring an Amazon SNS topic in the Elastic
Beanstalk console
The Elastic Beanstalk console lets you enter an email address during or after environment creation to
create an SNS topic for your environment.
During environment creation (p. 68), enter an Email address on the Configuration Details page:
API Version 2010-12-01
266
AWS Elastic Beanstalk Developer Guide
The aws:elasticbeanstalk:sns:topics Namespace
On a running environment, enter an Email on the environment configuration menu under Notifications:
When you enter an email address in either of these locations, Elastic Beanstalk creates an SNS topic for
your environment and adds a subscription. SNS sends an email to the subscribed address to confirm the
subscription. You must click on the link in the confirmation email to activate the subscription and receive
notifications.
The aws:elasticbeanstalk:sns:topics Namespace
Use the options in the aws:elasticbeanstalk:sns:topics namespace (p. 177) to configure SNS
notifications for your environment. These options can be set by using configuration files, a CLI or an SDK.
Notification Endpoint – Email address, SQS queue, or URL to send notifications to. Setting this
option creates an SQS queue and a subscription for the specified endpoint. If the endpoint is not an
email address, you must set the Notification Protocol option as well. SNS validates the value of
Notification Endpoint based on the value of Notification Protocol. Setting this option multiple
times creates additional subscriptions to the topic. Removing this option deletes the topic.
Notification Protocol – The protocol used to send notifications to the Notification Endpoint. This
option defaults to email. Set this option to email-json to send JSON formatted emails, http or https to
post JSON formatted notifications to an HTTP endpoint, or sqs to send notifications to an SQS queue.
Note
Lambda notifications are not currently supported.
Notification Topic ARN – After setting a notification endpoint for your environment, read this
setting to get the ARN of the SNS topic. You can also set this option to use an existing SNS topic for
notifications. A topic that you attach to your environment with this option is not deleted when this
option is changed or the environment is terminated.
Notification Topic Name – Set this option to customize the name of the SNS topic used for
environment notifications. If a topic with the same name already exists, Elastic Beanstalk attaches that
topic to the environment.
Warning
If you attach an existing SNS topic to an environment with Notification Topic Name, Elastic
Beanstalk will delete the topic if you terminate the environment or change this setting.
Changing this option also changes the Notification Topic ARN. If a topic is already attached to the
environment, Elastic Beanstalk deletes the old topic, and then creates a new topic and subscription.
API Version 2010-12-01
267
AWS Elastic Beanstalk Developer Guide
Domain Name
EB CLI and Elastic Beanstalk console apply recommended values for the preceding options.
These settings must be removed if you want to use configuration files to configure the same. See
Recommended Values (p. 195) for details.
Your Elastic Beanstalk Environment's Domain
Name
Your environment is available to users at a subdomain of elasticbeanstalk.com. When you create an
environment (p. 68), you can choose a unique subdomain that represents your application. To route users
to your environment Elastic Beanstalk registers a CNAME record that points to your environment's load
balancer. You can see the current value of the CNAME in the Environment Dashboard (p. 62):
You can change the CNAME on your environment by swapping it with the CNAME of another
environment. For instructions, see Blue/Green Deployments with AWS Elastic Beanstalk (p. 113).
If you own a domain name, you can use Amazon Route 53 to resolve it to your environment. You can
purchase a domain name with Amazon Route 53, or use one that you purchase from another provider. To
purchase a domain name with Amazon Route 53, see Registering a New Domain in the Amazon Route 53
Developer Guide.
To use a custom domain name, first create a hosted zone for your domain. A hosted zone contains the
name server and start of authority (SOA) records that specify the DNS hosts that will resolve requests for
your domain name.
To create a hosted zone in Amazon Route 53
1.
Open the Amazon Route 53 management console.
2.
3.
Choose Hosted Zones.
Choose Create Hosted Zone.
4.
5.
For Domain Name, type the domain name that you own. For example: example.com.
Choose Create.
Next, add a record to the hosted zone that resolves your domain name to your environment. When an
Amazon Route 53 DNS server receives a name request for your custom domain name, it resolves to the
elasticbeanstalk.com subdomain, which resolves to the public DNS name of your Elastic Load Balancing
load balancer, which relays requests to the instances in your environment.
Note
In a single-instance environment, the elasticbeanstalk.com subdomain resolves to an Elastic IP
address attached to the instance running your application.
If your environment has a regionalized subdomain, you can use an Amazon Route 53 alias resource
record set to save money on name resolution. The domain name for an environment with a regionalized
subdomain includes the region; for example, my-environment.us-west-2.elasticbeanstalk.com.
To add an alias resource record set in Amazon Route 53
1.
Open the Amazon Route 53 management console.
2.
3.
Choose Hosted Zones.
Choose your hosted zone's name.
API Version 2010-12-01
268
AWS Elastic Beanstalk Developer Guide
Domain Name
6.
7.
8.
Choose Create Record Set.
For Name, type the subdomain that will redirect to your Elastic Beanstalk application. For example:
www.
For Type, choose A - IPv4 address.
For Alias, choose yes
For Alias Target, choose the domain name of your Elastic Beanstalk environment.
9.
Choose Save Record Set.
4.
5.
If your environment does not have a regionalized subdomain, create a CNAME record instead.
To add a CNAME record in Amazon Route 53
1.
2.
Open the Amazon Route 53 management console.
Choose Hosted Zones.
3.
Choose your hosted zone's name.
4.
Choose Create Record Set.
5.
For Name, type the subdomain that will redirect to your Elastic Beanstalk application. For example:
www.
6.
For Type, choose CNAME - Canonical Name.
7.
For Value, type the domain name of your Elastic Beanstalk environment. For example:
example.elasticbeanstalk.com.
Choose Save Record Set.
8.
DNS records take up to 24 hours to propagate worldwide.
If you registered a domain name with another provider, register the name servers in your Amazon
Route 53 hosted zone in the domain configuration. When your provider receives DNS requests for your
domain name, it will forward them to Amazon Route 53's name servers to resolve the domain name to
an IP address. Look for a setting called Nameservers or check your provider's documentation.
The Amazon Route 53 console displays the list of name servers for your hosted zone in an NS record on
the Hosted Zones page:
If you have multiple environments running your application, you can use the Elastic Beanstalk console to
swap two environments' domain names. This allows you to deploy a new version of your application to a
standby environment, test it, and then swap domains with the production environment.
When you perform a CNAME swap, users are directed to the new version of your application with zero
downtime. This is known as a blue/green deployment.
To swap environment CNAMEs
1.
Open the Elastic Beanstalk console.
API Version 2010-12-01
269
AWS Elastic Beanstalk Developer Guide
Configuring HTTPS
2.
Choose either environment to open the Environment Dashboard.
3.
Choose Actions, and then choose Swap Environment URLs.
4.
Select the other environment.
5.
Choose Swap.
Configuring HTTPS for your Elastic Beanstalk
Environment
If you've purchased and configured a custom domain name (p. 268) for your Elastic Beanstalk
environment, you can use HTTPS to allow users to connect to your web site securely. If you don't own
a domain name, you can still use HTTPS with a self-signed certificate for development and testing
purposes. HTTPS is a must for any application that transmits user data or login information.
The simplest way to use HTTPS with an Elastic Beanstalk environment is to assign a server certificate to
your environment's load balancer (p. 273). When you configure your load balancer to terminate HTTPS,
the connection between the client and the load balancer is secure. Backend connections between the
load balancer and EC2 instances use HTTP, so no additional configuration of the instances is required.
Note
With AWS Certificate Manager (ACM), you can create a trusted certificate for your domain
names for free. ACM certificates can only be used with AWS load balancers and CloudFront
distributions.
To use an ACM certificate with Elastic Beanstalk, see Configuring Your Elastic Beanstalk
Environment's Load Balancer to Terminate HTTPS (p. 273)
If you run your application in a single instance environment, or need to secure the connection all the
way to the EC2 instances behind the load balancer, you can configure the proxy server that runs on the
instance to terminate HTTPS (p. 275). Configuring your instances to terminate HTTPS connections
requires the use of configuration files (p. 197) to modify the software running on the instances, and to
modify security groups to allow secure connections.
For end-to-end HTTPS in a load balanced environment, you can combine instance and load balancer
termination (p. 295) to encrypt both connections. By default, if you configure the load balancer to
forward traffic using HTTPS, it will trust any certificate presented to it by the backend instances. For
maximum security, you can attach policies to the load balancer that prevent it from connecting to
instances that don't present a public certificate that it trusts.
Note
You can also configure the load balancer to relay HTTPS traffic without decrypting it (p. 297).
The down side to this method is that the load balancer cannot see the requests and thus cannot
optimize routing or report response metrics.
If ACM is not available in your region, you can purchase a trusted certificate from a third party. A third
party certificate can be used to decrypt HTTPS traffic at your load balancer, on the backend instances, or
both.
For development and testing, you can create and sign a certificate (p. 271) yourself with open source
tools. Self-signed certificates are free and easy to create, but cannot be used for front-end decryption
on public sites. If you attempt to use a self-signed certificate for an HTTPS connection with a client, the
user's browser will show an error indicating that your web site is unsafe. You can, however, use a self
signed certificate to secure backend connections without issue.
You can upload a third party or self signed certificate and private key (p. 273) to AWS Identity and
Access Management (IAM) by using the AWS CLI. Certificates stored in IAM can be used with load
balancers and CloudFront distributions.
API Version 2010-12-01
270
AWS Elastic Beanstalk Developer Guide
Create a Certificate
Note
The Does it have Snakes? sample application on GitHub includes configuration files and
instructions for each method of configuring HTTPS with a Tomcat web application. See the
readme file and HTTPS instructions for details.
Topics
• Create and Sign an X509 Certificate (p. 271)
• Upload a Certificate to IAM (p. 273)
• Configuring Your Elastic Beanstalk Environment's Load Balancer to Terminate HTTPS (p. 273)
• Configuring Your Application to Terminate HTTPS Connections at the Instance (p. 275)
• Configuring End-to-End Encryption in a Load Balanced Elastic Beanstalk Environment (p. 295)
• Configuring Your Environment's Load Balancer for TCP Passthrough (p. 297)
• Storing Private Keys Securely in Amazon S3 (p. 298)
Create and Sign an X509 Certificate
You can create an X509 certificate for your application with OpenSSL. OpenSSL is a standard, open source
library that supports a wide range of cryptographic functions, including the creation and signing of x509
certificates. For more information about OpenSSL, visit www.openssl.org.
Note
You only need to create a certificate locally if you want to use HTTPS in a single instance
environment (p. 275) or re-encrypt on the backend (p. 295) with a self-signed certificate.
If you own a domain name, you can create a certificate in AWS and use it with a load balanced
environment for free by using AWS Certificate Manager (ACM). See Request a Certificate in the
AWS Certificate Manager User Guide for instructions.
Run openssl version at the command line to see if you already have OpenSSL installed. If you don't,
you can build and install the source code using the instructions at the public GitHub repository, or use
your favorite package manager. OpenSSL is also installed on Elastic Beanstalk's Linux images, so a quick
alternative is to connect to an EC2 instance in a running environment by using the EB CLI (p. 434)'s eb
ssh command:
~/eb$ eb ssh
[[email protected] ~]$ openssl version
OpenSSL 1.0.1k-fips 8 Jan 2015
You need to create an RSA private key to create your certificate signing request (CSR). To create your
private key, use the openssl genrsa command:
[[email protected] ~]$ openssl genrsa 2048 > privatekey.pem
Generating RSA private key, 2048 bit long modulus
.......................................................................................................
+++
...............+++
e is 65537 (0x10001)
privatekey.pem
The name of the file where you want to save the private key. Normally, the openssl genrsa
command prints the private key contents to the screen, but this command pipes the output to a file.
Choose any file name, and store the file in a secure place so that you can retrieve it later. If you lose
your private key, you won't be able to use your certificate.
API Version 2010-12-01
271
AWS Elastic Beanstalk Developer Guide
Create a Certificate
A CSR is a file you send to a certificate authority (CA) to apply for a digital server certificate. To create a
CSR, use the openssl req command:
$ openssl req -new -key privatekey.pem -out csr.pem
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
Enter the information requested and press Enter. The following table describes and shows examples for
each field:
Name
Description
Example
Country Name
The two-letter ISO abbreviation for your
country.
US = United States
State or Province
The name of the state or province where your
organization is located. You cannot abbreviate
this name.
Washington
Locality Name
The name of the city where your organization is
located.
Seattle
Organization Name
The full legal name of your organization. Do not
abbreviate your organization name.
Example Corporation
Organizational Unit
Optional, for additional organization
information.
Marketing
Common Name
The fully qualified domain name for your web
site. This must match the domain name that
users see when they visit your site, otherwise
certificate errors will be shown.
www.example.com
Email address
The site administrator's email address.
[email protected]
You can submit the signing request to a third party for signing, or sign it yourself for development and
testing. Self-signed certificates can also be used for backend HTTPS between a load balancer and EC2
instances.
To sign the certificate, use the openssl x509 command. The following example uses the private key
from the previous step (privatekey.pem) and the signing request (csr.pem) to create a public certificate
named server.crt that is valid for 365 days :
$ openssl x509 -req -days 365 -in csr.pem -signkey privatekey.pem -out server.crt
Signature ok
subject=/C=us/ST=washington/L=seattle/O=example corporation/OU=marketing/
CN=www.example.com/[email protected]
Getting Private key
Keep the private key and public certificate for later use. You can discard the signing request. Always store
the private key in a secure location (p. 298) and avoid adding it to your source code.
To use the certificate with the Windows Server platform, you must convert it to a PFX format. Use the
following command to create a PFX certificate from the private key and public certificate files:
API Version 2010-12-01
272
AWS Elastic Beanstalk Developer Guide
Upload a Certificate
$ openssl pkcs12 -export -out example.com.pfx -inkey privatekey.pem -in public.crt
Enter Export Password: password
Verifying - Enter Export Password: password
Now that you have a certificate, you can upload it to IAM (p. 273) for use with a load balancer, or
configure the instances in your environment to terminate HTTPS (p. 275).
Upload a Certificate to IAM
To use your certificate with your Elastic Beanstalk environment's load balancer, upload the certificate and
private key to AWS Identity and Access Management (IAM). You can use a certificate stored in IAM with
Elastic Load Balancing load balancers and CloudFront distributions.
You can use the AWS Command Line Interface (p. 433) (AWS CLI) to upload your certificate. The
following command uploads a self-signed certificate named https-cert.crt with a private key named
private-key.pem:
$ aws iam upload-server-certificate --server-certificate-name elastic-beanstalk-x509 -certificate-body file://https-cert.crt --private-key file://private-key.pem
{
"ServerCertificateMetadata": {
"ServerCertificateId": "AS5YBEIONO2Q7CAIHKNGC",
"ServerCertificateName": "elastic-beanstalk-x509",
"Expiration": "2017-01-31T23:06:22Z",
"Path": "/",
"Arn": "arn:aws:iam::123456789012:server-certificate/elastic-beanstalk-x509",
"UploadDate": "2016-02-01T23:10:34.167Z"
}
}
The file:// prefix tells the AWS CLI to load the contents of a file in the current directory. elasticbeanstalk-x509 specifies the name to call the certificate in IAM.
If you purchased a certificate from a certificate authority and received a certificate chain file, upload that
as well by including the --certificate-chain option:
$ aws iam upload-server-certificate --server-certificate-name elastic-beanstalk-x509 -certificate-chain file://certificate-chain.pem --certificate-body file://https-cert.crt -private-key file://private-key.pem
Make note of the Amazon Resource Name (ARN) for your certificate. You will use it when you update
your load balancer configuration settings to use HTTPS.
To see sample certificates that are valid with IAM, go to Sample Certificates in the AWS Identity and
Access Management Using IAM User Guide.
Configuring Your Elastic Beanstalk Environment's
Load Balancer to Terminate HTTPS
To update your Elastic Beanstalk environment to use HTTPS, you need to configure an HTTPS listener for
the load balancer in your environment.
You can use the Elastic Beanstalk Management Console to configure a secure listener and assign the
certificate.
To assign a certificate to your environment's load balancer (AWS Management Console)
1.
Open the Elastic Beanstalk console.
API Version 2010-12-01
273
AWS Elastic Beanstalk Developer Guide
Terminate HTTPS at the Load Balancer
2.
3.
4.
Navigate to the management page (p. 61) for your environment.
Choose Configuration.
In the Network Tier section, choose the gear icon next to Load Balancing.
Note
5.
If the Network Tier section is not shown, your environment does not have a load
balancer (p. 134).
In the Load Balancer section, choose your certificate from the SSL certificate ID drop down menu.
Configuring a Secure Listener with a Configuration File
You can configure a secure listener on your load balancer with a configuration file (p. 197) like the
following:
Example .ebextensions/securelistener.config
option_settings:
aws:elb:listener:443:
SSLCertificateId: arn:aws:acm:us-east-2:1234567890123:certificate/
####################################
ListenerProtocol: HTTPS
InstancePort: 80
Replace the highlighted text with the ARN of your certificate. The certificate can be one that you created
in ACM or one that you uploaded to IAM with the AWS CLI.
The above example uses options in the aws:elb:listener namespace to configure an HTTPS listener
on port 443 with the specified certificate, and forward the decrypted traffic to the instances in your
environment on port 80.
For more information on load balancer configuration options, see Load Balancer Configuration
Namespaces (p. 256).
Security Group Configuration
If you configure your load balancer to forward traffic to an instance port other than port 80, you must
add a rule to your security group that allows inbound traffic over the instance port from your load
balancer. If you create your environment in a custom VPC, Elastic Beanstalk adds this rule for you.
You add this rule by adding a Resources key to a configuration file (p. 197) in the .ebextensions
directory for your application.
The following example configuration file adds an ingress rule to the AWSEBSecurityGroup security group
allows traffic on port 1000 from the load balancer's security group.
Example .ebextensions/sg-ingressfromlb.config
Resources:
sslSecurityGroupIngress:
Type: AWS::EC2::SecurityGroupIngress
Properties:
GroupId: {"Fn::GetAtt" : ["AWSEBSecurityGroup", "GroupId"]}
IpProtocol: tcp
ToPort: 1000
FromPort: 1000
SourceSecurityGroupName: {"Fn::GetAtt" : ["AWSEBLoadBalancer" ,
"SourceSecurityGroup.GroupName"]}
API Version 2010-12-01
274
AWS Elastic Beanstalk Developer Guide
Terminate HTTPS at the Instance
Configuring Your Application to Terminate HTTPS
Connections at the Instance
You can use configuration files (p. 197) to configure the proxy server that passes traffic to your
application to terminate HTTPS connections. This is useful if you want to use HTTPS with a single
instance environment, or if you configure your load balancer to pass traffic through without decrypting
it.
To enable HTTPS, you must allow incoming traffic on port 443 to the EC2 instance that your Elastic
Beanstalk application is running on. You do this by using the Resources key in the configuration file to
add a rule for port 443 to the ingress rules for the AWSEBSecurityGroup security group.
The following snippet adds an ingress rule to the AWSEBSecurityGroup security group that opens port
443 to all traffic for a single instance environment:
.ebextensions/https-instance-securitygroup.config
Resources:
sslSecurityGroupIngress:
Type: AWS::EC2::SecurityGroupIngress
Properties:
GroupId: {"Fn::GetAtt" : ["AWSEBSecurityGroup", "GroupId"]}
IpProtocol: tcp
ToPort: 443
FromPort: 443
CidrIp: 0.0.0.0/0
In a load balanced environment in a default VPC, you can modify this policy to only accept traffic
from the load balancer. See Configuring End-to-End Encryption in a Load Balanced Elastic Beanstalk
Environment (p. 295) for an example.
Platforms
• Terminating HTTPS on EC2 Instances Running Docker (p. 275)
• Terminating HTTPS on EC2 Instances Running Go (p. 277)
• Terminating HTTPS on EC2 Instances Running Java SE (p. 279)
• Terminating HTTPS on EC2 Instances Running Node.js (p. 281)
• Terminating HTTPS on EC2 Instances Running PHP (p. 283)
• Terminating HTTPS on EC2 Instances Running Python (p. 285)
• Terminating HTTPS on EC2 Instances Running Ruby (p. 287)
• Terminating HTTPS on EC2 Instances Running Tomcat (p. 291)
• Terminating HTTPS on EC2 Instances Running .NET (p. 293)
Terminating HTTPS on EC2 Instances Running Docker
For Docker containers, you use a configuration file (p. 197) to enable HTTPS.
Add the following snippet to your configuration file, replacing the certificate and private key material as
instructed, and save it in your source bundle's .ebextensions directory. The configuration file performs
the following tasks:
• The files key creates the following files on the instance:
/etc/nginx/conf.d/https.conf
Configures the nginx server. This file is loaded when the nginx service starts.
API Version 2010-12-01
275
AWS Elastic Beanstalk Developer Guide
Terminate HTTPS at the Instance
/etc/pki/tls/certs/server.crt
Creates the certificate file on the instance. Replace certificate file contents with the contents
of your certificate.
Note
YAML relies on consistent indentation. Match the indentation level when replacing
content in an example configuration file and make sure that your text editor uses spaces,
not tab characters, to indent.
If you have intermediate certificates, include them in server.crt after your site certificate:
-----BEGIN CERTIFICATE----certificate file contents
-----END CERTIFICATE---------BEGIN CERTIFICATE----first intermediate certificate
-----END CERTIFICATE---------BEGIN CERTIFICATE----second intermediate certificate
-----END CERTIFICATE----/etc/pki/tls/certs/server.key
Creates the private key file on the instance. Replace private key contents with the contents of
the private key used to create the certificate request or self-signed certificate.
Example .ebextensions/https-instance.config
files:
/etc/nginx/conf.d/https.conf:
mode: "000644"
owner: root
group: root
content: |
# HTTPS Server
server {
listen 443;
server_name localhost;
ssl on;
ssl_certificate /etc/pki/tls/certs/server.crt;
ssl_certificate_key /etc/pki/tls/certs/server.key;
ssl_session_timeout 5m;
ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
ssl_ciphers "EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH";
ssl_prefer_server_ciphers on;
location / {
proxy_pass http://docker;
proxy_http_version 1.1;
}
}
proxy_set_header
proxy_set_header
proxy_set_header
proxy_set_header
Connection "";
Host $host;
X-Real-IP $remote_addr;
X-Forwarded-For $proxy_add_x_forwarded_for;
API Version 2010-12-01
276
AWS Elastic Beanstalk Developer Guide
Terminate HTTPS at the Instance
/etc/pki/tls/certs/server.crt:
mode: "000400"
owner: root
group: root
content: |
-----BEGIN CERTIFICATE----certificate file contents
-----END CERTIFICATE----/etc/pki/tls/certs/server.key:
mode: "000400"
owner: root
group: root
content: |
-----BEGIN RSA PRIVATE KEY----private key contents # See note below.
-----END RSA PRIVATE KEY-----
Note
Avoid commiting a configuration file that contains your private key to source control. After you
have tested the configuration and confirmed that it works, store your private key in Amazon S3
and modify the configuration to download it during deployment. For instructions, see Storing
Private Keys Securely in Amazon S3 (p. 298).
In a single instance environment, you must also modify the instance's security group to allow traffic on
port 443. The following configuration file retrieves the security group's ID using an AWS CloudFormation
function (p. 232) and adds a rule to it:
Example .ebextensions/https-instance-single.config
Resources:
sslSecurityGroupIngress:
Type: AWS::EC2::SecurityGroupIngress
Properties:
GroupId: {"Fn::GetAtt" : ["AWSEBSecurityGroup", "GroupId"]}
IpProtocol: tcp
ToPort: 443
FromPort: 443
CidrIp: 0.0.0.0/0
For a load balanced environment, you configure the load balancer to either pass secure traffic through
untouched (p. 297), or decrypt and re-encrypt (p. 295) for end-to-end encryption.
Terminating HTTPS on EC2 Instances Running Go
For Go container types, you enable HTTPS with a configuration file (p. 197) and an nginx configuration
file that configures the nginx server to use HTTPS.
Add the following snippet to your configuration file, replacing the certificate and private key
placeholders as instructed, and save it in your source bundle's .ebextensions directory. The
configuration file performs the following tasks:
• The Resources key enables port 443 on the security group used by your environment's instance.
• The files key creates the following files on the instance:
/etc/pki/tls/certs/server.crt
Creates the certificate file on the instance. Replace certificate file contents with the contents
of your certificate.
API Version 2010-12-01
277
AWS Elastic Beanstalk Developer Guide
Terminate HTTPS at the Instance
Note
YAML relies on consistent indentation. Match the indentation level when replacing
content in an example configuration file and make sure that your text editor uses spaces,
not tab characters, to indent.
If you have intermediate certificates, include them in server.crt after your site certificate:
-----BEGIN CERTIFICATE----certificate file contents
-----END CERTIFICATE---------BEGIN CERTIFICATE----first intermediate certificate
-----END CERTIFICATE---------BEGIN CERTIFICATE----second intermediate certificate
-----END CERTIFICATE----/etc/pki/tls/certs/server.key
Creates the private key file on the instance. Replace private key contents with the contents of
the private key used to create the certificate request or self-signed certificate.
• The container_commands key restarts the nginx server after everything is configured so that the server
loads the nginx configuration file.
Example .ebextensions/https-instance.config
files:
/etc/pki/tls/certs/server.crt:
content: |
-----BEGIN CERTIFICATE----certificate file contents
-----END CERTIFICATE----/etc/pki/tls/certs/server.key:
content: |
-----BEGIN RSA PRIVATE KEY----private key contents # See note below.
-----END RSA PRIVATE KEY----container_commands:
01restart_nginx:
command: "service nginx restart"
Note
Avoid commiting a configuration file that contains your private key to source control. After you
have tested the configuration and confirmed that it works, store your private key in Amazon S3
and modify the configuration to download it during deployment. For instructions, see Storing
Private Keys Securely in Amazon S3 (p. 298).
Place the following in a file with the .conf extension in the .ebextensions/nginx/conf.d/ directory of
your source bundle (e.g., .ebextensions/nginx/conf.d/https.conf). Replace app_port with the port
number that your application listens on. This example configures the nginx server to listen on port 443
using SSL. For more information about these configuration files on the Go platform, see Configuring the
Reverse Proxy (p. 616).
Example .ebextensions/nginx/conf.d/https.conf
# HTTPS server
API Version 2010-12-01
278
AWS Elastic Beanstalk Developer Guide
Terminate HTTPS at the Instance
server {
listen
server_name
443;
localhost;
ssl
ssl_certificate
ssl_certificate_key
on;
/etc/pki/tls/certs/server.crt;
/etc/pki/tls/certs/server.key;
ssl_session_timeout
5m;
ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
ssl_ciphers "EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH";
ssl_prefer_server_ciphers
on;
}
location / {
proxy_pass http://localhost:app_port;
proxy_set_header
Connection "";
proxy_http_version 1.1;
proxy_set_header
Host
$host;
proxy_set_header
X-Real-IP
$remote_addr;
proxy_set_header
X-Forwarded-For $proxy_add_x_forwarded_for;
}
In a single instance environment, you must also modify the instance's security group to allow traffic on
port 443. The following configuration file retrieves the security group's ID using an AWS CloudFormation
function (p. 232) and adds a rule to it:
Example .ebextensions/https-instance-single.config
Resources:
sslSecurityGroupIngress:
Type: AWS::EC2::SecurityGroupIngress
Properties:
GroupId: {"Fn::GetAtt" : ["AWSEBSecurityGroup", "GroupId"]}
IpProtocol: tcp
ToPort: 443
FromPort: 443
CidrIp: 0.0.0.0/0
For a load balanced environment, you configure the load balancer to either pass secure traffic through
untouched (p. 297), or decrypt and re-encrypt (p. 295) for end-to-end encryption.
Terminating HTTPS on EC2 Instances Running Java SE
For Java SE container types, you enable HTTPS with an .ebextensions configuration file (p. 197), and an
nginx configuration file that configures the nginx server to use HTTPS.
Add the following snippet to your configuration file, replacing the certificate and private key
placeholders as instructed, and save it in the .ebextensions directory. The configuration file performs
the following tasks:
• The files key creates the following files on the instance:
/etc/pki/tls/certs/server.crt
Creates the certificate file on the instance. Replace certificate file contents with the contents
of your certificate.
Note
YAML relies on consistent indentation. Match the indentation level when replacing
content in an example configuration file and make sure that your text editor uses spaces,
not tab characters, to indent.
API Version 2010-12-01
279
AWS Elastic Beanstalk Developer Guide
Terminate HTTPS at the Instance
If you have intermediate certificates, include them in server.crt after your site certificate:
-----BEGIN CERTIFICATE----certificate file contents
-----END CERTIFICATE---------BEGIN CERTIFICATE----first intermediate certificate
-----END CERTIFICATE---------BEGIN CERTIFICATE----second intermediate certificate
-----END CERTIFICATE----/etc/pki/tls/certs/server.key
Creates the private key file on the instance. Replace private key contents with the contents of
the private key used to create the certificate request or self-signed certificate.
• The container_commands key restarts the nginx server after everything is configured so that the server
loads the nginx configuration file.
Example .ebextensions/https-instance.config
files:
/etc/pki/tls/certs/server.crt:
content: |
-----BEGIN CERTIFICATE----certificate file contents
-----END CERTIFICATE----/etc/pki/tls/certs/server.key:
content: |
-----BEGIN RSA PRIVATE KEY----private key contents # See note below.
-----END RSA PRIVATE KEY----container_commands:
01restart_nginx:
command: "service nginx restart"
Note
Avoid commiting a configuration file that contains your private key to source control. After you
have tested the configuration and confirmed that it works, store your private key in Amazon S3
and modify the configuration to download it during deployment. For instructions, see Storing
Private Keys Securely in Amazon S3 (p. 298).
Place the following in a file with the .conf extension in the .ebextensions/nginx/conf.d/ directory of
your source bundle (e.g., .ebextensions/nginx/conf.d/https.conf). Replace app_port with the port
number that your application listens on. This example configures the nginx server to listen on port 443
using SSL. For more information about these configuration files on the Java SE platform, see Configuring
the Reverse Proxy (p. 637).
Example ebextensions/nginx/conf.d/https.conf
# HTTPS server
server {
listen
server_name
ssl
443;
localhost;
on;
API Version 2010-12-01
280
AWS Elastic Beanstalk Developer Guide
Terminate HTTPS at the Instance
ssl_certificate
ssl_certificate_key
/etc/pki/tls/certs/server.crt;
/etc/pki/tls/certs/server.key;
ssl_session_timeout
5m;
ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
ssl_ciphers "EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH";
ssl_prefer_server_ciphers
on;
}
location / {
proxy_pass http://localhost:app_port;
proxy_set_header
Connection "";
proxy_http_version 1.1;
proxy_set_header
Host
$host;
proxy_set_header
X-Real-IP
$remote_addr;
proxy_set_header
X-Forwarded-For $proxy_add_x_forwarded_for;
}
In a single instance environment, you must also modify the instance's security group to allow traffic on
port 443. The following configuration file retrieves the security group's ID using an AWS CloudFormation
function (p. 232) and adds a rule to it:
Example .ebextensions/https-instance-single.config
Resources:
sslSecurityGroupIngress:
Type: AWS::EC2::SecurityGroupIngress
Properties:
GroupId: {"Fn::GetAtt" : ["AWSEBSecurityGroup", "GroupId"]}
IpProtocol: tcp
ToPort: 443
FromPort: 443
CidrIp: 0.0.0.0/0
For a load balanced environment, you configure the load balancer to either pass secure traffic through
untouched (p. 297), or decrypt and re-encrypt (p. 295) for end-to-end encryption.
Terminating HTTPS on EC2 Instances Running Node.js
The following example configuration file extends the default nginx configuration (p. 724) to listen on
port 443 and terminate SSL/TLS connections with a public certificate and private key.
Example .ebextensions/https-instance.config
files:
/etc/nginx/conf.d/https.conf:
mode: "000644"
owner: root
group: root
content: |
# HTTPS server
server {
listen
server_name
443;
localhost;
ssl
ssl_certificate
ssl_certificate_key
on;
/etc/pki/tls/certs/server.crt;
/etc/pki/tls/certs/server.key;
ssl_session_timeout
5m;
API Version 2010-12-01
281
AWS Elastic Beanstalk Developer Guide
Terminate HTTPS at the Instance
ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
ssl_ciphers "EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH";
ssl_prefer_server_ciphers
on;
location / {
proxy_pass http://nodejs;
proxy_set_header
Connection "";
proxy_http_version 1.1;
proxy_set_header
Host
$host;
proxy_set_header
X-Real-IP
$remote_addr;
proxy_set_header
X-Forwarded-For $proxy_add_x_forwarded_for;
}
}
/etc/pki/tls/certs/server.crt:
mode: "000400"
owner: root
group: root
content: |
-----BEGIN CERTIFICATE----certificate file contents
-----END CERTIFICATE-----
/etc/pki/tls/certs/server.key:
mode: "000400"
owner: root
group: root
content: |
-----BEGIN RSA PRIVATE KEY----private key contents # See note below.
-----END RSA PRIVATE KEY-----
The files key creates the following files on the instance:
/etc/nginx/conf.d/https.conf
Configures the nginx server. This file is loaded when the nginx service starts.
/etc/pki/tls/certs/server.crt
Creates the certificate file on the instance. Replace certificate file contents with the contents of
your certificate.
Note
YAML relies on consistent indentation. Match the indentation level when replacing content
in an example configuration file and make sure that your text editor uses spaces, not tab
characters, to indent.
If you have intermediate certificates, include them in server.crt after your site certificate:
-----BEGIN CERTIFICATE----certificate file contents
-----END CERTIFICATE---------BEGIN CERTIFICATE----first intermediate certificate
-----END CERTIFICATE---------BEGIN CERTIFICATE----second intermediate certificate
-----END CERTIFICATE----/etc/pki/tls/certs/server.key
Creates the private key file on the instance. Replace private key contents with the contents of the
private key used to create the certificate request or self-signed certificate.
API Version 2010-12-01
282
AWS Elastic Beanstalk Developer Guide
Terminate HTTPS at the Instance
Note
Avoid commiting a configuration file that contains your private key to source control. After you
have tested the configuration and confirmed that it works, store your private key in Amazon S3
and modify the configuration to download it during deployment. For instructions, see Storing
Private Keys Securely in Amazon S3 (p. 298).
In a single instance environment, you must also modify the instance's security group to allow traffic on
port 443. The following configuration file retrieves the security group's ID using an AWS CloudFormation
function (p. 232) and adds a rule to it:
Example .ebextensions/https-instance-single.config
Resources:
sslSecurityGroupIngress:
Type: AWS::EC2::SecurityGroupIngress
Properties:
GroupId: {"Fn::GetAtt" : ["AWSEBSecurityGroup", "GroupId"]}
IpProtocol: tcp
ToPort: 443
FromPort: 443
CidrIp: 0.0.0.0/0
For a load balanced environment, you configure the load balancer to either pass secure traffic through
untouched (p. 297), or decrypt and re-encrypt (p. 295) for end-to-end encryption.
Terminating HTTPS on EC2 Instances Running PHP
For PHP container types, you use a configuration file (p. 197) to enable the Apache HTTP Server to use
HTTPS.
Add the following snippet to your configuration file, replacing the certificate and private key material as
instructed, and save it in your source bundle's .ebextensions directory.
The configuration file performs the following tasks:
• The packages key uses yum to install mod24_ssl.
• The files key creates the following files on the instance:
/etc/httpd/conf.d/ssl.conf
Configures the Apache server. This file loads when the Apache service starts.
/etc/pki/tls/certs/server.crt
Creates the certificate file on the instance. Replace certificate file contents with the contents
of your certificate.
Note
YAML relies on consistent indentation. Match the indentation level when replacing
content in an example configuration file and make sure that your text editor uses spaces,
not tab characters, to indent.
If you have intermediate certificates, include them in server.crt after your site certificate:
-----BEGIN CERTIFICATE----certificate file contents
-----END CERTIFICATE---------BEGIN CERTIFICATE----first intermediate certificate
-----END CERTIFICATE---------BEGIN CERTIFICATE-----
API Version 2010-12-01
283
AWS Elastic Beanstalk Developer Guide
Terminate HTTPS at the Instance
second intermediate certificate
-----END CERTIFICATE----/etc/pki/tls/certs/server.key
Creates the private key file on the instance. Replace private key contents with the contents of
the private key used to create the certificate request or self-signed certificate.
Example .ebextensions/https-instance.config
packages:
yum:
mod24_ssl : []
files:
/etc/httpd/conf.d/ssl.conf:
mode: "000644"
owner: root
group: root
content: |
LoadModule ssl_module modules/mod_ssl.so
Listen 443
<VirtualHost *:443>
<Proxy *>
Order deny,allow
Allow from all
</Proxy>
SSLEngine
SSLCertificateFile
SSLCertificateKeyFile
SSLCipherSuite
SSLProtocol
SSLHonorCipherOrder
SSLSessionTickets
on
"/etc/pki/tls/certs/server.crt"
"/etc/pki/tls/certs/server.key"
EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH
All -SSLv2 -SSLv3
On
Off
Header always set Strict-Transport-Security "max-age=63072000; includeSubdomains;
preload"
Header always set X-Frame-Options DENY
Header always set X-Content-Type-Options nosniff
ProxyPass / http://localhost:80/ retry=0
ProxyPassReverse / http://localhost:80/
ProxyPreserveHost on
RequestHeader set X-Forwarded-Proto "https" early
</VirtualHost>
/etc/pki/tls/certs/server.crt:
mode: "000400"
owner: root
group: root
content: |
-----BEGIN CERTIFICATE----certificate file contents
-----END CERTIFICATE----/etc/pki/tls/certs/server.key:
mode: "000400"
owner: root
group: root
content: |
-----BEGIN RSA PRIVATE KEY-----
API Version 2010-12-01
284
AWS Elastic Beanstalk Developer Guide
Terminate HTTPS at the Instance
private key contents # See note below.
-----END RSA PRIVATE KEY-----
Note
Avoid commiting a configuration file that contains your private key to source control. After you
have tested the configuration and confirmed that it works, store your private key in Amazon S3
and modify the configuration to download it during deployment. For instructions, see Storing
Private Keys Securely in Amazon S3 (p. 298).
In a single instance environment, you must also modify the instance's security group to allow traffic on
port 443. The following configuration file retrieves the security group's ID using an AWS CloudFormation
function (p. 232) and adds a rule to it:
Example .ebextensions/https-instance-single.config
Resources:
sslSecurityGroupIngress:
Type: AWS::EC2::SecurityGroupIngress
Properties:
GroupId: {"Fn::GetAtt" : ["AWSEBSecurityGroup", "GroupId"]}
IpProtocol: tcp
ToPort: 443
FromPort: 443
CidrIp: 0.0.0.0/0
For a load balanced environment, you configure the load balancer to either pass secure traffic through
untouched (p. 297), or decrypt and re-encrypt (p. 295) for end-to-end encryption.
Terminating HTTPS on EC2 Instances Running Python
For Python container types using Apache HTTP Server with the Web Server Gateway Interface (WSGI),
you use a configuration file (p. 197) to enable the Apache HTTP Server to use HTTPS.
Add the following snippet to your configuration file (p. 197), replacing the certificate and private key
material as instructed, and save it in your source bundle's .ebextensions directory. The configuration file
performs the following tasks:
• The packages key uses yum to install mod24_ssl.
• The files key creates the following files on the instance:
/etc/httpd/conf.d/ssl.conf
Configures the Apache server. Replace python site-packages directories with the Python sitepackages directories in your environment, separating each directory with a colon (:). The Python
site-packages directories vary depending on your environment.
Python 2.7
• /opt/python/run/venv/lib/python2.7/site-packages
• /opt/python/run/venv/lib64/python2.7/site-packages
Python 3.4
• /opt/python/run/venv/lib/python3.4/site-packages
• /opt/python/run/venv/lib64/python3.4/site-packages
Depending on your application requirements, you may also need to add other directories to the
python-path parameter.
/etc/pki/tls/certs/server.crt
Creates the certificate file on the instance. Replace certificate file contents with the contents
of your certificate.
API Version 2010-12-01
285
AWS Elastic Beanstalk Developer Guide
Terminate HTTPS at the Instance
Note
YAML relies on consistent indentation. Match the indentation level when replacing
content in an example configuration file and make sure that your text editor uses spaces,
not tab characters, to indent.
If you have intermediate certificates, include them in server.crt after your site certificate:
-----BEGIN CERTIFICATE----certificate file contents
-----END CERTIFICATE---------BEGIN CERTIFICATE----first intermediate certificate
-----END CERTIFICATE---------BEGIN CERTIFICATE----second intermediate certificate
-----END CERTIFICATE----/etc/pki/tls/certs/server.key
Creates the private key file on the instance. Replace private key contents with the contents of
the private key used to create the certificate request or self-signed certificate.
• The container_commands key stops the httpd service after everything has been configured so that the
service uses the new https.conf file and certificate.
• If your application is not named application.py, replace the highlighted text in the value for
WSGIScriptAlias with the local path to your application. For example, a django application's may be
at django/wsgi.py. The location should match the value of the WSGIPath option that you set for your
environment.
Example .ebextensions/https-instance.config
packages:
yum:
mod24_ssl : []
files:
/etc/httpd/conf.d/ssl.conf:
mode: "000644"
owner: root
group: root
content: |
LoadModule wsgi_module modules/mod_wsgi.so
WSGIPythonHome /opt/python/run/baselinenv
WSGISocketPrefix run/wsgi
WSGIRestrictEmbedded On
Listen 443
<VirtualHost *:443>
SSLEngine on
SSLCertificateFile "/etc/pki/tls/certs/server.crt"
SSLCertificateKeyFile "/etc/pki/tls/certs/server.key"
Alias /static/ /opt/python/current/app/static/
<Directory /opt/python/current/app/static>
Order allow,deny
Allow from all
</Directory>
WSGIScriptAlias / /opt/python/current/app/application.py
<Directory /opt/python/current/app>
Require all granted
API Version 2010-12-01
286
AWS Elastic Beanstalk Developer Guide
Terminate HTTPS at the Instance
</Directory>
WSGIDaemonProcess wsgi-ssl processes=1 threads=15 display-name=%{GROUP} \
python-path=/opt/python/current/app:<python site-packages directories> \
home=/opt/python/current/app \
user=wsgi \
group=wsgi
WSGIProcessGroup wsgi-ssl
</VirtualHost>
/etc/pki/tls/certs/server.crt:
mode: "000400"
owner: root
group: root
content: |
-----BEGIN CERTIFICATE----certificate file contents
-----END CERTIFICATE----/etc/pki/tls/certs/server.key:
mode: "000400"
owner: root
group: root
content: |
-----BEGIN RSA PRIVATE KEY----private key contents # See note below.
-----END RSA PRIVATE KEY----container_commands:
01killhttpd:
command: "killall httpd"
02waitforhttpddeath:
command: "sleep 3"
Note
Avoid commiting a configuration file that contains your private key to source control. After you
have tested the configuration and confirmed that it works, store your private key in Amazon S3
and modify the configuration to download it during deployment. For instructions, see Storing
Private Keys Securely in Amazon S3 (p. 298).
In a single instance environment, you must also modify the instance's security group to allow traffic on
port 443. The following configuration file retrieves the security group's ID using an AWS CloudFormation
function (p. 232) and adds a rule to it:
Example .ebextensions/https-instance-single.config
Resources:
sslSecurityGroupIngress:
Type: AWS::EC2::SecurityGroupIngress
Properties:
GroupId: {"Fn::GetAtt" : ["AWSEBSecurityGroup", "GroupId"]}
IpProtocol: tcp
ToPort: 443
FromPort: 443
CidrIp: 0.0.0.0/0
For a load balanced environment, you configure the load balancer to either pass secure traffic through
untouched (p. 297), or decrypt and re-encrypt (p. 295) for end-to-end encryption.
Terminating HTTPS on EC2 Instances Running Ruby
For Ruby container types, the way you enable HTTPS depends on the type of application server used.
API Version 2010-12-01
287
AWS Elastic Beanstalk Developer Guide
Terminate HTTPS at the Instance
Topics
• Configure HTTPS for Ruby with Puma (p. 288)
• Configure HTTPS for Ruby with Passenger (p. 290)
Configure HTTPS for Ruby with Puma
For Ruby container types that use Puma as the application server, you use a configuration file (p. 197)
to enable HTTPS.
Add the following snippet to your configuration file, replacing the certificate and private key material as
instructed, and save it in your source bundle's .ebextensions directory. The configuration file performs
the following tasks:
• The files key creates the following files on the instance:
/etc/nginx/conf.d/https.conf
Configures the nginx server. This file is loaded when the nginx service starts.
/etc/pki/tls/certs/server.crt
Creates the certificate file on the instance. Replace certificate file contents with the contents
of your certificate.
Note
YAML relies on consistent indentation. Match the indentation level when replacing
content in an example configuration file and make sure that your text editor uses spaces,
not tab characters, to indent.
If you have intermediate certificates, include them in server.crt after your site certificate:
-----BEGIN CERTIFICATE----certificate file contents
-----END CERTIFICATE---------BEGIN CERTIFICATE----first intermediate certificate
-----END CERTIFICATE---------BEGIN CERTIFICATE----second intermediate certificate
-----END CERTIFICATE----/etc/pki/tls/certs/server.key
Creates the private key file on the instance. Replace private key contents with the contents of
the private key used to create the certificate request or self-signed certificate.
• The container_commands key restarts the nginx server after everything is configured so that the server
uses the new https.conf file.
Example .ebextensions/https-instance.config
files:
/etc/nginx/conf.d/https.conf:
content: |
# HTTPS server
server {
listen
server_name
443;
localhost;
API Version 2010-12-01
288
AWS Elastic Beanstalk Developer Guide
Terminate HTTPS at the Instance
ssl
ssl_certificate
ssl_certificate_key
on;
/etc/pki/tls/certs/server.crt;
/etc/pki/tls/certs/server.key;
ssl_session_timeout
5m;
ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
ssl_ciphers "EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH";
ssl_prefer_server_ciphers
on;
location / {
proxy_pass http://my_app;
proxy_set_header
Host
$host;
proxy_set_header
X-Forwarded-For $proxy_add_x_forwarded_for;
}
location /assets {
alias /var/app/current/public/assets;
gzip_static on;
gzip on;
expires max;
add_header Cache-Control public;
}
}
location /public {
alias /var/app/current/public;
gzip_static on;
gzip on;
expires max;
add_header Cache-Control public;
}
/etc/pki/tls/certs/server.crt:
content: |
-----BEGIN CERTIFICATE----certificate file contents
-----END CERTIFICATE----/etc/pki/tls/certs/server.key:
content: |
-----BEGIN RSA PRIVATE KEY----private key contents # See note below.
-----END RSA PRIVATE KEY----container_commands:
01restart_nginx:
command: "service nginx restart"
Note
Avoid commiting a configuration file that contains your private key to source control. After you
have tested the configuration and confirmed that it works, store your private key in Amazon S3
and modify the configuration to download it during deployment. For instructions, see Storing
Private Keys Securely in Amazon S3 (p. 298).
In a single instance environment, you must also modify the instance's security group to allow traffic on
port 443. The following configuration file retrieves the security group's ID using an AWS CloudFormation
function (p. 232) and adds a rule to it:
Example .ebextensions/https-instance-single.config
Resources:
sslSecurityGroupIngress:
API Version 2010-12-01
289
AWS Elastic Beanstalk Developer Guide
Terminate HTTPS at the Instance
Type: AWS::EC2::SecurityGroupIngress
Properties:
GroupId: {"Fn::GetAtt" : ["AWSEBSecurityGroup", "GroupId"]}
IpProtocol: tcp
ToPort: 443
FromPort: 443
CidrIp: 0.0.0.0/0
For a load balanced environment, you configure the load balancer to either pass secure traffic through
untouched (p. 297), or decrypt and re-encrypt (p. 295) for end-to-end encryption.
Configure HTTPS for Ruby with Passenger
For Ruby container types that use Passenger as the application server, you use both a configuration file
and a JSON file to enable HTTPS.
To configure HTTPS for Ruby with Passenger
1.
Add the following snippet to your configuration file, replacing the certificate and private
key material as instructed, and save it in your source bundle's .ebextensions directory. The
configuration file performs the following tasks:
• The files key creates the following files on the instance:
/etc/pki/tls/certs/server.crt
Creates the certificate file on the instance. Replace certificate file contents with the
contents of your certificate.
Note
YAML relies on consistent indentation. Match the indentation level when replacing
content in an example configuration file and make sure that your text editor uses
spaces, not tab characters, to indent.
If you have intermediate certificates, include them in server.crt after your site certificate:
-----BEGIN CERTIFICATE----certificate file contents
-----END CERTIFICATE---------BEGIN CERTIFICATE----first intermediate certificate
-----END CERTIFICATE---------BEGIN CERTIFICATE----second intermediate certificate
-----END CERTIFICATE----/etc/pki/tls/certs/server.key
Creates the private key file on the instance. Replace private key contents with the contents
of the private key used to create the certificate request or self-signed certificate.
Example .ebextensions Snippet for Configuring HTTPS for Ruby with Passenger
files:
/etc/pki/tls/certs/server.crt:
content: |
-----BEGIN CERTIFICATE----certificate file contents
-----END CERTIFICATE-----
API Version 2010-12-01
290
AWS Elastic Beanstalk Developer Guide
Terminate HTTPS at the Instance
/etc/pki/tls/certs/server.key:
content: |
-----BEGIN RSA PRIVATE KEY----private key contents # See note below.
-----END RSA PRIVATE KEY-----
Note
Avoid commiting a configuration file that contains your private key to source control.
After you have tested the configuration and confirmed that it works, store your private
key in Amazon S3 and modify the configuration to download it during deployment. For
instructions, see Storing Private Keys Securely in Amazon S3 (p. 298).
2.
Create a text file and add the following JSON to the file. Save it in your source bundle's root
directory with the name passenger-standalone.json. This JSON file configures Passenger to use
HTTPS.
Important
This JSON file must not contain a byte order mark (BOM). If it does, the Passenger JSON
library will not read the file correctly and the Passenger service will not start.
Example passenger-standalone.json
{
}
"ssl" : true,
"ssl_port" : 443,
"ssl_certificate" : "/etc/pki/tls/certs/server.crt",
"ssl_certificate_key" : "/etc/pki/tls/certs/server.key"
In a single instance environment, you must also modify the instance's security group to allow traffic on
port 443. The following configuration file retrieves the security group's ID using an AWS CloudFormation
function (p. 232) and adds a rule to it:
Example .ebextensions/https-instance-single.config
Resources:
sslSecurityGroupIngress:
Type: AWS::EC2::SecurityGroupIngress
Properties:
GroupId: {"Fn::GetAtt" : ["AWSEBSecurityGroup", "GroupId"]}
IpProtocol: tcp
ToPort: 443
FromPort: 443
CidrIp: 0.0.0.0/0
For a load balanced environment, you configure the load balancer to either pass secure traffic through
untouched (p. 297), or decrypt and re-encrypt (p. 295) for end-to-end encryption.
Terminating HTTPS on EC2 Instances Running Tomcat
For Tomcat container types, you use a configuration file (p. 197) to enable the Apache HTTP Server to
use HTTPS when acting as the reverse proxy for Tomcat.
Add the following snippet to your configuration file, replacing the certificate and private key material as
instructed, and save it in your source bundle's .ebextensions directory. The configuration file performs
the following tasks:
• The packages key uses yum to install mod_ssl.
API Version 2010-12-01
291
AWS Elastic Beanstalk Developer Guide
Terminate HTTPS at the Instance
• The files key creates the following files on the instance:
/etc/pki/tls/certs/server.crt
Creates the certificate file on the instance. Replace certificate file contents with the contents
of your certificate.
Note
YAML relies on consistent indentation. Match the indentation level when replacing
content in an example configuration file and make sure that your text editor uses spaces,
not tab characters, to indent.
/etc/pki/tls/certs/server.key
Creates the private key file on the instance. Replace private key contents with the contents of
the private key used to create the certificate request or self-signed certificate.
• The container_commands key stops the httpd service after everything has been configured so that the
service uses the new https.conf file and certificate.
Example .ebextensions/https-instance.config
packages:
yum:
mod_ssl : []
files:
/etc/pki/tls/certs/server.crt:
mode: "000400"
owner: root
group: root
content: |
-----BEGIN CERTIFICATE----certificate file contents
-----END CERTIFICATE----/etc/pki/tls/certs/server.key:
mode: "000400"
owner: root
group: root
content: |
-----BEGIN RSA PRIVATE KEY----private key contents # See note below.
-----END RSA PRIVATE KEY----container_commands:
killhttpd:
command: "killall httpd"
waitforhttpddeath:
command: "sleep 3"
Your certificate vendor may include intermediate certificates that you can install for better compatibility
with mobile clients. Configure Apache with an intermediate certificate authority (CA) bundle by adding
the following to your SSL configuration file (see Extending the Default Apache Configuration (p. 630)
for the location):
• In the ssl.conf file contents, specify the chain file:
SSLCertificateKeyFile "/etc/pki/tls/certs/server.key"
SSLCertificateChainFile "/etc/pki/tls/certs/gd_bundle.crt"
SSLCipherSuite
EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH
• Add a new entry to the files key with the contents of the intermediate certificates:
API Version 2010-12-01
292
AWS Elastic Beanstalk Developer Guide
Terminate HTTPS at the Instance
files:
/etc/pki/tls/certs/gd_bundle.crt:
mode: "000400"
owner: root
group: root
content: |
-----BEGIN CERTIFICATE----First intermediate certificate
-----END CERTIFICATE---------BEGIN CERTIFICATE----Second intermediate certificate
-----END CERTIFICATE-----
Note
Avoid commiting a configuration file that contains your private key to source control. After you
have tested the configuration and confirmed that it works, store your private key in Amazon S3
and modify the configuration to download it during deployment. For instructions, see Storing
Private Keys Securely in Amazon S3 (p. 298).
In a single instance environment, you must also modify the instance's security group to allow traffic on
port 443. The following configuration file retrieves the security group's ID using an AWS CloudFormation
function (p. 232) and adds a rule to it:
Example .ebextensions/https-instance-single.config
Resources:
sslSecurityGroupIngress:
Type: AWS::EC2::SecurityGroupIngress
Properties:
GroupId: {"Fn::GetAtt" : ["AWSEBSecurityGroup", "GroupId"]}
IpProtocol: tcp
ToPort: 443
FromPort: 443
CidrIp: 0.0.0.0/0
For a load balanced environment, you configure the load balancer to either pass secure traffic through
untouched (p. 297), or decrypt and re-encrypt (p. 295) for end-to-end encryption.
Terminating HTTPS on EC2 Instances Running .NET
The following configuration file (p. 197) creates and runs a Windows PowerShell script that performs
the following tasks:
• Checks for an existing HTTPS certificate binding to port 443
• Gets the PFX certificate (p. 271) and password from an Amazon S3 bucket
Don't forget to to add an AmazonS3ReadOnlyAccess policy to the aws-elasticbeanstalk-service-role
to access the SSL certificate and password files on the Amazon S3 bucket.
• Installs the certificate
• Binds the certificate to port 443
See the comment above the Remove-WebBinding command if you want to remove the HTTP endpoint
(port 80).
API Version 2010-12-01
293
AWS Elastic Beanstalk Developer Guide
Terminate HTTPS at the Instance
Example .ebextensions/https-instance-dotnet.config
files:
"C:\\certs\\install-cert.ps1":
content: |
import-module webadministration
## Settings - replace the following values with your own
$bucket = "my-bucket"
## S3 bucket name
$certkey = "example.com.pfx" ## S3 object key for your PFX certificate
$pwdkey = "password.txt"
## S3 object key for a text file containing the
certificate's password
##
# Set variables
$certfile = "C:\cert.pfx"
$pwdfile = "C:\certs\pwdcontent"
Read-S3Object -BucketName $bucket -Key $pwdkey -File $pwdfile
$pwd = Get-Content $pwdfile -Raw
# Cleanup existing binding
if ( Get-WebBinding "Default Web Site" -Port 443 ) {
Echo "Removing WebBinding"
Remove-WebBinding -Name "Default Web Site" -BindingInformation *:443:
}
if ( Get-Item -path IIS:\SslBindings\0.0.0.0!443 ) {
Echo "Deregistering WebBinding from IIS"
Remove-Item -path IIS:\SslBindings\0.0.0.0!443
}
# Download certificate from S3
Read-S3Object -BucketName $bucket -Key $certkey -File $certfile
# Install certificate
Echo "Installing cert..."
$securepwd = ConvertTo-SecureString -String $pwd -Force -AsPlainText
$cert = Import-PfxCertificate -FilePath $certfile cert:\localMachine\my -Password
$securepwd
# Create site binding
Echo "Creating and registering WebBinding"
New-WebBinding -Name "Default Web Site" -IP "*" -Port 443 -Protocol https
New-Item -path IIS:\SslBindings\0.0.0.0!443 -value $cert -Force
80
## (optional) Remove the HTTP binding - uncomment the following line to unbind port
# Remove-WebBinding -Name "Default Web Site" -BindingInformation *:80:
##
# Update firewall
netsh advfirewall firewall add rule name="Open port 443" protocol=TCP localport=443
action=allow dir=OUT
commands:
00_install_ssl:
command: powershell -NoProfile -ExecutionPolicy Bypass -file C:\\certs\\installcert.ps1
In a single instance environment, you must also modify the instance's security group to allow traffic on
port 443. The following configuration file retrieves the security group's ID using an AWS CloudFormation
function (p. 232) and adds a rule to it:
Example .ebextensions/https-instance-single.config
Resources:
API Version 2010-12-01
294
AWS Elastic Beanstalk Developer Guide
End-to-End Encryption
sslSecurityGroupIngress:
Type: AWS::EC2::SecurityGroupIngress
Properties:
GroupId: {"Fn::GetAtt" : ["AWSEBSecurityGroup", "GroupId"]}
IpProtocol: tcp
ToPort: 443
FromPort: 443
CidrIp: 0.0.0.0/0
For a load balanced environment, you configure the load balancer to either pass secure traffic through
untouched (p. 297), or decrypt and re-encrypt (p. 295) for end-to-end encryption.
Configuring End-to-End Encryption in a Load
Balanced Elastic Beanstalk Environment
Terminating secure connections at the load balancer and using HTTP on the backend may be sufficient
for your application. Network traffic between AWS resources cannot be listened to by instances that are
not part of the connection, even if they are running under the same account.
However, if you are developing an application that needs to comply with strict external regulations, you
may be required to secure all network connections. You can use configuration files (p. 197) to make
your Elastic Beanstalk environment's load balancer connect to backend instances securely to meet these
requirements.
First add a secure listener to your load balancer (p. 273), if you haven't already:
.ebextensions/https-lbterminate.config
option_settings:
aws:elb:listener:443:
SSLCertificateId: arn:aws:acm:us-east-2:#############:certificate/
####################################
ListenerProtocol: HTTPS
You must also configure the instances in your environment to listen on the secure port and terminate
HTTPS connections. The configuration varies per platform. See Configuring Your Application to
Terminate HTTPS Connections at the Instance (p. 275) for instructions. You can use a self-signed
certificate (p. 271) for the EC2 instances without issue.
Next, configure the listener to forward traffic using HTTPS on the secure port used by your application.
You can also change the default health check to use this port and protocol to ensure that the load
balancer is able to connect securely. The following configuration file does both:
.ebextensions/https-reencrypt.config
option_settings:
aws:elb:listener:443:
InstancePort: 443
InstanceProtocol: HTTPS
aws:elasticbeanstalk:application:
Application Healthcheck URL: HTTPS:443/
Note
EB CLI and Elastic Beanstalk console apply recommended values for the preceding options.
These settings must be removed if you want to use configuration files to configure the same.
See Recommended Values (p. 195) for details.
API Version 2010-12-01
295
AWS Elastic Beanstalk Developer Guide
End-to-End Encryption
The next part is a bit more complex. You need to modify the load balancer's security group to allow
traffic, but depending on whether you launch your environment in the default VPC or a custom VPC,
the load balancer's security group will vary. In a default VPC, Elastic Load Balancing provides a default
security group that can be used by all load balancers. In a VPC that you create, Elastic Beanstalk creates a
security group for the load balancer to use.
To support both scenarios, you can create a security group and tell Elastic Beanstalk to use that. The
following configuration file creates a security group and attaches it to the load balancer:
.ebextensions/https-lbsecuritygroup.config
option_settings:
# Use the custom security group for the load balancer
aws:elb:loadbalancer:
SecurityGroups: '`{ "Ref" : "loadbalancersg" }`'
ManagedSecurityGroup: '`{ "Ref" : "loadbalancersg" }`'
Resources:
loadbalancersg:
Type: AWS::EC2::SecurityGroup
Properties:
GroupDescription: load balancer security group
VpcId: vpc-########
SecurityGroupIngress:
- IpProtocol: tcp
FromPort: 443
ToPort: 443
CidrIp: 0.0.0.0/0
- IpProtocol: tcp
FromPort: 80
ToPort: 80
CidrIp: 0.0.0.0/0
SecurityGroupEgress:
- IpProtocol: tcp
FromPort: 80
ToPort: 80
CidrIp: 0.0.0.0/0
Replace the highlighted text with your default or custom VPC ID. The above example includes ingress
and egress over port 80 to allow HTTP connections. You can remove those properties if you only want to
allow secure connections.
Finally, add ingress and egress rules that allow communication over 443 between the load balancer's
security group and the instances' security group:
.ebextensions/https-backendsecurity.config
Resources:
# Add 443-inbound to instance security group (AWSEBSecurityGroup)
httpsFromLoadBalancerSG:
Type: AWS::EC2::SecurityGroupIngress
Properties:
GroupId: {"Fn::GetAtt" : ["AWSEBSecurityGroup", "GroupId"]}
IpProtocol: tcp
ToPort: 443
FromPort: 443
SourceSecurityGroupId: {"Fn::GetAtt" : ["loadbalancersg", "GroupId"]}
# Add 443-outbound to load balancer security group (loadbalancersg)
httpsToBackendInstances:
Type: AWS::EC2::SecurityGroupEgress
Properties:
GroupId: {"Fn::GetAtt" : ["loadbalancersg", "GroupId"]}
IpProtocol: tcp
API Version 2010-12-01
296
AWS Elastic Beanstalk Developer Guide
TCP Passthrough
ToPort: 443
FromPort: 443
DestinationSecurityGroupId: {"Fn::GetAtt" : ["AWSEBSecurityGroup", "GroupId"]}
Doing this separately from security group creation allows you to restrict the source and destination
security groups without creating a circular dependency.
With all of the above pieces in place, the load balancer connects to your backend instances securely
Using HTTPS. The load balancer doesn't care if your instance's certificate is self-signed or issued by a
trusted certificate authority, and will accept any certificate presented to it.
You can change this by adding policies to the load balancer that tell it only to trust a specific certificate.
The following configuration file creates two policies. One policy specifies a public certificate, and the
other tells the load balancer to only trust that certificate for connections to instance port 443:
.ebextensions/https-backendauth.config
option_settings:
# Backend Encryption Policy
aws:elb:policies:backendencryption:
PublicKeyPolicyNames: backendkey
InstancePorts: 443
# Public Key Policy
aws:elb:policies:backendkey:
PublicKey: |
-----BEGIN CERTIFICATE----################################################################
################################################################
################################################################
################################################################
################################################
-----END CERTIFICATE-----
Replace the highlighted text with the contents of your EC2 instance's public certificate.
Configuring Your Environment's Load Balancer for
TCP Passthrough
If you don't want the load balancer in your AWS Elastic Beanstalk environment to decrypt HTTPS traffic,
you can configure the secure listener to relay requests to backend instances as-is.
First configure your environment's EC2 instances to terminate HTTPS (p. 275). Test the configuration on
a single instance environment to make sure everything works before adding a load balancer to the mix.
Add a configuration file (p. 197) to your project to configure a listener on port 443 that passes TCP
packets as-is to port 443 on backend instances:
.ebextensions/https-lb-passthrough.config
option_settings:
aws:elb:listener:443:
ListenerProtocol: TCP
InstancePort: 443
InstanceProtocol: TCP
In a default VPC, you also need to add a rule to the instances' security group to allow inbound traffic on
443 from the load balancer:
.ebextensions/https-instance-securitygroup.config
API Version 2010-12-01
297
AWS Elastic Beanstalk Developer Guide
Store Keys Securely
Resources:
443inboundfromloadbalancer:
Type: AWS::EC2::SecurityGroupIngress
Properties:
GroupId: {"Fn::GetAtt" : ["AWSEBSecurityGroup", "GroupId"]}
IpProtocol: tcp
ToPort: 443
FromPort: 443
SourceSecurityGroupName: { "Fn::GetAtt": ["AWSEBLoadBalancer",
"SourceSecurityGroup.GroupName"] }
In a custom VPC, Elastic Beanstalk updates the security group configuration for you.
Storing Private Keys Securely in Amazon S3
The private key that you use to sign your public certificate is private and should not be commited to
source code. You can avoid storing private keys in configuration files by uploading them to Amazon S3,
and configuring Elastic Beanstalk to download the file from Amazon S3 during application deployment.
The following example shows the Resources (p. 216) and files (p. 203) sections of a configuration
file (p. 197) downloads a private key file from an Amazon S3 bucket.
Example .ebextensions/privatekey.config
Resources:
AWSEBAutoScalingGroup:
Metadata:
AWS::CloudFormation::Authentication:
S3Auth:
type: "s3"
buckets: ["elasticbeanstalk-us-west-2-123456789012"]
roleName:
"Fn::GetOptionSetting":
Namespace: "aws:autoscaling:launchconfiguration"
OptionName: "IamInstanceProfile"
DefaultValue: "aws-elasticbeanstalk-ec2-role"
files:
# Private key
/etc/pki/tls/certs/server.key:
mode: "000400"
owner: root
group: root
authentication: "S3Auth"
source: https://s3-us-west-2.amazonaws.com/elasticbeanstalk-us-west-2-123456789012/
server.key
Replace the bucket name and URL in the example with your own. The first entry in this file adds an
authentication method named S3Auth to the environment's Auto Scaling group's metadata. If you have
configured a custom instance profile (p. 19) for your environment, that will be used, otherwise the
default value of aws-elasticbeanstalk-ec2-role is applied. The default instance profile has permission
to read from the Elastic Beanstalk storage bucket. If you use a different bucket, add permissions to the
instance profile (p. 357).
The second entry uses the S3Auth authentication method to download the private key from the specified
URL and save it to /etc/pki/tls/certs/server.key. The proxy server can then read the private key from
this location to terminate HTTPS connections at the instance (p. 275).
The instance profile assigned to your environment's EC2 instances must have permission to read the key
object from the specified bucket. Verify that the instance profile has permission (p. 357) to read the
object in IAM, and that the permissions on the bucket and object do not prohibit the instance profile.
API Version 2010-12-01
298
AWS Elastic Beanstalk Developer Guide
Store Keys Securely
To view a bucket's permissions
1.
2.
3.
4.
Open the Amazon S3 Management Console.
Choose a bucket.
Choose Properties and then choose Permissions.
Verify that your account is a grantee on the bucket with read permission.
5.
If a bucket policy is attached, the Edit bucket policy. Choose Edit bucket policy to view the
permissions assigned to the bucket.
API Version 2010-12-01
299
AWS Elastic Beanstalk Developer Guide
Monitoring Console
Monitoring an Environment
When you are running a production website, it is important to know that your application is available
and responding to requests. To assist with monitoring your application’s responsiveness, Elastic
Beanstalk provides features that monitor statistics about your application and create alerts that trigger
when thresholds are exceeded.
Topics
• Monitoring Environment Health in the AWS Management Console (p. 300)
• Basic Health Reporting (p. 303)
• Enhanced Health Reporting and Monitoring (p. 306)
• Manage Alarms (p. 330)
• Viewing an Elastic Beanstalk Environment's Event Stream (p. 333)
• Listing and Connecting to Server Instances (p. 334)
• Viewing Logs from Your Elastic Beanstalk Environment's Amazon EC2 Instances (p. 336)
Monitoring Environment Health in the AWS
Management Console
You can access operational information about your application from the AWS Management Console at
http://console.aws.amazon.com/elasticbeanstalk.
The AWS Management Console displays your environment's status and application health at a glance.
In the Elastic Beanstalk console applications page, each environment is color-coded to indicate an
environment's status.
To monitor an environment in the AWS Management Console
1.
Navigate to the Environment Management Console (p. 61) for your environment
2.
In the left navigation, click Monitoring.
The Monitoring page shows you overall statistics about your environment, such as CPU utilization
and average latency. In addition to the overall statistics, you can view monitoring graphs that show
resource usage over time. You can click any of the graphs to view more detailed information.
API Version 2010-12-01
300
AWS Elastic Beanstalk Developer Guide
Overview
Note
By default, only basic CloudWatch metrics are enabled, which return data in five-minute
periods. You can enable more granular one-minute CloudWatch metrics by editing your
environment's configuration settings.
Overview
An overview of the environment's health is shown near the top of the screen.
The overview panel shows a customizable summary of the activity in your environment over the last
hour. Click the Time Range drop-down and select a different length of time to view information for a
time period of five minutes to one day.
Monitoring Graphs
Below the overview are graphs that show data about overall environment health over the last twelve
hours. Click the Time Range drop-down and select a different length of time to view information for a
time period of three hours and two weeks.
API Version 2010-12-01
301
AWS Elastic Beanstalk Developer Guide
Customizing the Monitoring Console
Customizing the Monitoring Console
Click Edit next to either monitoring section to customize the information shown.
To remove any of the existing items, click the
in the top right corner.
To add an overview or graph
1.
Click Edit in the Overview or Monitoring section.
2.
Select a Resource. The supported resources are your environment's Auto Scaling group, Elastic Load
Balancing load balancer, and the environment itself.
3.
Select a CloudWatch metric for the resource. See Publishing Amazon CloudWatch Custom Metrics
for an Environment (p. 320) for a full list of supported metrics.
4.
Select a Statistic. The default statistic is the average value of the selected cloudwatch metric during
the time range (overview) or between plot points (graph).
5.
Enter a Description. The description is the label for the item shown in the monitoring console.
6.
Click Add.
7.
Repeat the previous steps to add more items or click Save to finish modifying the panel.
For more information about metrics and dimensions for each resource, see Amazon CloudWatch Metrics,
Namespaces, and Dimensions Reference in the Amazon CloudWatch User Guide.
Elastic Load Balancing and Amazon EC2 metrics are enabled for all environments.
With enhanced health (p. 306), the EnvironmentHealth metric is enabled and a graph is added to
the monitoring console automatically. Additional metrics become available for use in the monitoring
console when you enabled them in the environment configuration. Enhanced health also adds the Health
page (p. 314) to the management console.
API Version 2010-12-01
302
AWS Elastic Beanstalk Developer Guide
Basic Health Reporting
Note
When you enable additional CloudWatch metrics for your environment, it takes a few minutes
for them to start being reported and appear in the list of metrics that you use to add graphs and
overview stats.
See Publishing Amazon CloudWatch Custom Metrics for an Environment (p. 320) for a list of available
enhanced health metrics.
Basic Health Reporting
AWS Elastic Beanstalk uses information from multiple sources to determine if your environment is
available and processing requests from the Internet. An environment's health is represented by one
of four colors, which is displayed in the environment dashboard (p. 61), and is also available from the
DescribeEnvironments API and by calling eb status with the EB CLI (p. 434).
Prior to version 2 Linux platform configurations, the only health reporting system was basic health.
The basic health reporting system provides information about the health of instances in an Elastic
Beanstalk environment based on health checks performed by Elastic Load Balancing for load balanced
environments or Amazon Elastic Compute Cloud for single instance environments.
In addition to checking the health of your EC2 instances, Elastic Beanstalk also monitors the other
resources in your environment and reports missing or incorrectly configured resources that can cause
your environment to become unavailable to users.
Metrics gathered by the resources in your environment is published to Amazon CloudWatch in five
minute intervals. This includes operating system metrics from EC2, request metrics from Elastic Load
Balancing. You can view graphs based on these CloudWatch metrics on the Monitoring page (p. 300)
of the environment console. For basic health, these metrics are not used to determine an environment's
health.
Topics
• Health Colors (p. 303)
• Elastic Load Balancing Health Check (p. 304)
• Single Instance Environment Health Check (p. 304)
• Additional Checks (p. 304)
• Amazon CloudWatch Metrics (p. 305)
Health Colors
Elastic Beanstalk reports the health of a web server environment depending on how the application
running in it responds to the health check. Elastic Beanstalk uses one of four colors to describe status, as
shown in the following table:
Color
Description
Grey
Your environment is being updated.
Green
Your environment has passed the most recent health check. At least one
instance in your environment is available and taking requests.
Yellow
Your environment has failed one or more health checks. Some requests to
your environment are failing.
API Version 2010-12-01
303
AWS Elastic Beanstalk Developer Guide
Elastic Load Balancing Health Check
Color
Description
Red
Your environment has failed three or more health checks, or an environment
resource has become unavailable. Requests are consistently failing.
These descriptions only apply to environments using basic health reporting. See Health Colors and
Statuses (p. 317) for details related to enhanced health.
Elastic Load Balancing Health Check
In a load balanced environment, Elastic Load Balancing sends a request to each instance in an
environment every 30 seconds to confirm that instances are healthy. By default, the load balancer is
configured to open a TCP connection on port 80. If the instance acknowledges the connection, it is
considered healthy.
You can choose to override this setting by specifying an existing resource in your application. If you
specify a path, such as /health, the health check URL is set to http:80/health. The health check URL
should be set to a path that is always served by your application. If it is set to a static page that is served
or cached by the web server in front of your application, health checks will not reveal issues with the
application server or web container. For instructions on modifying your health check URL, see Health
Check (p. 255).
If a health check URL is configured, Elastic Load Balancing expects a GET request that it sends to return
a response of 200 OK. The application fails the health check if it fails to respond within 5 seconds or
if it responds with any other HTTP status code. After 5 consecutive health check failures, Elastic Load
Balancing takes the instance out of service.
For more information about Elastic Load Balancing health checks, see Health Check in the Elastic Load
Balancing User Guide.
Note
Configuring a health check URL does not change the health check behavior of an environment's
Auto Scaling group. An unhealthy instance is removed from the load balancer, but is not
automatically replaced by Auto Scaling unless you configure Auto Scaling to use the Elastic
Load Balancing health check as a basis for replacing instances. To configure Auto Scaling to
replace instances that fail an Elastic Load Balancing health check, see Auto Scaling Health Check
Setting (p. 246).
Single Instance Environment Health Check
In a single instance environment, Elastic Beanstalk determines the instance's health by monitoring its
Amazon EC2 instance status. Elastic Load Balancing health settings, including HTTP health check URLs,
cannot be used in a single instance environment.
For more information on Amazon EC2 instance status checks, see Monitoring Instances with Status
Checks in the Amazon EC2 User Guide for Linux Instances.
Additional Checks
In addition to Elastic Load Balancing health checks, Elastic Beanstalk monitors resources in your
environment and changes health status to red if they fail to deploy, are not configured correctly, or
become unavailable. These checks confirm that:
• The environment's Auto Scaling group is available and has a minimum of at least one instance.
• The environment's security group is available and is configured to allow incoming traffic on port 80.
API Version 2010-12-01
304
AWS Elastic Beanstalk Developer Guide
Amazon CloudWatch Metrics
• The environment CNAME exists and is pointing to the right load balancer.
• In a worker environment, the Amazon Simple Queue Service (Amazon SQS) queue is being polled at
least once every three minutes.
Amazon CloudWatch Metrics
With basic health reporting, the Elastic Beanstalk service does not publish any metrics to Amazon
CloudWatch. The CloudWatch metrics used to produce graphs on the Monitoring page (p. 300) of the
environment console are published by the resources in your environment.
For example, EC2 publishes the following metrics for the instances in your environment's Auto Scaling
group:
CPUUtilization
Percentage of compute units currently in use.
DiskReadBytes, DiskReadOps, DiskWriteBytes, DiskWriteOps
Number of bytes read and written, and number of read and write operations.
NetworkIn, NetworkOut
Number of bytes sent and received.
Elastic Load Balancing publishes the following metrics for your environment's load balancer:
BackendConnectionErrors
Number of connection failures between the load balancer and environment instances.
HTTPCode_Backend_2XX, HTTPCode_Backend_4XX
Number of successful (2XX) and client error (4XX) response codes generated by instances in your
environment.
Latency
Number of seconds between when the load balancer relays a request to an instance and when the
response is received.
RequestCount
Number of completed requests.
These lists are not comprehensive. For a full list of metrics that can be reported for these resources, see
the following topics in the Amazon CloudWatch Developer Guide:
Metrics
Namespace
Topic
AWS::ElasticLoadBalancing::LoadBalancer
Elastic Load Balancing Metrics and Resources
AWS::AutoScaling::AutoScalingGroup
Amazon Elastic Compute Cloud Metrics and
Resources
AWS::SQS::Queue
Amazon SQS Metrics and Resources
API Version 2010-12-01
305
AWS Elastic Beanstalk Developer Guide
Enhanced Health Reporting and Monitoring
Namespace
Topic
AWS::RDS::DBInstance
Amazon RDS Dimensions and Metrics
Worker Environment Health Metric
For worker environments only, the SQS daemon publishes a custom metric for environment health to
CloudWatch, where a value of 1 is Green. You can review the CloudWatch health metric data in your
account using the ElasticBeanstalk/SQSD namespace. The metric dimension is EnvironmentName, and
the metric name is Health. All instances publish their metrics to the same namespace.
To enable the daemon to publish metrics, the environment's instance profile must have permission to
call cloudwatch:PutMetricData. This permission is included in the default instance profile. For more
information, see Managing Elastic Beanstalk Instance Profiles (p. 354).
Enhanced Health Reporting and Monitoring
Enhanced health reporting is a feature that you can enable on your environment to allow AWS Elastic
Beanstalk to gather additional information about resources in your environment. Elastic Beanstalk
analyzes the information gathered to provide a better picture of overall environment health and aid in
the identification of issues that can cause your application to become unavailable.
In addition to changes in how health color works, enhanced health adds a status descriptor that provides
an indicator of the severity of issues observed when an environment is yellow or red. When more
information is available about the current status, you can choose the Causes button to view detailed
health information on the health page (p. 314).
To provide detailed health information about the EC2 instances running in your environment, Elastic
Beanstalk includes a health agent (p. 307) in the Amazon Machine Image (AMI) for each platform
configuration that supports enhanced health. The health agent monitors web server logs and system
metrics and relays them to the Elastic Beanstalk service. Elastic Beanstalk analyzes these metrics along
with data from Elastic Load Balancing and Auto Scaling to provide an overall picture of an environment's
health.
In addition to collecting and presenting information about your environment's resources, Elastic
Beanstalk monitors the resources in your environment for several error conditions and provides
API Version 2010-12-01
306
AWS Elastic Beanstalk Developer Guide
The Elastic Beanstalk Health Agent
notifications to help you avoid failures and resolve configuration issues. Factors that influence your
environment's health (p. 308) include the results of each request served by your application, metrics
from your instances' operating system, and the status of the most recent deployment.
You can view health status in real time by using the environment dashboard (p. 314) in the AWS
Management Console or the eb health (p. 457) command in the Elastic Beanstalk command line
interface (p. 434) (EB CLI). To record and track environment and instance health over time, you can
configure your environment to publish the information gathered by Elastic Beanstalk for enhanced
health reporting to Amazon CloudWatch as custom metrics. CloudWatch charges for custom metrics
apply to all metrics other than EnvironmentHealth, which is free of charge.
Enhanced health reporting requires a version 2 or newer platform configuration (p. 25) and is supported
by all platforms except Windows Server with IIS. In order to monitor resources and publish metrics, your
environment must have both an instance profile and service (p. 306) role. The Multicontainer Docker
configuration does not include a web server by default but can be used with enhanced health reporting if
you configure your web server to provide logs in the proper format (p. 327).
The first time you create an environment with a version 2 platform configuration in the AWS
Management Console, Elastic Beanstalk prompts you to create the required roles and enables enhanced
health reporting by default. Continue reading for details on how enhanced health reporting works, or
go to Enabling AWS Elastic Beanstalk Enhanced Health Reporting (p. 311) to get started using it right
away.
Topics
• The Elastic Beanstalk Health Agent (p. 307)
• Factors in Determining Instance and Environment Health (p. 308)
• Enhanced Health Roles (p. 310)
• Enhanced Health Events (p. 310)
• Enhanced Health Reporting Behavior During Updates, Deployments, and Scaling (p. 310)
• Enabling AWS Elastic Beanstalk Enhanced Health Reporting (p. 311)
• Enhanced Health Monitoring with the Environment Management Console (p. 314)
• Health Colors and Statuses (p. 317)
• Instance Metrics (p. 319)
• Publishing Amazon CloudWatch Custom Metrics for an Environment (p. 320)
• Using Enhanced Health Reporting with the AWS Elastic Beanstalk API (p. 325)
• Enhanced Health Log Format (p. 327)
• Notifications and Troubleshooting (p. 329)
The Elastic Beanstalk Health Agent
The Elastic Beanstalk health agent is a daemon process that runs on each EC2 instance in your
environment, monitoring operating system and application-level health metrics and reporting issues to
Elastic Beanstalk. The health agent is included in all Linux platform solution stacks starting with version
2.0 of each configuration.
The health agent reports similar metrics to those published to CloudWatch (p. 305) by Auto Scaling
and Elastic Load Balancing as part of basic health reporting (p. 303), including CPU load, HTTP codes,
and latency. The health agent, however, reports directly to Elastic Beanstalk, with greater granularity and
frequency than basic health reporting.
For basic health, these metrics are published every five minutes and can be monitored with graphs in the
environment management console. With enhanced health, the Elastic Beanstalk health agent reports
API Version 2010-12-01
307
AWS Elastic Beanstalk Developer Guide
Factors in Determining Instance and Environment Health
metrics to Elastic Beanstalk every ten seconds. Elastic Beanstalk uses the metrics provided by the health
agent to determine the health status of each instance in the environment, and, combined with other
factors (p. 308), to determine the overall health of the environment.
The overall health of the environment can be viewed in real-time in the environment dashboard and
is published to CloudWatch by Elastic Beanstalk every sixty seconds. Detailed metrics reported by the
health agent can be viewed in real time with the eb health (p. 457) command in the EB CLI (p. 434).
For an additional charge, you can choose to publish individual instance and environment level metrics to
CloudWatch every sixty seconds. Metrics published to CloudWatch can then be used to create monitoring
graphs (p. 302) in the environment management console (p. 61).
Enhanced health reporting only incurs a charge if you choose to publish enhanced health metrics to
CloudWatch. When you use enhanced health, you still get the basic health metrics published for free,
even if you don't choose to publish enhanced health metrics.
See Instance Metrics (p. 319) for details on the metrics reported by the health agent. For details on
publishing enhanced health metrics to CloudWatch, see Publishing Amazon CloudWatch Custom Metrics
for an Environment (p. 320).
Factors in Determining Instance and Environment
Health
In addition to the basic health reporting system checks, including Elastic Load Balancing Health
Check (p. 304) and resource monitoring (p. 304), Elastic Beanstalk enhanced health reporting gathers
additional data about the state of the instances in your environment, including operating system metrics,
server logs, and the state of ongoing environment operations such as deployments and updates. The
Elastic Beanstalk health reporting service combines information from all available sources and analyzes it
to determine the overall health of the environment.
Operations and Commands
When you perform an operation on your environment, such as deploying a new version of an application,
Elastic Beanstalk makes several changes that cause the health status of the environment to change.
For example, when you deploy a new version of an application to an environment that is running
multiple instances, you might see messages similar to the following as you monitor the environment's
health with the EB CLI (p. 457):
id
Overall
i-bb65c145
i-ba65c144
i-f6a2d525
seconds
i-e8a2d53b
i-e81cca40
status
Info
Pending
Pending
Ok
Pending
Ok
cause
Command is executing on 3 out of 5 instances
91 % of CPU is in use. 24 % in I/O wait
Performing application deployment (running for 31 seconds)
Performing initialization (running for 12 seconds)
Application deployment completed 23 seconds ago and took 26
94 % of CPU is in use. 52 % in I/O wait
Performing application deployment (running for 33 seconds)
In this example, the overall status of the environment is Ok and the cause of this status is that the
Command is executing on 3 out of 5 instances. Three of the instances in the environment have the status
Pending, indicating that an operation is in progress.
When an operation completes, Elastic Beanstalk reports additional information about the operation. For
the example, Elastic Beanstalk displays the following information about an instance that has already
been updated with the new version of the application:
API Version 2010-12-01
308
AWS Elastic Beanstalk Developer Guide
Factors in Determining Instance and Environment Health
i-f6a2d525
seconds
Ok
Application deployment completed 23 seconds ago and took 26
Instance health information also includes details about the most recent deployment to each instance
in your environment. Each instance reports a deployment ID and status. The deployment ID is an
integer that increases by one each time you deploy a new version of your application or change settings
for on-instance configuration options such as environment variables. You can use the deployment
information to identify instances that are running the wrong version of your application after a failed
rolling deployment (p. 110).
In the cause column, Elastic Beanstalk includes informational messages about successful operations
and other healthy states across multiple health checks, but they do not persist indefinitely. Causes for
unhealthy environment statuses persist until the environment returns to a healthy status.
Command Timeout
Elastic Beanstalk applies a command timeout from the time an operation begins to allow an instance
to transition into a healthy state. This command timeout is set in your environment's update and
deployment configuration (in the aws:elasticbeanstalk:command (p. 172) namespace) and defaults to 10
minutes.
During rolling updates, Elastic Beanstalk applies a separate timeout to each batch in the
operation. This timeout is set as part of the environment's rolling update configuration (in the
aws:autoscaling:updatepolicy:rollingupdate (p. 168) namespace). If all instances in the batch are healthy
within the command timeout, the operation continues to the next batch. If not, the operation fails.
Note
If your application does not pass health checks with Ok status but is stable at a different level,
you can set the HealthCheckSuccessThreshold option in the aws:elasticbeanstalk:command
namespace (p. 172) to change the level at which Elastic Beanstalk considers an instance to be
healthy.
For a web server environment to be considered healthy, each instance in the environment or batch must
pass 12 consecutive health checks over the course of two minutes. For worker tier, each instance must
pass 18 health checks. Prior to command timeout, Elastic Beanstalk does not lower an environment's
health status when health checks fail. As long as the instances in the environment and become healthy
within the command timeout, the operation succeeds.
HTTP Requests
When no operation is in progress on an environment, the primary source of information about instance
and environment health is the web server logs for each instance. To determine the health of an instance
and the overall health of the environment, Elastic Beanstalk considers the number of requests, the result
of each request, and the speed at which each request was resolved.
If you use Multicontainer Docker, which does not include a web server, or disable the web server (nginx or
Apache) that is included in other Elastic Beanstalk platforms, additional configuration is required to get
the Elastic Beanstalk health agent (p. 307) logs in the format that it needs to relay health information
to the Elastic Beanstalk service. See Enhanced Health Log Format (p. 327) for details.
Operating System Metrics
Elastic Beanstalk monitors operating system metrics reported by the health agent to identify instances
that are consistently low on system resources.
See Instance Metrics (p. 319) for details on the metrics reported by the health agent.
API Version 2010-12-01
309
AWS Elastic Beanstalk Developer Guide
Enhanced Health Roles
Enhanced Health Roles
Enhanced health reporting requires two roles—a service role for Elastic Beanstalk and an instance profile
for the environment. The service role allows Elastic Beanstalk to interact with other AWS services on
your behalf in order to gather information about the resources in your environment. The instance profile
allows the instances in your environment to write logs to Amazon S3.
When you create an Elastic Beanstalk environment in the AWS Management Console, the console
prompts you to create an instance profile and service role with appropriate permissions. The EB CLI also
assists you in creating these roles when you call eb create to create an environment.
If you use the API, an SDK, or the AWS CLI to create environments, you must create these roles
beforehand and specify them during environment creation to use enhanced health. For instructions
on creating appropriate roles for your environments, see Service Roles, Instance Profiles, and User
Policies (p. 17).
Enhanced Health Events
The enhanced health system generates events when an environment transitions between states. The
following example shows events output by an environment transitioning between Info, OK and Severe
states:
When transitioning to a worse state, Elastic Beanstalk includes a message indicating the cause in the
event.
Not all changes in status at an instance level will cause Elastic Beanstalk to emit an event. To prevent
false alarms, Elastic Beanstalk only generates a health related event if an issue persists across multiple
checks.
Real time environment level health information, including status, color and cause, is available in the
environment dashboard (p. 62) and the EB CLI (p. 434). By attaching the EB CLI to your environment
and running the eb health (p. 457) command, you can also view real time statuses from each of the
instances in your environment.
Enhanced Health Reporting Behavior During Updates,
Deployments, and Scaling
Enabling enhanced health reporting can affect how your environment behaves during configuration
updates and deployments. Elastic Beanstalk won't complete a batch of updates until all of the instances
API Version 2010-12-01
310
AWS Elastic Beanstalk Developer Guide
Enable Enhanced Health
pass health checks consistently, and since enhanced health reporting applies a higher standard for health
and monitors more factors, instances that pass basic health reporting's ELB health check (p. 304)
won't necessarily pass muster with enhanced health reporting. See the topics on rolling configuration
updates (p. 117) and rolling deployments (p. 110) for details on how health checks affect the update
process.
Enhanced health reporting can also highlight the need to set a proper health check URL (p. 255) for
Elastic Load Balancing. When your environment scales up to meet demand, new instances will start
taking requests as soon as they pass enough ELB health checks. If a health check URL is not configured,
this can be as little as 20 seconds after a new instance is able to accept a TCP connection.
If your application hasn't finished starting up by the time the load balancer declares it healthy enough
to receive traffic, you will see a flood of failed requests, and your environment will start to fail health
checks. A health check URL that hits a path served by your application can prevent this issue; ELB health
checks won't pass until a GET request to the health check URL returns a 200 status code.
Enabling AWS Elastic Beanstalk Enhanced Health
Reporting
New environments created with the latest platform versions (p. 25) include the AWS Elastic Beanstalk
health agent (p. 307), which supports enhanced health reporting. If you create your environment in the
AWS Management Console or with the EB CLI, enhanced health is enabled by default. You can also set
your health reporting preference in your application's source code using configuration files (p. 197).
Enhanced health reporting requires an instance profile (p. 19) and service role (p. 18) with the
standard set of permissions. When you create an environment in the Elastic Beanstalk Management
Console, Elastic Beanstalk creates the required roles automatically. See Getting Started Using Elastic
Beanstalk (p. 3) for instructions on creating your first environment.
Topics
• Enabling Enhanced Health Reporting with the AWS Management Console (p. 311)
• Enabling Enhanced Health Reporting with the EB CLI (p. 313)
• Enabling Enhanced Health Reporting with a Configuration File (p. 313)
Enabling Enhanced Health Reporting with the AWS
Management Console
To enable enhanced health reporting in a running environment with the AWS Management
Console
1.
Navigate to the management page (p. 61) for your environment.
2.
Choose Configuration.
3.
4.
On the Health panel under Web Tier, choose
.
Under Health Reporting, for System type, choose Enhanced.
API Version 2010-12-01
311
AWS Elastic Beanstalk Developer Guide
Enable Enhanced Health
Note
The options for enhanced health reporting do not appear if you are using an unsupported
platform or version (p. 306).
5.
Choose Apply.
The Elastic Beanstalk console defaults to enhanced health reporting when you create a new environment
with a version 2 platform configuration. You can disable enhanced health reporting by changing the
health reporting option during environment creation.
To disable enhanced health reporting when creating an environment using the AWS
Management Console
1.
Open the Elastic Beanstalk console.
2.
Create an application (p. 47) or select an existing one.
3.
Create an environment (p. 68). On the Configuration Details page, choose Basic for the health
reporting type under Health Reporting.
API Version 2010-12-01
312
AWS Elastic Beanstalk Developer Guide
Enable Enhanced Health
Enabling Enhanced Health Reporting with the EB CLI
When you create a new environment with the eb create command, the EB CLI enables enhanced health
reporting by default and applies the default instance profile and service role.
You can specify a different service role by name with the --service-role option.
If you have an environment running with basic health reporting on a version 2 platform configuration
and want to switch to enhanced health, follow these steps:
To enable enhanced health on a running environment using the EB CLI (p. 434)
1.
Use the eb config command to open the configuration file in the default text editor:
~/project$ eb config
2.
Locate the aws:elasticbeanstalk:environment namespace in the settings section. Ensure that the
value of ServiceRole is not null and that it matches the name of your service role (p. 18).
aws:elasticbeanstalk:environment:
EnvironmentType: LoadBalanced
ServiceRole: aws-elasticbeanstalk-service-role
3.
Under the aws:elasticbeanstalk:healthreporting:system: namespace, change the value of
SystemType to enhanced.
aws:elasticbeanstalk:healthreporting:system:
SystemType: enhanced
4.
Save the configuration file and close the text editor.
5.
The EB CLI starts an environment update to apply your configuration changes. Wait for the
operation to complete or press Ctrl-C to exit safely.
~/project$ eb config
Printing Status:
INFO: Environment update is starting.
INFO: Health reporting type changed to ENHANCED.
INFO: Updating environment no-role-test's configuration settings.
Enabling Enhanced Health Reporting with a Configuration File
You can enable enhanced health reporting by including a configuration file (p. 197) in your source
bundle. The following example shows a configuration file that enables enhanced health reporting and
assigns the default service and instance profile to the environment:
Example .ebextensions/enhanced-health.config
option_settings:
aws:elasticbeanstalk:healthreporting:system:
SystemType: enhanced
aws:autoscaling:launchconfiguration:
IamInstanceProfile: aws-elasticbeanstalk-ec2-role
aws:elasticbeanstalk:environment:
ServiceRole: aws-elasticbeanstalk-service-role
If you created your own instance profile or service role, replace the highlighted text with the names of
those roles.
API Version 2010-12-01
313
AWS Elastic Beanstalk Developer Guide
Health Console
Enhanced Health Monitoring with the Environment
Management Console
When you have enabled enhanced health reporting in AWS Elastic Beanstalk, you can monitor
environment health in the environment management console (p. 61).
Topics
• Environment Dashboard (p. 314)
• Environment Health Page (p. 314)
• Monitoring Page (p. 317)
Environment Dashboard
The environment dashboard (p. 62) displays the health status (p. 317) of the environment and lists
events that provide information about recent changes in health status.
To view the environment dashboard
1.
Open the Elastic Beanstalk console.
2.
Navigate to the management page (p. 61) for your environment.
For detailed information about the current environment's health, open the Health page by choosing
Causes.
Environment Health Page
The Health page displays health status, metrics and causes for the environment and for each EC2
instance in the environment.
Note
Elastic Beanstalk displays the Health page only if you have enabled enhanced health
monitoring (p. 311) for the environment.
API Version 2010-12-01
314
AWS Elastic Beanstalk Developer Guide
Health Console
To display only instances that have a particular status, chooseFilter By, and then choose a
status (p. 317).
To reboot or terminate an unhealthy instance, choose Instance Actions, and then choose Reboot or
Terminate.
To hide detailed information about the environment and instances' health, choose Hide Details. To show
or hide the details for a single instance, use the arrow at the beginning of the row:
Elastic Beanstalk updates the Health page every ten seconds. It reports information about environment
health for five categories.
API Version 2010-12-01
315
AWS Elastic Beanstalk Developer Guide
Health Console
The first category, Server, displays information about each of the EC2 instances in the environment,
including the instance's ID and status (p. 317), the amount of time since the instance was launched, and
the ID of the most recent deployment executed on the instance.
For more information about an instance, including its Availability Zone and instance type, pause on its
Instance ID:
For information about the last deployment (p. 108) to the instance, pause on the Deployment ID:
Deployment information includes the following:
API Version 2010-12-01
316
AWS Elastic Beanstalk Developer Guide
Health Colors and Statuses
• Deployment ID—The unique identifier for the deployment (p. 108). Deployment IDs starts at 1 and
increase by one each time you deploy a new application version or change configuration settings that
affect the software or operating system running on the instances in your environment.
• Version—The version label of the application source code used in the deployment.
• Status—The status of the deployment, which can be In Progress, Deployed, or Failed.
• Time— For in-progress deployments, the time that the deployment started. For completed
deployments, the time that the deployment ended.
The other categories provide detailed information about the results and latency of requests served by
each instance, and load and CPU utilization information for each instance. For details on these metrics,
see Instance Metrics (p. 319).
If you enable X-Ray integration (p. 262) on your environment and instrument your application with the
AWS X-Ray SDK, the Health page adds links to the AWS X-Ray console in the overview row.
Choose a link to view traces related to the highlighted statistic in the AWS X-Ray console.
Monitoring Page
The Monitoring page displays summary statistics and graphs for the custom Amazon CloudWatch metrics
generated by the enhanced health reporting system. See Monitoring Environment Health in the AWS
Management Console (p. 300) for instructions on adding graphs and statistics to this page.
Health Colors and Statuses
Enhanced health reporting represents instance and overall environment health with four colors, similar
to basic health reporting (p. 303). Enhanced health reporting also provides seven health statuses,
single word descriptors that provide a better indication of the state of your environment.
Instance Status and Environment Status
Every time Elastic Beanstalk runs a health check on your environment, enhanced health reporting checks
the health of each instance in your environment by analyzing all of the data (p. 308) available. If any of
the lower-level checks fails, Elastic Beanstalk downgrades the health of the instance.
Elastic Beanstalk displays the health information for the overall environment (color, status, and cause)
in the environment management console (p. 61). This information is also available in the EB CLI. Health
status and cause messages for individual instances are updated every ten seconds and are available from
the EB CLI (p. 434) when you view health status with eb health (p. 457).
API Version 2010-12-01
317
AWS Elastic Beanstalk Developer Guide
Health Colors and Statuses
Elastic Beanstalk uses changes in instance health to evaluate environment health, but does not
immediately change environment health status. When an instance fails health checks at least three times
in any one-minute period, Elastic Beanstalk may downgrade the health of the environment. Depending
on the number of instances in the environment and the issue identified, one unhealthy instance may
cause Elastic Beanstalk to display an informational message or to change the environment's health status
from green (OK) to yellow (Warning) or red (Degraded or Severe).
OK (Green)
An instance is passing health checks and the health agent is not reporting any problems.
Most instances in the environment are passing health checks and the health agent is not reporting major
issues.
An instance is passing health checks and is completing requests normally.
Example: Your environment was recently deployed and is taking requests normally. Five percent of
requests are returning 400 series errors. Deployment completed normally on each instance.
Message (Instance): Application deployment completed 23 seconds ago and took 26 seconds.
Warning (Yellow)
The health agent is reporting a moderate number of request failures or other issues for an instance or
environment.
An operation in progress on an instance and is taking a very long time.
Example: One instance in the environment has a status of Severe.
Message (Environment): Impaired services on 1 out of 5 instances
Degraded (Red)
The health agent is reporting a high number of request failures or other issues for an instance or
environment.
Example: Environment is in the process of scaling up to 5 instances.
Message (Environment): 4 active instances is below Auto Scaling group minimum size 5
Severe (Red)
The health agent is reporting a very high number of request failures or other issues for an instance or
environment.
Example: Elastic Beanstalk is unable to contact the load balancer to get instance health.
Message (Environment): ELB health is failing or not available for all instances. None of the instances are
sending data. Unable to assume role "arn:aws:iam::0123456789012:role/aws-elasticbeanstalk-servicerole". Verify that the role exists and is configured correctly.
Message (Instances): Instance ELB health has not been available for 37 minutes. No data. Last seen 37
minutes ago.
Info (Green)
An operation is in progress on an instance.
API Version 2010-12-01
318
AWS Elastic Beanstalk Developer Guide
Instance Metrics
An operation is in progress on several instances in an environment.
Example: A new application version is being deployed to running instances.
Message (Environment): Command is executing on 3 out of 5 instances
Message (Instance): Performing application deployment (running for 3 seconds)
Pending (Grey)
An operation is in progress on an instance within the command timeout (p. 309).
Example: You have recently created the environment and instances are being bootstrapped.
Message: Performing initialization (running for 12 seconds)
Unknown (Grey)
Elastic Beanstalk and the health agent are reporting an insufficient amount of data on an instance.
Example: No data is being received.
Instance Metrics
Instance metrics provide information about the health of instances in your environment. The AWS Elastic
Beanstalk Elastic Beanstalk health agent (p. 307) gathers and relays metrics about instances to Elastic
Beanstalk, which analyzes the metrics to determine the health of the instances in your environments.
The Elastic Beanstalk health agent gathers metrics about instances from web server logs and the
operating system. Web server logs provide information about incoming HTTP requests: how many
requests came in, how many resulted in errors, and how long they took to resolve. The operating system
provides snapshot information about the state of the instances' resources: the CPU load and distribution
of time spent on each process type. These metrics are a subset of the information that you would see if
you ran top on a Linux server.
The health agent gathers web server and operating system metrics and relays them to Elastic Beanstalk
every ten seconds. Elastic Beanstalk analyzes the data and uses the results to update the health status
for each instance and the environment.
Web Server Metrics
The Elastic Beanstalk health agent reads web server metrics from logs generated by the web container
or server that processes requests on each instance in your environment. Elastic Beanstalk platforms are
configured to generate two logs: one in human readable format and one in machine readable format.
The health agent relays machine-readable logs to Elastic Beanstalk every ten seconds.
For more information on the log format used by Elastic Beanstalk, see Enhanced Health Log
Format (p. 327).
Web Server Metrics
RequestCount
Number of requests handled by the web server per second over the last 10 seconds. Shown as an
average r/sec (requests per second) in the EB CLI and Environment Health Page (p. 314)
API Version 2010-12-01
319
AWS Elastic Beanstalk Developer Guide
CloudWatch
Status2xx, Status3xx, Status4xx, Status5xx
Number of requests that resulted in each type of status code over the last 10 seconds. For example,
successful requests return a 200 OK, redirects are a 301, and a 404 is returned if the URL entered
does not match any resources in the application.
The EB CLI and Environment Health Page (p. 314) show these metrics both as a raw number of
requests for instances, and as a percentage of overall requests for environments.
p99.9, p99, p95, p90, p85, p75, p50, p10
Average latency for the slowest x percent of requests over the last 10 seconds, where x is the
difference between the number and 100. For example, p99 indicates the latency for the slowest 1%
of requests over the last 10 seconds.
Operating System Metrics
The Elastic Beanstalk health agent reports the following operating system metrics. Elastic Beanstalk uses
these metrics to identify instances that are under sustained heavy load:
Operating System Metrics
Running
The amount of time that has passed since the instance was launched.
Load 1, Load 5
Load average in the last 1-minute and 5-minute periods. Shown as a decimal value indicating the
average number of processes running during that time. If the number shown is higher than the
number of vCPUs (threads) available, then the remainder is the average number of processes that
were waiting.
For example, if your instance type has 4 vCPUs, and the load is 4.5, there was an average of .5
processes in wait during that time period, equivalent to one process was waiting 50 percent of the
time.
User %, Nice %, System %, Idle %, I/O Wait %
Percentage of time that the CPU has spent in each state over the last 10 seconds.
Publishing Amazon CloudWatch Custom Metrics for
an Environment
You can publish the data gathered by AWS Elastic Beanstalk enhanced health reporting to Amazon
CloudWatch as custom metrics. Publishing metrics to CloudWatch lets you monitor changes in
application performance over time and identify potential issues by tracking how resource usage and
request latency scale with load.
By publishing metrics to CloudWatch you also make them available for use with monitoring
graphs (p. 301) and alarms (p. 330). One free metric, EnvironmentHealth is enabled automatically
when you use enhanced health reporting. Custom metrics other than EnvironmentHealth incur standard
CloudWatch charges.
To publish CloudWatch custom metrics for an environment, you must first enable enhanced health
reporting on the environment. See Enabling AWS Elastic Beanstalk Enhanced Health Reporting (p. 311)
for instructions.
API Version 2010-12-01
320
AWS Elastic Beanstalk Developer Guide
CloudWatch
Topics
• Enhanced Health Reporting Metrics (p. 321)
• Configuring CloudWatch Metrics in the AWS Management Console (p. 322)
• Configuring CloudWatch Custom Metrics with the EB CLI (p. 322)
• Providing Custom Metric Config Documents (p. 323)
Enhanced Health Reporting Metrics
When you enabled enhanced health reporting in your environment, the enhanced health reporting
system automatically publishes one CloudWatch custom metric, EnvironmentHealth. To publish
additional metrics to CloudWatch, configure your environment with the metrics that you want to publish
using the AWS Management Console (p. 322), the EB CLI (p. 322), or .ebextensions (p. 145).
EnvironmentHealth
Environment only. This is the only CloudWatch metric that is published by the enhanced health
system unless you configure additional metrics. Environment health is represented by one of seven
statuses (p. 317). In the CloudWatch console, these statuses map to the following values:
• 0 – OK
• 1 – Info
• 5 – Unknown
• 10 – No data
• 15 – Warning
• 20 – Degraded
• 25 – Severe
InstancesSevere, InstancesDegraded, InstancesWarning, InstancesInfo, InstancesOk,
InstancesPending, InstancesUnknown, InstancesNoData
Environment only. These metrics indicate the number of instances in the environment with each
health status. InstancesNoData indicates the number of instances for which no data is being
received for (if any).
ApplicationRequestsTotal, ApplicationRequests5xx, ApplicationRequests4xx,
ApplicationRequests3xx, ApplicationRequests2xx
Instance and environment. Indicates the total number of requests completed by the instance or
environment, and the number of requests that completed with each status code category.
ApplicationLatencyP10, ApplicationLatencyP50, ApplicationLatencyP75, ApplicationLatencyP85,
ApplicationLatencyP90, ApplicationLatencyP95, ApplicationLatencyP99, ApplicationLatencyP99.9
Instance and environment. Indicates the average amount of time, in seconds, it takes to complete
the fastest x percent of requests.
LoadAverage1min
Instance only. The average CPU load of the instance over the last minute.
InstanceHealth
Instance only. Indicates the current health status of the instance.
RootFilesystemUtil
Instance only. Indicates the percentage of disk space in use.
API Version 2010-12-01
321
AWS Elastic Beanstalk Developer Guide
CloudWatch
CPUIrq, CPUUser, CPUIdle, CPUSystem, CPUSoftirq, CPUIowait, CPUNice
Instance only. Indicates the percentage of time that the CPU has spent in each state over the last
minute.
Configuring CloudWatch Metrics in the AWS Management
Console
Use the AWS Management Console to configure your environment to publish enhanced health reporting
metrics to CloudWatch and make them available for use with monitoring graphs and alarms.
To configure CloudWatch custom metrics in the AWS Management Console
1.
Open the Elastic Beanstalk console.
2.
Navigate to the management page (p. 61) for your environment.
3.
Choose Configuration.
4.
5.
On the Health panel, under Web Tier, choose
(edit).
Under Health Reporting, select the instance and environment metrics that you want to publish to
CloudWatch. To select multiple metrics, hold the Ctrl key while choosing.
Enabling CloudWatch custom metrics adds them to the list of metrics available in the Monitoring
Console (p. 300).
Configuring CloudWatch Custom Metrics with the EB CLI
You can use the EB CLI to configure custom metrics by saving your environment's configuration locally,
adding an entry that defines the metrics to publish, and then uploading the configuration to Elastic
Beanstalk. The saved configuration can be applied to an environment during or after creation.
To configure CloudWatch custom metrics with the EB CLI and saved configurations
1.
2.
Initialize your project folder with eb init (p. 443).
Create an environment by running the eb create (p. 446) command.
3.
Save a configuration template locally by running the eb config save command. The following
example uses the --cfg option to specify the name of the configuration.
$ eb config save --cfg 01-base-state
Configuration saved at: ~/project/.elasticbeanstalk/saved_configs/01-base-state.cfg.yml
4.
5.
Open the saved configuration file in a text editor.
Under OptionSettings > aws:elasticbeanstalk:healthreporting:system:, add a ConfigDocument
key to enable each of the CloudWatch metrics that you want to enable. For example, the following
ConfigDocument publishes ApplicationRequests5xx and ApplicationRequests4xx metrics at the
environment level, and ApplicationRequestsTotal metrics at the instance level:
OptionSettings:
...
aws:elasticbeanstalk:healthreporting:system:
ConfigDocument:
CloudWatchMetrics:
Environment
ApplicationRequests5xx: 60
ApplicationRequests4xx: 60
Instance:
API Version 2010-12-01
322
AWS Elastic Beanstalk Developer Guide
CloudWatch
...
ApplicationRequestsTotal: 60
Version: 1
SystemType: enhanced
Note
In the example, 60 indicates the number of seconds between measurements. This is the
only currently supported value.
6.
Save the configuration file and close the text editor. In this example, the updated configuration
file is saved with a different name (02-cloudwatch-enabled.cfg.yml) than the downloaded
configuration file. This will create a separate saved configuration when the file is uploaded. You can
use the same name as the downloaded file to overwrite the existing configuration without creating a
new one.
7.
Upload the updated configuration file to Elastic Beanstalk with the eb config put command:
$ eb config put 02-cloudwatch-enabled
When using the eb config get and put commands with saved configurations, do not include the file
extension..
8.
Apply the saved configuration to your running environment:
$ eb config --cfg 02-cloudwatch-enabled
The --cfg option specifies a named configuration file that is applied to the environment. The
configuration can be saved locally or in Elastic Beanstalk. If a configuration file with the specified
name exists in both locations, the EB CLI uses the local file.
Providing Custom Metric Config Documents
The config document for Amazon CloudWatch custom metrics is a JSON document that lists the metrics
to publish at an environment and instance level. The following example shows a config document that
enables all available custom metrics:
{
"CloudWatchMetrics": {
"Environment": {
"ApplicationLatencyP99.9": 60,
"InstancesSevere": 60,
"ApplicationLatencyP90": 60,
"ApplicationLatencyP99": 60,
"ApplicationLatencyP95": 60,
"InstancesUnknown": 60,
"ApplicationLatencyP85": 60,
"InstancesInfo": 60,
"ApplicationRequests2xx": 60,
"InstancesDegraded": 60,
"InstancesWarning": 60,
"ApplicationLatencyP50": 60,
"ApplicationRequestsTotal": 60,
"InstancesNoData": 60,
"InstancesPending": 60,
"ApplicationLatencyP10": 60,
"ApplicationRequests5xx": 60,
"ApplicationLatencyP75": 60,
"InstancesOk": 60,
"ApplicationRequests3xx": 60,
API Version 2010-12-01
323
AWS Elastic Beanstalk Developer Guide
CloudWatch
}
"ApplicationRequests4xx": 60
},
"Instance": {
"ApplicationLatencyP99.9": 60,
"ApplicationLatencyP90": 60,
"ApplicationLatencyP99": 60,
"ApplicationLatencyP95": 60,
"ApplicationLatencyP85": 60,
"CPUUser": 60,
"ApplicationRequests2xx": 60,
"CPUIdle": 60,
"ApplicationLatencyP50": 60,
"ApplicationRequestsTotal": 60,
"RootFilesystemUtil": 60,
"LoadAverage1min": 60,
"CPUIrq": 60,
"CPUNice": 60,
"CPUIowait": 60,
"ApplicationLatencyP10": 60,
"LoadAverage5min": 60,
"ApplicationRequests5xx": 60,
"ApplicationLatencyP75": 60,
"CPUSystem": 60,
"ApplicationRequests3xx": 60,
"ApplicationRequests4xx": 60,
"InstanceHealth": 60,
"CPUSoftirq": 60
}
},
"Version": 1
For the AWS CLI, you pass the document as a value for the Value key in an option settings argument,
which itself is a JSON object. In this case, quotes in the embedded document must be escaped:
$ aws elasticbeanstalk validate-configuration-settings --application-name my-app -environment-name my-env --option-settings '[
{
"Namespace": "aws:elasticbeanstalk:healthreporting:system",
"OptionName": "ConfigDocument",
"Value": "{\"CloudWatchMetrics\": {\"Environment\": {\"ApplicationLatencyP99.9\":
60,\"InstancesSevere\": 60,\"ApplicationLatencyP90\": 60,\"ApplicationLatencyP99\":
60,\"ApplicationLatencyP95\": 60,\"InstancesUnknown\": 60,\"ApplicationLatencyP85\":
60,\"InstancesInfo\": 60,\"ApplicationRequests2xx\": 60,\"InstancesDegraded\": 60,
\"InstancesWarning\": 60,\"ApplicationLatencyP50\": 60,\"ApplicationRequestsTotal
\": 60,\"InstancesNoData\": 60,\"InstancesPending\": 60,\"ApplicationLatencyP10\":
60,\"ApplicationRequests5xx\": 60,\"ApplicationLatencyP75\": 60,\"InstancesOk\":
60,\"ApplicationRequests3xx\": 60,\"ApplicationRequests4xx\": 60},\"Instance\":
{\"ApplicationLatencyP99.9\": 60,\"ApplicationLatencyP90\": 60,\"ApplicationLatencyP99\":
60,\"ApplicationLatencyP95\": 60,\"ApplicationLatencyP85\": 60,\"CPUUser\": 60,
\"ApplicationRequests2xx\": 60,\"CPUIdle\": 60,\"ApplicationLatencyP50\": 60,
\"ApplicationRequestsTotal\": 60,\"RootFilesystemUtil\": 60,\"LoadAverage1min\":
60,\"CPUIrq\": 60,\"CPUNice\": 60,\"CPUIowait\": 60,\"ApplicationLatencyP10\": 60,
\"LoadAverage5min\": 60,\"ApplicationRequests5xx\": 60,\"ApplicationLatencyP75\":
60,\"CPUSystem\": 60,\"ApplicationRequests3xx\": 60,\"ApplicationRequests4xx\": 60,
\"InstanceHealth\": 60,\"CPUSoftirq\": 60}},\"Version\": 1}"}
]'
For an .ebextensions configuration file in YAML, you can provide the JSON document as is:
option_settings:
- namespace: aws:elasticbeanstalk:healthreporting:system
option_name: ConfigDocument
API Version 2010-12-01
324
AWS Elastic Beanstalk Developer Guide
API Users
}
value: {
"CloudWatchMetrics": {
"Environment": {
"ApplicationLatencyP99.9": 60,
"InstancesSevere": 60,
"ApplicationLatencyP90": 60,
"ApplicationLatencyP99": 60,
"ApplicationLatencyP95": 60,
"InstancesUnknown": 60,
"ApplicationLatencyP85": 60,
"InstancesInfo": 60,
"ApplicationRequests2xx": 60,
"InstancesDegraded": 60,
"InstancesWarning": 60,
"ApplicationLatencyP50": 60,
"ApplicationRequestsTotal": 60,
"InstancesNoData": 60,
"InstancesPending": 60,
"ApplicationLatencyP10": 60,
"ApplicationRequests5xx": 60,
"ApplicationLatencyP75": 60,
"InstancesOk": 60,
"ApplicationRequests3xx": 60,
"ApplicationRequests4xx": 60
},
"Instance": {
"ApplicationLatencyP99.9": 60,
"ApplicationLatencyP90": 60,
"ApplicationLatencyP99": 60,
"ApplicationLatencyP95": 60,
"ApplicationLatencyP85": 60,
"CPUUser": 60,
"ApplicationRequests2xx": 60,
"CPUIdle": 60,
"ApplicationLatencyP50": 60,
"ApplicationRequestsTotal": 60,
"RootFilesystemUtil": 60,
"LoadAverage1min": 60,
"CPUIrq": 60,
"CPUNice": 60,
"CPUIowait": 60,
"ApplicationLatencyP10": 60,
"LoadAverage5min": 60,
"ApplicationRequests5xx": 60,
"ApplicationLatencyP75": 60,
"CPUSystem": 60,
"ApplicationRequests3xx": 60,
"ApplicationRequests4xx": 60,
"InstanceHealth": 60,
"CPUSoftirq": 60
}
},
"Version": 1
Using Enhanced Health Reporting with the AWS
Elastic Beanstalk API
Because AWS Elastic Beanstalk enhanced health reporting has role and solution stack requirements, you
must update scripts and code that you used prior to the release of enhanced health reporting before
you can use it. To maintain backward compatibility, enhanced health reporting is not enabled by default
when you create an environment using the Elastic Beanstalk API.
API Version 2010-12-01
325
AWS Elastic Beanstalk Developer Guide
API Users
You configure enhanced health reporting by setting the service role, the instance profile, and Amazon
CloudWatch configuration options for your environment. You can do this in three ways: by setting the
configuration options in the .ebextensions folder, with saved configurations, or by configuring them
directly in the create-environment call's option-settings parameter.
To use the API, SDKs, or AWS command line interface (CLI) to create an environment that supports
enhanced health, you must:
• Create a service role and instance profile with the appropriate permissions (p. 17)
• Create a new environment with a solution stack for a new version of the platform configuration (p. 25)
• Set the health system type, instance profile, and service role configuration options (p. 145)
Use the following configuration options in the aws:elasticbeanstalk:healthreporting:system,
aws:autoscaling:launchconfiguration, and aws:elasticbeanstalk:environment namespaces to
configure your environment for enhanced health reporting.
Enhanced Health Configuration Options
SystemType
Namespace: aws:elasticbeanstalk:healthreporting:system
To enable enhanced health reporting, set to enhanced.
IamInstanceProfile
Namespace: aws:autoscaling:launchconfiguration
Set to the name of an instance profile configured for use with Elastic Beanstalk.
ServiceRole
Namespace: aws:elasticbeanstalk:environment
Set to the name of a service role configured for use with Elastic Beanstalk.
ConfigDocument (optional)
Namespace: aws:elasticbeanstalk:healthreporting:system
A JSON document that defines the and instance and environment metrics to publish to CloudWatch. For
example:
{
}
"CloudWatchMetrics":
{
"Environment":
{
"ApplicationLatencyP99.9":60,
"InstancesSevere":60
}
"Instance":
{
"ApplicationLatencyP85":60,
"CPUUser": 60
}
}
"Version":1
API Version 2010-12-01
326
AWS Elastic Beanstalk Developer Guide
Enhanced Health Log Format
Note
Config documents may require special formatting, such as escaping quotes, depending
on how you provide them to Elastic Beanstalk. See Providing Custom Metric Config
Documents (p. 323) for examples.
Enhanced Health Log Format
AWS Elastic Beanstalk platforms use a custom web server log format to efficiently relay information
about HTTP requests to the enhanced health reporting system, which analyzes the logs, identifies issues,
and sets the instance and environment health accordingly. If you disable the web server proxy on your
environment and serve requests directly from the web container, you can still make full use of enhanced
health reporting by configuring your server to output logs in the location and format that the Elastic
Beanstalk health agent (p. 307) uses.
Web Server Log Configuration
Elastic Beanstalk platforms are configured to output two logs with information about HTTP requests.
The first is in verbose format and provides detailed information about the request, including the
requester's user agent information and a human-readable timestamp.
/var/log/nginx/access.log
The following example is from an nginx proxy running on a Ruby web server environment, but the
format is similar for Apache:
172.31.24.3 - - [23/Jul/2015:00:21:20
(x86_64-pc-linux-gnu) libcurl/7.22.0
"177.72.242.17"
172.31.24.3 - - [23/Jul/2015:00:21:21
(x86_64-pc-linux-gnu) libcurl/7.22.0
"177.72.242.17"
172.31.24.3 - - [23/Jul/2015:00:21:22
(x86_64-pc-linux-gnu) libcurl/7.22.0
"177.72.242.17"
172.31.24.3 - - [23/Jul/2015:00:21:22
(x86_64-pc-linux-gnu) libcurl/7.22.0
"177.72.242.17"
172.31.24.3 - - [23/Jul/2015:00:21:22
(x86_64-pc-linux-gnu) libcurl/7.22.0
"177.72.242.17"
+0000] "GET / HTTP/1.1" 200 11 "-" "curl/7.22.0
OpenSSL/1.0.1 zlib/1.2.3.4 libidn/1.23 librtmp/2.3"
+0000] "GET / HTTP/1.1" 200 11 "-" "curl/7.22.0
OpenSSL/1.0.1 zlib/1.2.3.4 libidn/1.23 librtmp/2.3"
+0000] "GET / HTTP/1.1" 200 11 "-" "curl/7.22.0
OpenSSL/1.0.1 zlib/1.2.3.4 libidn/1.23 librtmp/2.3"
+0000] "GET / HTTP/1.1" 200 11 "-" "curl/7.22.0
OpenSSL/1.0.1 zlib/1.2.3.4 libidn/1.23 librtmp/2.3"
+0000] "GET / HTTP/1.1" 200 11 "-" "curl/7.22.0
OpenSSL/1.0.1 zlib/1.2.3.4 libidn/1.23 librtmp/2.3"
The second log is in terse format. It includes information relevant only to enhanced health reporting.
This log is output to a subfolder named healthd and rotates hourly. Old logs are deleted immediately
after rotating out.
/var/log/nginx/healthd/application.log.2015-07-23-00
The following example shows a log in the machine-readable format.
1437609879.311"/"200"0.083"0.083"177.72.242.17
1437609879.874"/"200"0.347"0.347"177.72.242.17
1437609880.006"/bad/path"404"0.001"0.001"177.72.242.17
1437609880.058"/"200"0.530"0.530"177.72.242.17
1437609880.928"/bad/path"404"0.001"0.001"177.72.242.17
The enhanced health log format includes the following information:
• The time of the request, in Unix time.
API Version 2010-12-01
327
AWS Elastic Beanstalk Developer Guide
Enhanced Health Log Format
• The path of the request.
• The HTTP status code for the result.
• The request time.
• The upstream time.
• The X-Forwarded-For HTTP header.
For nginx proxies, times are printed in floating-point seconds, with three decimal places. For Apache,
whole milliseconds are used.
Note
If you see a warning similar to the following in a log file, where DATE-TIME is a date and time,
and you are using a custom proxy, such as in a multi-container Docker environment. you must
use an .ebextension to configure your environment so that healthd can read your log files:
W, [DATE-TIME #1922] WARN -- : log file "/var/log/nginx/healthd/
application.log.DATE-TIME" does not exist
You can start with the .ebextension in the Multicontainer Docker sample.
/etc/nginx/conf.d/webapp_healthd.conf
The following example shows the log configuration for nginx with the healthd log format highlighted:
upstream my_app {
server unix:///var/run/puma/my_app.sock;
}
log_format healthd '$msec"$uri"'
'$status"$request_time"$upstream_response_time"'
'$http_x_forwarded_for';
server {
listen 80;
server_name _ localhost; # need to listen to localhost for worker tier
if ($time_iso8601 ~ "^(\d{4})-(\d{2})-(\d{2})T(\d{2})") {
set $year $1;
set $month $2;
set $day $3;
set $hour $4;
}
access_log /var/log/nginx/access.log main;
access_log /var/log/nginx/healthd/application.log.$year-$month-$day-$hour healthd;
location / {
proxy_pass http://my_app; # match the name of upstream directive which is defined above
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
location /assets {
alias /var/app/current/public/assets;
gzip_static on;
gzip on;
expires max;
add_header Cache-Control public;
}
location /public {
API Version 2010-12-01
328
AWS Elastic Beanstalk Developer Guide
Notifications and Troubleshooting
}
}
alias /var/app/current/public;
gzip_static on;
gzip on;
expires max;
add_header Cache-Control public;
Generating Logs for Enhanced Health Reporting
To provide logs to the health agent, you must do the following:
• Output logs in the correct format, as shown in the previous section
• Output logs to /var/log/nginx/healthd/
• Name logs using the following format: application.log.$year-$month-$day-$hour
• Rotate logs once per hour
• Do not truncate logs
Notifications and Troubleshooting
This page lists example cause messages for common issues and links to more information. Cause
messages appear in the environment dashboard (p. 300) and are recorded in events (p. 333) when
health issues persist across several checks.
Deployments
Elastic Beanstalk monitors your environment for consistency following deployments. If a rolling
deployment fails, the version of your application running on the instances in your environment may vary.
This can occur if a deployment succeeds on one or more batches but fails prior to all batches completing.
Incorrect application version found on 2 out of 5 instances. Expected version "v1" (deployment 1).
Incorrect application version on environment instances. Expected version "v1" (deployment 1).
The expected application version is not running on some or all instances in an environment.
Incorrect application version "v2" (deployment 2). Expected version "v1" (deployment 1).
The application deployed to an instance differs from the expected version. If a deployment fails, the
expected version is reset to the version from the most recent successful deployment. In the above
example, the first deployment (version "v1") succeeded, but the second deployment (version "v2") failed.
Any instances running "v2" are considered unhealthy.
To solve this issue, start another deployment. You can redeploy a previous version (p. 108) that you know
works, or configure your environment to ignore health checks (p. 110) during deployment and redeploy
the new version to force the deployment to complete.
You can also identify and terminate the instances that are running the wrong application version. Elastic
Beanstalk will launch instances with the correct version to replace any instances that you terminate.
Use the EB CLI health command (p. 457) to identify instances that are running the wrong application
version.
Application Server
15% of requests are erroring with HTTP 4xx
API Version 2010-12-01
329
AWS Elastic Beanstalk Developer Guide
Manage Alarms
20% of the requests to the ELB are erroring with HTTP 4xx.
A high percentage of HTTP requests to an instance or environment are failing with 4xx errors.
A 400 series status code indicates that the user made a bad request, such as requesting a page that
doesn't exist (404 File Not Found) or that the user doesn't have access to (403 Forbidden). A low number
of 404s is not unusual but a large number could mean that there are internal or external links to
unavailable pages. These issues can be resolved by fixing bad internal links and adding redirects for bad
external links.
5% of the requests are failing with HTTP 5xx
3% of the requests to the ELB are failing with HTTP 5xx.
A high percentage of HTTP requests to an instance or environment are failing with 500 series status
codes.
A 500 series status code indicates that the application server encountered an internal error. These issues
indicate that there is an error in your application code and should be identified and fixed quickly.
95% of CPU is in use
On an instance, the health agent is reporting an extremely high percentage of CPU usage and sets the
instance health to Warning or Degraded.
Scale your environment to take load off of instances.
Worker Instance
20 messages waiting in the queue (25 seconds ago)
Requests are being added to your worker environment's queue faster than they can be processed. Scale
your environment to increase capacity.
5 messages in Dead Letter Queue (15 seconds ago)
Worker requests are failing repeatedly and being added to the Dead Letter Queue (p. 139). Check the
requests in the dead letter queue to see why they are failing.
Other Resources
4 active instances is below Auto Scaling group minimum size 5
The number of instances running in your environment is fewer than the minimum configured for the
Auto Scaling group.
Auto Scaling group (groupname) notifications have been deleted or modified
The notifications configured for your Auto Scaling group have been modified outside of Elastic
Beanstalk.
Manage Alarms
You can create alarms for metrics that you are monitoring by using the AWS Management Console.
Alarms help you monitor changes to your environment so that you can easily identify and mitigate
API Version 2010-12-01
330
AWS Elastic Beanstalk Developer Guide
Manage Alarms
problems before they occur. For example, you can set an alarm that notifies you when CPU utilization in
an environment exceeds a certain threshold, ensuring that you are notified before a potential problem
occurs. For more information, see Using Elastic Beanstalk with Amazon CloudWatch (p. 345).
Note
Elastic Beanstalk uses CloudWatch for monitoring and alarms, meaning CloudWatch costs are
applied to your AWS account for any alarms that you use.
For more information about monitoring specific metrics, see Basic Health Reporting (p. 303).
To check the state of your alarms
1.
From the Elastic Beanstalk console applications page, click the environment name that you want to
manage alarms for.
2.
From the navigation menu, click Alarms to see a list of alarms.
If any alarms is in the alarm state, they are flagged with
3.
4.
(warning).
To filter alarms, click the drop-down filter and select the filter that you want.
To edit or delete an alarm, click
(edit) or
(delete).
To create an alarm
1.
From the Elastic Beanstalk console applications page, click the environment name that you want to
add alarms to.
2.
From the navigation menu, click Monitoring.
API Version 2010-12-01
331
AWS Elastic Beanstalk Developer Guide
Manage Alarms
3.
4.
For the metric that you want to create an alarm for, click
. You are directed to the Alarms page.
Enter details about the alarm:
• Name: A name for this alarm.
• Description (optional): A short description of what this alarm is.
• Period: The time interval between readings.
API Version 2010-12-01
332
AWS Elastic Beanstalk Developer Guide
View Events
• Threshold: Describes the behavior and value that the metric must exceed in order to trigger an
alarm.
• Change state after: The amount a time after a threshold has been exceed that triggers a change
in state of the alarm.
• Notify: The Amazon SNS topic that is notified when an alarm changes state.
• Notify when state changes to:
• OK: The metric is within the defined threshold.
• Alarm: The metric exceeded the defined threshold.
• Insufficient data: The alarm has just started, the metric is not available, or not enough data is
available for the metric to determine the alarm state.
5.
Click Add. The environment status changes to gray while the environment updates. You can view the
alarm that you created by going to the Alarms page.
Viewing an Elastic Beanstalk Environment's Event
Stream
You can use the AWS Management Console to access events and notifications associated with your
application.
To view events
1.
Navigate to the management page (p. 61) for your environment.
2.
From the navigation menu, click Events.
The Events page shows you a list of all events that have been recorded for the environment and
application version. You can filter on the type of events by using the Severity drop-down list. You
can also filter when the events occurred by using the time slider.
API Version 2010-12-01
333
AWS Elastic Beanstalk Developer Guide
Monitor Instances
The EB CLI (p. 434) and AWS CLI both provide commands for retrieving events. If you are managing
your environment using the EB CLI, use eb events (p. 481) to print a list of events. This command also
has a --follow option that continues to show new events until you press Ctrl-C to stop output.
To pull events using the AWS CLI, use the describe-events command and specify the environment by
name or ID:
$ aws elasticbeanstalk describe-events --environment-id e-gbjzqccra3
{
"Events": [
{
"ApplicationName": "elastic-beanstalk-example",
"EnvironmentName": "elasticBeanstalkExa-env",
"Severity": "INFO",
"RequestId": "a4c7bfd6-2043-11e5-91e2-9114455c358a",
"Message": "Environment update completed successfully.",
"EventDate": "2015-07-01T22:52:12.639Z"
},
...
For more information on the command line tools, see Tools (p. 434).
Listing and Connecting to Server Instances
You can view a list of Amazon EC2 instances running your Elastic Beanstalk application environment
through the AWS Management Console. You can connect to the instances using any SSH client. For
more information about listing and connecting to Server Instances using the AWS Toolkit for Eclipse, see
Listing and Connecting to Server Instances (p. 657). You can connect to the instances running Windows
using Remote Desktop. For more information about listing and connecting to Server Instances using the
AWS Toolkit for Visual Studio, see Listing and Connecting to Server Instances (p. 701).
Important
You must create an Amazon EC2 key pair and configure your Elastic Beanstalk–provisioned
Amazon EC2 instances to use the Amazon EC2 key pair before you can access your Elastic
Beanstalk–provisioned Amazon EC2 instances. You can set up your Amazon EC2 key pairs using
the AWS Management Console. For instructions on creating a key pair for Amazon EC2, go to the
Amazon EC2 Getting Started Guide. For more information on how to configure your Amazon EC2
instances to use an Amazon EC2 key pair, see EC2 Key Pair (p. 249).
Elastic Beanstalk does not enable remote connections to EC2 instances in a Windows container
by default except for legacy Windows containers. (Beanstalk configures EC2 instances in legacy
Windows containers to use port 3389 for RDP connections.) You can enable remote connections
to your EC2 instances running Windows by adding a rule to a security group that authorizes
inbound traffic to the instances. We strongly recommend that you remove the rule when
you end your remote connection. You can add the rule again the next time you need to log
in remotely. For more information, see Adding a Rule for Inbound RDP Traffic to a Windows
Instance and Connect to Your Windows Instance in the Amazon Elastic Compute Cloud User
Guide for Microsoft Windows.
To view and connect to Amazon EC2 instances for an environment
1.
Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.
2.
In the navigation (left) pane of the console, click Load Balancers.
API Version 2010-12-01
334
AWS Elastic Beanstalk Developer Guide
Monitor Instances
3.
Load balancers created by Elastic Beanstalk will have a awseb in the name. Find the load balancer
for your environment and click it.
4.
Click the Instances tab in the bottom pane of the console window.
A list of the instances that the load balancer for your Elastic Beanstalk environment uses is
displayed. Make a note of an instance ID that you want to connect to.
5.
Click the Instances link in the left side of the Amazon EC2 console, and find your instance ID in the
list.
API Version 2010-12-01
335
AWS Elastic Beanstalk Developer Guide
View Instance Logs
6.
Right-click the instance ID for the Amazon EC2 instance running in your environment's load balancer,
and then select Connect from the context menu.
7.
Make a note of the instance's public DNS address on the Description tab.
8.
To connect to an instance running Linux, use the SSH client of your choice to connect to your
instance and type ssh -i .ec2/mykeypair.pem [email protected]<public-DNS-of-the-instance> . For
instructions on how to connect to an instance running Windows, see Connect to your Windows
Instance in the Amazon Elastic Compute Cloud Microsoft Windows Guide.
For more information on connecting to an Amazon EC2 instance, see the Amazon Elastic Compute Cloud
Getting Started Guide.
Viewing Logs from Your Elastic Beanstalk
Environment's Amazon EC2 Instances
The EC2 instances in your Elastic Beanstalk environment generate logs that you can view to troubleshoot
issues with your application or configuration files. Logs created by the web server, application server,
Elastic Beanstalk platform scripts, and AWS CloudFormation are stored locally on individual instances,
and can be easily retrieved with the environment management console or the EB CLI. You can also
configure your environment to stream logs to Amazon CloudWatch Logs in real time.
Tail logs are the last 100 lines of the most commonly used log files – Elastic Beanstalk operational logs
and logs from the web server and/or application server. When you request tail logs in the environment
management console or with eb logs, an instance in your environment concatenates the most recent log
entries into a single text file and uploads it to Amazon S3.
Bundle logs are full logs for a wider range of log files, including logs from yum and cron and several logs
from AWS CloudFormation. When you request bundle logs, an instance in your environment packages
the full log files into a ZIP archive and uploads it to Amazon S3.
Note
Elastic Beanstalk Windows Server platforms do not support bundle logs.
To retrieve logs in the environment management console (p. 61), navigate to Logs, choose Request Logs,
and then choose the type of logs to retrieve. To get tail logs, choose Last 100 Lines. To get bundle logs,
choose Full Logs.
API Version 2010-12-01
336
AWS Elastic Beanstalk Developer Guide
Log Location on-Instance
When Elastic Beanstalk finishes retrieving your logs, choose Download.
Tail and bundle logs are removed from Amazon S3 15 minutes after they are created. To persist logs,
you can configure your environment to publish logs to Amazon S3 automatically after they have been
rotated.
To enable log rotation to Amazon S3, navigate to the Software Configuration section of the
Configuration page (p. 155) in the environment management console. Under Log Options, select Enable
log file rotation to Amazon S3 and then choose Apply. Instances in your environment will attempt to
upload logs that have been rotated once per hour.
To upload rotated logs to Amazon S3, the instances in your environment must have an instance
profile (p. 19) with permission to write to your Elastic Beanstalk Amazon S3 bucket. These permissions
are included in the default instance profile that Elastic Beanstalk prompts you to create when you launch
an environment in the Elastic Beanstalk console for the first time.
If your application generates logs in a location that is not part of the default configuration for
your environment's platform, you can extend the default configuration by using configuration files
(.ebextensions (p. 197)). You can add your application's log files to tail logs, bundle logs, or log
rotation.
For real time log streaming and long term storage, configure your environment to stream logs to
Amazon CloudWatch Logs (p. 341).
Sections
• Log Location on-Instance (p. 337)
• Log Location in S3 (p. 338)
• Log Rotation Settings on Linux (p. 338)
• Extending the Default Log Task Configuration (p. 339)
• Amazon CloudWatch Logs (p. 341)
Log Location on-Instance
Logs are stored in standard locations on the EC2 instances in your environment. Elastic Beanstalk
generates the following logs:
Linux
• /var/log/eb-activity.log
• /var/log/eb-commandprocessor.log
• /var/log/eb-version-deployment.log
API Version 2010-12-01
337
AWS Elastic Beanstalk Developer Guide
Log Location in S3
Windows Server
• C:\Program Files\Amazon\ElasticBeanstalk\logs\
These logs contain messages about deployment activities including messages related to configuration
files (.ebextensions (p. 197)).
Each application and web server stores logs in its own folder:
• Apache – /var/log/httpd/
• IIS – C:\inetpub\wwwroot\
• Node.js – /var/log/nodejs/
• nginx – /var/log/nginx/
• Passenger – /var/app/support/logs/
• Puma – /var/log/puma/
• Python – /opt/python/log/
• Tomcat – /var/log/tomcat8/
Log Location in S3
When you request tail or bundle logs from your environment, or instances upload rotated logs, they
are stored in your Elastic Beanstalk bucket in Amazon S3. Elastic Beanstalk creates a bucket named
elasticbeanstalk-region-account-id for each region in which you create environments. Within
this bucket, logs are stored under the path resources/environments/logs/logtype/environmentid/instance-id.
For example, logs from instance i-0a1fd158, in Elastic Beanstalk environment e-mpcwnwheky in region
us-west-2 in account 0123456789012, are stored in the following locations:
• Tail Logs –
s3://elasticbeanstalk-us-west-2-0123456789012/resources/environments/logs/tail/empcwnwheky/i-0a1fd158
• Bundle Logs –
s3://elasticbeanstalk-us-west-2-0123456789012/resources/environments/logs/bundle/empcwnwheky/i-0a1fd158
• Rotated Logs –
s3://elasticbeanstalk-us-west-2-0123456789012/resources/environments/logs/publish/empcwnwheky/i-0a1fd158
Note
You can find your environment ID in the environment management console (p. 61).
Elastic Beanstalk deletes tail and bundle logs from Amazon S3 automatically 15 minutes after they are
created. Rotated logs persist until you delete them or move them to Amazon Glacier.
Log Rotation Settings on Linux
On Linux platforms, Elastic Beanstalk uses logrotate to rotate logs periodically. After a log is rotated
locally, the log rotation task picks it up and uploads it to Amazon S3, if configured. Logs that are rotated
locally do not appear in tail or bundle logs by default.
API Version 2010-12-01
338
AWS Elastic Beanstalk Developer Guide
Extending the Default Log Task Configuration
You can find Elastic Beanstalk configuration files for logrotate in /etc/
logrotate.elasticbeanstalk.hourly/. The specific rotation settings are platform-specific and might
change in future versions of the platform. For more information on the available settings and example
configurations, run man logrotate.
The configuration files are invoked by cron jobs in /etc/cron.hourly/. For more information on cron,
run man cron.
Extending the Default Log Task Configuration
Elastic Beanstalk uses files in subfolders of /opt/elasticbeanstalk/tasks (Linux) or C:\Program Files
\Amazon\ElasticBeanstalk\config (Windows Server) on the EC2 instance to configure tasks for tail logs,
bundle logs and log rotation.
On Linux:
• Tail Logs –
/opt/elasticbeanstalk/tasks/taillogs.d/
• Bundle Logs –
/opt/elasticbeanstalk/tasks/bundlelogs.d/
• Rotated Logs –
/opt/elasticbeanstalk/tasks/publishlogs.d/
On Windows Server:
• Tail Logs –
c:\Program Files\Amazon\ElasticBeanstalk\config\taillogs.d\
• Rotated Logs –
c:\Program Files\Amazon\ElasticBeanstalk\config\publogs.d\
For example, the file eb-activity.conf on Linux adds two log files to the tail logs task:
/opt/elasticbeanstalk/tasks/taillogs.d/eb-activity.conf
/var/log/eb-commandprocessor.log
/var/log/eb-activity.log
You can use environment configuration files (.ebextensions (p. 197)) to add your own .conf files to
these folders. A .conf file lists log files specific to your application, which Elastic Beanstalk adds to the
log file tasks.
Use the files (p. 203) section to add configuration files to the tasks that you want to modify. For
example, the following configuration file adds a config to each instance in your environment that adds /
var/log/cloud-init.log to tail logs:
files:
"/opt/elasticbeanstalk/tasks/taillogs.d/cloud-init.conf" :
mode: "000755"
owner: root
group: root
content: |
API Version 2010-12-01
339
AWS Elastic Beanstalk Developer Guide
Extending the Default Log Task Configuration
/var/log/cloud-init.log
Add this text to a file with the .config extension to your source bundle under a folder named
.ebextensions:
~/workspace/my-app
|-- .ebextensions
|
`-- tail-logs.config
|-- index.php
`-- styles.css
On Linux platforms, you can also use wildcards in log task configurations. This configuration file adds all
files with the .log extension from the log folder in the application root to bundle logs:
files:
"/opt/elasticbeanstalk/tasks/bundlelogs.d/applogs.conf" :
mode: "000755"
owner: root
group: root
content: |
/var/app/current/log/*.log
Note
Log task configurations don't support wildcards on Windows platforms.
For more information on using configuration files, see Advanced Environment Customization with
Configuration Files (.ebextensions) (p. 197).
Much like extending tail logs and bundle logs, you can extend log rotation using a configuration file.
Whenever Elastic Beanstalk rotates its own logs and uploads them to Amazon S3, it also rotates and
uploads your additional logs. Log rotation extension behaves differently depending on the platform's
operating system. The following sub-sections describe the two cases.
Extending Log Rotation on Linux
As explained in Log Rotation Settings on Linux (p. 338), Elastic Beanstalk uses logrotate to rotate
logs on Linux platforms. When you configure your application's log files for log rotation, the application
doesn't need to create copies of log files. Elastic Beanstalk configures logrotate to make a copy of your
application's log files for each rotation. Therefore, the application must keep log files unlocked when it
isn't actively writing to them.
Extending Log Rotation on Windows Server
On Windows Server, when you configure your application's log files for log rotation, the application must
rotate the log files periodically. Elastic Beanstalk looks for files with names starting with the pattern
you configured, and picks them up for uploading to Amazon S3. In addition, periods in the file name are
ignored, and Elastic Beanstalk considers the name up to the period to be the base log file name.
Elastic Beanstalk uploads all versions of a base log file except for the newest one, because it considers
that one to be the active application log file, which can potentially be locked. Your application may,
therefore, keep the active log file locked between rotations.
For example: your application writes to a log file named my_log.log, and you specify this name in
your .conf file. The application periodically rotates the file. During Elastic Beanstalk's rotation cycle, it
finds the following files in the log file's folder: my_log.log, my_log.0800.log, my_log.0830.log. Elastic
Beanstalk considers all of them to be versions of the base name my_log. The file my_log.log has the
latest modification time, so Elastic Beanstalk uploads only the other two files, my_log.0800.log and
my_log.0830.log.
API Version 2010-12-01
340
AWS Elastic Beanstalk Developer Guide
Amazon CloudWatch Logs
Amazon CloudWatch Logs
You can configure your environment to stream logs to Amazon CloudWatch Logs in the AWS
Management Console or with configuration options (p. 145). With CloudWatch Logs, each instance in
your environment streams logs to log groups that you can configure to be retained for weeks or years,
even after your environment is terminated.
The set of logs streamed varies per environment but always includes eb-activity.log and access logs from
the nginx or Apache proxy server that runs in front of your application.
You can configure log streaming in the AWS Management Console during environment creation on the
Software settings page (p. 76), as shown in the following screen shot, which saves logs up to 60 days,
even when the environment has terminated.
The following configuration file (p. 197) enables log streaming with 180 days retention, even if the
environment is terminated:
Example .ebextensions/log-streaming.config
option_settings:
aws:elasticbeanstalk:cloudwatch:logs:
StreamLogs: true
DeleteOnTerminate: false
RetentionInDays: 180
API Version 2010-12-01
341
AWS Elastic Beanstalk Developer Guide
Architectural Overview
Using Elastic Beanstalk with Other
AWS Services
The topics in this chapter discusses the integration of Elastic Beanstalk with resources from other AWS
services that are not managed by Elastic Beanstalk as part of your environment.
Topics
• Architectural Overview (p. 342)
• Using Elastic Beanstalk with Amazon CloudFront (p. 343)
• Logging Elastic Beanstalk API Calls with AWS CloudTrail (p. 344)
• Using Elastic Beanstalk with Amazon CloudWatch (p. 345)
• Using Elastic Beanstalk with Amazon CloudWatch Logs (p. 346)
• Using Elastic Beanstalk with DynamoDB (p. 351)
• Using Elastic Beanstalk with Amazon ElastiCache (p. 352)
• Using Elastic Beanstalk with Amazon Elastic File System (p. 352)
• Using Elastic Beanstalk with AWS Identity and Access Management (p. 353)
• Using Elastic Beanstalk with Amazon RDS (p. 398)
• Using Elastic Beanstalk with Amazon S3 (p. 408)
• Using Elastic Beanstalk with Amazon VPC (p. 408)
Architectural Overview
The following diagram illustrates an example architecture of Elastic Beanstalk across multiple Availability
Zones working with other AWS products such as Amazon CloudFront, Amazon Simple Storage Service
(Amazon S3), and Amazon Relational Database Service (Amazon RDS). For a more detailed discussion
about Amazon Route 53, Elastic Load Balancing, Amazon Elastic Compute Cloud (Amazon EC2) and host
manager (HM), see Architectural Overview (p. 15).
API Version 2010-12-01
342
AWS Elastic Beanstalk Developer Guide
CloudFront
To plan for fault-tolerance, it is advisable to have N+1 Amazon EC2 instances and spread your instances
across multiple Availability Zones. In the unlikely case that one Availability Zone goes down, you will still
have your other Amazon EC2 instances running in another Availability Zone. You can adjust Auto Scaling
to allow for a minimum number of instances as well as multiple Availability Zones. For instructions on
how to do this, see Launch Configuration (p. 240). For more information about building fault-tolerant
applications, go to Building Fault-Tolerant Applications on AWS.
The following sections discuss in more detail integration with Amazon CloudFront, Amazon CloudWatch,
Amazon DynamoDB Amazon ElastiCache, Amazon RDS, Amazon Route 53, Amazon Simple Storage
Service, Amazon VPC , and IAM.
Using Elastic Beanstalk with Amazon CloudFront
Amazon CloudFront is a web service that speeds up distribution of your static and dynamic web content,
for example, .html, .css, .php, image, and media files, to end users. CloudFront delivers your content
through a worldwide network of edge locations. When an end user requests content that you're serving
with CloudFront, the user is routed to the edge location that provides the lowest latency, so content is
delivered with the best possible performance. If the content is already in that edge location, CloudFront
delivers it immediately. If the content is not currently in that edge location, CloudFront retrieves it from
an Amazon S3 bucket or an HTTP server (for example, a web server) that you have identified as the
source for the definitive version of your content.
After you have created and deployed your Elastic Beanstalk application you can sign up for CloudFront
and start using CloudFront to distribute your content. Learn more about CloudFront from the Amazon
CloudFront Developer Guide.
API Version 2010-12-01
343
AWS Elastic Beanstalk Developer Guide
CloudTrail
Logging Elastic Beanstalk API Calls with AWS
CloudTrail
Elastic Beanstalk is integrated with CloudTrail, a service that captures all of the Elastic BeanstalkAPI calls
and delivers the log files to an Amazon S3 bucket that you specify. CloudTrail captures API calls from the
Elastic Beanstalk console or from your code to the Elastic Beanstalk APIs. Using the information collected
by CloudTrail, you can determine the request that was made to Elastic Beanstalk, the source IP address
from which the request was made, who made the request, when it was made, and so on.
To learn more about CloudTrail, including how to configure and enable it, see the AWS CloudTrail User
Guide.
Elastic Beanstalk Information in CloudTrail History
The CloudTrail API activity history feature lets you look up and filter events captured by CloudTrail. You
can look up events related to the creation, modification, or deletion of resources in your AWS account
on a per-region basis. Events can be looked up by using the CloudTrail console, or programmatically by
using the AWS SDKs or AWS CLI (lookup-events).
For a list of supported actions, see AWS Elastic Beanstalk APIs in the CloudTrail User Guide.
Elastic Beanstalk Information in CloudTrail Logging
When CloudTrail logging is enabled in your AWS account, API calls made to Elastic Beanstalk actions
are tracked in CloudTrail log files, where they are written with other AWS service records. CloudTrail
determines when to create and write to a new file based on a time period and file size.
All Elastic Beanstalk actions are logged by CloudTrail and are documented in the Elastic
Beanstalk API Reference. For example, calls to the CreateEnvironment, UpdateEnvironment and
TerminateEnvironment sections generate entries in the CloudTrail log files.
Every log entry contains information about who generated the request. The user identity information in
the log entry helps you determine the following:
• Whether the request was made with root or IAM user credentials
• Whether the request was made with temporary security credentials for a role or federated user
• Whether the request was made by another AWS service
For more information, see the CloudTrail userIdentity Element.
You can store your log files in your Amazon S3 bucket for as long as you want, but you can also define
Amazon S3 lifecycle rules to archive or delete log files automatically. By default, your log files are
encrypted with Amazon S3 server-side encryption (SSE).
If you want to be notified upon log file delivery, you can configure CloudTrail to publish Amazon SNS
notifications when new log files are delivered. For more information, see Configuring Amazon SNS
Notifications for CloudTrail.
You can also aggregate Elastic Beanstalk log files from multiple AWS regions and multiple AWS accounts
into a single Amazon S3 bucket.
For more information, see Receiving CloudTrail Log Files from Multiple Regions and Receiving CloudTrail
Log Files from Multiple Accounts.
API Version 2010-12-01
344
AWS Elastic Beanstalk Developer Guide
Understanding Elastic Beanstalk Log File Entries
Understanding Elastic Beanstalk Log File Entries
CloudTrail log files can contain one or more log entries. Each entry lists multiple JSON-formatted events.
A log entry represents a single request from any source and includes information about the requested
action, the date and time of the action, request parameters, and so on. Log entries are not an ordered
stack trace of the public API calls, so they do not appear in any specific order.
The following example shows a CloudTrail log entry that demonstrates the UpdateEnvironment action
called by an IAM user named intern.
{
}
"Records": [{
"eventVersion": "1.03",
"userIdentity": {
"type": "IAMUser",
"principalId": "AIXDAYQEXAMPLEUMLYNGL",
"arn": "arn:aws:iam::123456789012:user/intern",
"accountId": "123456789012",
"accessKeyId": "ASXIAGXEXAMPLEQULKNXV",
"userName": "intern",
"sessionContext": {
"attributes": {
"mfaAuthenticated": "false",
"creationDate": "2016-04-22T00:23:24Z"
}
},
"invokedBy": "signin.amazonaws.com"
},
"eventTime": "2016-04-22T00:24:14Z",
"eventSource": "elasticbeanstalk.amazonaws.com",
"eventName": "UpdateEnvironment",
"awsRegion": "us-west-2",
"sourceIPAddress": "255.255.255.54",
"userAgent": "signin.amazonaws.com",
"requestParameters": {
"optionSettings": []
},
"responseElements": null,
"requestID": "84ae9ecf-0280-17ce-8612-705c7b132321",
"eventID": "e48b6a08-c6be-4a22-99e1-c53139cbfb18",
"eventType": "AwsApiCall",
"recipientAccountId": "123456789012"
}]
Using Elastic Beanstalk with Amazon CloudWatch
Amazon CloudWatch enables you to monitor, manage, and publish various metrics, as well as configure
alarm actions based on data from metrics. Amazon CloudWatch monitoring enables you to collect,
analyze, and view system and application metrics so that you can make operational and business
decisions more quickly and with greater confidence. You can use Amazon CloudWatch to collect metrics
about your Amazon Web Services (AWS) resources—such as the performance of your Amazon EC2
instances. You can also publish your own metrics directly to Amazon CloudWatch. Amazon CloudWatch
alarms help you implement decisions more easily by enabling you to send notifications or automatically
make changes to the resources you are monitoring, based on rules that you define. For example, you can
create alarms that initiate Auto Scaling and Amazon Simple Notification Service (Amazon SNS) actions
on your behalf. Elastic Beanstalk automatically uses Amazon CloudWatch to help you monitor your
application and environment status. You can navigate to the Amazon CloudWatch console to see your
API Version 2010-12-01
345
AWS Elastic Beanstalk Developer Guide
CloudWatch Logs
dashboard and get an overview of all of your resources as well as your alarms. You can also choose to
view more metrics or add custom metrics. For more information about Amazon CloudWatch, go to the
Amazon CloudWatch Developer Guide. For an example of how to use Amazon CloudWatch with Elastic
Beanstalk, see Example: Using Custom Amazon CloudWatch Metrics (p. 208).
Using Elastic Beanstalk with Amazon CloudWatch
Logs
With CloudWatch Logs, you can monitor and archive your Elastic Beanstalk application, system, and
custom log files. Furthermore, you can configure alarms that make it easier for you to take actions
in response to specific log stream events that your metric filters extract. The CloudWatch Logs agent
installed on each Amazon EC2 in your environment publishes metric data points to the CloudWatch
service for each log group you configure. Each log group applies its own filter patterns to determine
what log stream events to send to CloudWatch as data points. Log streams that belong to the same
log group share the same retention, monitoring, and access control settings. You can configure
Elastic Beanstalk to automatically stream logs to the CloudWatch service, as described in Streaming
CloudWatch Logs (p. 348). For more information about CloudWatch Logs, including terminology and
concepts, go to Monitoring System, Application, and Custom Log Files.
The following figure displays graphs on the Monitoring page for an environment that is configured
with CloudWatch Logs integration. The example metrics in this environment are named CWLHttp4xx
and CWLHttp5xx. In the image, the CWLHttp4xx metric has triggered an alarm according to conditions
specified in the configuration files.
The following figure displays graphs on the Alarms page for the example alarms named
AWSEBCWLHttp4xxPercentAlarm and AWSEBCWLHttp5xxCountAlarm that correspond to the
CWLHttp4xx and CWLHttp5xx metrics, respectively.
API Version 2010-12-01
346
AWS Elastic Beanstalk Developer Guide
Granting IAM Permissions
Granting IAM Permissions for the CloudWatch Logs
Agent
Before you can configure integration with CloudWatch Logs, you must set up IAM permissions to
use with the CloudWatch Logs agent. You can attach the following custom policy to the instance
profile (p. 19) that you assign to your environment:
{
}
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"logs:CreateLogGroup",
"logs:CreateLogStream",
"logs:GetLogEvents",
"logs:PutLogEvents",
"logs:DescribeLogGroups",
"logs:DescribeLogStreams",
"logs:PutRetentionPolicy"
],
"Resource": [
"arn:aws:logs:us-west-2:*:*"
]
}
]
Replace the region in the above policy with the region in which you launch your environment.
API Version 2010-12-01
347
AWS Elastic Beanstalk Developer Guide
Streaming CloudWatch Logs
Streaming CloudWatch Logs
Since Elastic Beanstalk can spin up Amazon EC2 instances on demand (provided you have enabled
that feature), Elastic Beanstalk provides another option so that you can stream log entries from those
Amazon EC2 instances to CloudWatch. To enable this feature, select Enabled for Log streaming, set
Retention to the number of days to save the logs, and select the Lifecycle setting for whether the logs
are saved after the instance is terminated, as shown in the following figure, which saves the logs for 7
days and keeps the logs after terminating the instance. You can also enable these settings using the eb
logs (p. 490) command. Note that this feature is only available in containers since this release.
Note also that once you enable CloudWatch logs, you'll see the View in CloudWatch Console link. Click
that link to see your CloudWatch logs in the CloudWatch console.
Note
If you do not have the AWSElasticBeanstalkWebTier or AWSElasticBeanstalkWorkerTier Elastic
Beanstalk managed policy in your Elastic Beanstalk instance profile (p. 19), you must add the
following to your profile to enable this feature.
{
}
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"logs:PutLogEvents",
"logs:CreateLogStream"
],
"Resource": [
"arn:aws:logs:*:*:log-group:/aws/elasticbeanstalk*"
]
}
]
Elastic Beanstalk installs a CloudWatch log agent with the default configuration settings on each
instance it creates. Learn more at CloudWatch Logs Agent Reference.
Different containers stream different logs. The following table lists the logs, by container.
Container
Logs
Java
• /var/log/eb-activity.log
API Version 2010-12-01
348
AWS Elastic Beanstalk Developer Guide
Streaming CloudWatch Logs
Container
Logs
• /var/log/nginx/access.log
• /var/log/nginx/error.log
• /var/log/web-1.error.log
• /var/log/web-1.log
Node.js
• /var/log/eb-activity.log
• /var/log/nodejs/nodejs.log
• /var/log/nginx/error.log
• /var/log/nginx/access.log
• /var/log/httpd/error.log
• /var/log/httpd/access.log
Php
• /var/log/eb-activity.log
• /var/log/httpd/error_log
• /var/log/httpd/access_log
Python
• /var/log/eb-activity.log
• /var/log/httpd/error_log
• /var/log/httpd/access_log
• /opt/python/log/supervisord.log
Ruby (Puma)
• /var/log/eb-activity.log
• /var/log/nginx/error.log
• /var/log/puma/puma.log
• /var/log/nginx/access.log
Ruby (passenger)
• /var/log/eb-activity.log
• /var/app/support/logs/passenger.log
• /var/app/support/logs/access.log
• /var/app/support/logs/error.log
Tomcat
• /var/log/eb-activity.log
• /var/log/httpd/error_log
• /var/log/httpd/access_log
• /var/log/nginx/error_log
• /var/log/nginx/access_log
Go
• /var/log/eb-activity.log
• /var/log/nginx/error.log
• /var/log/nginx/access.log
Docker
• /var/log/eb-activity.log
• /var/log/nginx/error.log
• /var/log/docker-events.log
• /var/log/docker
• /var/log/nginx/access.log
API Version 2010-12-01
349
AWS Elastic Beanstalk Developer Guide
Setting Up CloudWatch Logs
Integration with Configuration Files
Container
Logs
Multi-Docker(generic)
• /var/log/eb-activity.log
• /var/log/ecs/ecs-init.log
• /var/log/eb-ecs-mgr.log
• /var/log/ecs/ecs-agent.log
• /var/log/docker-events.log
Glass fish (Preconfigured
docker)
• /var/log/eb-activity.log
• /var/log/nginx/error.log
• /var/log/docker-events.log
• /var/log/docker
• /var/log/nginx/access.log
Go (Preconfigured docker)
• /var/log/eb-activity.log
• /var/log/nginx/error.log
• /var/log/docker-events.log
• /var/log/docker
• /var/log/nginx/access.log
Python (Preconfigured
docker)
• /var/log/eb-activity.log
• /var/log/nginx/error.log
• /var/log/docker-events.log
• /var/log/docker
• /var/log/nginx/access.log
You can also enable CloudWatch logs using the eb logs --cloudwatch enable (p. 490) command.
Setting Up CloudWatch Logs Integration with
Configuration Files
When you create or update an environment, you can use the sample configuration files in the following
list to set up and configure integration with CloudWatch Logs. You can include the .zip file that contains
following configuration files or the extracted configuration files in the .ebextensions directory at
the top level of your application source bundle. Use the appropriate files for the web server for your
container type. For more information about the web server used by each container type, see Elastic
Beanstalk Supported Platforms (p. 25).
Note
You cannot configure CloudWatch Logs integration with Elastic Beanstalk applications created
in .NET containers.
You can download the configuration files at the following locations:
• Tomcat (Java) configuration files
• Apache (PHP and Python) configuration files
• nginx (Ruby, Node.js, and Docker) configuration files
Each .zip file contains the following configuration files:
API Version 2010-12-01
350
AWS Elastic Beanstalk Developer Guide
Troubleshooting CloudWatch Logs Integration
• cwl-setup.config – This file installs the CloudWatch Logs agent on each Amazon EC2 instance in your
environment and then configures the agent. This file also creates the general.conf file when Elastic
Beanstalk launches the instance. You can use the cwl-setup.config file without any modifications.
If you prefer, you can manually set up the CloudWatch Logs agent on a new instance as explained in
either Quick Start: Install and Configure the CloudWatch Logs Agent on a New EC2 Instance (for new
instances) or Quick Start: Install and Configure the CloudWatch Logs Agent on an Existing EC2 Instance
(for existing instances) in the Amazon CloudWatch Developer Guide.
• cwl-webrequest-metrics.config – This file specifies which logs the CloudWatch Logs agent monitors.
The file also specifies the metric filters the CloudWatch Logs agent applies to each log that it monitors.
Metric filters include filter patterns that map to the space-delimited entries in your log files. (If you
have custom logs, update or replace the example filter patterns in this example configuration file as
needed.)
Metric filters also include metric transformations that specify what metric name and value to use when
the CloudWatch Logs agent sends metric data points to the CloudWatch service. The CloudWatch Logs
agent sends metric data points based on whether any entries in the web server access log file match
the filter patterns.
Finally, the configuration file also includes an alarm action to send a message to an Amazon Simple
Notification Service topic, if you created one for your environment, when the alarm conditions
specified in the cwl-setup.config file are met. For more information about filter patterns, see Filter
and Pattern Syntax in the Amazon CloudWatch Developer Guide. For more information about Amazon
SNS, go to the Amazon Simple Notification Service Developer Guide. For more information about
managing alarms from the Elastic Beanstalk management console, see Manage Alarms (p. 330).
Note
CloudWatch costs are applied to your AWS account for any alarms that you use.
• eb-logs.config – This file sets up the CloudWatch Logs log files for the CloudWatch Logs agent. This
configuration file also ensures that log files are copied to Amazon S3 as part of log rotation. You can
use this file without any modifications.
Troubleshooting CloudWatch Logs Integration
If Elastic Beanstalk cannot launch your environment when you try to integrate Elastic Beanstalk with
CloudWatch Logs, you can investigate the following common issues:
• Your IAM role lacks the required IAM permissions.
• You attempted to launch an environment in a region where CloudWatch Logs is not supported.
• Access logs do not exist at the path specified in the cwl-webrequest-metrics.config file (/var/log/
httpd/elasticbeanstalk-access_log).
Using Elastic Beanstalk with DynamoDB
DynamoDB is a fully managed NoSQL database service that provides fast and predictable performance
with seamless scalability. If you are a developer, you can use DynamoDB to create a database table
that can store and retrieve any amount of data, and serve any level of request traffic. DynamoDB
automatically spreads the data and traffic for the table over a sufficient number of servers to handle the
request capacity specified by the customer and the amount of data stored, while maintaining consistent
and fast performance. All data items are stored on Solid State Disks (SSDs) and are automatically
replicated across multiple Availability Zones in a Region to provide built-in high availability and data
durability.
If you use periodic tasks (p. 139) in a worker environment, Elastic Beanstalk creates a DynamoDB
table and uses it to perform leader election and store information about the task. Each instance in the
API Version 2010-12-01
351
AWS Elastic Beanstalk Developer Guide
ElastiCache
environment attempts to write to the table every few seconds to become leader and perform the task
when scheduled.
You can use configuration files (p. 197) to create a DynamoDB table for your application. See eb-nodeexpress-sample on GitHub for a sample Node.js application that creates a table with a configuration file
and connects to it with the AWS SDK for Node.js. For an example walkthrough using DynamoDB with
PHP, see Example: DynamoDB, CloudWatch, and SNS (p. 225). For an example that uses the AWS SDK for
Java, see Manage Tomcat Session State with DynamoDB in the AWS SDK for Java documentation.
For more information about DynamoDB, go to the DynamoDB Developer Guide.
Using Elastic Beanstalk with Amazon ElastiCache
Amazon ElastiCache is a web service that makes it easy to set up, manage, and scale distributed
in-memory cache environments in the cloud. It provides a high performance, resizable, and costeffective in-memory cache, while removing the complexity associated with deploying and managing a
distributed cache environment. Amazon ElastiCache is protocol-compliant with Memcached, so the code,
applications, and most popular tools that you use today with your existing Memcached environments will
work seamlessly with the service. For more information about Amazon ElastiCache, go to the Amazon
ElastiCache product page.
To use Elastic Beanstalk with Amazon ElastiCache
1.
2.
Create an ElastiCache cluster. For instructions on how to create an ElastiCache cluster, go to Create a
Cache Cluster in the Amazon ElastiCache Getting Started Guide.
Configure your Amazon ElastiCache Security Group to allow access from the Amazon EC2 security
group used by your Elastic Beanstalk application. For instructions on how to find the name of your
EC2 security group using the AWS Management Console, see Security Groups (p. 248). For more
information, go to Authorize Access in the Amazon ElastiCache Getting Started Guide.
If you are using a non-legacy container, you can also use configuration files to customize your Elastic
Beanstalk environment to use Amazon ElastiCache. For information on supported container types
and customizing your environment, see AWS Elastic Beanstalk Environment Configuration (p. 144).
For an example snippet using Amazon ElastiCache with Elastic Beanstalk, see Example Snippets:
ElastiCache (p. 218).
Using Elastic Beanstalk with Amazon Elastic File
System
With Amazon Elastic File System, you can create network file systems that can be mounted by instances
across multiple Availability Zones. An Amazon EFS file system is an AWS resource that uses security
groups to control access over the network in your default or custom VPC.
In an Elastic Beanstalk environment, you can use Amazon EFS to create a shared directory that stores
files uploaded or modified by users of your application. Your application can treat a mounted Amazon
EFS volume like local storage, so you don't have to change your application code to scale up to multiple
instances.
For more information about Amazon EFS, see the Amazon Elastic File System User Guide.
Sections
• Configuration Files (p. 353)
• Sample Applications (p. 353)
API Version 2010-12-01
352
AWS Elastic Beanstalk Developer Guide
Configuration Files
Configuration Files
Elastic Beanstalk provides configuration files (p. 197) that you can use to create and mount Amazon EFS
file systems. You can create an Amazon EFS volume as part of your environment, or mount an Amazon
EFS volume that you created independently of Elastic Beanstalk.
• storage-efs-createfilesystem.config – Uses the Resources key to create a new file system and mount
points in Amazon EFS. All instances in your environment can connect to the same file system for
shared, scalable storage. Use storage-efs-mountfilesystem.config to mount the file system on each
instance.
Internal Resources
Any resources that you create with configuration files are tied to the lifecycle of your
environment and will be lost if you terminate your environment or remove the configuration
file.
• storage-efs-mountfilesystem.config – Mount an Amazon EFS file system to a local path on the
instances in your environment. You can create the volume as part of the environment with storageefs-createfilesystem.config, or external to your environment by using the Amazon EFS console,
AWS CLI, or AWS SDK.
To use the configuration files, start by creating your Amazon EFS file system with storage-efscreatefilesystem.config. Follow the instructions in the configuration file and add it to the
.ebextensions directory in your source code to create the file system in your VPC.
Deploy your updated source code to your Elastic Beanstalk environment to confirm that the file system
is created successfully. Then, add the storage-efs-mountfilesystem.config to mount the file system
to the instances in your environment. Doing this in two separate deployments ensures that if the mount
operation fails, the file system is left intact. If you do both in the same deployment, an issue with either
step will cause the file system to terminate when the deployment fails.
Sample Applications
Elastic Beanstalk also provides sample applications that use Amazon EFS for shared storage. The two
projects are configuration files that you can use with a standard WordPress or Drupal installer to run
a blog or other content management system in a load-balanced environment. When a user uploads a
photo or other media, it is stored on an Amazon EFS file system, avoiding the need to use a plugin to
store uploaded files in Amazon S3.
• Load Balanced WordPress – Configuration files for installing WordPress securely and running it in a
load-balanced AWS Elastic Beanstalk environment.
• Load Balanced Drupal – Configuration files and instructions for installing Drupal securely and running
it in a load-balanced AWS Elastic Beanstalk environment.
Using Elastic Beanstalk with AWS Identity and
Access Management
AWS Identity and Access Management (IAM) helps you securely control access to your AWS resources.
This section includes reference materials for working with IAM policies, instance profiles, and service
roles.
For an overview of permissions, see Service Roles, Instance Profiles, and User Policies (p. 17). For most
environments, the service role and instance profile that the AWS Management Console prompts you to
create when you launch your first environment have all of the permissions that you need. Likewise, the
API Version 2010-12-01
353
AWS Elastic Beanstalk Developer Guide
Instance Profiles
managed policies (p. 362) provided by Elastic Beanstalk for full access and read-only access contain all
of the user permissions required for daily use.
The IAM User Guide provides in-depth coverage of AWS permissions.
Topics
• Managing Elastic Beanstalk Instance Profiles (p. 354)
• Managing Elastic Beanstalk Service Roles (p. 358)
• Controlling Access to Elastic Beanstalk (p. 362)
• Amazon Resource Name Format for Elastic Beanstalk (p. 366)
• Resources and Conditions for Elastic Beanstalk Actions (p. 368)
• Example Policies Based on Managed Policies (p. 389)
• Example Policies Based on Resource Permissions (p. 391)
Managing Elastic Beanstalk Instance Profiles
An instance profile is a container for an AWS Identity and Access Management (IAM) role that you can use
to pass role information to an EC2 instance when the instance starts. When you launch an environment
in the AWS Elastic Beanstalk environment management console, the console creates a default instance
profile, called aws-elasticbeanstalk-ec2-role, and assigns managed policies with default permissions
to it.
Elastic Beanstalk provides three managed policies: one for the web server tier, one for the worker tier,
and one with additional permissions required for multicontainer Docker environments. The console
assigns all of these policies to the role attached to the default instance profile. The policies follow.
Managed Instance Profile Policies
• AWSElasticBeanstalkWebTier – Grants permissions for the application to upload logs to Amazon S3
and debugging information to AWS X-Ray.
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "BucketAccess",
"Action": [
"s3:Get*",
"s3:List*",
"s3:PutObject"
],
"Effect": "Allow",
"Resource": [
"arn:aws:s3:::elasticbeanstalk-*",
"arn:aws:s3:::elasticbeanstalk-*/*"
]
},
{
"Sid": "XRayAccess",
"Action":[
"xray:PutTraceSegments",
"xray:PutTelemetryRecords"
],
"Effect": "Allow",
"Resource": "*"
},
{
"Sid": "CloudWatchLogsAccess",
API Version 2010-12-01
354
AWS Elastic Beanstalk Developer Guide
Instance Profiles
}
]
}
"Action": [
"logs:PutLogEvents",
"logs:CreateLogStream"
],
"Effect": "Allow",
"Resource": [
"arn:aws:logs:*:*:log-group:/aws/elasticbeanstalk*"
]
• AWSElasticBeanstalkWorkerTier – Grants permissions for log uploads, debugging, metric publication,
and worker instance tasks, including queue management, leader election, and periodic tasks.
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "MetricsAccess",
"Action": [
"cloudwatch:PutMetricData"
],
"Effect": "Allow",
"Resource": "*"
},
{
"Sid": "XRayAccess",
"Action":[
"xray:PutTraceSegments",
"xray:PutTelemetryRecords"
],
"Effect": "Allow",
"Resource": "*"
},
{
"Sid": "QueueAccess",
"Action": [
"sqs:ChangeMessageVisibility",
"sqs:DeleteMessage",
"sqs:ReceiveMessage",
"sqs:SendMessage"
],
"Effect": "Allow",
"Resource": "*"
},
{
"Sid": "BucketAccess",
"Action": [
"s3:Get*",
"s3:List*",
"s3:PutObject"
],
"Effect": "Allow",
"Resource": [
"arn:aws:s3:::elasticbeanstalk-*",
"arn:aws:s3:::elasticbeanstalk-*/*"
]
},
{
"Sid": "DynamoPeriodicTasks",
"Action": [
"dynamodb:BatchGetItem",
"dynamodb:BatchWriteItem",
"dynamodb:DeleteItem",
API Version 2010-12-01
355
AWS Elastic Beanstalk Developer Guide
Instance Profiles
"dynamodb:GetItem",
"dynamodb:PutItem",
"dynamodb:Query",
"dynamodb:Scan",
"dynamodb:UpdateItem"
}
]
}
],
"Effect": "Allow",
"Resource": [
"arn:aws:dynamodb:*:*:table/*-stack-AWSEBWorkerCronLeaderRegistry*"
]
• AWSElasticBeanstalkMulticontainerDocker – Grants permissions for the Amazon EC2 Container
Service to coordinate cluster tasks.
{
}
"Version": "2012-10-17",
"Statement": [
{
"Sid": "ECSAccess",
"Effect": "Allow",
"Action": [
"ecs:Poll",
"ecs:StartTask",
"ecs:StopTask",
"ecs:DiscoverPollEndpoint",
"ecs:StartTelemetrySession",
"ecs:RegisterContainerInstance",
"ecs:DeregisterContainerInstance",
"ecs:DescribeContainerInstances",
"ecs:Submit*"
],
"Resource": "*"
}
]
To allow the EC2 instances in your environment to assume the aws-elasticbeanstalk-ec2-role role, the
instance profile specifies Amazon EC2 as a trusted entity in the trust relationship policy:
{
}
"Version": "2008-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "ec2.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
To customize permissions, you can either add policies to the role attached to the default instance profile,
or create your own instance profile with a restricted set of permissions.
Sections
• Verifying the Permissions Assigned to the Default Instance Profile (p. 357)
• Updating an Out-of-Date Default Instance Profile (p. 357)
API Version 2010-12-01
356
AWS Elastic Beanstalk Developer Guide
Instance Profiles
• Adding Permissions to the Default Instance Profile (p. 357)
• Creating an Instance Profile (p. 358)
Verifying the Permissions Assigned to the Default Instance
Profile
The permissions assigned to your default instance profile can vary depending on when it was created,
the last time you launched an environment, and which client you used. You can verify the permissions on
the default instance profile in the IAM console.
To verify the default instance profile's permissions
1.
Open the Roles page in the IAM console.
2.
Choose aws-elasticbeanstalk-ec2-role.
3.
Choose the Permissions tab and review the Managed Policies and Inline Policies sections to see the
policies attached to the role.
4.
To see the permissions that a policy grants, choose Show Policy next to the policy.
Updating an Out-of-Date Default Instance Profile
If the default instance profile lacks the required permissions, you can update it by creating a new
environment (p. 68) in the Elastic Beanstalk environment management console.
Alternatively, you can add the managed policies to the role attached to the default instance profile
manually.
To add managed policies to the role attached to the default instance profile
1.
Open the Roles page in the IAM console.
2.
3.
4.
Choose aws-elasticbeanstalk-ec2-role.
On the Permissions tab, under Managed Policies, choose Attach Policy.
Type AWSElasticBeanstalk to filter the policies.
5.
Select the following policies, and then choose Attach Policies:
• AWSElasticBeanstalkWebTier
• AWSElasticBeanstalkWorkerTier
• AWSElasticBeanstalkMulticontainerDocker
Adding Permissions to the Default Instance Profile
If your application accesses AWS APIs or resources to which permissions aren't granted in the default
instance profile, add policies that grant permissions in the IAM console.
To add policies to the role attached to the default instance profile
1.
2.
3.
Open the Roles page in the IAM console.
Choose aws-elasticbeanstalk-ec2-role.
On the Permissions tab, under Managed Policies, choose Attach Policy.
4.
Select the managed policy for the additional services that your application uses. For example,
AmazonS3FullAccess or AmazonDynamoDBFullAccess.
Choose Attach Policies.
5.
API Version 2010-12-01
357
AWS Elastic Beanstalk Developer Guide
Service Roles
Creating an Instance Profile
An instance profile is a wrapper around a standard IAM role that allows an EC2 instance to assume the
role. You can create additional instance profiles to customize permissions for different applications or
to create an instance profile that doesn't grant permissions for worker tier or multicontainer Docker
environments if you don't use those features.
To create an instance profile
1.
Open the Roles page in the IAM console.
2.
Choose Create New Role.
3.
Type a name, and then choose Next Step.
4.
Under AWS Service Roles, choose Amazon EC2.
5.
Attach the appropriate managed policies provided by Elastic Beanstalk and any additional policies
that provide permissions that your application needs.
6.
Choose Next Step.
7.
Choose Create Role.
Managing Elastic Beanstalk Service Roles
When you launch an environment in the AWS Elastic Beanstalk environment management console,
the console creates a default service role, called aws-elasticbeanstalk-service-role, and attaches
managed policies with default permissions to it.
Elastic Beanstalk provides a managed policy for enhanced health monitoring (p. 306), and one with
additional permissions required for managed platform updates (p. 125). The console assigns both of
these policies to the default service role. The managed service role policies follow.
Managed Service Role Policies
• AWSElasticBeanstalkEnhancedHealth – Grants permissions for Elastic Beanstalk to monitor instance
and environment health.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"elasticloadbalancing:DescribeInstanceHealth",
"ec2:DescribeInstances",
"ec2:DescribeInstanceStatus",
"ec2:GetConsoleOutput",
"ec2:AssociateAddress",
"ec2:DescribeAddresses",
"ec2:DescribeSecurityGroups",
"sqs:GetQueueAttributes",
"sqs:GetQueueUrl",
"autoscaling:DescribeAutoScalingGroups",
"autoscaling:DescribeAutoScalingInstances",
"autoscaling:DescribeScalingActivities",
"autoscaling:DescribeNotificationConfigurations"
],
"Resource": [
"*"
]
}
API Version 2010-12-01
358
AWS Elastic Beanstalk Developer Guide
Service Roles
}
]
• AWSElasticBeanstalkService – Grants permissions for Elastic Beanstalk to update environments on
your behalf to perform managed updates.
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowCloudformationOperationsOnElasticBeanstalkStacks",
"Effect": "Allow",
"Action": [
"cloudformation:*"
],
"Resource": [
"arn:aws:cloudformation:*:*:stack/awseb-*",
"arn:aws:cloudformation:*:*:stack/eb-*"
]
},
{
"Sid": "AllowS3OperationsOnElasticBeanstalkBuckets",
"Effect": "Allow",
"Action": [
"s3:*"
],
"Resource": [
"arn:aws:s3:::elasticbeanstalk-*",
"arn:aws:s3:::elasticbeanstalk-*/*"
]
},
{
"Sid": "AllowOperations",
"Effect": "Allow",
"Action": [
"autoscaling:AttachInstances",
"autoscaling:CreateAutoScalingGroup",
"autoscaling:CreateLaunchConfiguration",
"autoscaling:DeleteLaunchConfiguration",
"autoscaling:DeleteAutoScalingGroup",
"autoscaling:DeleteScheduledAction",
"autoscaling:DescribeAccountLimits",
"autoscaling:DescribeAutoScalingGroups",
"autoscaling:DescribeAutoScalingInstances",
"autoscaling:DescribeLaunchConfigurations",
"autoscaling:DescribeLoadBalancers",
"autoscaling:DescribeNotificationConfigurations",
"autoscaling:DescribeScalingActivities",
"autoscaling:DescribeScheduledActions",
"autoscaling:DetachInstances",
"autoscaling:PutScheduledUpdateGroupAction",
"autoscaling:ResumeProcesses",
"autoscaling:SetDesiredCapacity",
"autoscaling:SuspendProcesses",
"autoscaling:TerminateInstanceInAutoScalingGroup",
"autoscaling:UpdateAutoScalingGroup",
"cloudwatch:PutMetricAlarm",
"ec2:AuthorizeSecurityGroupEgress",
"ec2:AuthorizeSecurityGroupIngress",
"ec2:CreateSecurityGroup",
"ec2:DeleteSecurityGroup",
"ec2:DescribeAccountAttributes",
"ec2:DescribeImages",
"ec2:DescribeInstances",
"ec2:DescribeKeyPairs",
API Version 2010-12-01
359
AWS Elastic Beanstalk Developer Guide
Service Roles
"ec2:DescribeSecurityGroups",
"ec2:DescribeSubnets",
"ec2:DescribeVpcs",
"ec2:RevokeSecurityGroupEgress",
"ec2:RevokeSecurityGroupIngress",
"ec2:TerminateInstances",
"ecs:CreateCluster",
"ecs:DeleteCluster",
"ecs:DescribeClusters",
"ecs:RegisterTaskDefinition",
"elasticbeanstalk:*",
"elasticloadbalancing:ApplySecurityGroupsToLoadBalancer",
"elasticloadbalancing:ConfigureHealthCheck",
"elasticloadbalancing:CreateLoadBalancer",
"elasticloadbalancing:DeleteLoadBalancer",
"elasticloadbalancing:DeregisterInstancesFromLoadBalancer",
"elasticloadbalancing:DescribeInstanceHealth",
"elasticloadbalancing:DescribeLoadBalancers",
"elasticloadbalancing:DescribeTargetHealth",
"elasticloadbalancing:RegisterInstancesWithLoadBalancer",
"iam:ListRoles",
"iam:PassRole",
"logs:CreateLogGroup",
"logs:PutRetentionPolicy",
"rds:DescribeDBInstances",
"rds:DescribeOrderableDBInstanceOptions",
"s3:CopyObject",
"s3:GetObject",
"s3:GetObjectAcl",
"s3:GetObjectMetadata",
"s3:ListBucket",
"s3:listBuckets",
"s3:ListObjects",
"sns:CreateTopic",
"sns:GetTopicAttributes",
"sns:ListSubscriptionsByTopic",
"sns:Subscribe",
"sqs:GetQueueAttributes",
"sqs:GetQueueUrl"
}
]
}
],
"Resource": [
"*"
]
To allow Elastic Beanstalk to assume the aws-elasticbeanstalk-service-role role, the service role
specifies Elastic Beanstalk as a trusted entity in the trust relationship policy:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": {
"Service": "elasticbeanstalk.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"sts:ExternalId": "elasticbeanstalk"
API Version 2010-12-01
360
AWS Elastic Beanstalk Developer Guide
Service Roles
]
}
}
}
}
The Elastic Beanstalk Command Line Interface (p. 434) (EB CLI) uses the default service role if it's
available. If you use the Elastic Beanstalk API to create an environment, specify a service role with the
ServiceRole configuration option in the aws:elasticbeanstalk:environment namespace. See Using
Enhanced Health Reporting with the AWS Elastic Beanstalk API (p. 325) for details on using enhanced
health monitoring with the Elastic Beanstalk API.
Sections
• Verifying the Default Service Role's Permissions (p. 361)
• Updating an Out-of-Date Default Service Role (p. 361)
• Adding Permissions to the Default Service Role (p. 362)
• Creating a Service Role (p. 362)
Verifying the Default Service Role's Permissions
The permissions granted by your default service role can vary depending on when it was created, the last
time you launched an environment, and which client you used. You can verify the permissions granted by
the default service role in the IAM console.
To verify the default service role's permissions
1.
Open the Roles page in the IAM console.
2.
Choose aws-elasticbeanstalk-service-role.
3.
On the Permissions tab, in the Managed Policies and Inline Policies sections, review the list of
policies attached to the role.
4.
To view the permissions that a policy grants, choose Show Policy next to the policy.
Updating an Out-of-Date Default Service Role
If the default service role lacks the required permissions, you can update it by creating a new
environment (p. 68) in the Elastic Beanstalk environment management console.
Alternatively, you can add the managed policies to the default service role manually.
To add managed policies to the default service role
1.
Open the Roles page in the IAM console.
2.
Choose aws-elasticbeanstalk-service-role.
3.
On the Permissions tab, under Managed Policies, choose Attach Policy.
4.
Type AWSElasticBeanstalk to filter the policies.
5.
Select the following policies, and then choose Attach Policies:
• AWSElasticBeanstalkEnhancedHealth
• AWSElasticBeanstalkService
API Version 2010-12-01
361
AWS Elastic Beanstalk Developer Guide
User Policies
Adding Permissions to the Default Service Role
If your application includes configuration files that refer to AWS resources for which permissions aren't
included in the default service role, Elastic Beanstalk might need additional permissions to resolve these
references when it processes the configuration files during a managed update. If permissions are missing,
the update fails and Elastic Beanstalk returns a message indicating which permission it needs. Add
permissions for additional services to the default service role in the IAM console.
To add additional policies to the default service role
1.
2.
Open the Roles page in the IAM console.
Choose aws-elasticbeanstalk-service-role.
3.
On the Permissions tab, under Managed Policies, choose Attach Policy.
4.
Select the managed policy for the additional services that your application uses. For example,
AmazonAPIGatewayAdministrator or AmazonElasticFileSystemFullAccess.
5.
Choose Attach Policies.
Creating a Service Role
If you can't use the default service role, create a service role.
To create a service role
1.
2.
Open the Roles page in the IAM console.
Choose Create New Role.
3.
4.
5.
Type a name, and then choose Next Step.
Under AWS Service Roles, choose AWS Elastic Beanstalk.
Attach the AWSElasticBeanstalkService and AWSElasticBeanstalkEnhancedHealth managed
policies and any additional policies that provide permissions that your application needs.
6.
7.
Choose Next Step.
Choose Create Role.
You can apply your custom service role when you create an environment in the environment creation
wizard (p. 71) or with the --service-role option on the eb create (p. 474) command.
Controlling Access to Elastic Beanstalk
AWS Elastic Beanstalk provides two managed policies that enable you to assign full access or readonly access to all Elastic Beanstalk resources. You can attach the policies to AWS Identity and Access
Management (IAM) users or groups.
Managed User Policies
• AWSElasticBeanstalkFullAccess – Allows the user to create, modify, and delete Elastic Beanstalk
applications, application versions, configuration settings, environments, and their underlying
resources.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
API Version 2010-12-01
362
AWS Elastic Beanstalk Developer Guide
User Policies
"elasticbeanstalk:*",
"ec2:*",
"ecs:*",
"ecr:*",
"elasticloadbalancing:*",
"autoscaling:*",
"cloudwatch:*",
"s3:*",
"sns:*",
"cloudformation:*",
"dynamodb:*",
"rds:*",
"sqs:*",
"iam:GetPolicyVersion",
"iam:GetRole",
"iam:PassRole",
"iam:ListRolePolicies",
"iam:ListAttachedRolePolicies",
"iam:ListInstanceProfiles",
"iam:ListRoles",
"iam:ListServerCertificates",
"acm:DescribeCertificate",
"acm:ListCertificates",
"codebuild:CreateProject",
"codebuild:DeleteProject",
"codebuild:BatchGetBuilds",
"codebuild:StartBuild"
},
{
},
{
}
]
}
],
"Resource": "*"
"Effect": "Allow",
"Action": [
"iam:AddRoleToInstanceProfile",
"iam:CreateInstanceProfile",
"iam:CreateRole"
],
"Resource": [
"arn:aws:iam::*:role/aws-elasticbeanstalk*",
"arn:aws:iam::*:instance-profile/aws-elasticbeanstalk*"
]
"Effect": "Allow",
"Action": [
"iam:AttachRolePolicy"
],
"Resource": "*",
"Condition": {
"StringLike": {
"iam:PolicyArn": [
"arn:aws:iam::aws:policy/AWSElasticBeanstalk*",
"arn:aws:iam::aws:policy/service-role/AWSElasticBeanstalk*"
]
}
}
• AWSElasticBeanstalkReadOnlyAccess – Allows the user to view applications and environments, but
not to perform operations on them. It provides read-only access to all Elastic Beanstalk resources. Note
that read-only access does not enable actions such as downloading Elastic Beanstalk logs so that you
can read them. See the example at the end of this topic for information on how to enable read-only
access to Elastic Beanstalk logs.
API Version 2010-12-01
363
AWS Elastic Beanstalk Developer Guide
User Policies
{
}
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"elasticbeanstalk:Check*",
"elasticbeanstalk:Describe*",
"elasticbeanstalk:List*",
"elasticbeanstalk:RequestEnvironmentInfo",
"elasticbeanstalk:RetrieveEnvironmentInfo",
"ec2:Describe*",
"elasticloadbalancing:Describe*",
"autoscaling:Describe*",
"cloudwatch:Describe*",
"cloudwatch:List*",
"cloudwatch:Get*",
"s3:Get*",
"s3:List*",
"sns:Get*",
"sns:List*",
"cloudformation:Describe*",
"cloudformation:Get*",
"cloudformation:List*",
"cloudformation:Validate*",
"cloudformation:Estimate*",
"rds:Describe*",
"sqs:Get*",
"sqs:List*"
],
"Resource": "*"
}
]
Controlling Access with Managed Policies
You can use managed policies to grant full access or read-only access to Elastic Beanstalk. Elastic
Beanstalk updates these policies automatically when additional permissions are required to access new
features.
To apply a managed policy to an IAM user
1.
Open the Users page in the IAM console.
2.
In the navigation pane, choose Permissions.
3.
Choose Attach Policy.
4.
Type AWSElasticBeanstalk to filter the policies.
5.
Select AWSElasticBeanstalkReadOnlyAccess or AWSElasticBeanstalkFullAccess, and then choose
Attach Policy.
Creating a Custom User Policy
You can create your own IAM policy to allow or deny specific Elastic Beanstalk API actions on specific
Elastic Beanstalk resources. For more information about attaching a policy to a user or group, see
Working with Policies in Using AWS Identity and Access Management.
API Version 2010-12-01
364
AWS Elastic Beanstalk Developer Guide
User Policies
An IAM policy contains policy statements that describe the permissions that you want to grant. When
you create a policy statement for Elastic Beanstalk, you need to understand how to use the following
four parts of a policy statement:
• Effect specifies whether to allow or deny the actions in the statement.
• Action specifies the API operations that you want to control. For example, use
elasticbeanstalk:CreateEnvironment to specify the CreateEnvironment operation. Certain
operations, such as creating an environment, require additional permissions to perform those actions.
For more information, see Resources and Conditions for Elastic Beanstalk Actions (p. 368).
Resource specifies the resources that you want to control access to. To specify Elastic Beanstalk
resources, list the Amazon Resource Name (p. 366) (ARN) of each resource.
• (optional) Condition specifies restrictions on the permission granted in the statement. For more
information, see Resources and Conditions for Elastic Beanstalk Actions (p. 368).
The following example policy contains three statements that enable a user who has this policy to call the
CreateEnvironment action to create an environment whose name begins with Test with the specified
application and application version.
{
"Version": "2012-10-17",
"Statement": [
{
"Sid":"CreateEnvironmentPerm",
"Action": [
"elasticbeanstalk:CreateEnvironment"
],
"Effect": "Allow",
"Resource": [
"arn:aws:elasticbeanstalk:us-east-2:123456789012:environment/My First Elastic
Beanstalk Application/Test*"
],
"Condition": {
"StringEquals": {
"elasticbeanstalk:InApplication": ["arn:aws:elasticbeanstalk:useast-2:123456789012:application/My First Elastic Beanstalk Application"],
"elasticbeanstalk:FromApplicationVersion": ["arn:aws:elasticbeanstalk:useast-2:123456789012:applicationversion/My First Elastic Beanstalk Application/First
Release"]
}
}
},
{
"Sid":"AllNonResourceCalls",
"Action":[
"elasticbeanstalk:CheckDNSAvailability",
"elasticbeanstalk:CreateStorageLocation"
],
"Effect":"Allow",
"Resource":[
"*"
]
}
]
}
The above policy shows how to grant limited access to Elastic Beanstalk operations. In order to actually
launch an environment, the user must have permission to create the AWS resources that power the
environment as well. For example, the following policy grants access to the default set of resources for a
web server environment:
API Version 2010-12-01
365
AWS Elastic Beanstalk Developer Guide
ARN Format
{
}
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:*",
"ecs:*",
"elasticloadbalancing:*",
"autoscaling:*",
"cloudwatch:*",
"s3:*",
"sns:*",
"cloudformation:*",
"sqs:*"
],
"Resource": "*"
}
]
Note that while you can restrict how a user interacts with Elastic Beanstalk APIs, there is not currently an
effective way to prevent users who have permission to create the necessary underlying resources from
creating other resources in Amazon EC2 and other services.
Enabling Read-Only Access to Elastic Beanstalk Logs
The following example policy contains two statements that enable a user who has this policy to view and
pull Elastic Beanstalk logs.
{
}
"Version": "2012-10-17",
"Statement": [
{
"Sid": "Stmt1491295324000",
"Effect": "Allow",
"Action": [
"s3:PutObjectAcl"
],
"Resource": [
"arn:aws:s3:::elasticbeanstalk-*/*"
]
},
{
"Sid": "Stmt1491295472000",
"Effect": "Allow",
"Action": [
"s3:PutObjectAcl"
],
"Resource": [
"arn:aws:s3:::elasticbeanstalk-*"
]
}
]
Amazon Resource Name Format for Elastic Beanstalk
You specify a resource for an IAM policy using that resource's Amazon Resource Name (ARN). For Elastic
Beanstalk, the ARN has the following format.
API Version 2010-12-01
366
AWS Elastic Beanstalk Developer Guide
ARN Format
arn:aws:elasticbeanstalk:region:accountid:resourcetype/resourcepath
Where:
• region is the region the resource resides in (for example, us-west-2).
• accountid is the AWS account ID, with no hyphens (for example, 123456789012)
• resourcetype identifies the type of the Elastic Beanstalk resource—for example, environment. See the
table below for a list of all Elastic Beanstalk resource types.
• resourcepath is the portion that identifies the specific resource. An Elastic Beanstalk resource has a
path that uniquely identifies that resource. See the table below for the format of the resource path
for each resource type. For example, an environment is always associated with an application. The
resource path for the environment myEnvironment in the application myApp would look like this:
myApp/myEnvironment
Elastic Beanstalk has several types of resources you can specify in a policy. The following table shows the
ARN format for each resource type and an example.
Resource Type
Format for ARN
application
arn:aws:elasticbeanstalk:region:accountid:application/applicationname
Example: arn:aws:elasticbeanstalk:us-west-2:123456789012:application/My
App
applicationversion
arn:aws:elasticbeanstalk:region:accountid:applicationversion/
applicationname/versionlabel
Example: arn:aws:elasticbeanstalk:uswest-2:123456789012:applicationversion/My App/My Version
configurationtemplate
arn:aws:elasticbeanstalk:region:accountid:configurationtemplate/
applicationname/templatename
Example: arn:aws:elasticbeanstalk:uswest-2:123456789012:configurationtemplate/My App/My Template
environment
arn:aws:elasticbeanstalk:region:accountid:environment/applicationname/
environmentname
Example: arn:aws:elasticbeanstalk:us-west-2:123456789012:environment/My
App/MyEnvironment
platform
arn:aws:elasticbeanstalk:REGION:ACCOUNT_ID:platform/PLATFORM_NAME/
PLATFORM_VERSION
Example: arn:aws:elasticbeanstalk:us-west-2:123456789:platform/
MyPlatform/1.0
solutionstack
arn:aws:elasticbeanstalk:region::solutionstack/solutionstackname
Example: arn:aws:elasticbeanstalk:us-west-2::solutionstack/32bit Amazon
Linux running Tomcat 7
API Version 2010-12-01
367
AWS Elastic Beanstalk Developer Guide
Resources and Conditions
An environment, application version, and configuration template are always contained within a specific
application. You'll notice that these resources all have an application name in their resource path so that
they are uniquely identified by their resource name and the containing application. Although solution
stacks are used by configuration templates and environments, solution stacks are not specific to an
application or AWS account and do not have the application or AWS account in their ARNs.
Resources and Conditions for Elastic Beanstalk
Actions
This section describes the resources and conditions that you can use in policy statements to grant
permissions that allow specific Elastic Beanstalk actions to be performed on specific Elastic Beanstalk
resources.
Conditions enable you to specify permissions to resources that the action needs to complete. For
example, when you can call the CreateEnvironment action, you must also specify the application version
to deploy as well as the application that contains that application name. When you set permissions for
the CreateEnvironment action, you specify the application and application version that you want the
action to act upon by using the InApplication and FromApplicationVersion conditions.
In addition, you can specify the environment configuration with a solution stack (FromSolutionStack)
or a configuration template (FromConfigurationTemplate). The following policy statement allows
the CreateEnvironment action to create an environment with the name myenv (specified by Resource)
in the application My App (specified by the InApplication condition) using the application version
My Version (FromApplicationVersion) with a 32bit Amazon Linux running Tomcat 7 configuration
(FromSolutionStack):
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"elasticbeanstalk:CreateEnvironment"
],
"Effect": "Allow",
"Resource": [
"arn:aws:elasticbeanstalk:us-west-2:123456789012:environment/My App/myenv"
],
"Condition": {
"StringEquals": {
"elasticbeanstalk:InApplication": ["arn:aws:elasticbeanstalk:uswest-2:123456789012:application/My App"],
"elasticbeanstalk:FromApplicationVersion": ["arn:aws:elasticbeanstalk:uswest-2:123456789012:applicationversion/My App/My Version"],
"elasticbeanstalk:FromSolutionStack": ["arn:aws:elasticbeanstalk:uswest-2::solutionstack/32bit Amazon Linux running Tomcat 7"]
}
}
}
]
}
Sections
• Policy Information for Elastic Beanstalk Actions (p. 369)
• Condition Keys for Elastic Beanstalk Actions (p. 386)
API Version 2010-12-01
368
AWS Elastic Beanstalk Developer Guide
Resources and Conditions
Policy Information for Elastic Beanstalk Actions
The following table lists all Elastic Beanstalk actions, the resource that each action acts upon, and the
additional contextual information that can be provided using conditions.
Policy information for Elastic Beanstalk actions, including resources, conditions, examples,
and dependencies
Resource
Conditions
Example Statement
Action: AbortEnvironmentUpdate
application
N/A
environment
The following policy allows a user to abort environment
update operations on environments in an application
named My App.
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"elasticbeanstalk:AbortEnvironmentUpdate"
],
"Effect": "Allow",
"Resource": [
"arn:aws:elasticbeanstalk:uswest-2:123456789012:application/My App"
]
}
]
}
Action: CheckDNSAvailability
"*"
N/A
{
}
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"elasticbeanstalk:CheckDNSAvailability"
],
"Effect": "Allow",
"Resource": "*"
}
]
Action: ComposeEnvironments
application
N/A
The following policy allows a user to compose
environments that belong to an application named My
App.
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"elasticbeanstalk:ComposeEnvironments"
],
"Effect": "Allow",
API Version 2010-12-01
369
AWS Elastic Beanstalk Developer Guide
Resources and Conditions
Resource
Conditions
Example Statement
"Resource": [
"arn:aws:elasticbeanstalk:uswest-2:123456789012:environment/My App"
]
}
]
}
Action: CreateApplication
application
N/A
This example allows the CreateApplication action to
create applications whose names begin with DivA:
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"elasticbeanstalk:CreateApplication"
],
"Effect": "Allow",
"Resource": [
"arn:aws:elasticbeanstalk:uswest-2:123456789012:application/DivA*"
]
}
]
}
Action: CreateApplicationVersion
applicationversion InApplication
This example allows the CreateApplicationVersion
action to create application versions with any name (*) in
the application My App:
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"elasticbeanstalk:CreateApplicationVersion"
],
"Effect": "Allow",
"Resource": [
"arn:aws:elasticbeanstalk:uswest-2:123456789012:applicationversion/My App/*"
],
"Condition": {
"StringEquals": {
"elasticbeanstalk:InApplication":
["arn:aws:elasticbeanstalk:uswest-2:123456789012:application/My App"]
}
}
}
]
}
API Version 2010-12-01
370
AWS Elastic Beanstalk Developer Guide
Resources and Conditions
Resource
Conditions
Example Statement
Action: CreateConfigurationTemplate
configurationtemplate
InApplication
FromApplication
The following policy allows the
CreateConfigurationTemplate action to create
configuration templates whose name begins with My
Template (My Template*) in the application My App:
FromApplicationVersion
{
FromConfigurationTemplate
"Version": "2012-10-17",
"Statement": [
FromEnvironment
{
"Action": [
FromSolutionStack
"elasticbeanstalk:CreateConfigurationTemplate"
],
"Effect": "Allow",
"Resource": [
"arn:aws:elasticbeanstalk:uswest-2:123456789012:configurationtemplate/My App/
My Template*"
],
"Condition": {
"StringEquals": {
"elasticbeanstalk:InApplication":
["arn:aws:elasticbeanstalk:uswest-2:123456789012:application/My App"],
"elasticbeanstalk:FromSolutionStack":
["arn:aws:elasticbeanstalk:uswest-2::solutionstack/32bit Amazon Linux running
Tomcat 7"]
}
}
}
]
}
Action: CreateEnvironment
API Version 2010-12-01
371
AWS Elastic Beanstalk Developer Guide
Resources and Conditions
Resource
Conditions
Example Statement
environment
InApplication
The following policy allows the CreateEnvironment action
to create an environment whose name is myenv in the
FromApplicationVersion
application My App and using the solution stack 32bit
Amazon Linux running Tomcat 7:
FromConfigurationTemplate
FromSolutionStack
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"elasticbeanstalk:CreateEnvironment"
],
"Effect": "Allow",
"Resource": [
"arn:aws:elasticbeanstalk:uswest-2:123456789012:environment/My App/myenv"
],
"Condition": {
"StringEquals": {
"elasticbeanstalk:InApplication":
["arn:aws:elasticbeanstalk:uswest-2:123456789012:application/My App"],
"elasticbeanstalk:FromApplicationVersion":
["arn:aws:elasticbeanstalk:uswest-2:123456789012:applicationversion/My App/My
Version"],
"elasticbeanstalk:FromSolutionStack":
["arn:aws:elasticbeanstalk:uswest-2::solutionstack/32bit Amazon Linux running
Tomcat 7"]
}
}
}
]
}
Action: CreateStorageLocation
"*"
N/A
{
}
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"elasticbeanstalk:CreateStorageLocation"
],
"Effect": "Allow",
"Resource": "*"
}
]
Action: DeleteApplication
API Version 2010-12-01
372
AWS Elastic Beanstalk Developer Guide
Resources and Conditions
Resource
Conditions
Example Statement
application
N/A
The following policy allows the DeleteApplication action
to delete the application My App:
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"elasticbeanstalk:DeleteApplication"
],
"Effect": "Allow",
"Resource": [
"arn:aws:elasticbeanstalk:uswest-2:123456789012:application/My App"
]
}
]
}
Action: DeleteApplicationVersion
applicationversion InApplication
The following policy allows the
DeleteApplicationVersion action to delete an
application version whose name is My Version in the
application My App:
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"elasticbeanstalk:DeleteApplicationVersion"
],
"Effect": "Allow",
"Resource": [
"arn:aws:elasticbeanstalk:uswest-2:123456789012:applicationversion/My App/My
Version"
],
"Condition": {
"StringEquals": {
"elasticbeanstalk:InApplication":
["arn:aws:elasticbeanstalk:uswest-2:123456789012:application/My App"]
}
}
}
]
}
Action: DeleteConfigurationTemplate
API Version 2010-12-01
373
AWS Elastic Beanstalk Developer Guide
Resources and Conditions
Resource
Conditions
Example Statement
configurationtemplate
InApplication
(Optional)
The following policy allows the
DeleteConfigurationTemplate action to delete a
configuration template whose name is My Template in the
application My App. Specifying the application name as a
condition is optional.
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"elasticbeanstalk:DeleteConfigurationTemplate"
],
"Effect": "Allow",
"Resource": [
"arn:aws:elasticbeanstalk:uswest-2:123456789012:configurationtemplate/My App/
My Template"
]
}
]
}
Action: DeleteEnvironmentConfiguration
environment
InApplication
(Optional)
The following policy allows the
DeleteEnvironmentConfiguration action to delete a
draft configuration for the environment myenv in the
application My App. Specifying the application name as a
condition is optional.
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"elasticbeanstalk:DeleteEnvironmentConfiguration"
],
"Effect": "Allow",
"Resource": [
"arn:aws:elasticbeanstalk:uswest-2:123456789012:environment/My App/myenv"
]
}
]
}
Action: DescribeApplications
API Version 2010-12-01
374
AWS Elastic Beanstalk Developer Guide
Resources and Conditions
Resource
Conditions
Example Statement
application
N/A
The following policy allows the DescribeApplications
action to describe the application My App.
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"elasticbeanstalk:DescribeApplications"
],
"Effect": "Allow",
"Resource": [
"arn:aws:elasticbeanstalk:uswest-2:123456789012:application/My App"
]
}
]
}
Action: DescribeApplicationVersions
applicationversion InApplication
(Optional)
The following policy allows the
DescribeApplicationVersions action to describe the
application version My Version in the application My
App. Specifying the application name as a condition is
optional.
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"elasticbeanstalk:DescribeApplicationVersions"
],
"Effect": "Allow",
"Resource": [
"arn:aws:elasticbeanstalk:uswest-2:123456789012:applicationversion/My App/My
Version"
]
}
]
}
Action: DescribeConfigurationOptions
API Version 2010-12-01
375
AWS Elastic Beanstalk Developer Guide
Resources and Conditions
Resource
Conditions
Example Statement
environment
InApplication
The following policy allows the
(Optional)
configurationtemplate
solutionstack
DescribeConfigurationOptions action to describe the
configuration options for the environment myenv in the
application My App. Specifying the application name as a
condition is optional.
{
"Version": "2012-10-17",
"Statement": [
{
"Action":
"elasticbeanstalk:DescribeConfigurationOptions",
"Effect": "Allow",
"Resource": [
"arn:aws:elasticbeanstalk:uswest-2:123456789012:environment/My App/myenv"
]
}
]
}
Action: DescribeConfigurationSettings
environment,
InApplication
configurationtemplate
(Optional)
The following policy allows the
DescribeConfigurationSettings action to describe the
configuration settings for the environment myenv in the
application My App. Specifying the application name as a
condition is optional.
{
"Version": "2012-10-17",
"Statement": [
{
"Action":
"elasticbeanstalk:DescribeConfigurationSettings",
"Effect": "Allow",
"Resource": [
"arn:aws:elasticbeanstalk:uswest-2:123456789012:environment/My App/myenv"
]
}
]
}
Action: DescribeEnvironmentHealth
API Version 2010-12-01
376
AWS Elastic Beanstalk Developer Guide
Resources and Conditions
Resource
Conditions
Example Statement
environment
N/A
The following policy allows use of
DescribeEnvironmentHealth to retrieve health
information for an environment named myenv.
{
"Version": "2012-10-17",
"Statement": [
{
"Action":
"elasticbeanstalk:DescribeEnvironmentHealth",
"Effect": "Allow",
"Resource": [
"arn:aws:elasticbeanstalk:uswest-2:123456789012:environment/My App/myenv"
]
}
]
}
Action: DescribeEnvironmentResources
environment
InApplication
(Optional)
The following policy allows the
DescribeEnvironmentResources action to return list
of AWS resources for the environment myenv in the
application My App. Specifying the application name as a
condition is optional.
{
"Version": "2012-10-17",
"Statement": [
{
"Action":
"elasticbeanstalk:DescribeEnvironmentResources",
"Effect": "Allow",
"Resource": [
"arn:aws:elasticbeanstalk:uswest-2:123456789012:environment/My App/myenv"
]
}
]
}
Action: DescribeEnvironments
API Version 2010-12-01
377
AWS Elastic Beanstalk Developer Guide
Resources and Conditions
Resource
Conditions
Example Statement
environment
InApplication
The following policy allows the DescribeEnvironments
action to describe the environments myenv and
myotherenv in the application My App. Specifying the
application name as a condition is optional.
(Optional)
{
"Version": "2012-10-17",
"Statement": [
{
"Action":
"elasticbeanstalk:DescribeEnvironments",
"Effect": "Allow",
"Resource": [
"arn:aws:elasticbeanstalk:uswest-2:123456789012:environment/My App/myenv",
"arn:aws:elasticbeanstalk:uswest-2:123456789012:environment/My App2/
myotherenv"
]
}
]
}
Action: DescribeEvents
application
InApplication
applicationversion
configurationtemplate
The following policy allows the DescribeEvents action to
list event descriptions for the environment myenv and the
application version My Version in the application My App.
{
"Version": "2012-10-17",
"Statement": [
{
"Action": "elasticbeanstalk:DescribeEvents",
"Effect": "Allow",
"Resource": [
"arn:aws:elasticbeanstalk:uswest-2:123456789012:environment/My App/myenv",
"arn:aws:elasticbeanstalk:uswest-2:123456789012:applicationversion/My App/My
Version"
],
"Condition": {
"StringEquals": {
"elasticbeanstalk:InApplication":
["arn:aws:elasticbeanstalk:uswest-2:123456789012:application/My App"]
}
}
}
]
}
environment
Action: DescribeInstancesHealth
API Version 2010-12-01
378
AWS Elastic Beanstalk Developer Guide
Resources and Conditions
Resource
Conditions
Example Statement
environment
N/A
The following policy allows use of
DescribeInstancesHealth to retrieve health information
for instances in an environment named myenv.
{
"Version": "2012-10-17",
"Statement": [
{
"Action":
"elasticbeanstalk:DescribeInstancesHealth",
"Effect": "Allow",
"Resource": [
"arn:aws:elasticbeanstalk:uswest-2:123456789012:environment/My App/myenv"
]
}
]
}
Action: ListAvailableSolutionStacks
solutionstack
N/A
The following policy allows the
ListAvailableSolutionStacks action to return only the
solution stack 32bit Amazon Linux running Tomcat 7.
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"elasticbeanstalk:ListAvailableSolutionStacks"
],
"Effect": "Allow",
"Resource": "arn:aws:elasticbeanstalk:uswest-2::solutionstack/32bit Amazon Linux running
Tomcat 7"
}
]
}
Action: RebuildEnvironment
API Version 2010-12-01
379
AWS Elastic Beanstalk Developer Guide
Resources and Conditions
Resource
Conditions
Example Statement
environment
InApplication
The following policy allows the RebuildEnvironment
action to rebuild the environment myenv in the
application My App.
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"elasticbeanstalk:RebuildEnvironment"
],
"Effect": "Allow",
"Resource": [
"arn:aws:elasticbeanstalk:uswest-2:123456789012:environment/My App/myenv"
],
"Condition": {
"StringEquals": {
"elasticbeanstalk:InApplication":
["arn:aws:elasticbeanstalk:uswest-2:123456789012:application/My App"]
}
}
}
]
}
Action: RequestEnvironmentInfo
environment
InApplication
The following policy allows the RequestEnvironmentInfo
action to compile information about the environment
myenv in the application My App.
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"elasticbeanstalk:RequestEnvironmentInfo"
],
"Effect": "Allow",
"Resource": [
"arn:aws:elasticbeanstalk:uswest-2:123456789012:environment/My App/myenv"
],
"Condition": {
"StringEquals": {
"elasticbeanstalk:InApplication":
["arn:aws:elasticbeanstalk:uswest-2:123456789012:application/My App"]
}
}
}
]
}
Action: RestartAppServer
API Version 2010-12-01
380
AWS Elastic Beanstalk Developer Guide
Resources and Conditions
Resource
Conditions
Example Statement
environment
InApplication
The following policy allows the RestartAppServer
action to restart the application container server for the
environment myenv in the application My App.
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"elasticbeanstalk:RestartAppServer"
],
"Effect": "Allow",
"Resource": [
"arn:aws:elasticbeanstalk:uswest-2:123456789012:environment/My App/myenv"
],
"Condition": {
"StringEquals": {
"elasticbeanstalk:InApplication":
["arn:aws:elasticbeanstalk:uswest-2:123456789012:application/My App"]
}
}
}
]
}
Action: RetrieveEnvironmentInfo
environment
InApplication
The following policy allows the
RetrieveEnvironmentInfo action to retrieve the compiled
information for the environment myenv in the application
My App.
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"elasticbeanstalk:RetrieveEnvironmentInfo"
],
"Effect": "Allow",
"Resource": [
"arn:aws:elasticbeanstalk:uswest-2:123456789012:environment/My App/myenv"
],
"Condition": {
"StringEquals": {
"elasticbeanstalk:InApplication":
["arn:aws:elasticbeanstalk:uswest-2:123456789012:application/My App"]
}
}
}
]
}
Action: SwapEnvironmentCNAMEs
API Version 2010-12-01
381
AWS Elastic Beanstalk Developer Guide
Resources and Conditions
Resource
Conditions
Example Statement
environment
InApplication
The following policy allows the SwapEnvironmentCNAMEs
action to swap the CNAMEs for the environments
mysrcenv and mydestenv.
(Optional)
FromEnvironment
(Optional)
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"elasticbeanstalk:SwapEnvironmentCNAMEs"
],
"Effect": "Allow",
"Resource": [
"arn:aws:elasticbeanstalk:uswest-2:123456789012:environment/My App/mysrcenv",
"arn:aws:elasticbeanstalk:uswest-2:123456789012:environment/My App/mydestenv"
]
}
]
}
Action: TerminateEnvironment
environment
InApplication
The following policy allows the TerminateEnvironment
action to terminate the environment myenv in the
application My App.
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"elasticbeanstalk:TerminateEnvironment"
],
"Effect": "Allow",
"Resource": [
"arn:aws:elasticbeanstalk:uswest-2:123456789012:environment/My App/myenv"
],
"Condition": {
"StringEquals": {
"elasticbeanstalk:InApplication":
["arn:aws:elasticbeanstalk:uswest-2:123456789012:application/My App"]
}
}
}
]
}
Action: UpdateApplication
API Version 2010-12-01
382
AWS Elastic Beanstalk Developer Guide
Resources and Conditions
Resource
Conditions
Example Statement
application
N/A
The following policy allows the UpdateApplication action
to update properties of the application My App.
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"elasticbeanstalk:UpdateApplication"
],
"Effect": "Allow",
"Resource": [
"arn:aws:elasticbeanstalk:uswest-2:123456789012:application/My App"
]
}
]
}
Action: UpdateApplicationVersion
applicationversion InApplication
The following policy allows the
UpdateApplicationVersion action to update the
properties of the application version My Version in the
application My App.
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"elasticbeanstalk:UpdateApplicationVersion"
],
"Effect": "Allow",
"Resource": [
"arn:aws:elasticbeanstalk:uswest-2:123456789012:applicationversion/My App/My
Version"
],
"Condition": {
"StringEquals": {
"elasticbeanstalk:InApplication":
["arn:aws:elasticbeanstalk:uswest-2:123456789012:application/My App"]
}
}
}
]
}
Action: UpdateConfigurationTemplate
API Version 2010-12-01
383
AWS Elastic Beanstalk Developer Guide
Resources and Conditions
Resource
Conditions
Example Statement
configurationtemplate
InApplication
The following policy allows the
UpdateConfigurationTemplate action to update the
properties or options of the configuration template My
Template in the application My App.
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"elasticbeanstalk:UpdateConfigurationTemplate"
],
"Effect": "Allow",
"Resource": [
"arn:aws:elasticbeanstalk:uswest-2:123456789012:configurationtemplate/My App/
My Template"
],
"Condition": {
"StringEquals": {
"elasticbeanstalk:InApplication":
["arn:aws:elasticbeanstalk:uswest-2:123456789012:application/My App"]
}
}
}
]
}
Action: UpdateEnvironment
API Version 2010-12-01
384
AWS Elastic Beanstalk Developer Guide
Resources and Conditions
Resource
Conditions
Example Statement
environment
InApplication
The following policy allows the UpdateEnvironment action
to update the environment myenv in the application My
FromApplicationVersion
App by deploying the application version My Version.
FromConfigurationTemplate
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"elasticbeanstalk:UpdateEnvironment"
],
"Effect": "Allow",
"Resource": [
"arn:aws:elasticbeanstalk:uswest-2:123456789012:environment/My App/myenv"
],
"Condition": {
"StringEquals": {
"elasticbeanstalk:InApplication":
["arn:aws:elasticbeanstalk:uswest-2:123456789012:application/My App"],
"elasticbeanstalk:FromApplicationVersion":
["arn:aws:elasticbeanstalk:uswest-2:123456789012:applicationversion/My App/My
Version"]
}
}
}
]
}
Action: ValidateConfigurationSettings
API Version 2010-12-01
385
AWS Elastic Beanstalk Developer Guide
Resources and Conditions
Resource
Conditions
Example Statement
template
InApplication
The following policy allows the
environment
ValidateConfigurationSettings action to validates
configuration settings against the environment myenv in
the application My App.
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"elasticbeanstalk:ValidateConfigurationSettings"
],
"Effect": "Allow",
"Resource": [
"arn:aws:elasticbeanstalk:uswest-2:123456789012:environment/My App/myenv"
],
"Condition": {
"StringEquals": {
"elasticbeanstalk:InApplication":
["arn:aws:elasticbeanstalk:uswest-2:123456789012:application/My App"]
}
}
}
]
}
Condition Keys for Elastic Beanstalk Actions
Keys enable you to specify conditions that express dependencies, restrict permissions, or specify
constraints on the input parameters for an action. Elastic Beanstalk supports the following keys.
InApplication
Specifies the application that contains the resource that the action operates on.
The following example allows the UpdateApplicationVersion action to update the properties of the
application version My Version. The InApplication condition specifies My App as the container for
My Version.
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"elasticbeanstalk:UpdateApplicationVersion"
],
"Effect": "Allow",
"Resource": [
"arn:aws:elasticbeanstalk:us-west-2:123456789012:applicationversion/My App/My
Version"
],
"Condition": {
"StringEquals": {
"elasticbeanstalk:InApplication": ["arn:aws:elasticbeanstalk:uswest-2:123456789012:application/My App"]
API Version 2010-12-01
386
AWS Elastic Beanstalk Developer Guide
Resources and Conditions
}
]
}
}
}
FromApplicationVersion
Specifies an application version as a dependency or a constraint on an input parameter.
The following example allows the UpdateEnvironment action to update the environment myenv in the
application My App. The FromApplicationVersion condition constrains the VersionLabel parameter
to allow only the application version My Version to update the environment.
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"elasticbeanstalk:UpdateEnvironment"
],
"Effect": "Allow",
"Resource": [
"arn:aws:elasticbeanstalk:us-west-2:123456789012:environment/My App/myenv"
],
"Condition": {
"StringEquals": {
"elasticbeanstalk:InApplication": ["arn:aws:elasticbeanstalk:uswest-2:123456789012:application/My App"],
"elasticbeanstalk:FromApplicationVersion": ["arn:aws:elasticbeanstalk:uswest-2:123456789012:applicationversion/My App/My Version"]
}
}
}
]
}
FromConfigurationTemplate
Specifies a configuration template as a dependency or a constraint on an input parameter.
The following example allows the UpdateEnvironment action to update the environment myenv in
the application My App. The FromConfigurationTemplate condition constrains the TemplateName
parameter to allow only the configuration template My Template to update the environment.
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"elasticbeanstalk:UpdateEnvironment"
],
"Effect": "Allow",
"Resource": [
"arn:aws:elasticbeanstalk:us-west-2:123456789012:environment/My App/myenv"
],
"Condition": {
"StringEquals": {
"elasticbeanstalk:InApplication": ["arn:aws:elasticbeanstalk:uswest-2:123456789012:application/My App"],
"elasticbeanstalk:FromConfigurationTemplate": ["arn:aws:elasticbeanstalk:uswest-2:123456789012:configurationtemplate/My App/My Template"]
API Version 2010-12-01
387
AWS Elastic Beanstalk Developer Guide
Resources and Conditions
}
]
}
}
}
FromEnvironment
Specifies an environment as a dependency or a constraint on an input parameter.
The following example allows the SwapEnvironmentCNAMEs action to swap the CNAMEs in My App
for all environments whose names begin with mysrcenv and mydestenv but not those environments
whose names begin with mysrcenvPROD* and mydestenvPROD*.
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"elasticbeanstalk:SwapEnvironmentCNAMEs"
],
"Effect": "Allow",
"Resource": [
"arn:aws:elasticbeanstalk:us-west-2:123456789012:environment/My App/mysrcenv*",
"arn:aws:elasticbeanstalk:us-west-2:123456789012:environment/My App/mydestenv*"
],
"Condition": {
"StringNotLike": {
"elasticbeanstalk:FromEnvironment": ["arn:aws:elasticbeanstalk:uswest-2:123456789012:environment/My App/mysrcenvPROD*"],
"elasticbeanstalk:FromEnvironment": ["arn:aws:elasticbeanstalk:uswest-2:123456789012:environment/My App/mydestenvPROD*"
]
}
}
}
]
}
FromSolutionStack
Specifies a solution stack as a dependency or a constraint on an input parameter.
The following policy allows the CreateConfigurationTemplate action to create configuration
templates whose name begins with My Template (My Template*) in the application My App. The
FromSolutionStack condition constrains the solutionstack parameter to allow only the solution
stack 32bit Amazon Linux running Tomcat 7 as the input value for that parameter.
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"elasticbeanstalk:CreateConfigurationTemplate"
],
"Effect": "Allow",
"Resource": [
"arn:aws:elasticbeanstalk:us-west-2:123456789012:configurationtemplate/My App/
My Template*"
],
"Condition": {
"StringEquals": {
API Version 2010-12-01
388
AWS Elastic Beanstalk Developer Guide
Example Policies
"elasticbeanstalk:InApplication": ["arn:aws:elasticbeanstalk:uswest-2:123456789012:application/My App"],
"elasticbeanstalk:FromSolutionStack": ["arn:aws:elasticbeanstalk:uswest-2::solutionstack/32bit Amazon Linux running Tomcat 7"]
}
}
}
]
}
Example Policies Based on Managed Policies
This section demonstrates how to control user access to AWS Elastic Beanstalk and includes example
policies that provide the required access for common scenarios. These policies are derived from the
Elastic Beanstalk managed policies. For information about attaching managed policies to users and
groups, see Controlling Access to Elastic Beanstalk (p. 362).
In this scenario, Example Corp. is a software company with three teams responsible for the company
website: administrators who manage the infrastructure, developers who build the software for the
website, and a QA team that tests the website. To help manage permissions to their Elastic Beanstalk
resources, Example Corp. creates three groups to which members of each respective team belong:
Admins, Developers, and Testers. Example Corp. wants the Admins group to have full access to all
applications, environments, and their underlying resources so that they can create, troubleshoot, and
delete all Elastic Beanstalk assets. Developers require permissions to view all Elastic Beanstalk assets and
to create and deploy application versions. Developers should not be able to create new applications or
environments or terminate running environments. Testers need to view all Elastic Beanstalk resources to
monitor and test applications. The Testers should not be able to make changes to any Elastic Beanstalk
resources.
The following example policies provide the required permissions for each group.
Example 1: Allow the Admins group to use all Elastic Beanstalk and related service APIs
The following policy gives users permissions for all actions required to use Elastic Beanstalk. This policy
also allows Elastic Beanstalk to provision and manage resources on your behalf in the following services.
Elastic Beanstalk relies on these additional services to provision underlying resources when creating an
environment.
• Amazon Elastic Compute Cloud
• Elastic Load Balancing
• Auto Scaling
• Amazon CloudWatch
• Amazon Simple Storage Service
• Amazon Simple Notification Service
• Amazon Relational Database Service
• AWS CloudFormation
Note that this policy is an example. It gives a broad set of permissions to the AWS services that Elastic
Beanstalk uses to manage applications and environments. For example, ec2:* allows an AWS Identity
and Access Management (IAM) user to perform any action on any Amazon EC2 resource in the AWS
account. These permissions are not limited to the resources that you use with Elastic Beanstalk. As a best
practice, you should grant individuals only the permissions they need to perform their duties.
{
API Version 2010-12-01
389
AWS Elastic Beanstalk Developer Guide
Example Policies
}
"Version" : "2012-10-17",
"Statement" : [
{
"Effect" : "Allow",
"Action" : [
"elasticbeanstalk:*",
"ec2:*",
"elasticloadbalancing:*",
"autoscaling:*",
"cloudwatch:*",
"s3:*",
"sns:*",
"rds:*",
"cloudformation:*"
],
"Resource" : "*"
}
]
Example 2: Allow the Developers group to perform all actions except highly privileged
operations, such as creating applications and environments
The following policy denies permission to create applications and environments, but allows all other
Elastic Beanstalk actions.
Note that this policy is an example. It gives a broad set of permissions to the AWS products that Elastic
Beanstalk uses to manage applications and environments. For example, ec2:* allows an IAM user to
perform any action on any Amazon EC2 resource in the AWS account. These permissions are not limited
to the resources that you use with Elastic Beanstalk. As a best practice, you should grant individuals only
the permissions they need to perform their duties.
{
}
"Version" : "2012-10-17",
"Statement" : [
{
"Action" : [
"elasticbeanstalk:CreateApplication",
"elasticbeanstalk:CreateEnvironment",
"elasticbeanstalk:DeleteApplication",
"elasticbeanstalk:RebuildEnvironment",
"elasticbeanstalk:SwapEnvironmentCNAMEs",
"elasticbeanstalk:TerminateEnvironment"],
"Effect" : "Deny",
"Resource" : "*"
},
{
"Action" : [
"elasticbeanstalk:*",
"ec2:*",
"elasticloadbalancing:*",
"autoscaling:*",
"cloudwatch:*",
"s3:*",
"sns:*",
"rds:*",
"cloudformation:*"],
"Effect" : "Allow",
"Resource" : "*"
}
]
API Version 2010-12-01
390
AWS Elastic Beanstalk Developer Guide
Example Policies Based on Resource Permissions
Example 3: Allow the Testers group to view all Elastic Beanstalk assets, but not to perform
any actions
The following policy allows read-only access to all applications, application versions, events, and
environments.
{
}
"Version" : "2012-10-17",
"Statement" : [
{
"Effect" : "Allow",
"Action" : [
"elasticbeanstalk:Check*",
"elasticbeanstalk:Describe*",
"elasticbeanstalk:List*",
"elasticbeanstalk:RequestEnvironmentInfo",
"elasticbeanstalk:RetrieveEnvironmentInfo",
"ec2:Describe*",
"elasticloadbalancing:Describe*",
"autoscaling:Describe*",
"cloudwatch:Describe*",
"cloudwatch:List*",
"cloudwatch:Get*",
"s3:Get*",
"s3:List*",
"sns:Get*",
"sns:List*",
"rds:Describe*",
"cloudformation:Describe*",
"cloudformation:Get*",
"cloudformation:List*",
"cloudformation:Validate*",
"cloudformation:Estimate*"
],
"Resource" : "*"
}
]
Example Policies Based on Resource Permissions
This section walks through a use case for controlling user permissions for Elastic Beanstalk actions
that access specific Elastic Beanstalk resources. We'll walk through the sample policies that support
the use case. For more information policies on Elastic Beanstalk resources, see Creating a Custom User
Policy (p. 364). For information about attaching policies to users and groups, go to Managing IAM
Policies in Using AWS Identity and Access Management.
In our use case, Example Corp. is a small consulting firm developing applications for two different
customers. John is the development manager overseeing the development of the two Elastic Beanstalk
applications, app1 and app2. John does development and some testing on the two applications, and only
he can update the production environment for the two applications. These are the permissions that he
needs for app1 and app2:
• View application, application versions, environments, and configuration templates
• Create application versions and deploy them to the staging environment
• Update the production environment
• Create and terminate environments
API Version 2010-12-01
391
AWS Elastic Beanstalk Developer Guide
Example Policies Based on Resource Permissions
Jill is a tester who needs access to view the following resources in order to monitor and test the two
applications: applications, application versions, environments, and configuration templates. However, she
should not be able to make changes to any Elastic Beanstalk resources.
Jack is the developer for app1 who needs access to view all resources for app1 and also needs to create
application versions for app1 and deploy them to the staging environment.
Joe is the administrator of the AWS account for Example Corp. He has created IAM users for John, Jill,
and Jack and attaches the following policies to those users to grant the appropriate permissions to the
app1 and app2 applications.
Example 1: Policies that allow John to perform his development, test, and deployment
actions on app1 and app2
We have broken down John's policy into three separate policies so that they are easier to read and
manage. Together, they give John the permissions he needs to perform the Elastic Beanstalk actions on
the two applications.
The first policy specifies actions for Auto Scaling, Amazon S3, Amazon EC2, CloudWatch, Amazon
SNS, Elastic Load Balancing, Amazon RDS, and AWS CloudFormation. Elastic Beanstalk relies on these
additional services to provision underlying resources when creating an environment.
Note that this policy is an example. It gives a broad set of permissions to the AWS products that Elastic
Beanstalk uses to manage applications and environments. For example, ec2:* allows an IAM user to
perform any action on any Amazon EC2 resource in the AWS account. These permissions are not limited
to the resources that you use with Elastic Beanstalk. As a best practice, you should grant individuals only
the permissions they need to perform their duties.
{
"Version": "2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":[
"ec2:*",
"ecs:*",
"ecr:*",
"elasticloadbalancing:*",
"autoscaling:*",
"cloudwatch:*",
"s3:*",
"sns:*",
"cloudformation:*",
"dynamodb:*",
"rds:*",
"sqs:*",
"logs:*",
"iam:GetPolicyVersion",
"iam:GetRole",
"iam:PassRole",
"iam:ListRolePolicies",
"iam:ListAttachedRolePolicies",
"iam:ListInstanceProfiles",
"iam:ListRoles",
"iam:ListServerCertificates",
"acm:DescribeCertificate",
"acm:ListCertificates",
"codebuild:CreateProject",
"codebuild:DeleteProject",
"codebuild:BatchGetBuilds",
"codebuild:StartBuild"
],
"Resource":"*"
API Version 2010-12-01
392
AWS Elastic Beanstalk Developer Guide
Example Policies Based on Resource Permissions
}
]
}
The second policy specifies the Elastic Beanstalk actions that John is allowed to perform on the
app1 and app2 resources. The AllCallsInApplications statement allows all Elastic Beanstalk
actions ("elasticbeanstalk:*") performed on all resources within app1 and app2 (for example,
elasticbeanstalk:CreateEnvironment). The AllCallsOnApplications statement allows all Elastic
Beanstalk actions ("elasticbeanstalk:*") on the app1 and app2 application resources (for example,
elasticbeanstalk:DescribeApplications, elasticbeanstalk:UpdateApplication, etc.). The
AllCallsOnSolutionStacks statement allows all Elastic Beanstalk actions ("elasticbeanstalk:*") for
solution stack resources (for example, elasticbeanstalk:ListAvailableSolutionStacks).
{
}
"Version": "2012-10-17",
"Statement":[
{
"Sid":"AllCallsInApplications",
"Action":[
"elasticbeanstalk:*"
],
"Effect":"Allow",
"Resource":[
"*"
],
"Condition":{
"StringEquals":{
"elasticbeanstalk:InApplication":[
"arn:aws:elasticbeanstalk:us-west-2:123456789012:application/app1",
"arn:aws:elasticbeanstalk:us-west-2:123456789012:application/app2"
]
}
}
},
{
"Sid":"AllCallsOnApplications",
"Action":[
"elasticbeanstalk:*"
],
"Effect":"Allow",
"Resource":[
"arn:aws:elasticbeanstalk:us-west-2:123456789012:application/app1",
"arn:aws:elasticbeanstalk:us-west-2:123456789012:application/app2"
]
},
{
"Sid":"AllCallsOnSolutionStacks",
"Action":[
"elasticbeanstalk:*"
],
"Effect":"Allow",
"Resource":[
"arn:aws:elasticbeanstalk:us-west-2::solutionstack/*"
]
}
]
The third policy specifies the Elastic Beanstalk actions that the second policy needs
permissions to in order to complete those Elastic Beanstalk actions. The AllNonResourceCalls
statement allows the elasticbeanstalk:CheckDNSAvailability action, which is
required to call elasticbeanstalk:CreateEnvironment and other actions. It also
API Version 2010-12-01
393
AWS Elastic Beanstalk Developer Guide
Example Policies Based on Resource Permissions
allows the elasticbeanstalk:CreateStorageLocation action, which is required for
elasticbeanstalk:CreateApplication, elasticbeanstalk:CreateEnvironment, and other actions.
{
}
"Version": "2012-10-17",
"Statement":[
{
"Sid":"AllNonResourceCalls",
"Action":[
"elasticbeanstalk:CheckDNSAvailability",
"elasticbeanstalk:CreateStorageLocation"
],
"Effect":"Allow",
"Resource":[
"*"
]
}
]
Example 2: Policies that allow Jill to test and monitor app1 and app2
We have broken down Jill's policy into three separate policies so that they are easier to read and manage.
Together, they give Jill the permissions she needs to perform the Elastic Beanstalk actions on the two
applications.
The first policy specifies Describe*, List*, and Get* actions on Auto Scaling, Amazon S3, Amazon EC2,
CloudWatch, Amazon SNS, Elastic Load Balancing, Amazon RDS, and AWS CloudFormation (for nonlegacy container types) so that the Elastic Beanstalk actions are able to retrieve the relevant information
about the underlying resources of the app1 and app2 applications.
{
}
"Version": "2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":[
"ec2:Describe*",
"elasticloadbalancing:Describe*",
"autoscaling:Describe*",
"cloudwatch:Describe*",
"cloudwatch:List*",
"cloudwatch:Get*",
"s3:Get*",
"s3:List*",
"sns:Get*",
"sns:List*",
"rds:Describe*",
"cloudformation:Describe*",
"cloudformation:Get*",
"cloudformation:List*",
"cloudformation:Validate*",
"cloudformation:Estimate*"
],
"Resource":"*"
}
]
The second policy specifies the Elastic Beanstalk actions that Jill is allowed to perform on the app1
and app2 resources. The AllReadCallsInApplications statement allows her to call the Describe*
API Version 2010-12-01
394
AWS Elastic Beanstalk Developer Guide
Example Policies Based on Resource Permissions
actions and the environment info actions. The AllReadCallsOnApplications statement allows her
to call the DescribeApplications and DescribeEvents actions on the app1 and app2 application
resources. The AllReadCallsOnSolutionStacks statement allows viewing actions that involve
solution stack resources (ListAvailableSolutionStacks, DescribeConfigurationOptions, and
ValidateConfigurationSettings).
{
}
"Version": "2012-10-17",
"Statement":[
{
"Sid":"AllReadCallsInApplications",
"Action":[
"elasticbeanstalk:Describe*",
"elasticbeanstalk:RequestEnvironmentInfo",
"elasticbeanstalk:RetrieveEnvironmentInfo"
],
"Effect":"Allow",
"Resource":[
"*"
],
"Condition":{
"StringEquals":{
"elasticbeanstalk:InApplication":[
"arn:aws:elasticbeanstalk:us-west-2:123456789012:application/app1",
"arn:aws:elasticbeanstalk:us-west-2:123456789012:application/app2"
]
}
}
},
{
"Sid":"AllReadCallsOnApplications",
"Action":[
"elasticbeanstalk:DescribeApplications",
"elasticbeanstalk:DescribeEvents"
],
"Effect":"Allow",
"Resource":[
"arn:aws:elasticbeanstalk:us-west-2:123456789012:application/app1",
"arn:aws:elasticbeanstalk:us-west-2:123456789012:application/app2"
]
},
{
"Sid":"AllReadCallsOnSolutionStacks",
"Action":[
"elasticbeanstalk:ListAvailableSolutionStacks",
"elasticbeanstalk:DescribeConfigurationOptions",
"elasticbeanstalk:ValidateConfigurationSettings"
],
"Effect":"Allow",
"Resource":[
"arn:aws:elasticbeanstalk:us-west-2::solutionstack/*"
]
}
]
The third policy specifies the Elastic Beanstalk actions that the second policy needs permissions to in
order to complete those Elastic Beanstalk actions. The AllNonResourceCalls statement allows the
elasticbeanstalk:CheckDNSAvailability action, which is required for some viewing actions.
{
"Version": "2012-10-17",
"Statement":[
API Version 2010-12-01
395
AWS Elastic Beanstalk Developer Guide
Example Policies Based on Resource Permissions
{
}
]
}
"Sid":"AllNonResourceCalls",
"Action":[
"elasticbeanstalk:CheckDNSAvailability"
],
"Effect":"Allow",
"Resource":[
"*"
]
Example 3: Policies that allow Jack to access app1 to test, monitor, create application
versions, and deploy to the staging environment
We have broken down Jack's policy into three separate policies so that they are easier to read and
manage. Together, they give Jack the permissions he needs to perform the Elastic Beanstalk actions on
the app1 resource.
The first policy specifies the actions on Auto Scaling, Amazon S3, Amazon EC2, CloudWatch, Amazon
SNS, Elastic Load Balancing, Amazon RDS, and AWS CloudFormation (for non-legacy container types) so
that the Elastic Beanstalk actions are able to view and work with the underlying resources of app1. For a
list of supported non-legacy container types, see Why are some container types marked legacy? (p. 130).
Note that this policy is an example. It gives a broad set of permissions to the AWS products that Elastic
Beanstalk uses to manage applications and environments. For example, ec2:* allows an IAM user to
perform any action on any Amazon EC2 resource in the AWS account. These permissions are not limited
to the resources that you use with Elastic Beanstalk. As a best practice, you should grant individuals only
the permissions they need to perform their duties.
{
}
"Version": "2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":[
"ec2:*",
"elasticloadbalancing:*",
"autoscaling:*",
"cloudwatch:*",
"s3:*",
"sns:*",
"rds:*",
"cloudformation:*"
],
"Resource":"*"
}
]
The second policy specifies the Elastic Beanstalk actions that Jack is allowed to perform on the app1
resource.
{
"Version": "2012-10-17",
"Statement":[
{
"Sid":"AllReadCallsAndAllVersionCallsInApplications",
"Action":[
"elasticbeanstalk:Describe*",
API Version 2010-12-01
396
AWS Elastic Beanstalk Developer Guide
Example Policies Based on Resource Permissions
"elasticbeanstalk:RequestEnvironmentInfo",
"elasticbeanstalk:RetrieveEnvironmentInfo",
"elasticbeanstalk:CreateApplicationVersion",
"elasticbeanstalk:DeleteApplicationVersion",
"elasticbeanstalk:UpdateApplicationVersion"
},
{
],
"Effect":"Allow",
"Resource":[
"*"
],
"Condition":{
"StringEquals":{
"elasticbeanstalk:InApplication":[
"arn:aws:elasticbeanstalk:us-west-2:123456789012:application/app1"
]
}
}
},
{
"Sid":"AllReadCallsOnApplications",
"Action":[
"elasticbeanstalk:DescribeApplications",
"elasticbeanstalk:DescribeEvents"
],
"Effect":"Allow",
"Resource":[
"arn:aws:elasticbeanstalk:us-west-2:123456789012:application/app1"
]
"Sid":"UpdateEnvironmentInApplications",
"Action":[
"elasticbeanstalk:UpdateEnvironment"
],
"Effect":"Allow",
"Resource":[
"arn:aws:elasticbeanstalk:us-west-2:123456789012:environment/app1/app1-
staging*"
],
"Condition":{
"StringEquals":{
"elasticbeanstalk:InApplication":[
"arn:aws:elasticbeanstalk:us-west-2:123456789012:application/app1"
]
},
"StringLike":{
"elasticbeanstalk:FromApplicationVersion":[
"arn:aws:elasticbeanstalk:us-west-2:123456789012:applicationversion/app1/
*"
},
{
]
}
}
}
]
"Sid":"AllReadCallsOnSolutionStacks",
"Action":[
"elasticbeanstalk:ListAvailableSolutionStacks",
"elasticbeanstalk:DescribeConfigurationOptions",
"elasticbeanstalk:ValidateConfigurationSettings"
],
"Effect":"Allow",
"Resource":[
"arn:aws:elasticbeanstalk:us-west-2::solutionstack/*"
]
API Version 2010-12-01
397
AWS Elastic Beanstalk Developer Guide
Amazon RDS
}
The third policy specifies the Elastic Beanstalk actions that the second policy needs
permissions to in order to complete those Elastic Beanstalk actions. The AllNonResourceCalls
statement allows the elasticbeanstalk:CheckDNSAvailability action, which is
required to call elasticbeanstalk:CreateEnvironment and other actions. It also
allows the elasticbeanstalk:CreateStorageLocation action, which is required for
elasticbeanstalk:CreateEnvironment, and other actions.
{
}
"Version": "2012-10-17",
"Statement":[
{
"Sid":"AllNonResourceCalls",
"Action":[
"elasticbeanstalk:CheckDNSAvailability",
"elasticbeanstalk:CreateStorageLocation"
],
"Effect":"Allow",
"Resource":[
"*"
]
}
]
Using Elastic Beanstalk with Amazon RDS
Elastic Beanstalk provides support for running Amazon RDS instances in your Elastic Beanstalk
environment (p. 260). This works great for development and testing environments, but is not ideal for
a production environment because it ties the lifecycle of the database instance to the lifecycle of your
application's environment.
Note
If you haven't used a DB instance with your application before, try adding one to a test
environment with the Elastic Beanstalk console first. This lets you verify that your application
is able to read environment properties, construct a connection string, and connect to a DB
instance prior to adding VPCs and security group configuration to the mix. See Configuring
Databases with Elastic Beanstalk (p. 260) for details.
To decouple your database instance from your environment, you can run a database instance in Amazon
Relational Database Service and configure your application to connect to it on launch. This allows you to
connect multiple environments to a database, terminate an environment without affecting the database,
and perform seamless updates with blue-green deployments.
To allow the EC2 instances in your environment to connect to an outside database, you can configure the
environment's Auto Scaling group with an additional security group. The security group that you attach
to your environment can be the same one that is attached to your database instance, or a separate
security group from which the database's security group allows ingress.
Note
It is possible to connect your environment to a database by adding a rule to your database's
security group that allows ingress from the autogenerated security group that Elastic
Beanstalk attaches to your environment's Auto Scaling group. However, doing so creates a
dependency between the two security groups. Subsequently, when you attempt to terminate
the environment, Elastic Beanstalk will be unable to delete the environment's security group
because the database's security group is dependent on it.
API Version 2010-12-01
398
AWS Elastic Beanstalk Developer Guide
Launching and Connecting to an
External RDS Instance in a Default VPC
After launching your database instance and configuring security groups, you can pass the connection
information (endpoint, password, etc.) to your application by using environment properties, the same
mechanism that Elastic Beanstalk uses when you run a database instance in your environment.
For additional security, you can store your connection information in Amazon S3, and configure Elastic
Beanstalk to retrieve it during deployment. With configuration files (.ebextensions) (p. 197), you can
configure the instances in your environment to securely retrieve files from Amazon S3 when you deploy
your application.
Topics
• Launching and Connecting to an External RDS Instance in a Default VPC (p. 399)
• Launching and Connecting to an External RDS Instance in EC2 Classic (p. 402)
• Storing the Connection String in Amazon S3 (p. 406)
Launching and Connecting to an External RDS
Instance in a Default VPC
To use an external database with a application running in Elastic Beanstalk, first launch a DB instance
with Amazon RDS. Any instance that you launch with Amazon RDS is completely independent of Elastic
Beanstalk and your Elastic Beanstalk environments, and is not dependent on Elastic Beanstalk for
configuration. This means that you can use any DB engine and instance type supported by Amazon RDS,
even those not used by Elastic Beanstalk.
The following procedures describe the process for a default VPC. The process is the same if you are using
a custom VPC. The only additional requirements are that your environment and DB instance are in the
same subnet, or in subnets that are allowed to communicate with each other. See Using Elastic Beanstalk
with Amazon VPC (p. 408) for details on configuring a custom VPC for use with Elastic Beanstalk.
To launch an RDS DB instance in a default VPC
1.
Open the RDS console.
2.
3.
4.
Choose Instances in the navigation pane.
Choose Launch DB Instance.
Choose a DB Engine and preset configuration.
5.
Under Specify DB Details, choose a DB Instance Class. For high availability, set Multi-AZ
Deployment to Yes.
Under Settings, enter values for DB Instance Identifier, Master Username, and Master Password
(and Confirm Password). Note the values that you entered for later.
Choose Next.
For Network and Security settings, choose the following:
6.
7.
8.
•
•
•
•
9.
VPC – Default VPC
Subnet Group – default
Publicly Accessible – No
Availability Zone – No Preference
• VPC Security Groups – Default VPC Security Group
For Database Name, type ebdb, and verify the default settings for the remaining options. Note the
values of the following options:
• Database Name
• Database Port
10. Choose Launch DB Instance.
API Version 2010-12-01
399
AWS Elastic Beanstalk Developer Guide
Launching and Connecting to an
External RDS Instance in a Default VPC
Next, modify the security group attached to your DB instance to allow inbound traffic on the appropriate
port. This is the same security group that you will attach to your Elastic Beanstalk environment later, so
the rule that you add will grant ingress permission to other resources in the same security group.
To modify the ingress rules on your RDS instance's security group
1.
Open the Amazon RDS console.
2.
Choose Instances.
3.
Choose the arrow next to the entry for your DB instance to expand the view.
4.
Choose the Details tab.
5.
In the Security and Network section, the security group associated with the DB instance is shown.
Open the link to view the security group in the Amazon EC2 console.
Note
While you have the Details tab open, note the Endpoint and security group name shown on
this page for use later.
The security group name is the first value of the link shown in Security Groups, before the
parentheses. The second value, in parentheses, is the security group ID.
6.
In the security group details, choose the Inbound tab.
7.
Choose Edit.
8.
Choose Add Rule.
9.
For Type, choose the DB engine that your application uses.
10. For Source, choose Custom, and then type the group ID of the security group. This allows resources
in the security group to receive traffic on the database port from other resources in the same group.
API Version 2010-12-01
400
AWS Elastic Beanstalk Developer Guide
Launching and Connecting to an
External RDS Instance in a Default VPC
11. Choose Save.
Next, add the DB instance's security group to your running environment. This procedure causes Elastic
Beanstalk to reprovision all instances in your environment with the additional security group attached.
Note
In a custom VPC, use the security group's group ID instead of its group name.
To add a security group to your environment
1.
Open the Elastic Beanstalk console.
2.
Navigate to the management page (p. 61) for your environment.
3.
Choose Configuration.
4.
In the Instances section, choose the settings icon (
).
5.
For EC2 security groups, type a comma after the name of the autogenerated security group
followed by the name of the RDS DB instance's security group. It is the name you noted while
configuring the security group earlier.
6.
Choose Apply.
7.
Read the warning, and then choose Save.
Next, pass the connection information to your environment by using environment properties. When you
add a DB instance to your environment (p. 260) with the Elastic Beanstalk console, Elastic Beanstalk uses
environment properties like RDS_HOSTNAME to pass connection information to your application. You
can use the same properties, which will let you use the same application code with both integrated DB
instances and external DB instances, or choose your own property name(s).
To configure environment properties for an Amazon RDS DB instance
1.
Open the Elastic Beanstalk console.
2.
Navigate to the management page (p. 61) for your environment.
3.
Choose Configuration.
4.
5.
In the Software Configuration section, choose the settings icon (
).
In the Environment Properties section, define the variables that your application reads to construct
a connection string. For compatibility with environments that have an integrated RDS DB instance,
use the following:
• RDS_HOSTNAME – The hostname of the DB instance.
Amazon RDS console label – Endpoint is the hostname.
• RDS_PORT – The port on which the DB instance accepts connections. The default value varies
between DB engines.
Amazon RDS console label – Port
• RDS_DB_NAME – The database name, ebdb.
Amazon RDS console label – DB Name
• RDS_USERNAME – The user name that you configured for your database.
Amazon RDS console label – Username
• RDS_PASSWORD – The password that you configured for your database.
Choose the plus symbol (+) to add additional properties.
API Version 2010-12-01
401
AWS Elastic Beanstalk Developer Guide
Launching and Connecting to an
External RDS Instance in EC2 Classic
6.
Choose Apply.
If you haven't programmed your application to read environment properties and construct a connection
string yet, see the following language-specific topics for instructions:
• Java SE – Connecting to a Database (Java SE Platforms) (p. 640)
• Java with Tomcat – Connecting to a Database (Tomcat Platforms) (p. 641)
• Node.js – Connecting to a Database (p. 750)
• .NET – Connecting to a Database (p. 688)
• PHP – Connecting to a Database with a PDO or MySQLi (p. 800)
• Python – Connecting to a Database (p. 823)
• Ruby – Connecting to a Database (p. 842)
Finally, depending on when your application reads environment variables, you may need to restart the
application server on the instances in your environment.
To restart your environment's app servers
1.
Open the Elastic Beanstalk console.
2.
Navigate to the management page (p. 61) for your environment.
3.
Choose Actions and then choose Restart App Server(s).
Launching and Connecting to an External RDS
Instance in EC2 Classic
If you use EC2 Classic (no VPC) with Elastic Beanstalk, the procedure changes slightly due to differences
in how security groups work. In EC2 Classic, DB instances cannot use EC2 security groups, so they get a
DB security group that only works with Amazon RDS.
API Version 2010-12-01
402
AWS Elastic Beanstalk Developer Guide
Launching and Connecting to an
External RDS Instance in EC2 Classic
You can add rules to a DB security group that allows ingress from EC2 security groups, but you cannot
attach a DB security group to your environment's Auto Scaling group. To avoid creating a dependency
between the DB security group and your environment, you must create a third security group in Amazon
EC2, grant it ingress from the DB security group, and then assign it to the Auto Scaling group in your
Elastic Beanstalk environment.
To launch an RDS instance in EC2 Classic (no VPC)
1.
Open the RDS management console.
2.
Choose Launch a DB Instance.
3.
Proceed through the wizard until you reach the Advanced Settings page. Note the values that you
enter for the following options:
• Master Username
• Master Password
4.
For Network and Security settings, choose the following:
• VPC – Not in VPC. If this option is not available, your account may not support EC2-Classic, or you
may have chosen an instance type that is only available in VPC.
• Availability Zone – No Preference
• DB Security Group(s) – Create new Security Group
5.
Configure the remaining options and choose Launch DB Instance. Note the values that you enter for
the following options:
• Database Name
• Database Port
In EC2-classic, your DB instance will have a DB security group instead of a VPC security group. You cannot
attach a DB security group to your Elastic Beanstalk environment, so you need to create a new security
group that you can authorize to access the DB instance and attach to your environment. We will refer to
this as a bridge security group and name it webapp-bridge.
To create a bridge security group
1.
Open the Amazon EC2 console
2.
Choose Security Groups under Network & Security in the navigation sidebar.
3.
Choose Create Security Group.
4.
For Security group name, type webapp-bridge.
5.
For Description, type Provide access to DB instance from Elastic Beanstalk environment
instances.
6.
For VPC, select No VPC.
7.
Choose Create
Next, modify the security group attached to your DB instance to allow inbound traffic from the bridge
security group.
To modify the ingress rules on your RDS instance's security group
1.
Open the Amazon RDS console.
2.
Choose Instances.
3.
Choose the arrow next to the entry for your DB instance to expand the view.
4.
Choose the Details tab.
API Version 2010-12-01
403
AWS Elastic Beanstalk Developer Guide
Launching and Connecting to an
External RDS Instance in EC2 Classic
5.
In the Security and Network section, the security group associated with the DB instance is shown.
Open the link to view the security group in the Amazon EC2 console.
6.
In the security group details, set Connection Type to EC2 Security Group.
7.
Set EC2 Security Group Name to the name of the bridge security group that you created.
8.
Choose Authorize.
Next, add the bridge security group to your running environment. This procedure requires all instances in
your environment to be reprovisioned with the additional security group attached.
To add a security group to your environment
1.
Open the Elastic Beanstalk console.
2.
3.
Navigate to the management page (p. 61) for your environment.
Choose Configuration.
4.
5.
Choose Instances.
For EC2 security groups, type a comma after the name of the autogenerated security group
followed by the name of the bridge security group that you created.
Choose Apply
Read the warning and then choose Save.
6.
7.
Next, pass the connection information to your environment by using environment properties. When you
add a DB instance to your environment (p. 260) with the Elastic Beanstalk console, Elastic Beanstalk uses
environment properties like RDS_HOSTNAME to pass connection information to your application. You
can use the same properties, which will let you use the same application code with both integrated DB
instances and external DB instances, or choose your own property name(s).
To configure environment properties
1.
2.
Open the Elastic Beanstalk console.
Navigate to the management page (p. 61) for your environment.
3.
4.
Choose Configuration.
5.
In the Software Configuration section, choose the settings icon (
).
In the Environment Properties section, define the variables that your application reads to construct
a connection string. For compatibility with environments that have an integrated RDS instance, use
the following:
API Version 2010-12-01
404
AWS Elastic Beanstalk Developer Guide
Launching and Connecting to an
External RDS Instance in EC2 Classic
• RDS_DB_NAME – The DB Name shown in the Amazon RDS console.
• RDS_USERNAME – The Master Username that you enter when you add the database to your
environment.
• RDS_PASSWORD – The Master Password that you enter when you add the database to your
environment.
• RDS_HOSTNAME – The Endpoint of the DB instance shown in the Amazon RDS console.
• RDS_PORT – The Port shown in the Amazon RDS console.
Choose the plus symbol to add additional properties:
6.
Choose Apply
If you haven't programmed your application to read environment properties and construct a connection
string yet, see the following language-specific topics for instructions:
• Java SE – Connecting to a Database (Java SE Platforms) (p. 640)
• Java with Tomcat – Connecting to a Database (Tomcat Platforms) (p. 641)
• Node.js – Connecting to a Database (p. 750)
• .NET – Connecting to a Database (p. 688)
• PHP – Connecting to a Database with a PDO or MySQLi (p. 800)
• Python – Connecting to a Database (p. 823)
• Ruby – Connecting to a Database (p. 842)
Finally, depending on when your application reads environment variables, you may need to restart the
application server on the instances in your environment.
To restart your environment's app servers
1.
Open the Elastic Beanstalk console.
API Version 2010-12-01
405
AWS Elastic Beanstalk Developer Guide
Storing the Connection String in Amazon S3
2.
Navigate to the management page (p. 61) for your environment.
3.
Choose Actions and then choose Restart App Server(s).
Storing the Connection String in Amazon S3
Providing connection information to your application with environment properties is a good way to
keep passwords out of your code, but it's not a perfect solution. Environment properties are discoverable
in the Environment Management Console (p. 61), and can be viewed by any user that has permission
to describe configuration settings on your environment. Depending on the platform, environment
properties may also appear in instance logs (p. 336).
You can lock down your connection information by storing it in an Amazon S3 bucket that you control.
The basic steps are as follows:
• Upload a file that contains your connection string to an Amazon S3 bucket.
• Grant the EC2 instance profile permission to read the file.
• Configure your application to download the file during deployment.
• Read the file in your application code.
First, create a bucket to store the file that contains your connection string. For this example, we will use
a JSON file that has a single key and value. The value is a JDBC connection string for a PostgreSQL DB
instance in Amazon RDS:
beanstalk-database.json
{
"connection": "jdbc:postgresql://mydb.b5uacpxznijm.us-west-2.rds.amazonaws.com:5432/ebdb?
user=username&password=mypassword"
}
The highlighted portions of the URL correspond to the endpoint, port, DB name, username and password
for the database.
To create a bucket and upload a file
1.
Open the Amazon S3 console.
2.
Choose Create Bucket.
3.
Type a Bucket Name and choose a Region.
4.
Choose Create.
5.
Open the bucket and choose Upload
6.
Follow the prompts to upload the file.
By default, your account owns the file and has permission to manage it, but IAM users and roles do not
unless you grant them access explicitly. Grant the instances in your Elastic Beanstalk environment by
adding a policy to the instance profile (p. 19).
The default instance is named aws-elasticbeanstalk-ec2-role. If you are not sure what your instance
profile is called, you can find it on the Configuration page in Environment Management Console (p. 247).
To add permissions to the instance profile
1.
Open the IAM console.
API Version 2010-12-01
406
AWS Elastic Beanstalk Developer Guide
Storing the Connection String in Amazon S3
2.
Choose Roles.
3.
Choose aws-elasticbeanstalk-ec2-role.
4.
Under Inline Policies, choose Create Role Policy. Choose Custom Policy.
5.
Add a policy that allows the instance to retrieve the file:
{
}
"Version": "2012-10-17",
"Statement": [
{
"Sid": "database",
"Action": [
"s3:GetObject"
],
"Effect": "Allow",
"Resource": [
"arn:aws:s3:::my-secret-bucket-123456789012/beanstalk-database.json"
]
}
]
Replace the bucket and object names with the names of your bucket and object.
Next, add a configuration file (p. 197) to your source code that tells Elastic Beanstalk to download the
file from Amazon S3 during deployment:
~/my-app/.ebextensions/database.config
Resources:
AWSEBAutoScalingGroup:
Metadata:
AWS::CloudFormation::Authentication:
S3Auth:
type: "s3"
buckets: ["my-secret-bucket-123456789012"]
roleName: "aws-elasticbeanstalk-ec2-role"
files:
"/tmp/beanstalk-database.json" :
mode: "000644"
owner: root
group: root
authentication: "S3Auth"
source: https://s3-us-west-2.amazonaws.com/my-secret-bucket-123456789012/beanstalkdatabase.json
This configuration file does two things. The Resources key adds an authentication method to your
environment's Auto Scaling group metadata that Elastic Beanstalk can use to access Amazon S3. The
files key tells Elastic Beanstalk to download the file from Amazon S3 and store it locally in /tmp/ during
deployment.
Deploy your application with the configuration file in .ebextensions folder at the root of your
source code. If you configured permissions correctly, the deployment will succeed and the file will be
downloaded to all of the instances in your environment. If not, the deployment will fail.
Finally, add code to your application to read the JSON file and use the connection string to connect to
the database. See the following language-specific topics for more information:
• Java SE – Connecting to a Database (Java SE Platforms) (p. 640)
API Version 2010-12-01
407
AWS Elastic Beanstalk Developer Guide
Amazon S3
• Java with Tomcat – Connecting to a Database (Tomcat Platforms) (p. 641)
• Node.js – Connecting to a Database (p. 750)
• .NET – Connecting to a Database (p. 688)
• PHP – Connecting to a Database with a PDO or MySQLi (p. 800)
• Python – Connecting to a Database (p. 823)
• Ruby – Connecting to a Database (p. 842)
Using Elastic Beanstalk with Amazon S3
Amazon S3 provides highly durable, fault-tolerant data storage. Behind the scenes, Amazon S3 stores
objects redundantly on multiple devices across multiple facilities in a region.
Elastic Beanstalk creates an Amazon S3 bucket named elasticbeanstalk-region-account-id for each
region in which you create environments. Elastic Beanstalk uses this bucket to store application versions,
logs, and other supporting files.
Elastic Beanstalk applies a bucket policy to buckets it creates to allow environments to write to the
bucket and prevent accidental deletion. If you need to delete a bucket that Elastic Beanstalk created,
first delete the bucket policy from the Permissions section of the bucket properties in the Amazon S3
Management Console.
To delete an Elastic Beanstalk storage bucket (console)
1.
Open the Amazon S3 Management Console
2.
Select the Elastic Beanstalk storage bucket.
3.
Choose Properties.
4.
Choose Permissions.
5.
Choose Edit Bucket Policy.
6.
Choose Delete.
7.
Choose OK.
8.
Choose Actions and then choose Delete Bucket.
9.
Type the name of the bucket and then choose Delete.
Using Elastic Beanstalk with Amazon VPC
Amazon Virtual Private Cloud (Amazon VPC) enables you to define a virtual network in your own isolated
section within the Amazon Web Services (AWS) cloud, known as a virtual private cloud (VPC). Using VPC,
you can deploy a new class of web applications on Elastic Beanstalk, including internal web applications
(such as your recruiting application), web applications that connect to an on-premise database (using a
VPN connection), as well as private web service backends. Elastic Beanstalk launches your AWS resources,
such as instances, into your VPC. Your VPC closely resembles a traditional network, with the benefits
of using AWS's scalable infrastructure. You have complete control over your VPC; you can select the IP
address range, create subnets, and configure routes and network gateways. To protect the resources in
each subnet, you can use multiple layers of security, including security groups and network access control
lists. For more information about Amazon VPC, go to the Amazon VPC User Guide.
Note
Elastic Beanstalk does not currently support linux proxy settings (HTTP_PROXY, HTTPS_PROXY
and NO_PROXY) for configuring a web proxy. Instances in your environment must have access to
the Internet directly or through a NAT device.
API Version 2010-12-01
408
AWS Elastic Beanstalk Developer Guide
What VPC Configurations Do I Need?
Important
Instances in your Elastic Beanstalk environment use Network Time Protocol (NTP) to syncronize
the system clock. If instances are unable to communicate on UDP port 123, the clock may go
out of sync, causing issues with Elastic Beanstalk health reporting. Ensure that your VPC security
groups and network ACLs allow outbound UDP traffic on port 123 to avoid these issues.
What VPC Configurations Do I Need?
When you use Amazon VPC with Elastic Beanstalk, you can launch Elastic Beanstalk resources, such as
Amazon EC2 instances, in a public or private subnet. The subnets that you require depend on your Elastic
Beanstalk application environment type and whether the resources you launch are public or private. The
following scenarios discuss sample VPC configurations that you might use for a particular environment.
Topics
• Single-instance environments (p. 409)
• Load-balancing, autoscaling environments (p. 409)
• Extend your own network into AWS (p. 410)
Single-instance environments
For single-instance environments, Elastic Beanstalk assigns an Elastic IP address (a static, public IP
address) to the instance so that it can communicate directly with the Internet. No additional network
interface, such as a network address translator (NAT), is required for a single-instance environment.
If you have a single-instance environment without any associated private resources, such as a back-end
Amazon RDS DB instance, create a VPC with one public subnet, and include the instance in that subnet.
For more information, see Example: Launching a Single-Instance Environment without Any Associated
Private Resources in a VPC (p. 410).
If you have resources that you don't want public, create a VPC with one public subnet and one private
subnet. Add all of your public resources, such as the single Amazon EC2 instance, in the public subnet,
and add private resources such as a back-end Amazon RDS DB instance in the private subnet. If you do
launch an Amazon RDS DB instance in a VPC, you must create at least two different private subnets that
are in different Availability Zones (an Amazon RDS requirement).
Load-balancing, autoscaling environments
For load-balancing, autoscaling environments, you can either create a public and private subnet for your
VPC, or use a single public subnet. In the case of a load-balancing, autoscaling environment, with both
a public and private subnet, Amazon EC2 instances in the private subnet require Internet connectivity.
Consider the following scenarios:
Scenarios
• You want your Amazon EC2 instances to have a private IP address (p. 409)
• You have resources that are private (p. 410)
• You don't have any private resources (p. 410)
• You require direct access to your Amazon EC2 instances in a private subnet (p. 410)
You want your Amazon EC2 instances to have a private IP address
Create a public and private subnet for your VPC in each Availability Zone (an Elastic Beanstalk
requirement). Then add your public resources, such as the load balancer and NAT, to the public subnet.
API Version 2010-12-01
409
AWS Elastic Beanstalk Developer Guide
Single-Instance Environment in a VPC
Elastic Beanstalk assigns them a unique Elastic IP addresses (a static, public IP address). Launch your
Amazon EC2 instances in the private subnet so that Elastic Beanstalk assigns them private IP addresses.
Without a public IP address, an Amazon EC2 instance can't directly communicate with the Internet.
Although Amazon EC2 instances in a private subnet can't send outbound traffic by default, neither can
they receive unsolicited inbound connections from the Internet.
To enable communication between the private subnet, and the public subnet and the Internet beyond
the public subnet, create routing rules that do the following:
• Route all inbound traffic to your Amazon EC2 instances through the load balancer.
• Route all outbound traffic from your Amazon EC2 instances through the NAT device.
You have resources that are private
If you have associated resources that are private, such as a back-end Amazon RDS DB instance, launch
the resources in private subnets.
Note
Amazon RDS requires at least two subnets, each in a separate Availability Zone. For more
information, see Example: Launching an Elastic Beanstalk in a VPC with Amazon RDS (p. 421).
You don't have any private resources
You can create a single public subnet for your VPC. If you want to use a single public subnet, you must
choose the Associate Public IP Address option to add the load balancer and your Amazon EC2 instances
to the public subnet. Elastic Beanstalk assigns a public IP address to each Amazon EC2 instance, and
eliminates the need for a NAT device to allow the instances to communicate with the Internet.
For more information, see Example: Launching a Load-Balancing, Autoscaling Environment with Public
and Private Resources in a VPC (p. 414).
You require direct access to your Amazon EC2 instances in a private subnet
If you require direct access to your Amazon EC2 instances in a private subnet (for example, if you want
to use SSH to sign in to an instance), create a bastion host in the public subnet that proxies requests
from the Internet. From the Internet, you can connect to your instances by using the bastion host.
For more information, see Example: Launching an Elastic Beanstalk Application in a VPC with Bastion
Hosts (p. 418).
Extend your own network into AWS
If you want to extend your own network into the cloud and also directly access the Internet from your
VPC, create a VPN gateway. For more information about creating a VPN Gateway, see Scenario 3: VPC
with Public and Private Subnets and Hardware VPN Access in the Amazon VPC User Guide.
Example: Launching a Single-Instance Environment
without Any Associated Private Resources in a VPC
You can deploy an Elastic Beanstalk application in a public subnet. Use this configuration if you just have
a single instance without any private resources that are associated with the instance, such as an Amazon
RDS DB instance that you don't want publicly accessible. Elastic Beanstalk assigns an Elastic IP address to
the instance so that it can access the Internet through the VPC Internet gateway.
API Version 2010-12-01
410
AWS Elastic Beanstalk Developer Guide
Single-Instance Environment in a VPC
To deploy a single-instance Elastic Beanstalk application inside a VPC, you need to complete the
following:
Topics
• Create a VPC with a Public Subnet (p. 411)
• Deploy to Elastic Beanstalk (p. 413)
Create a VPC with a Public Subnet
To create a VPC
1.
Sign in to the AWS Management Console and open the Amazon VPC console at https://
console.aws.amazon.com/vpc/.
2.
In the navigation pane, choose VPC Dashboard and then choose Start VPC Wizard.
3.
Select VPC with a Single Public Subnet and then choose Select.
API Version 2010-12-01
411
AWS Elastic Beanstalk Developer Guide
Single-Instance Environment in a VPC
A confirmation page shows the CIDR blocks used for the VPC and subnet. The page also shows the
subnet and the associated Availability Zone.
4.
Choose Create VPC.
AWS creates your VPC, subnet, Internet gateway, and route table. Choose OK to exit the wizard.
After AWS successfully creates the VPC, it assigns the VPC a VPC ID. You will need this for this for the
next step. To view your VPC ID, choose Your VPCs in the left pane of the Amazon VPC console.
API Version 2010-12-01
412
AWS Elastic Beanstalk Developer Guide
Single-Instance Environment in a VPC
Deploy to Elastic Beanstalk
After you set up your VPC, you can create your environment inside your VPC and deploy your application
to Elastic Beanstalk. You can do this using the Elastic Beanstalk console, or you can use the AWS toolkits,
AWS CLI, EB CLI, or Elastic Beanstalk API. If you use the Elastic Beanstalk console, you just need to upload
your .war or .zip file and select the VPC settings inside the wizard. Elastic Beanstalk then creates your
environment inside your VPC and deploys your application. Alternatively, you can use the AWS toolkits,
AWS CLI, EB CLI, or Elastic Beanstalk API to deploy your application. To do this, you need to define
your VPC option settings in a configuration file and deploy this file with your source bundle. This topic
provides instructions for both methods.
Deploying with the Elastic Beanstalk Console
When you create an Elastic Beanstalk application or launch an environment, the Elastic Beanstalk console
walks you through creating your environment inside a VPC. For more information, see Managing and
Configuring AWS Elastic Beanstalk Applications (p. 47).
You'll need to select the VPC ID and subnet ID for your instance. By default, VPC creates a public subnet
using 10.0.0.0/24. You can view your subnet IDs by choosing Subnets in the Amazon VPC console.
Deploying with the AWS Toolkits, Eb, CLI, or API
When deploying your application to Elastic Beanstalk using the AWS toolkits, EB CLI, the AWS CLI, or API,
you can specify your VPC option settings in a file and deploy it with your source bundle. See Advanced
Environment Customization with Configuration Files (.ebextensions) (p. 197) for more information.
aws:ec2:vpc (p. 170) Namespace:
VPCId
The identifier of your VPC.
Subnets
The identifier(s) of the subnet(s) to launch the instances in.
You can specify multiple identifiers by separating them with a comma.
option_settings:
aws:ec2:vpc:
VPCId: "vpd_id"
Subnets: "instance_subnet, etc"
API Version 2010-12-01
413
AWS Elastic Beanstalk Developer Guide
Load-Balancing Environment with Private Instances
Example: Launching a Load-Balancing, Autoscaling
Environment with Public and Private Resources in a
VPC
You can deploy an Elastic Beanstalk application in a load balancing, autoscaling environment in a VPC
that has both a public and private subnet. Use this configuration if you want Elastic Beanstalk to assign
private IP addresses to your Amazon EC2 instances. In this configuration, the Amazon EC2 instances in
the private subnet require a load balancer and a network address translation (NAT) gateway in the public
subnet. The load balancer routes inbound traffic from the Internet to the Amazon EC2 instances. You
need to create a NAT gateway to route outbound traffic from the Amazon EC2 instances to the Internet.
Your infrastructure will look similar to the following diagram.
Elastic Beanstalk and VPC Topology
Note
In this configuration, you cannot connect to your instances remotely because the instances
are located in a private subnet. If you need to be able to connect to your instances, and your
instances must be in a private subnet, you must implement a bastion host as described in
Example: Launching an Elastic Beanstalk Application in a VPC with Bastion Hosts (p. 418).
To deploy an Elastic Beanstalk application inside a VPC using a NAT gateway, you need to complete the
following:
Topics
• Create a VPC with a Public and Private Subnet (p. 414)
• Create a Security Group for Your Instances (p. 415)
• Deploy to Elastic Beanstalk (p. 416)
Create a VPC with a Public and Private Subnet
You can use the Amazon VPC console to create a VPC.
To create a VPC
1.
Sign in to the Amazon VPC console.
2.
In the navigation pane, choose VPC Dashboard. Then choose Start VPC Wizard.
3.
Choose VPC with Public and Private Subnets and then choose Select.
4.
Your Elastic Load Balancing load balancer and your Amazon EC2 instances must be in the same
Availability Zone so they can communicate with each other. Choose the same Availability Zone from
each Availability Zone list.
API Version 2010-12-01
414
AWS Elastic Beanstalk Developer Guide
Load-Balancing Environment with Private Instances
5.
Choose an Elastic IP address for your NAT gateway.
6.
Choose Create VPC.
The wizard begins to create your VPC, subnets, and Internet gateway. It also updates the main route
table and creates a custom route table. Finally, the wizard creates a NAT gateway in the public
subnet.
Note
You can choose to launch a NAT instance in the public subnet instead of a NAT gateway. For
more information, see Scenario 2: VPC with Public and Private Subnets (NAT) in the Amazon
VPC User Guide.
7.
After the VPC is successfully created, you get a VPC ID. You need this value for this for the next step.
To view your VPC ID, choose Your VPCs in the left pane of the Amazon VPC console.
Create a Security Group for Your Instances
You can optionally create a security group for your Elastic Beanstalk instances. You can add rules to the
security group to control inbound and outbound traffic for the instances associated with that security
group. To create a security group, perform the following procedure. You should give this security group a
meaningful name, such as Instance Group, that will allow you to easily identify the security group later.
For more information about security groups, see Security Groups for Your VPC in the Amazon VPC User
Guide.
To create a new security group
1.
Open the Amazon VPC console at https://console.aws.amazon.com/vpc/.
2.
In the navigation pane, choose Security Groups.
3.
Choose Create Security Group.
API Version 2010-12-01
415
AWS Elastic Beanstalk Developer Guide
Load-Balancing Environment with Private Instances
4.
In the Create Security Group dialog box, enter the following and choose Yes, Create.
Name tag (Optional)
Enter a name tag for the security group.
Group name
Enter the name of the security group.
Description
Enter a description for the security group.
VPC
Select your VPC.
The security group is created and appears on the Security Groups page. Notice that it has an ID (e.g.,
sg-xxxxxxxx). You might have to turn on the Group ID column by clicking Show/Hide in the top
right corner of the page.
Deploy to Elastic Beanstalk
After you set up your VPC, you can create your environment inside your VPC and deploy your application
to Elastic Beanstalk. You can do this using the Elastic Beanstalk console, or you can use the AWS toolkits,
AWS CLI, EB CLI, or Elastic Beanstalk API. If you use the Elastic Beanstalk console, you just need to upload
your .war or .zip file and select the VPC settings inside the wizard. Elastic Beanstalk then creates your
environment inside your VPC and deploys your application. Alternatively, you can use the AWS toolkits,
AWS CLI, EB CLI, or Elastic Beanstalk API to deploy your application. To do this, you need to define
your VPC option settings in a configuration file and deploy this file with your source bundle. This topic
provides instructions for both methods.
Topics
• Deploying with the Elastic Beanstalk Console (p. 416)
• Deploying with the AWS Toolkits, AWS CLI, EB CLI, or Elastic Beanstalk API (p. 417)
Deploying with the Elastic Beanstalk Console
The Elastic Beanstalk console walks you through creating your new environment inside your VPC.
You need to provide a .war file (for Java applications) or a .zip file (for all other applications). In the
VPC Configuration page of the Elastic Beanstalk environment wizard, you must make the following
selections:
VPC
Select your VPC
VPC security group
Select the instance security group you created above.
ELB visibility
Select External if your load balancer should be publicly available, or select Internal if the load
balancer should only be available within your VPC.
API Version 2010-12-01
416
AWS Elastic Beanstalk Developer Guide
Load-Balancing Environment with Private Instances
Select the subnets for your load balancer and EC2 instances. Make sure you select the public subnet for
the load balancer, and the private subnet for your Amazon EC2 instances. By default, the VPC creation
wizard creates the public subnet in 10.0.0.0/24 and the private subnet in 10.0.1.0/24.
You can view your subnet IDs by choosing Subnets in the Amazon VPC console.
Deploying with the AWS Toolkits, AWS CLI, EB CLI, or Elastic Beanstalk API
When deploying your application to Elastic Beanstalk using the AWS toolkits, EB CLI, the AWS CLI, or API,
you can specify your VPC option settings in a file and deploy it with your source bundle. See Advanced
Environment Customization with Configuration Files (.ebextensions) (p. 197) for more information.
When you create your configuration file with your option settings, you need to specify the following
configuration options:
aws:autoscaling:launchconfiguration (p. 162) Namespace:
EC2KeyName
The name of the Amazon EC2 key pair to apply to the instances.
InstanceType
The instance type used to run your application in the environment.
The instance types available depend on platform, solution stack (configuration) and
region. To get a list of available instance types for your solution stack of choice, use the
DescribeConfigurationOptions action in the API, describe-configuration-options command in the
AWS CLI.
SecurityGroups
The identifier(s) of the security group(s) to apply to the instances. In this example, this will be the
identifier of the security group you created in Create a Security Group for Your Instances (p. 415). If
you did not create a security group, you can use the default security group for your VPC.
You can specify multiple identifiers by separating them with a comma.
aws:ec2:vpc (p. 170) Namespace:
VPCId
The identifier of your VPC.
API Version 2010-12-01
417
AWS Elastic Beanstalk Developer Guide
Bastion Hosts
Subnets
The identifier(s) of the subnet(s) to launch the instances in. In this example, this is the ID of the
private subnet.
You can specify multiple identifiers by separating them with a comma.
ELBSubnets
The identifier(s) of the subnet(s) for the load balancer. In this example, this is the ID of the public
subnet.
You can specify multiple identifiers by separating them with a comma.
ELBScheme (Optional)
Specify internal if you want to create an internal load balancer inside your VPC so that your Elastic
Beanstalk application cannot be accessed from outside your VPC.
DBSubnets (Optional)
Contains the identifiers of the Amazon RDS DB subnets. This is only used if you want to add an
Amazon RDS DB Instance as part of your application. For an example, see Example: Launching an
Elastic Beanstalk in a VPC with Amazon RDS (p. 421).
Note
When using DBSubnets, you need to create additional subnets in your VPC to cover all the
Availability Zones in the region.
The following is an example of the option settings you could set when deploying your Elastic Beanstalk
application inside a VPC.
option_settings:
aws:autoscaling:launchconfiguration:
EC2KeyName: "ec2_key_name"
InstanceType: "instance_type"
SecurityGroups: "security_group_id, etc"
aws:ec2:vpc:
VPCId: "vpc_id"
Subnets: "instance_subnet, etc"
ELBSubnets: "elb_subnet, etc"
Example: Launching an Elastic Beanstalk Application
in a VPC with Bastion Hosts
If your Amazon EC2 instances are located inside a private subnet, you will not be able to connect to them
remotely. To connect to your instances, you can set up bastion servers in the public subnet to act as
proxies. For example, you can set up SSH port forwarders or RDP gateways in the public subnet to proxy
the traffic going to your database servers from your own network. This section provides an example
of how to create a VPC with a private and public subnet. The instances are located inside the private
subnet, and the bastion host, NAT gateway, and load balancer are located inside the public subnet. Your
infrastructure will look similar to the following diagram:
API Version 2010-12-01
418
AWS Elastic Beanstalk Developer Guide
Bastion Hosts
To deploy an Elastic Beanstalk application inside a VPC using a bastion host, you need to complete the
following:
Topics
• Create a VPC with a Public and Private Subnet (p. 419)
• Create and Configure the Bastion Host Security Group (p. 419)
• Update the Instance Security Group (p. 421)
• Create a Bastion Host (p. 421)
Create a VPC with a Public and Private Subnet
Complete all of the procedures in Example: Launching a Load-Balancing, Autoscaling Environment
with Public and Private Resources in a VPC (p. 414), including deployment of your application. When
deploying the application, you must specify an Amazon EC2 key pair for the instances so you can connect
to them remotely. For more information about how to specify the instance key pair, see Configuring the
EC2 Instances in your Elastic Beanstalk Environment (p. 247).
Create and Configure the Bastion Host Security Group
Create a security group for the bastion host, and add rules that allow inbound SSH traffic from the
Internet, and outbound SSH traffic to the private subnet that contains the Amazon EC2 instances.
API Version 2010-12-01
419
AWS Elastic Beanstalk Developer Guide
Bastion Hosts
1.
Create the bastion host security group.
To create a new security group
1.
Open the Amazon VPC console at https://console.aws.amazon.com/vpc/.
2.
In the navigation pane, choose Security Groups.
3.
Choose Create Security Group.
4.
In the Create Security Group dialog box, enter the following and choose Yes, Create.
Name tag (Optional)
Enter a name tag for the security group.
Group name
Enter the name of the security group.
Description
Enter a description for the security group.
VPC
Select your VPC.
The security group is created and appears on the Security Groups page. Notice that it has an ID
(e.g., sg-xxxxxxxx). You might have to turn on the Group ID column by clicking Show/Hide in
the top right corner of the page.
2.
Configure the bastion host security group.
To update the security group for the bastion host
1.
In the list of security groups, select the check box for the security group you just created for
your bastion host.
2.
On the Inbound tab, choose Edit.
3.
If needed, choose Add another rule.
4.
If your bastion host is a Linux instance, under Type, select SSH.
If your bastion host is a Windows instance, under Type, select RDP.
5.
Enter the desired source CIDR range in the Source field and choose Save.
API Version 2010-12-01
420
AWS Elastic Beanstalk Developer Guide
Amazon RDS
Update the Instance Security Group
By default, the security group you created for your instances does not allow incoming traffic. While
Elastic Beanstalk will modify the default group for the instances to allow SSH traffic, you must modify
your custom instance security group to allow RDP traffic if your instances are Windows instances.
To update the instance security group for RDP
1.
In the list of security groups, select the check box for the instance security group.
2.
On the Inbound tab, choose Edit.
3.
If needed, choose Add another rule.
4.
Enter the following values, and choose Save.
Type
RDP
Protocol
TCP
Port Range
3389
Source
Enter the ID of the bastion host security group (e.g., sg-8a6f71e8) and choose Save.
Create a Bastion Host
To create a bastion host, you launch an Amazon EC2 instance in your public subnet that will act as the
bastion host.
For more information about setting up a bastion host for Windows instances in the private subnet, see
Controlling Network Access to EC2 Instances Using a Bastion Server .
For more information about setting up a bastion host for Linux instances in the private subnet, see
Securely Connect to Linux Instances Running in a Private Amazon VPC .
Example: Launching an Elastic Beanstalk in a VPC
with Amazon RDS
This topic walks you through deploying an Elastic Beanstalk application with Amazon RDS in a VPC using
a NAT gateway. Your infrastructure will look similar to the following diagram:
API Version 2010-12-01
421
AWS Elastic Beanstalk Developer Guide
Amazon RDS
Note
If you haven't used a DB instance with your application before, try adding one to a test
environment (p. 260), and connecting to an external DB instance (p. 398) before adding VPC
configuration to the mix.
To deploy an Elastic Beanstalk application with Amazon RDS inside a VPC using a NAT gateway, you need
to complete the following:
Topics
• Create a VPC with a Public and Private Subnet (p. 422)
• Create a DB Subnet Group (p. 424)
• Deploy to Elastic Beanstalk (p. 424)
Create a VPC with a Public and Private Subnet
You can use the Amazon VPC console to create a VPC.
To create a VPC
1.
Sign in to the Amazon VPC console.
2.
In the navigation pane, choose VPC Dashboard. Then choose Start VPC Wizard.
API Version 2010-12-01
422
AWS Elastic Beanstalk Developer Guide
Amazon RDS
3.
Choose VPC with Public and Private Subnets and then choose Select.
4.
Your Elastic Load Balancing load balancer and your Amazon EC2 instances must be in the same
Availability Zone so they can communicate with each other. Choose the same Availability Zone from
each Availability Zone list.
5.
Choose an Elastic IP address for your NAT gateway.
6.
Choose Create VPC.
The wizard begins to create your VPC, subnets, and Internet gateway. It also updates the main route
table and creates a custom route table. Finally, the wizard creates a NAT gateway in the public
subnet.
Note
You can choose to launch a NAT instance in the public subnet instead of a NAT gateway. For
more information, see Scenario 2: VPC with Public and Private Subnets (NAT) in the Amazon
VPC User Guide.
7.
After the VPC is successfully created, you get a VPC ID. You need this value for this for the next step.
To view your VPC ID, choose Your VPCs in the left pane of the Amazon VPC console.
API Version 2010-12-01
423
AWS Elastic Beanstalk Developer Guide
Amazon RDS
Create a DB Subnet Group
A DB Subnet Group for a VPC is a collection of subnets (typically private) that you may want to designate
for your back-end RDS DB Instances. Each DB Subnet Group should have at least one subnet for every
Availability Zone in a given region.
Create a DB subnet group
1.
Open the Amazon RDS console at https://console.aws.amazon.com/rds/.
2.
In the navigation pane, click Subnet Groups.
3.
Click Create DB Subnet Group.
4.
Click Name, and then type the name of your DB Subnet Group.
5.
Click Description, and then describe your DB Subnet Group.
6.
Next to VPC ID, select the ID of the VPC that you created.
7.
Click the add all the subnets link in the Add Subnet(s) to this Subnet Group section.
8.
When you are finished, click Yes, Create.
9.
In the confirmation window, click Close.
Your new DB Subnet Group appears in the DB Subnet Groups list of the RDS console. You can click it
to see details, such as all of the subnets associated with this group, in the details pane at the bottom
of the window.
Deploy to Elastic Beanstalk
After you set up your VPC, you can create your environment inside your VPC and deploy your application
to Elastic Beanstalk. You can do this using the Elastic Beanstalk console, or you can use the AWS toolkits,
AWS CLI, EB CLI, or Elastic Beanstalk API. If you use the Elastic Beanstalk console, you just need to upload
API Version 2010-12-01
424
AWS Elastic Beanstalk Developer Guide
Amazon RDS
your .war or .zip file and select the VPC settings inside the wizard. Elastic Beanstalk then creates your
environment inside your VPC and deploys your application. Alternatively, you can use the AWS toolkits,
AWS CLI, EB CLI, or Elastic Beanstalk API to deploy your application. To do this, you need to define
your VPC option settings in a configuration file and deploy this file with your source bundle. This topic
provides instructions for both methods.
Deploying with the Elastic Beanstalk Console
The Elastic Beanstalk console walks you through creating your new environment inside your VPC.
You need to provide a .war file (for Java applications) or a .zip file (for all other applications). In the
VPC Configuration page of the Elastic Beanstalk environment wizard, you must make the following
selections:
VPC
Select your VPC
VPC security group
Select the instance security group you created above.
ELB visibility
Select External if your load balancer should be publicly available, or select Internal if the load
balancer should only be available within your VPC.
Select the subnets for your load balancer and EC2 instances. Make sure you select the public subnet for
the load balancer, and the private subnet for your Amazon EC2 instances. By default, the VPC creation
wizard creates the public subnet in 10.0.0.0/24 and the private subnet in 10.0.1.0/24.
You can view your subnet IDs by choosing Subnets in the Amazon VPC console.
Deploying with the AWS Toolkits, Eb, CLI, or API
When deploying your application to Elastic Beanstalk using the AWS toolkits, EB CLI, the AWS CLI, or API,
you can specify your VPC option settings in a file and deploy it with your source bundle. See Advanced
Environment Customization with Configuration Files (.ebextensions) (p. 197) for more information.
When you update the option settings, you will need to specify at least the following:
• VPCId–Contains the ID of the VPC.
API Version 2010-12-01
425
AWS Elastic Beanstalk Developer Guide
Amazon RDS
• Subnets–Contains the ID of the Auto Scaling group subnet. In this example, this is the ID of the private
subnet.
• ELBSubnets–Contains the ID of the subnet for the elastic load balancer. In this example, this is the ID
of the public subnet.
• SecurityGroups–Contains the ID of the security groups.
• DBSubnets–Contains the ID of the DB subnets.
Note
When using DBSubnets, you need to create additional subnets in your VPC to cover all the
Availability Zones in the region.
Optionally, you can also specify the following information:
• ELBScheme — Specify internal if you want to create an internal load balancer inside your VPC so that
your Elastic Beanstalk application cannot be accessed from outside your VPC.
The following is an example of the option settings you could use when deploying your Elastic Beanstalk
application inside a VPC. For more information about VPC option settings (including examples for how
to specify them, default values, and valid values), see the aws:ec2:vpc namespace table in Configuration
Options (p. 145).
option_settings:
- namespace: aws:autoscaling:launchconfiguration
option_name: EC2KeyName
value: ec2keypair
- namespace: aws:ec2:vpc
option_name: VPCId
value: vpc-170647c
- namespace: aws:ec2:vpc
option_name: Subnets
value: subnet-4f195024
- namespace: aws:ec2:vpc
option_name: ELBSubnets
value: subnet-fe064f95
- namespace: aws:ec2:vpc
option_name: DBSubnets
value: subnet-fg148g78
- namespace: aws:autoscaling:launchconfiguration
option_name: InstanceType
value: m1.small
- namespace: aws:autoscaling:launchconfiguration
option_name: SecurityGroups
value: sg-7f1ef110
Note
When using DBSubnets, make sure you have subnets in your VPC to cover all the Availability
Zones in the region.
API Version 2010-12-01
426
AWS Elastic Beanstalk Developer Guide
Load-Balancing Environment with Public Instances
Example: Launching a Load-Balancing, Autoscaling
Environment with Public Instances in a VPC
You can deploy an Elastic Beanstalk application in a load balancing, autoscaling environment in a single
public subnet. Use this configuration if you have a single public subnet without any private resources
associated with your Amazon EC2 instances. In this configuration, Elastic Beanstalk assigns public IP
addresses to the Amazon EC2 instances so that each can directly access the Internet through the VPC
Internet gateway. You do not need to create a network address translation (NAT) configuration in your
VPC.
To deploy an Elastic Beanstalk application in a load balancing, autoscaling environment in a single public
subnet, you need to complete the following:
Topics
• Create a VPC with a Public Subnet (p. 427)
• Deploy to Elastic Beanstalk (p. 429)
Create a VPC with a Public Subnet
To create a VPC
1.
Sign in to the AWS Management Console and open the Amazon VPC console at https://
console.aws.amazon.com/vpc/.
2.
In the navigation pane, choose VPC Dashboard and then choose Start VPC Wizard.
3.
Select VPC with a Single Public Subnet and then choose Select.
API Version 2010-12-01
427
AWS Elastic Beanstalk Developer Guide
Load-Balancing Environment with Public Instances
A confirmation page shows the CIDR blocks used for the VPC and subnet. The page also shows the
subnet and the associated Availability Zone.
4.
Choose Create VPC.
AWS creates your VPC, subnet, Internet gateway, and route table. Choose OK to exit the wizard.
After AWS successfully creates the VPC, it assigns the VPC a VPC ID. You will need this for this for the
next step. To view your VPC ID, choose Your VPCs in the left pane of the Amazon VPC console.
API Version 2010-12-01
428
AWS Elastic Beanstalk Developer Guide
Load-Balancing Environment with Public Instances
Deploy to Elastic Beanstalk
After you set up your VPC, you can create your environment inside your VPC and deploy your application
to Elastic Beanstalk. You can do this using the Elastic Beanstalk console, or you can use the AWS toolkits,
AWS CLI, EB CLI, or Elastic Beanstalk API. If you use the Elastic Beanstalk console, you just need to upload
your .war or .zip file and select the VPC settings inside the wizard. Elastic Beanstalk then creates your
environment inside your VPC and deploys your application. Alternatively, you can use the AWS toolkits,
AWS CLI, EB CLI, or Elastic Beanstalk API to deploy your application. To do this, you need to define
your VPC option settings in a configuration file and deploy this file with your source bundle. This topic
provides instructions for both methods.
Topics
• Deploying with the Elastic Beanstalk Console (p. 429)
• Deploying with the AWS Toolkits, AWS CLI, EB CLI, or Elastic Beanstalk API (p. 429)
Deploying with the Elastic Beanstalk Console
When you create an Elastic Beanstalk application or launch an environment, the Elastic Beanstalk console
walks you through creating your environment inside a VPC. For more information, see Managing and
Configuring AWS Elastic Beanstalk Applications (p. 47).
You'll need to select the VPC ID and subnet ID for your instance. By default, VPC creates a public subnet
using 10.0.0.0/24. You can view your subnet ID by clicking Subnets in the Amazon VPC console.
Deploying with the AWS Toolkits, AWS CLI, EB CLI, or Elastic Beanstalk API
When deploying your application to Elastic Beanstalk using the AWS toolkits, EB CLI, the AWS CLI, or API,
you can specify your VPC option settings in a file and deploy it with your source bundle. See Advanced
Environment Customization with Configuration Files (.ebextensions) (p. 197) for more information.
When you create your configuration file with your option settings, you need to specify the following
configuration options:
aws:ec2:vpc (p. 170) Namespace:
VPCId
The identifier of your VPC.
Subnets
The identifier(s) of the subnet(s) to launch the instances in.
You can specify multiple identifiers by separating them with a comma.
AssociatePublicIpAddress
Specifies whether to launch instances in your VPC with public IP addresses. Instances with public IP
addresses do not require a NAT device to communicate with the Internet. You must set the value to
true if you want to include your load balancer and instances in a single public subnet.
API Version 2010-12-01
429
AWS Elastic Beanstalk Developer Guide
Load-Balancing Environment with Public Instances
The following is an example of the option settings you could set when deploying your Elastic Beanstalk
application inside a VPC.
option_settings:
aws:ec2:vpc:
VPCId: "vpd_id"
Subnets: "instance_subnet, etc"
AssociatePublicIpAddress: "true"
API Version 2010-12-01
430
AWS Elastic Beanstalk Developer Guide
Creating a Project Folder
Configuring your development
environment for use with AWS
Elastic Beanstalk
Topics
• Creating a Project Folder (p. 431)
• Setting Up Source Control (p. 432)
• Configuring a Remote Repository (p. 432)
• Installing the EB CLI (p. 432)
• Installing the AWS CLI (p. 433)
Creating a Project Folder
Create a folder for your project. You can store the folder anywhere on your local disk as long as you have
permission to read from and write to it. Creating a folder in your user folder is acceptable. If you plan on
working on multiple applications, create your project folders inside another folder named something like
workspace or projects to keep everything organized:
workspace/
|-- my-first-app
`-- my-second-app
The contents of your project folder will vary depending on the web container or framework that your
application uses.
Note
Avoid folders and paths with single-quote (') or double-quote (") characters in the folder name
or any path element. Some Elastic Beanstalk commands fail when run within a folder with either
character in the name.
API Version 2010-12-01
431
AWS Elastic Beanstalk Developer Guide
Setting Up Source Control
Setting Up Source Control
Set up source control to protect yourself from accidentally deleting files or code in your project folder,
and for a way to revert changes that break your project.
If you don't have a source control system, consider Git, a free and easy-to-use option, and it integrates
well with the Elastic Beanstalk Command Line Interface (CLI). Visit the Git homepage to install Git.
Follow the instructions on the Git website to install and configure Git, and then run git init in your
project folder to set up a local repository:
~/workspace/my-first-app$ git init
Initialized empty Git repository in /home/local/username/workspace/my-first-app/.git/
As you add content to your project folder and update content, commit the changes to your Git
repository:
~/workspace/my-first-app$ git add default.jsp
~/workspace/my-first-app$ git commit -m "add default JSP"
Every time you commit, you create a snapshot of your project that you can restore later if anything goes
wrong. For much more information on Git commands and workflows, see the Git documentation.
Configuring a Remote Repository
What if your hard drive crashes, or you want to work on your project on a different computer? To back up
your source code online and access it from any computer, configure a remote repository to which you can
push your commits.
AWS CodeCommit lets you create a private repository in the AWS cloud, and is free in the AWS Free Tier
for up to five AWS Identity and Access Management (IAM) users in your account. For pricing details, see
AWS CodeCommit Pricing.
Visit the AWS CodeCommit User Guide for instructions on getting set up.
GitHub is another popular option for storing your project code online. It lets you create a public online
repository for free and also supports private repositories for a monthly charge. Sign up for GitHub at
github.com.
After you've created a remote repository for your project, attach it to your local repository with git
remote add:
~/workspace/my-first-app$ git remote add origin ssh://git-codecommit.useast-2.amazonaws.com/v1/repos/my-repo
Installing the EB CLI
Use the EB CLI (p. 434) to manage your Elastic Beanstalk environments and monitor health from the
command line. See Install the EB CLI (p. 435) for installation instructions.
By default, the EB CLI packages everything in your project folder and uploads it to Elastic Beanstalk as
a source bundle. When you use Git and the EB CLI together, you can prevent built class files from being
committed to source with .gitignore and prevent source files from being deployed with .ebignore.
API Version 2010-12-01
432
AWS Elastic Beanstalk Developer Guide
Installing the AWS CLI
You can also configure the EB CLI to deploy a build artifact (p. 445) (a WAR or ZIP file) instead of the
contents of your project folder.
Installing the AWS CLI
The AWS Command Line Interface (AWS CLI) is a unified client for AWS services that provides commands
for all public API operations. These commands are lower level than those provided by the EB CLI, so
it often takes more commands to do an operation with the AWS CLI. On the other hand, the AWS
CLI allows you to work with any application or environment running in your account without setting
up a repository on your local machine. Use the AWS CLI to create scripts that simplify or automate
operational tasks.
For more information about supported services and to download the AWS Command Line Interface, see
AWS Command Line Interface.
API Version 2010-12-01
433
AWS Elastic Beanstalk Developer Guide
The Elastic Beanstalk Command Line
Interface (EB CLI)
The EB CLI is a command line interface for Elastic Beanstalk that provides interactive commands that
simplify creating, updating and monitoring environments from a local repository. Use the EB CLI as part
of your everyday development and testing cycle as an alternative to the AWS Management Console.
Note
The current version of the EB CLI has a different base set of commands than versions prior to
version 3.0. See EB CLI 2.6 (Deprecated) (p. 508) if you use an older version.
Once you've installed the EB CLI and configured a repository, you can create environments with a single
command:
~/my-app$ eb create my-env
Previously, Elastic Beanstalk supported a separate CLI that provided direct access to API operations called
the Elastic Beanstalk API CLI (p. 535). This has been replaced with the AWS CLI (p. 433), which provides
the same functionality but for all AWS services' APIs.
With the AWS CLI you have direct access to the Elastic Beanstalk API. The AWS CLI is great for scripting,
but is not as easy to use from the command line because of the number of commands that you need to
run and the number of parameters on each command. For example, creating an environment requires a
series of commands:
~$ aws elasticbeanstalk check-dns-availability --cname-prefix my-cname
~$ aws elasticbeanstalk create-application-version --application-name my-application -version-label v1 --source-bundle S3Bucket=my-bucket,S3Key=php-proxy-sample.zip
~$ aws elasticbeanstalk create-environment --cname-prefix my-cname --application-name myapp --version-label v1 --environment-name my-env --solution-stack-name "64bit Amazon Linux
2015.03 v2.0.0 running Ruby 2.2 (Passenger Standalone)"
For information about installing the EB CLI, configuring a repository, and working with environments, see
the following topics:
Topics
• Install the Elastic Beanstalk Command Line Interface (EB CLI) (p. 435)
API Version 2010-12-01
434
AWS Elastic Beanstalk Developer Guide
Install the EB CLI
• Configure the EB CLI (p. 443)
• Managing Elastic Beanstalk Environments with the EB CLI (p. 446)
• Using the EB CLI with AWS CodeBuild (p. 451)
• Using the EB CLI with Git (p. 451)
• Using the EB CLI with AWS CodeCommit (p. 453)
• Using the EB CLI to Monitor Environment Health (p. 457)
• Managing Multiple AWS Elastic Beanstalk Environments as a Group with the EB CLI (p. 461)
• Troubleshooting issues with the EB CLI (p. 463)
• EB CLI Command Reference (p. 465)
• EB CLI 2.6 (Deprecated) (p. 508)
• Elastic Beanstalk API Command Line Interface (deprecated) (p. 535)
Install the Elastic Beanstalk Command Line
Interface (EB CLI)
The Elastic Beanstalk Command Line Interface (EB CLI) is a command line client that you can use to
create, configure, and manage Elastic Beanstalk environments. The EB CLI is developed in Python and
requires Python version 2.7, version 3.4, or newer.
Note
Amazon Linux comes with Python 2.7 and pip starting with version 2015.03.
The primary distribution method for the EB CLI on Linux, Windows, and macOS is pip, a package
manager for Python that provides an easy way to install, upgrade, and remove Python packages and
their dependencies. For macOS, you can also get the latest version of the EB CLI with Homebrew.
If you already have pip and a supported version of Python, you can install the EB CLI with the following
command:
$ pip install awsebcli --upgrade --user
The --upgrade option tells pip to upgrade any requirements that are already installed. The --user
option tells pip to install the program to a subdirectory of your user directory to avoid modifying
libraries used by your operating sytem.
Note
If you encounter issues when you attempt to install the EB CLI with pip, you can install the EB
CLI in a virtual environment (p. 442) to isolate the tool and its dependencies, or use a different
version of Python than you normally do.
After you install the EB CLI, add the path to the executable file to your PATH variable:
Linux – ~/.local/bin
macOS – ~/Library/Python/3.4/bin
To modify your PATH variable (Linux, macOS, or Unix)
1.
Find your shell's profile script in your user folder. If you are not sure which shell you have, run echo
$SHELL.
$ ls -a ~
API Version 2010-12-01
435
AWS Elastic Beanstalk Developer Guide
Install the EB CLI
.
..
.bash_logout
.bash_profile
.bashrc
Desktop
Documents
Downloads
• Bash – .bash_profile, .profile, or .bash_login.
• Zsh – .zshrc
• Tcsh – .tcshrc, .cshrc or .login.
2.
Add an export command to your profile script. The following example adds the path represented by
LOCAL_PATH to the current PATH variable.
export PATH=LOCAL_PATH:$PATH
3.
Load the profile script described in the first step into your current session. The following example
loads the profile script represented by PROFILE_SCRIPT into your current session.
$ source ~/PROFILE_SCRIPT
Windows – %USERPROFILE%\AppData\Roaming\Python\Scripts
Python 3.5 on Windows – %USERPROFILE%\AppData\Roaming\Python\Python3.5\Scripts
Python 3.6 on Windows – %USERPROFILE%\AppData\Local\Programs\Python\Python36\Scripts
To modify your PATH variable (Windows)
1.
Press the Windows key and type environment variables.
2.
Choose Edit environment variables for your account.
3.
Choose PATH and then choose Edit.
4.
Add paths to the Variable value field, separated by semicolons. For example: C:\existing\path;C:
\new\path
5.
Choose OK twice to apply the new settings.
6.
Close any running command prompts and re-open.
Verify that the EB CLI installed correctly by running eb --version.
$ eb --version
EB CLI 3.7.8 (Python 3.4.3)
The EB CLI is updated regularly to add functionality that supports the latest Elastic Beanstalk features.
To update to the latest version of the EB CLI, run the installation command again.
$ pip install awsebcli --upgrade --user
If you need to uninstall the EB CLI, use pip uninstall.
$ pip uninstall awsebcli
If you don't have Python and pip, use the procedure for your operating system:
Topics
• Install Python, pip, and the EB CLI on Linux (p. 437)
• Install Python, pip, and the EB CLI on Windows (p. 439)
• Install the EB CLI on macOS (p. 441)
API Version 2010-12-01
436
AWS Elastic Beanstalk Developer Guide
Linux
• Install the EB CLI in a Virtual Environment (p. 442)
Install Python, pip, and the EB CLI on Linux
The EB CLI requires Python 2.7 or 3.4+. If your distribution did not come with Python, or came with an
older version, install Python before installing pip and the EB CLI.
To install Python 3.4 on Linux
1.
Check to see if Python is already installed:
$ python --version
Note
If your Linux distribution came with Python, you may need to install the Python developer
package in order to get the headers and libraries required to compile extensions and install
the EB CLI. Install the developer package (typically named python-dev or python-devel)
using your package manager.
2.
If Python 2.7 or later is not installed, install Python 3.4 with your distribution's package manager.
The command and package name varies:
• On Debian derivatives such as Ubuntu, use APT:
$ sudo apt-get install python3.4
• On Red Hat and derivatives, use yum:
$ sudo yum install python34
• On SUSE and derivatives, use zypper:
$ sudo zypper install python3-3.4.1
3.
Open a command prompt or shell and run the following command to verify that Python installed
correctly:
$ python3 --version
Python 3.4.3
Install pip by using the script provided by the Python Packaging Authority, and then install the EB CLI.
To install pip and the EB CLI
1.
Download the installation script from pypa.io:
$ curl -O https://bootstrap.pypa.io/get-pip.py
The script downloads and installs the latest version of pip and another required package named
setuptools.
2.
Run the script with Python:
$ python3 get-pip.py --user
Collecting pip
API Version 2010-12-01
437
AWS Elastic Beanstalk Developer Guide
Linux
Downloading pip-8.1.2-py2.py3-none-any.whl (1.2MB)
Collecting setuptools
Downloading setuptools-26.1.1-py2.py3-none-any.whl (464kB)
Collecting wheel
Downloading wheel-0.29.0-py2.py3-none-any.whl (66kB)
Installing collected packages: pip, setuptools, wheel
Successfully installed pip setuptools wheel
Invoking version Python 3 directly by using the python3 command instead of python ensures that
pip is installed in the proper location, even if an older system version of Python is present on your
system.
3.
Add the executable path to your PATH variable: ~/.local/bin
To modify your PATH variable (Linux, macOS, or Unix)
1.
Find your shell's profile script in your user folder. If you are not sure which shell you have, run
echo $SHELL.
$ ls -a ~
. .. .bash_logout
.bash_profile
.bashrc
Desktop
Documents
Downloads
• Bash – .bash_profile, .profile, or .bash_login.
• Zsh – .zshrc
• Tcsh – .tcshrc, .cshrc or .login.
2.
Add an export command to your profile script. The following example adds the path
represented by LOCAL_PATH to the current PATH variable.
export PATH=LOCAL_PATH:$PATH
3.
Load the profile script described in the first step into your current session. The following
example loads the profile script represented by PROFILE_SCRIPT into your current session.
$ source ~/PROFILE_SCRIPT
4.
Verify that pip is installed correctly.
$ pip --version
pip 8.1.2 from ~/.local/lib/python3.4/site-packages (python 3.4)
5.
Finally, use pip to install the EB CLI.
$ pip install awsebcli --upgrade --user
Collecting awsebcli
Downloading awsebcli-3.7.8.tar.gz (176kB)
Collecting pyyaml>=3.11 (from awsebcli)
Downloading PyYAML-3.12.tar.gz (253kB)
Collecting botocore>=1.0.1 (from awsebcli)
Downloading botocore-1.4.53-py2.py3-none-any.whl (2.6MB)s
Collecting cement==2.8.2 (from awsebcli)
Downloading cement-2.8.2.tar.gz (165kB)
Collecting colorama==0.3.7 (from awsebcli)
Downloading colorama-0.3.7-py2.py3-none-any.whl
Collecting pathspec==0.3.4 (from awsebcli)
Downloading pathspec-0.3.4.tar.gz
Requirement already satisfied (use --upgrade to upgrade): setuptools>=20.0 in ./.local/
lib/python3.4/site-packages (from awsebcli)
Collecting docopt<0.7,>=0.6.1 (from awsebcli)
Downloading docopt-0.6.2.tar.gz
API Version 2010-12-01
438
AWS Elastic Beanstalk Developer Guide
Windows
Collecting requests<=2.9.1,>=2.6.1 (from awsebcli)
Downloading requests-2.9.1-py2.py3-none-any.whl (501kB)
Collecting texttable<0.9,>=0.8.1 (from awsebcli)
Downloading texttable-0.8.4.tar.gz
Collecting websocket-client<1.0,>=0.11.0 (from awsebcli)
Downloading websocket_client-0.37.0.tar.gz (194kB)
Collecting docker-py<=1.7.2,>=1.1.0 (from awsebcli)
Downloading docker-py-1.7.2.tar.gz (68kB)
Collecting dockerpty<=0.4.1,>=0.3.2 (from awsebcli)
Downloading dockerpty-0.4.1.tar.gz
Collecting semantic_version==2.5.0 (from awsebcli)
Downloading semantic_version-2.5.0-py3-none-any.whl
Collecting blessed==1.9.5 (from awsebcli)
Downloading blessed-1.9.5-py2.py3-none-any.whl (77kB)
Collecting docutils>=0.10 (from botocore>=1.0.1->awsebcli)
Downloading docutils-0.12-py3-none-any.whl (508kB)
Collecting python-dateutil<3.0.0,>=2.1 (from botocore>=1.0.1->awsebcli)
Downloading python_dateutil-2.5.3-py2.py3-none-any.whl (201kB)
Collecting jmespath<1.0.0,>=0.7.1 (from botocore>=1.0.1->awsebcli)
Downloading jmespath-0.9.0-py2.py3-none-any.whl
Collecting six (from websocket-client<1.0,>=0.11.0->awsebcli)
Downloading six-1.10.0-py2.py3-none-any.whl
Collecting wcwidth>=0.1.0 (from blessed==1.9.5->awsebcli)
Downloading wcwidth-0.1.7-py2.py3-none-any.whl
Building wheels for collected packages: awsebcli, pyyaml, cement, pathspec, docopt,
texttable, websocket-client, docker-py, dockerpty
Running setup.py bdist_wheel for awsebcli ... done
Running setup.py bdist_wheel for pyyaml ... done
Running setup.py bdist_wheel for cement ... done
Running setup.py bdist_wheel for pathspec ... done
Running setup.py bdist_wheel for docopt ... done
Running setup.py bdist_wheel for texttable ... done
Running setup.py bdist_wheel for websocket-client ... done
Running setup.py bdist_wheel for docker-py ... done
Running setup.py bdist_wheel for dockerpty ... done
Successfully built awsebcli pyyaml cement pathspec docopt texttable websocket-client
docker-py dockerpty
Installing collected packages: pyyaml, docutils, six, python-dateutil, jmespath,
botocore, cement, colorama, pathspec, docopt, requests, texttable, websocket-client,
docker-py, dockerpty, semantic-version, wcwidth, blessed, awsebcli
Successfully installed awsebcli-3.7.8 blessed-1.9.5 botocore-1.4.53 cement-2.8.2
colorama-0.3.7 docker-py-1.7.2 dockerpty-0.4.1 docopt-0.6.2 docutils-0.12
jmespath-0.9.0 pathspec-0.3.4 python-dateutil-2.5.3 pyyaml-3.12 requests-2.9.1
semantic-version-2.5.0 six-1.10.0 texttable-0.8.4 wcwidth-0.1.7 websocketclient-0.37.0
6.
Verify that the EB CLI installed correctly.
$ eb --version
EB CLI 3.7.8 (Python 3.4.3)
To upgrade to the latest version, run the installation command again:
$ pip install awsebcli --upgrade --user
Install Python, pip, and the EB CLI on Windows
The Python Software Foundation provides installers for Windows that include pip.
API Version 2010-12-01
439
AWS Elastic Beanstalk Developer Guide
Windows
To install Python 3.6 and pip (Windows)
1.
Download the Python 3.6 Windows x86-64 executable installer from the downloads page of
Python.org.
2.
Run the installer.
3.
Choose Add Python 3.6 to PATH.
4.
Choose Install Now.
The installer installs Python in your user folder and adds its executable directories to your user path.
To install the AWS CLI with pip (Windows)
1.
Open the Windows Command Processor from the Start menu.
2.
Verify that Python and pip are both installed correctly with the following commands:
C:\Windows\System32> python --version
Python 3.6.2
C:\Windows\System32> pip --version
pip 9.0.1 from c:\users\myname\appdata\local\programs\python\python36\lib\site-packages
(python 3.6)
3.
Install the EB CLI using pip:
C:\Windows\System32> pip install awsebcli --upgrade --user
Collecting awsebcli
Downloading awsebcli-3.2.2.tar.gz (828kB)
Collecting pyyaml>=3.11 (from awsebcli)
Downloading PyYAML-3.11.tar.gz (248kB)
Collecting cement==2.4 (from awsebcli)
Downloading cement-2.4.0.tar.gz (129kB)
Collecting python-dateutil<3.0.0,>=2.1 (from awsebcli)
Downloading python_dateutil-2.4.2-py2.py3-none-any.whl (188kB)
Collecting jmespath>=0.6.1 (from awsebcli)
Downloading jmespath-0.6.2.tar.gz
Collecting six>=1.5 (from python-dateutil<3.0.0,>=2.1->awsebcli)
Downloading six-1.9.0-py2.py3-none-any.whl
Installing collected packages: six, jmespath, python-dateutil, cement, pyyaml, awsebcli
Running setup.py install for jmespath
Running setup.py install for cement
Running setup.py install for pyyaml
checking if libyaml is compilable
Microsoft Visual C++ 10.0 is required (Unable to find vcvarsall.bat).
skipping build_ext
Running setup.py install for awsebcli
Installing eb-script.py script to C:\Python34\Scripts
Installing eb.exe script to C:\Python34\Scripts
Installing eb.exe.manifest script to C:\Python34\Scripts
Successfully installed awsebcli-3.2.2 cement-2.4.0 jmespath-0.6.2 python-dateutil-2.4.2
pyyaml-3.11 six-1.9.0
4.
Verify that the EB CLI is installed correctly:
C:\Windows\System32> eb --version
EB CLI 3.2.2 (Python 3.4.3)
To upgrade to the latest version, run the installation command again:
API Version 2010-12-01
440
AWS Elastic Beanstalk Developer Guide
macOS
C:\Windows\System32> pip install awsebcli --upgrade --user
Install the EB CLI on macOS
If you use the Homebrew package manager, you can install the EB CLI with the brew command. You can
also install Python and pip, and then use pip to install the EB CLI.
Install the EB CLI with Homebrew
If you have Homebrew, you can use it to install the EB CLI. The latest version of the EB CLI is typically
available from Homebrew a couple of days after it appears in pip.
To install the EB CLI with Homebrew
1.
Make sure you have the latest version of Homebrew
$ brew update
2.
Run brew install awsebcli:
$ brew install awsebcli
3.
Verify that the EB CLI is installed correctly:
$ eb --version
EB CLI 3.2.2 (Python 3.4.3)
Install Python, pip, and the EB CLI on macOS
You can install the latest version of Python and pip and then use them to install the EB CLI.
To install the EB CLI on macOS
1.
Download and install Python 3.4 from the downloads page of Python.org.
2.
Install pip with the script provided by the Python Packaging Authority.
$ curl -O https://bootstrap.pypa.io/get-pip.py
$ python3 get-pip.py --user
3.
Use pip to install the EB CLI.
$ pip3 install awsebcli --upgrade --user
4.
Add the path to the executable (~/Library/Python/3.4/bin) to your path variable:
To modify your PATH variable (Linux, macOS, or Unix)
1.
Find your shell's profile script in your user folder. If you are not sure which shell you have, run
echo $SHELL.
$ ls -a ~
. .. .bash_logout
.bash_profile
.bashrc
API Version 2010-12-01
441
Desktop
Documents
Downloads
AWS Elastic Beanstalk Developer Guide
Virtualenv
• Bash – .bash_profile, .profile, or .bash_login.
• Zsh – .zshrc
• Tcsh – .tcshrc, .cshrc or .login.
2.
Add an export command to your profile script. The following example adds the path
represented by LOCAL_PATH to the current PATH variable.
export PATH=LOCAL_PATH:$PATH
3.
Load the profile script described in the first step into your current session. The following
example loads the profile script represented by PROFILE_SCRIPT into your current session.
$ source ~/PROFILE_SCRIPT
5.
Verify that the EB CLI is installed correctly.
$ eb --version
EB CLI 3.7.8 (Python 3.4.1)
To upgrade to the latest version, run the installation command again:
$ pip3 install awsebcli --upgrade --user
Install the EB CLI in a Virtual Environment
You can avoid requirement version conflicts with other pip packages by installing the EB CLI in a virtual
environment.
To install the EB CLI in a virtual environment
1.
Install virtualenv with pip.
$ pip install --user virtualenv
2.
Create a virtual environment.
$ virtualenv ~/eb-ve
You can use the -p option to use a Python executable other than the default.
$ virtualenv -p /usr/bin/python3.4 ~/eb-ve
3.
Activate the virtual environment.
Linux, macOS, or Unix
$ source ~/eb-ve/bin/activate
Windows
$ %USERPROFILE%\eb-ve\Scripts\activate
4.
Install the EB CLI.
API Version 2010-12-01
442
AWS Elastic Beanstalk Developer Guide
Configure the EB CLI
(eb-ve)~$ pip install awsebcli --upgrade
5.
Verify that the EB CLI is installed correctly.
$ eb --version
EB CLI 3.7.8 (Python 3.4.1)
You can use the deactivate command to exit the virtual environment. Whenever you start a new session,
run the activation command again.
To upgrade to the latest version, run the installation command again:
(eb-ve)~$ pip install awsebcli --upgrade
Configure the EB CLI
After installing the EB CLI (p. 435), you are ready to configure your project folder with eb init.
Run eb init in your application's project directory to configure the EB CLI and your project.
The following example shows the configuration steps when running eb init for the first time in a
project folder named eb:
To initialize an EB CLI project
1.
First, the EB CLI prompts you to select a region. Type the number that corresponds to the region that
you would like to use and press Enter.
~/eb $ eb init
Select a default region
1) us-east-1 : US East (N. Virginia)
2) us-west-1 : US West (N. California)
3) us-west-2 : US West (Oregon)
4) eu-west-1 : EU (Ireland)
5) eu-central-1 : EU (Frankfurt)
6) ap-south-1 : Asia Pacific (Mumbai)
7) ap-southeast-1 : Asia Pacific (Singapore)
8) ap-southeast-2 : Asia Pacific (Sydney)
9) ap-northeast-1 : Asia Pacific (Tokyo)
10) ap-northeast-2 : Asia Pacific (Seoul)
11) sa-east-1 : South America (Sao Paulo)
12) cn-north-1 : China (Beijing)
13) us-east-2 : US East (Columbus)
14) ca-central-1 : Canada (Central)
15) eu-west-2 : EU (London)
(default is 3): 3
2.
Next, provide your access key and secret key so that the EB CLI can manage resources for you. Access
keys are created in the AWS Identity and Access Management management console. If you don't
have keys, see How Do I Get Security Credentials? in the Amazon Web Services General Reference.
You have not yet set up your credentials or your credentials are incorrect
You must provide your credentials.
(aws-access-id): AKIAJOUAASEXAMPLE
API Version 2010-12-01
443
AWS Elastic Beanstalk Developer Guide
Configure the EB CLI
(aws-secret-key): 5ZRIrtTM4ciIAvd4EXAMPLEDtm+PiPSzpoK
3.
An application in Elastic Beanstalk is a resource that contains a set of application versions (source),
environments, and saved configurations that are associated with a single web application. Each
time you deploy your source code to Elastic Beanstalk using the EB CLI, a new application version is
created and added to the list.
Select an application to use
1) [ Create new Application ]
(default is 1): 1
4.
The default application name is the name of the folder in which you run eb init. Enter any name
that describes your project.
Enter Application Name
(default is "eb"): eb
Application eb has been created.
5.
Select a platform that matches the language or framework that your web application is developed
in. If you haven't started developing an application yet, choose a platform that you are interested
in. You will see how to launch a sample application shortly, and you can always change this setting
later.
Select a platform.
1) Node.js
2) PHP
3) Python
4) Ruby
5) Tomcat
6) IIS
7) Docker
8) Multi-container Docker
9) GlassFish
10) Go
11) Java
(default is 1): 1
6.
Choose yes to assign an SSH key pair to the instances in your Elastic Beanstalk environment,
allowing you to connect directly to them for troubleshooting.
Do you want to set up SSH for your instances?
(y/n): y
7.
Choose an existing key pair or create a new one. To use eb init to create a new key pair, you must
have ssh-keygen installed on your local machine and available from the command line. The CLI
registers the new key pair with Amazon EC2 for you and stores the private key locally in a folder
named .ssh in your user directory.
Select a keypair.
1) [ Create new KeyPair ]
(default is 1): 1
Your EB CLI installation is now configured and ready to use. See Managing Elastic Beanstalk
Environments with the EB CLI (p. 446) for instructions on creating and working with an Elastic
Beanstalk environment.
Advanced Configuration
• Ignoring files with .ebignore (p. 445)
API Version 2010-12-01
444
AWS Elastic Beanstalk Developer Guide
Ignoring files with .ebignore
• Using Named Profiles (p. 445)
• Deploying an Artifact Instead of the Project Folder (p. 445)
• Configuration Settings and Precedence (p. 446)
• Instance Metadata (p. 446)
Ignoring files with .ebignore
You can tell the EB CLI to ignore certain files in your project directory with a .ebignore file. This file
works like a .gitignore. When you deploy your project directory to Elastic Beanstalk and create a new
application version, the EB CLI will not include files specified by the .ebignore in the source bundle that
it creates.
If no .ebignore is present, but a .gitignore is, the EB CLI will ignore files specified in the .gitignore. If
an .ebignore file is present, the EB CLI will not read the .gitignore.
Note
In Windows, adding an .ebignore file causes the EB CLI to follow symbolic links and include
the linked file when creating a source bundle. This is a known issue and will be fixed in a future
update.
Using Named Profiles
If you store your credentials as a named profile in a credentials or config file, you can use the -profile (p. 465) option to explicitly specify a profile. For example, the following command creates a
new application using the user2 profile.
$ eb init --profile user2
You can also change the default profile by setting the AWS_EB_PROFILE environment variable. When this
variable is set, the EB CLI will read credentials from the specified profile instead of default or eb-cli.
Linux, macOS, or Unix
$ export AWS_EB_PROFILE=user2
Windows
> set AWS_EB_PROFILE=user2
Deploying an Artifact Instead of the Project Folder
You can tell the EB CLI to deploy a ZIP or WAR file that you generate as part of a separate build process
by adding the following lines to .elasticbeanstalk/config.yml in your project folder.
deploy:
artifact: path/to/buildartifact.zip
If you configure the EB CLI in your Git repository (p. 451), and you don't commit the artifact to source,
use the --staged option to deploy the latest build:
~/eb$ eb deploy --staged
API Version 2010-12-01
445
AWS Elastic Beanstalk Developer Guide
Configuration Settings and Precedence
Configuration Settings and Precedence
The EB CLI uses a provider chain to look for AWS credentials in a number of different places, including
system or user environment variables and local AWS configuration files.
The AWS CLI looks for credentials and configuration settings in the following order:
1. Command Line Options – a named profile can be specified with --profile to override default
settings.
2. Environment Variables – AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
3. The AWS credentials file – located at ~/.aws/credentials on Linux and OS X systems or at C:\Users
\USERNAME\.aws\credentials on Windows systems. This file can contain multiple named profiles in
addition to a default profile.
4. The AWS CLI configuration file – located at ~/.aws/config on Linux and OS X systems or C:\Users
\USERNAME\.aws\config on Windows systems. This file can contain a default profile, named profiles,
and AWS CLI specific configuration parameters for each.
5. Legacy EB CLI configuration file – located at ~/.elasticbeanstalk/config on Linux and OS X
systems or C:\Users\USERNAME\.elasticbeanstalk/config on Windows systems.
6. Instance profile credentials – these credentials can be used on EC2 instances with an assigned
instance role, and are delivered through the Amazon EC2 metadata service. The instance profile (p. 19)
must have permission to use Elastic Beanstalk.
If the credentials file contains a named profile with the name "eb-cli", the EB CLI will prefer that profile
over the default profile. If no profiles are found, or a profile is found but does not have permission to use
Elastic Beanstalk, the EB CLI prompts you to enter keys.
Instance Metadata
To use the EB CLI from an EC2 instance, create a role that has access to the resources needed and assign
that role to the instance when it is launched. Launch the instance and install the EB CLI with pip:
~$ sudo pip install awsebcli
pip comes pre-installed on Amazon Linux.
The EB CLI will read credentials from the instance metadata. For more information, see Granting
Applications that Run on Amazon EC2 Instances Access to AWS Resources in IAM User Guide.
Managing Elastic Beanstalk Environments with the
EB CLI
After installing the EB CLI (p. 435) and configuring your project directory (p. 443), you are ready to
create an Elastic Beanstalk environment using the EB CLI, deploy source and configuration updates, and
pull logs and events.
Note
Creating environments with EB CLI requires a service role (p. 18). You can create a service role
by creating an environment in the Elastic Beanstalk Management Console. If you don't have a
service role, EB CLI attempts to create one when you run eb create.
The following examples use an empty project folder named eb that was initialized with the EB CLI for use
with a sample Docker application.
API Version 2010-12-01
446
AWS Elastic Beanstalk Developer Guide
eb create
Basic Commands
• eb create (p. 447)
• eb status (p. 447)
• eb health (p. 448)
• eb events (p. 448)
• eb logs (p. 449)
• eb open (p. 449)
• eb deploy (p. 449)
• eb config (p. 450)
• eb terminate (p. 450)
eb create
To create your first environment, run eb create (p. 474) and follow the prompts. If your project
directory has source code in it, the EB CLI will bundle it up and deploy it to your environment. Otherwise,
a sample application will be used.
~/eb$ eb create
Enter Environment Name
(default is eb-dev): eb-dev
Enter DNS CNAME prefix
(default is eb-dev): eb-dev
WARNING: The current directory does not contain any source code. Elastic Beanstalk is
launching the sample application instead.
Environment details for: elasticBeanstalkExa-env
Application name: elastic-beanstalk-example
Region: us-west-2
Deployed Version: Sample Application
Environment ID: e-j3pmc8tscn
Platform: 64bit Amazon Linux 2015.03 v1.4.3 running Docker 1.6.2
Tier: WebServer-Standard
CNAME: eb-dev.elasticbeanstalk.com
Updated: 2015-06-27 01:02:24.813000+00:00
Printing Status:
INFO: createEnvironment is starting.
-- Events -- (safe to Ctrl+C) Use "eb abort" to cancel the command.
Your environment can take several minutes to become ready. Press Ctrl-C to return to the command line
while the environment is created.
eb status
Run eb status to see the current status of your environment. When the status is ready, the sample
application is available at elasticbeanstalk.com and the environment is ready to be updated.
~/eb$ eb status
Environment details for: elasticBeanstalkExa-env
Application name: elastic-beanstalk-example
Region: us-west-2
Deployed Version: Sample Application
Environment ID: e-gbzqc3jcra
Platform: 64bit Amazon Linux 2015.03 v1.4.3 running Docker 1.6.2
Tier: WebServer-Standard
CNAME: elasticbeanstalkexa-env.elasticbeanstalk.com
Updated: 2015-06-30 01:47:45.589000+00:00
Status: Ready
API Version 2010-12-01
447
AWS Elastic Beanstalk Developer Guide
eb health
Health: Green
eb health
Use the eb health command to view health information (p. 306) about the instances in your
environment and the state of your environment overall. Use the --refresh option to view health in an
interactive view that updates every 10 seconds.
~/eb$ eb health
api
WebServer
total
ok
3
3
Ok
warning
0
degraded
0
instance-id
Overall
i-0ef05ec54918bf567
i-001880c1187493460
i-04703409d90d7c353
status
Ok
Ok
Ok
Ok
instance-id
p50
p10
Overall
0.040
0.019
i-0ef05ec54918bf567
0.050
0.023
i-001880c1187493460
0.050
0.034
i-04703409d90d7c353
0.021
0.015
r/sec
info
0
cause
health
%2xx
%3xx
%4xx
%5xx
p99
8.6
100.0
0.0
0.0
0.0
2.9
29
0
0
2.9
29
0
2.8
28
0
az
running
load 1
load 5
user%
nice%
1c
23 mins
0.19
0.05
3.0
0.0
1a
23 mins
0.0
0.0
3.2
0.0
1b
1 day
0.0
0.0
3.6
0.0
status
id
version
ago
Deployed
Deployed
Deployed
28
28
28
app-bc1b-160915_181041
app-bc1b-160915_181041
app-bc1b-160915_181041
20 mins
20 mins
27 mins
instance-id
type
system% idle%
iowait%
i-0ef05ec54918bf567
t2.micro
0.3
96.7
0.0
i-001880c1187493460
t2.micro
0.3
96.5
0.0
i-04703409d90d7c353
t2.micro
0.2
96.2
0.0
instance-id
deployments
i-0ef05ec54918bf567
i-001880c1187493460
i-04703409d90d7c353
severe
0
2016-09-15 18:39:04
Java 8
pending unknown
0
0
p90
p75
0.083*
0.065
0.053
0
0.069*
0.066
0.057
0
0
0.087*
0.069
0.056
0
0
0.051*
0.027
0.024
eb events
Use eb events to see a list of events output by Elastic Beanstalk.
~/eb$ eb events
2015-06-29 23:21:09
INFO
createEnvironment is starting.
2015-06-29 23:21:10
INFO
Using elasticbeanstalk-us-west-2-EXAMPLE as Amazon S3
storage bucket for environment data.
2015-06-29 23:21:23
INFO
Created load balancer named: awseb-e-g-AWSEBLoa-EXAMPLE
2015-06-29 23:21:42
INFO
Created security group named: awseb-e-gbzqc3jcra-stackAWSEBSecurityGroup-EXAMPLE
2015-06-29 23:21:45
INFO
Created Auto Scaling launch configuration named: awseb-egbzqc3jcra-stack-AWSEBAutoScalingLaunchConfiguration-EXAMPLE
...
API Version 2010-12-01
448
AWS Elastic Beanstalk Developer Guide
eb logs
eb logs
Use eb logs to pull logs from an instance in your environment. By default, eb logs pull logs from the
first instance launched and displays them in standard output. You can specify an instance ID with the -instance option to get logs from a specific instance.
The --all option pulls logs from all instances and saves them to subdirectories under
.elasticbeanstalk/logs.
~/eb$ eb logs --all
Retrieving logs...
Logs were saved to /home/local/ANT/mwunderl/ebcli/environments/test/.elasticbeanstalk/
logs/150630_201410
Updated symlink at /home/local/ANT/mwunderl/ebcli/environments/test/.elasticbeanstalk/logs/
latest
eb open
To open your environment's website in a browser, use eb open:
~/eb$ eb open
In a windowed environment, your default browser will open in a new window. In a terminal environment,
a command line browser (e.g. w3m) will be used if available.
eb deploy
Once the environment is up and ready, you can update it using eb deploy.
This command works better with some source code to bundle up and deploy, so for this example we've
created a Dockerfile in the project directory with the following content:
~/eb/Dockerfile
FROM ubuntu:12.04
RUN apt-get update
RUN apt-get install -y nginx zip curl
RUN echo "daemon off;" >> /etc/nginx/nginx.conf
RUN curl -o /usr/share/nginx/www/master.zip -L https://codeload.github.com/
gabrielecirulli/2048/zip/master
RUN cd /usr/share/nginx/www/ && unzip master.zip && mv 2048-master/* . && rm -rf 2048master master.zip
EXPOSE 80
CMD ["/usr/sbin/nginx", "-c", "/etc/nginx/nginx.conf"]
This Dockerfile deploys an image of Ubuntu 12.04 and installs the game 2048. Run eb deploy to upload
the application to your environment:
~/eb$ eb deploy
Creating application version archive "app-150630_014338".
Uploading elastic-beanstalk-example/app-150630_014338.zip to S3. This may take a while.
API Version 2010-12-01
449
AWS Elastic Beanstalk Developer Guide
eb config
Upload Complete.
INFO: Environment update is starting.
-- Events -- (safe to Ctrl+C) Use "eb abort" to cancel the command.
When you run eb deploy, the EB CLI bundles up the contents of your project directory and deploys it to
your environment.
Note
If you have initialized a git repository in your project folder, the EB CLI will always deploy the
latest commit, even if you have pending changes. Commit your changes prior to running eb
deploy to deploy them to your environment.
eb config
Take a look at the configuration options available for your running environment with the eb config
command:
~/eb$ eb config
ApplicationName: elastic-beanstalk-example
DateUpdated: 2015-06-30 02:12:03+00:00
EnvironmentName: elasticBeanstalkExa-env
SolutionStackName: 64bit Amazon Linux 2015.03 v1.4.3 running Docker 1.6.2
settings:
AWSEBAutoScalingScaleDownPolicy.aws:autoscaling:trigger:
LowerBreachScaleIncrement: '-1'
AWSEBAutoScalingScaleUpPolicy.aws:autoscaling:trigger:
UpperBreachScaleIncrement: '1'
AWSEBCloudwatchAlarmHigh.aws:autoscaling:trigger:
UpperThreshold: '6000000'
...
This command populates a list of available configuration options in a text editor. Many of the options
shown have a null value, these are not set by default but can be modified to update the resources in
your environment. See Configuration Options (p. 145) for more information about these options.
eb terminate
If you are done using the environment for now, use eb terminate to terminate it.
~/eb$ eb terminate
The environment "eb-dev" and all associated instances will be terminated.
To confirm, type the environment name: eb-dev
INFO: terminateEnvironment is starting.
INFO: Deleted CloudWatch alarm named: awseb-e-jc8t3pmscn-stackAWSEBCloudwatchAlarmHigh-1XLMU7DNCBV6Y
INFO: Deleted CloudWatch alarm named: awseb-e-jc8t3pmscn-stackAWSEBCloudwatchAlarmLow-8IVI04W2SCXS
INFO: Deleted Auto Scaling group policy named: arn:aws:autoscaling:uswest-2:210774411744:scalingPolicy:1753d43e-ae87-4df6a405-11d31f4c8f97:autoScalingGroupName/awseb-e-jc8t3pmscn-stackAWSEBAutoScalingGroup-90TTS2ZL4MXV:policyName/awseb-e-jc8t3pmscn-stackAWSEBAutoScalingScaleUpPolicy-A070H1BMUQAJ
INFO: Deleted Auto Scaling group policy named: arn:aws:autoscaling:uswest-2:210774411744:scalingPolicy:1fd24ea4-3d6f-4373affc-4912012092ba:autoScalingGroupName/awseb-e-jc8t3pmscn-stackAWSEBAutoScalingGroup-90TTS2ZL4MXV:policyName/awseb-e-jc8t3pmscn-stackAWSEBAutoScalingScaleDownPolicy-LSWFUMZ46H1V
INFO: Waiting for EC2 instances to terminate. This may take a few minutes.
-- Events -- (safe to Ctrl+C)
API Version 2010-12-01
450
AWS Elastic Beanstalk Developer Guide
Using the EB CLI with AWS CodeBuild
For a full list of available EB CLI commands, check out the EB CLI Command Reference (p. 465).
Using the EB CLI with AWS CodeBuild
You can use the EB CLI to build your application from your source code using AWS CodeBuild. With AWS
CodeBuild, you can compile your source code, run unit tests, and produce artifacts that are ready to
deploy.
Creating an Application
You can use the Elastic Beanstalk CLI to create an application that uses AWS CodeBuild to compile
your source code. If you run eb init in a folder with a buildspec.yml file, Elastic Beanstalk detects the
file and parses it to detect any Elastic Beanstalk settings. Elastic Beanstalk extends the format of the
buildspec.yml file to include the following additional settings, as described in eb init (p. 483).
Using the EB CLI with Git
The EB CLI provides integration with Git. This section provides an overview of how to use Git with the EB
CLI.
To install Git and initialize your Git repository
1.
Download the most recent version of Git by going to http://git-scm.com
2.
Initialize your Git repository by typing the following:
~/eb$ git init
3.
EB CLI will now recognize that your application is set up with Git.
If you haven't already run eb init, do that now:
~/eb$ eb init
Associating Elastic Beanstalk environments with Git
branches
You can associate a different environment with each branch of your code. When you checkout a
branch, changes are deployed to the associated environment. For example, you can type the following
to associate your production environment with your master branch, and a separate development
environment with your development branch:
~/eb$
~/eb$
~/eb$
~/eb$
git checkout master
eb use prod
git checkout develop
eb use dev
Deploying changes
By default, the EB CLI deploys the latest commit in the current branch, using the commit ID and message
as the application version label and description, respectively. If you want to deploy to your environment
API Version 2010-12-01
451
AWS Elastic Beanstalk Developer Guide
Using Git submodules
without committing, you can use the --staged option to deploy changes that have been added to the
staging area.
To deploy changes without committing
1.
Add new and changed files to the staging area:
~/eb$ git add .
2.
Deploy the staged changes with eb deploy:
~/eb$ eb deploy --staged
If you have configured the EB CLI to deploy an artifact (p. 445), and you don't commit the artifact to
your git repository, use the --staged option to deploy the latest build.
Using Git submodules
Some code projects benefit from having Git submodules — repositories within the top-level repository.
When you deploy your code using eb create or eb deploy, the EB CLI can include submodules in the
application version zip file and upload them with the rest of the code.
You can control the inclusion of submodules by using the include_git_submodules option in the global
section of the EB CLI configuration file, .elasticbeanstalk/config.yml in your project folder.
To include submodules, set this option to true:
global:
include_git_submodules: true
When the include_git_submodules option is missing or set to false, EB CLI does not include
submodules in the uploaded zip file.
See Git Tools - Submodules for more details about Git submodules.
Default behavior
When you run eb init to configure your project, the EB CLI adds the include_git_submodules
option and sets it to true. This ensures that any submodules you have in your project are
included in your deployments.
The EB CLI did not always support including submodules. To avoid an accidental and undesirable
change to projects that had existed before we added submodule support, the EB CLI does not
include submodules when the include_git_submodules option is missing. If you have one
of these existing projects and you want to include submodules in your deployments, add the
option and set it to true as explained in this section.
CodeCommit behavior
Elastic Beanstalk's integration with AWS CodeCommit (p. 453) doesn't support submodules at
this time. If you enabled your environment to integrate with AWS CodeCommit, submodules are
not included in your deployments.
Assigning Git tags to your application version
You can use a Git tag as your version label to identify what application version is running in your
environment. For example, type the following:
~/eb$ git tag -a v1.0 -m "My version 1.0"
API Version 2010-12-01
452
AWS Elastic Beanstalk Developer Guide
AWS CodeCommit
Using the EB CLI with AWS CodeCommit
You can use the EB CLI to deploy your application directly from your AWS CodeCommit repository.
With AWS CodeCommit, you can upload only your changes to the repository when you deploy, instead
of uploading your entire project. This can save you time and bandwidth if you have a large project or
limited Internet connectivity. The EB CLI pushes your local commits and uses them to create application
versions when you use eb create or eb deploy.
To deploy your changes, AWS CodeCommit integration requires you to commit changes first. However, as
you develop or debug, you might not want to push changes that you haven't confirmed are working. You
can avoid committing your changes by staging them and using eb deploy --staged (which performs a
standard deployment). Or commit your changes to a development or testing branch first, and merge to
your master branch only when your code is ready. With eb use, you can configure the EB CLI to deploy
to one environment from your development branch, and to a different environment from your master
branch.
Sections
• Prerequisites (p. 453)
• Creating an AWS CodeCommit Repository with the EB CLI (p. 453)
• Deploying from Your AWS CodeCommit Repository (p. 454)
• Configuring Additional Branches and Environments (p. 455)
• Using an Existing AWS CodeCommit Repository (p. 456)
Prerequisites
To use AWS CodeCommit with AWS Elastic Beanstalk, you need a local Git repository (either one you
have already or a new one you create) with at least one commit, permission to use AWS CodeCommit,
and an Elastic Beanstalk environment in a region that AWS CodeCommit supports. Your environment and
repository must be in the same region.
To initialize a Git repository
1.
Run git init in your project folder.
~/my-app$ git init
2.
Stage your project files with git add.
~/my-app$ git add .
3.
Commit changes with git commit.
~/my-app$ git commit -m "Elastic Beanstalk application"
Creating an AWS CodeCommit Repository with the
EB CLI
To get started with AWS CodeCommit, run eb init (p. 483). During repository configuration, the EB
CLI prompts you to use AWS CodeCommit to store your code and speed up deployments. Even if you
previously configured your project with eb init, you can run it again to configure AWS CodeCommit.
API Version 2010-12-01
453
AWS Elastic Beanstalk Developer Guide
Deploying from Your AWS CodeCommit Repository
To create an AWS CodeCommit repository with the EB CLI
1.
Run eb init in your project folder. During configuration, the EB CLI asks if you want to use AWS
CodeCommit to store your code and speed up deployments. If you previously configured your
project with eb init, you can still run it again to configure AWS CodeCommit. Type y at the prompt
to set up AWS CodeCommit.
~/my-app$ eb init
Note: Elastic Beanstalk now supports AWS CodeCommit; a fully-managed source control
service. To learn more, see Docs: https://aws.amazon.com/codecommit/
Do you wish to continue with CodeCommit? (y/n)(default is n): y
2.
Choose Create new Repository.
Select a repository
1) my-repo
2) [ Create new Repository ]
(default is 2): 2
3.
Type a repository name or press Enter to accept the default name.
Enter Repository Name
(default is "codecommit-origin"): my-app
Successfully created repository: my-app
4.
Choose an existing branch for your commits, or use the EB CLI to create a new branch.
Enter Branch Name
***** Must have at least one commit to create a new branch with CodeCommit *****
(default is "master"): ENTER
Successfully created branch: master
Deploying from Your AWS CodeCommit Repository
When you configure AWS CodeCommit with your EB CLI repository, the EB CLI uses the contents of
the repository to create source bundles. When you run eb deploy or eb create, the EB CLI pushes new
commits and uses the HEAD revision of your branch to create the archive that it deploys to the EC2
instances in your environment.
To use AWS CodeCommit integration with the EB CLI
1.
Create a new environment with eb create.
~/my-app$ eb create my-app-env
Starting environment deployment via CodeCommit
--- Waiting for application versions to be pre-processed --Finished processing application version app-ac1ea-161010_201918
Setting up default branch
Environment details for: my-app-env
Application name: my-app
Region: us-east-2
Deployed Version: app-ac1ea-161010_201918
Environment ID: e-pm5mvvkfnd
Platform: 64bit Amazon Linux 2016.03 v2.1.6 running Java 8
Tier: WebServer-Standard
CNAME: UNKNOWN
Updated: 2016-10-10 20:20:29.725000+00:00
Printing Status:
API Version 2010-12-01
454
AWS Elastic Beanstalk Developer Guide
Configuring Additional Branches and Environments
INFO: createEnvironment is starting.
...
The EB CLI uses the latest commit in the tracked branch to create the application version that is
deployed to the environment.
2.
When you have new local commits, use eb deploy to push the commits and deploy to your
environment.
~/my-app$ eb deploy
Starting environment deployment via CodeCommit
INFO: Environment update is starting.
INFO: Deploying new version to instance(s).
INFO: New application version was deployed to running EC2 instances.
INFO: Environment update completed successfully.
3.
To test changes before you commit them, use the --staged option to deploy changes that you
added to the staging area with git add.
~/my-app$ git add new-file
~/my-app$ eb deploy --staged
Deploying with the --staged option performs a standard deployment, bypassing AWS CodeCommit.
Configuring Additional Branches and Environments
AWS CodeCommit configuration applies to a single branch. You can use eb use and eb codesource to
configure additional branches or modify the current branch's configuration.
To configure AWS CodeCommit integration with the EB CLI
1.
To change the remote branch, use the eb use (p. 507) command's --source option.
~/my-app$ eb use test-env --source my-app/test
2.
To create a new branch and environment, check out a new branch, push it to AWS CodeCommit,
create the environment, and then use eb use to connect the local branch, remote branch, and
environment.
~/my-app$
~/my-app$
~/my-app$
~/my-app$
3.
git checkout -b production
git push --set-upstream production
eb create production-env
eb use --source my-app/production production-env
To configure AWS CodeCommit interactively, use eb codesource codecommit (p. 470).
~/my-app$ eb codesource codecommit
Current CodeCommit setup:
Repository: my-app
Branch: test
Do you wish to continue (y/n): y
Select a repository
1) my-repo
2) my-app
3) [ Create new Repository ]
(default is 2): 2
API Version 2010-12-01
455
AWS Elastic Beanstalk Developer Guide
Using an Existing AWS CodeCommit Repository
Select a branch
1) master
2) test
3) [ Create new Branch with local HEAD ]
(default is 1): 1
4.
To disable AWS CodeCommit integration, use eb codesource local (p. 470).
~/my-app$ eb codesource local
Current CodeCommit setup:
Repository: my-app
Branch: master
Default set to use local sources
Using an Existing AWS CodeCommit Repository
If you already have an AWS CodeCommit repository and want to use it with Elastic Beanstalk, run eb
init at the root of your local Git repository.
To use an existing AWS CodeCommit repository with the EB CLI
1.
Clone your AWS CodeCommit repository.
~$ git clone ssh://git-codecommit.us-east-2.amazonaws.com/v1/repos/my-app
2.
Check out and push a branch to use for your Elastic Beanstalk environment.
~/my-app$ git checkout -b dev-env
~/my-app$ git push --set-upstream origin dev-env
3.
Run eb init. Choose the same region, repository, and branch name that you are currently using.
~/my-app$ eb init
Select a default region
1) us-east-1 : US East (N. Virginia)
2) us-west-1 : US West (N. California)
3) us-west-2 : US West (Oregon)
4) eu-west-1 : EU (Ireland)
5) eu-central-1 : EU (Frankfurt)
6) ap-south-1 : Asia Pacific (Mumbai)
7) ap-southeast-1 : Asia Pacific (Singapore)
8) ap-southeast-2 : Asia Pacific (Sydney)
9) ap-northeast-1 : Asia Pacific (Tokyo)
10) ap-northeast-2 : Asia Pacific (Seoul)
11) sa-east-1 : South America (Sao Paulo)
12) cn-north-1 : China (Beijing)
13) us-east-2 : US East (Columbus)
14) ca-central-1 : Canada (Central)
15) eu-west-2 : EU (London)
(default is 3): 1
...
Note: Elastic Beanstalk now supports AWS CodeCommit; a fully-managed source control
service. To learn more, s