Menu
Sign In to the Console
AWS Elastic Beanstalk
Developer Guide (API Version 2010-12-01)

AWS Documentation » AWS Elastic Beanstalk » Developer Guide » Using Elastic Beanstalk with Other AWS Services » Using Elastic Beanstalk with Amazon RDS

Using Elastic Beanstalk with Amazon RDS

Elastic Beanstalk provides support for running Amazon RDS instances in your Elastic Beanstalk environment. 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 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.

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), 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

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 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. Choose Instances in the navigation pane.

  3. Choose Launch DB Instance.

  4. 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.

  6. Under Settings, enter values for DB Instance Identifier, Master Username, and Master Password (and Confirm Password). Note the values that you entered for later.

  7. Choose Next.

  8. For Network and Security settings, choose the following:

    • VPC – Default VPC

    • Subnet Group – default

    • Publicly Accessible – No

    • Availability Zone – No Preference

    • VPC Security Groups – Default VPC Security Group

  9. 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.

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.

  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 for your environment.

  3. Choose Configuration.

  4. In the Instances section, choose the settings icon ( Edit ).

  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 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 for your environment.

  3. Choose Configuration.

  4. In the Software Configuration section, choose the settings icon ( Edit ).

  5. 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.

  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:

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

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:

  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.

  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. Navigate to the management page for your environment.

  3. Choose Configuration.

  4. Choose Instances.

  5. 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.

  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 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. Open the Elastic Beanstalk console.

  2. Navigate to the management page for your environment.

  3. Choose Configuration.

  4. In the Software Configuration section, choose the settings icon ( Edit ).

  5. 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 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:

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 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, 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, 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.

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.

To add permissions to the instance profile

  1. Open the IAM console.

  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 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. See the following language-specific topics for more information: