Skip to content

Toro Cloud Dev Center


Configuring and connecting to an existing AWS RDS instance from TORO Cloud

This document will guide you on how to configure your existing Amazon RDS instance so that it can be used by Martini instances in TORO Cloud. To summarize, this guide will cover the following steps:

  1. Permitting connections from the Martini instance to the Amazon RDS instance
  2. Configuring the Amazon RDS instance
  3. Creating a database connection for the RDS instance in Martini

The database in the example uses MySQL

The instructions below are specific for MySQL and Amazon Aurora. If you're going to use a different database engine, you may need to review the ports used in the firewall configuration.

Allowing access to the Amazon RDS instance

A security group is like a firewall for your resources in AWS. It can control outbound and inbound traffic and is used to filter traffic going in and out of your resources. This part will create a security group that whitelists the public IP addresses of TORO Cloud in order to allow these IPs to connect to your AWS resources – Amazon RDS instances, specifically.

There are two ways you can create the security group:

Using CloudFormation templates are recommended

TORO maintains a CloudFormation template which creates a security group that whitelists all TORO Cloud IP addresses in order to allow connections between VPC resources and TORO Cloud. Whenever a new public IP is added to TORO Cloud, the CloudFormation template will also be updated. Using the CloudFormation template is an easy way to create or update firewall configurations that allow connections from TORO Cloud IPs.

Using the CloudFormation template

You should have permission to create the resources

When deploying a CloudFormation template, your user account should have the permission to create the resources specified by the CloudFormation template. Specifically, you should have permission to create a security group.

  1. Download the CloudFormation template from this repository. This repository contains multiple CloudFormation templates specific to the application or database engine you're going to use. This example will use the MySQL/Aurora template which whitelists port 3306.
  2. From the AWS Console, go to the CloudFormation service's dashboard. From the CloudFormation dashboard, click the Create Stack button.

    Creating a Stack in CloudFormation

  3. From the Create Stack page, select "Upload a template to Amazon S3", and then select the JSON file downloaded in step #1. Once you've selected the file, press the Next button.

    Selecting and uploading a CloudFormation template

  4. The next page will ask you to name your CloudFormation stack1 and define your stack's parameter values2. For the (1) Stack name, this can be anything; for the (2) SecurityGroupVPC parameter, you have to select the VPC where the security group will be used. Once done, press the Next button.

    Specifying CloudFormation stack details

  5. After clicking Next, CloudFormation will ask you to provide additional details or settings. You can leave all these fields to their default values. Press Next to proceed.

  6. The last page before deploying the stack is the Review page. This page shows the summary of all the resources that the CloudFormation template will deploy. Press the Create button to start deploying your template. After pressing Create, you should now see the CloudFormation template being deployed:

    CloudFormation template being deployed

  7. Once deployment is completed, go to your VPC and click Security Groups. You should now see the newly created security group with all the firewall rules needed.

    The newly created security group

Don't manually edit resources deployed using CloudFormation

Manually editing resources that were deployed through CloudFormation can cause issues in future updates or deployments.

Updating the security group created by CloudFormation

Whenever there are changes in TORO's public IPs, the CloudFormation templates maintained by TORO on Github will also be updated. Because of these templates, it will be easy to add the new IPs to your security group. When an IP change does happen, these are the steps you need to do:

This will only work on security groups managed by CloudFormation

This would only work if you have properly followed the instructions above. It cannot be used to update other security groups not deployed via CloudFormation.

  1. Download the newly updated CloudFormation template.
  2. Go to CloudFormation dashboard and:

    1. Select your existing stack.
    2. Press the Action button.
    3. Click Update Stack from the list.

    Updating the CloudFormation stack

  3. Select "Upload a template to Amazon S3", and then select the updated template file.

    Uploading the updated CloudFormation template

  4. You will be directed to the Specify Details section, where you should simply press Next.

  5. You should also press the Next button in the Options section.
  6. Finally, on the Review section, press the Update button. You will be redirected to your stacks and you should see that the status of the stack is UPDATE_IN_PROGRESS, which means, updates are being implemented as of the moment.

    CloudFormation stack being updated

    In this update, a third IP has been added to the security group. You should see from the VPC dashboard that the security group has been updated, and a third rule has been added to it.

    Updated security group

Manually creating the security group

