The AWS Documentation website is getting a new look!
Try it now and let us know what you think. Switch to the new look >>

You can return to the original look by selecting English in the language selector above.

Using Elastic Beanstalk with Amazon Relational Database Service

AWS Elastic Beanstalk provides support for running Amazon Relational Database Service (Amazon RDS) instances in your Elastic Beanstalk environment. This works great for development and testing environments. However, it isn't 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 before you add Amazon Virtual Private Cloud (Amazon VPC) and security group configuration to the mix. See Adding a Database to Your Elastic Beanstalk Environment for details.

To decouple your database instance from your environment, you can run a database instance in Amazon RDS and configure your application to connect to it on launch. This enables you to connect multiple environments to a database, terminate an environment without affecting the database, and perform seamless updates with blue-green deployments. For a detailed procedure, see How do I decouple an Amazon RDS instance from an AWS Elastic Beanstalk environment without downtime, database sync issues, or data loss?.

To allow the Amazon 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

You can 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.

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. This is 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), 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 Amazon RDS Instance in a Default VPC
Launching and Connecting to an External Amazon RDS Instance in EC2 Classic
Storing the Connection String in Amazon S3
Cleaning Up an External Amazon RDS Instance

Launching and Connecting to an External Amazon RDS Instance in a Default VPC

To use an external database with an 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 Virtual Private Cloud for details on configuring a custom VPC for use with Elastic Beanstalk.

To launch an RDS DB instance in a default VPC

Open the RDS console.
Choose Databases in the navigation pane.
Choose Create database.
Choose a database engine. Choose Next.
Choose a use case, if prompted.
Under Specify DB details, review the default settings and adjust as necessary. Pay attention to the following options:
- DB instance class – Choose an instance size that has an appropriate amount of memory and CPU power for your workload.
- Multi-AZ deployment – For high availability, set to Create replica in different zone.
- Master username and Master password – The database username and password. Make a note of these settings because you'll use them later.
Choose Next.
Under Database options, for Database name, type ebdb. Make a note of the Database port value for use later.
Verify the default settings for the remaining options, and choose Create database.

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

Open the Amazon RDS console.
Choose Databases.
Choose the name of your DB instance to view its details.
In the Connectivity section, note the Subnets, Security groups, and Endpoint shown on this page so you can use this information later.
Under Security, you can see the security group associated with the DB instance. Open the link to view the security group in the Amazon EC2 console.
In the security group details, choose Inbound.
Choose Edit.
Choose Add Rule.
For Type, choose the DB engine that your application uses.
For Source, type sg- to view a list of available security groups. Choose the current security group to allow resources in the security group to receive traffic on the database port from other resources in the same group.
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.

To add a security group to your environment

Do one of the following:
- To add a security group using the Elastic Beanstalk console
  1. Open the Elastic Beanstalk console.
  2. Navigate to the management page for your environment.
  3. Choose Configuration.
  4. In the Instances configuration category, choose Modify.
  5. Under EC2 security groups, choose the security group to attach to the instances, in addition to the instance security group that Elastic Beanstalk creates.
  6. Choose Apply.
  7. Read the warning, and then choose Confirm.
- To add a security group using a configuration file, use the securitygroup-addexisting.config example file.

Next, pass the connection information to your environment by using environment properties. When you add a DB instance to your environment 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 names.

To configure environment properties for an Amazon RDS DB instance

Open the Elastic Beanstalk console.
Navigate to the management page for your environment.
Choose Configuration.
In the Software configuration category, choose Modify.
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 (this is the hostname)
- RDS_PORT – The port on which the DB instance accepts connections. The default value varies among 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 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)
Java with Tomcat – Connecting to a Database (Tomcat Platforms)
Node.js – Connecting to a Database
.NET – Connecting to a Database
PHP – Connecting to a Database with a PDO or MySQLi
Python – Connecting to a Database
Ruby – Connecting to a Database

Finally, depending on when your application reads environment variables, you might need to restart the application server on the instances in your environment.

To restart your environment's app servers

Open the Elastic Beanstalk console.
Navigate to the management page for your environment.
Choose Actions, and then choose Restart App Server(s).

Launching and Connecting to an External Amazon RDS Instance in EC2 Classic

If you use EC2 Classic (no VPC) with AWS Elastic Beanstalk, the procedure changes slightly due to differences in how security groups work. In EC2 Classic, DB instances can't use EC2 security groups, so they get a DB security group that works only with Amazon RDS.

You can add rules to a DB security group that allow 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, add a rule in the DB security group to grant ingress to the new 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)

Open the RDS management console.
Choose Create database.
Proceed through the wizard. Note the values that you enter for the following options:
- Master Username
- Master Password
When you reach Configure advanced settings, for Network and Security settings, choose the following:
- VPC – Not in VPC. If this option isn't available, your account might 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
Configure the remaining options and choose Create database. 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 can't 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

Open the Amazon EC2 console.
Choose Security Groups under Network & Security in the navigation sidebar.
Choose Create Security Group.
For Security group name, type webapp-bridge.
For Description, type Provide access to DB instance from Elastic Beanstalk environment instances.
For VPC, leave the default selected.
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

Open the Amazon RDS console.
Choose Databases.
Choose the name of your DB instance to view its details.
In the Connectivity section, under Security, the security group associated with the DB instance is shown. Open the link to view the security group in the Amazon EC2 console.
In the security group details, set Connection Type to EC2 Security Group.
Set EC2 Security Group Name to the name of the bridge security group that you created.
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

Do one of the following:
- To add a security group using the Elastic Beanstalk console
  1. Open the Elastic Beanstalk console.
  2. Navigate to the management page for your environment.
  3. Choose Configuration.
  4. In the Instances configuration category, choose Modify.
  5. Under EC2 security groups, choose the security group to attach to the instances, in addition to the instance security group that Elastic Beanstalk creates.
  6. Choose Apply.
  7. Read the warning, and then choose Confirm.
- To add a security group using a configuration file, use the securitygroup-addexisting.config example file.

To configure environment properties

Open the Elastic Beanstalk console.
Navigate to the management page for your environment.
Choose Configuration.
In the Software configuration category, choose Modify.
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:
- 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 more properties.
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)
Java with Tomcat – Connecting to a Database (Tomcat Platforms)
Node.js – Connecting to a Database
.NET – Connecting to a Database
PHP – Connecting to a Database with a PDO or MySQLi
Python – Connecting to a Database
Ruby – Connecting to a Database

Finally, depending on when your application reads environment variables, you might need to restart the application server on the instances in your environment.

To restart your environment's app servers

Open the Elastic Beanstalk console.
Navigate to the management page for your environment.
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, 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.

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, user name and password for the database.

To create a bucket and upload a file

Open the Amazon S3 console.
Choose Create Bucket.
Type a Bucket Name, and then choose a Region.
Choose Create.
Open the bucket, and then choose Upload
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.

The default instance profile is named aws-elasticbeanstalk-ec2-role. If you're not sure what your instance profile is named, you can find it on the Configuration page in the environment management console.

To add permissions to the instance profile

Open the IAM console.
Choose Roles.
Choose aws-elasticbeanstalk-ec2-role.
Choose Add inline policy.

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 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/beanstalk-database.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.

Cleaning Up an External Amazon RDS Instance

When you connect an external Amazon RDS instance to your Elastic Beanstalk environment, the database instance isn't tied to your environment's lifecycle, and isn't deleted when you terminate your environment. To ensure that personal information that you might have stored in the database instance isn't unnecessarily retained, delete any records that you don't need anymore, or delete the database instance.

Warning Javascript is disabled or is unavailable in your browser.

To use the AWS Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

« Previous Next »