If you prefer to create the security group manually, these are the steps you need to do:

  1. From the AWS console, select the VPC service. You should be redirected to the VPC service dashboard. From the VPC dashboard, click on the Security Groups panel.

    Accessing security groups via the VPC dashboard

  2. In the following page, click the Create Security Group button. From the Create Security Group modal, input enter the security group's name tag, group name, and description to identify this security group. Lastly, specify the VPC where you'd like to apply the security group.

    Creating a security group

  3. Define the security group's rules. To do this:

    1. Select the newly created security group from the dashboard.
    2. Click Inbound Rules.
    3. Click the Edit button.

    Editing the security group's inbound rules

  4. Upon clicking Edit, you should now be able to add new firewall rules. You will need to add an entry for each TORO Cloud IP address. In general, what you should do is:

    1. Select the your RDS instance's type. This example will use MySQL/Aurora (3306).
    2. By specifying Type, the Protocol will automatically be populated.
    3. By specifying Type, the Port Range will automatically be populated.
    4. In the Source column, you must type in the TORO Cloud IP address.
    5. You may use the Description column to describe or identify each rule.

    Do these steps repeatedly for every TORO Cloud IP address. After adding an entry per IP address, click the Save button to save your changes.

    Adding inbound rules to a security group

    Make sure to add all TORO Cloud public IPs

    To ensure that your TORO Cloud instance can always connect to your external RDS instance, make sure to whitelist all public IPs listed on our page.

Associating the security group with the Amazon RDS instance and enabling its public endpoint

After creating the necessary firewall configuration in your VPC, you should now associate the security group you created in the previous step. You will also need to configure the Amazon RDS instance so that it has a publicly accessible endpoint.

Review all security groups

You will be enabling the public endpoint of your RDS instance. Make sure to review all security groups assigned to it.

  1. From AWS console, go to the RDS service page. From the Amazon RDS dashboard, click Instances.

    Viewing Amazon RDS instances

  2. Once your instances are listed:

    1. Select the instance you want to configure. This is the database you want to connect to from TORO Cloud.
    2. Click the Instance actions dropdown on the upper right part of the dashboard.
    3. Select Modify.

    Modifying the Amazon RDS instance

  3. You should now be redirected to the Modify DB Instance page. Scroll down to the Network & Security section and on the (1) Security group dropdown, select the security group you have recently created which, in this case, is (2) toro-cloud-public-ips.

    Associating the security group with the Amazon RDS instance

  4. In the same section, enable the instance's public endpoint. Do this by clicking on the (2) Yes checkbox under (1) Public accessibility.

    Enabling the Amazon RDS instance's public endpoint

  5. Scroll down to the bottom of the page and press the Continue button. You should now see a summary of your modifications. Select (1) when to apply your modifications and then click on the (2) Modify DB Instance button.

    Applying Amazon RDS instance modifications

    Changes might trigger downtime

    The changes shouldn't cause any downtime. However, since Apply immediately has been selected, the update might carry other changes that are in the queue and these changes might trigger some downtime. Always review the changes and keep in mind any possible downtime.

  6. After applying the changes, go back to the Amazon RDS dashboard. The status of instance you have just modified should now be modifying.

    Changes being applied to the Amazon RDS instance, as indicated by its status

  7. If your database instance has replicas, make sure to do all the steps above on all of those replicas.

Connecting from TORO Cloud

This part will try to establish a connection between the Martini instance running in TORO Cloud and the Amazon RDS instance. This is simple and in fact, all you have to do is to create a database connection in the Martini instance. But before creating, test your connection first. If it receives a positive response from the RDS instance, then you are all set; a connection can be established between Martini and the RDS instance. However, if you are still unable to connect to the external Amazon RDS instance, here are some things you can try:

  • Ensure the user you're using to connect to your database server is allowed remote access.
  • Verify from a database client like MySQL Workbench if you can connect to your database.
  • Raise a support ticket in our portal or contact AWS support.

  1. A stack is a collection of AWS resources that you can manage as a single unit. In other words, you can create, update, or delete a collection of resources by creating, updating, or deleting stacks. All the resources in a stack are defined by the stack's AWS CloudFormation template. 

  2. CloudFormation parameters are input fields that would display during the deployment of the template. It lets the user define needed information before deploying the template.