Skip to main content

AWS with ECS and Fargate

Overview​

This document explains how to install PolyScale Self Hosted on AWS using Elastic Container Service (ECS) and Fargate.

AWS Install OverviewRunning PolyScale on AWS with ECS and Fargate

Prerequisites​

Before starting the deployment of the PolyScale Private Cache Endpoint (PCE), you will need to have an AWS account and a basic understanding of the following services:

  • Elastic Container Service (ECS): A fully-managed AWS container orchestration service that simplifies the deployment and management of containers.
  • Fargate: An AWS service that provides automatically managed compute capacity in the cloud.
  • Docker: An open-source platform for building, shipping, and running distributed applications.
  • A PolyScale account with a PCE enabled API key. (See https://docs.polyscale.ai/self-hosted-install for instructions on getting a key.)

Installation​

Step 1: Create an ECS Cluster​

The first step is to create an ECS cluster to manage the PCE container. Follow these steps:

  1. Open the AWS Management Console and navigate to the ECS service.
  2. Click on the "Create Cluster" button.
  3. Under “Cluster configuration” give the Cluster a name (e.g. PCE-Cluster)
  4. Under “Networking”, be sure to choose the VPC for the application and database for which you are looking to provide a cache.
  5. Under Infrastructure, AWS Fargate should already be selected.
  6. Click "Create".

AWS will then begin the creation process for the Cluster behind the scenes. Once the cluster is successfully created, a message at the top of the dashboard will indicate so.

Create ECS ClusterCreating an ECS Cluster

Step 2: Define the task to Run the PCE​

Next, we need to define a task that will be run by ECS to run the PCE.

  1. From ECS, click on “Task definitions” on the left hand side
  2. Click “Create new task definition” on the top right of the Task definitions page
  3. Under “Task definition configuration” give the Task definition family a name, e.g. PCE-Task
  4. Under “Container - 1” specify a name (PCE) and Image URI (ghcr.io/polyscale/pce:stable) for the PCE Image.
  5. Under “Port mappings” expose the ports the PCE uses for the different database protocols:
    • 9000 for MySQL
    • 9001 for MariaDB
    • 9010 for Postgres
    • 9020 for MSSql
      Mapping PortsMapping Ports for PCE
  6. Click “Add environment variable” to add the following environment variables:
    • PCE_API_KEY – your PolyScale API key that has been enabled for use with the PCE
    • PCE_TAG – the text you want to appear in the PolyScale observability overview to identify queries made to this instance of the PCE
      Setting Environment VariablesSetting Environment Variables
  7. Click “Next”
  8. On the “Configure environment, storage, monitoring, and tags” page, accept the defaults and click “Next” at the bottom
  9. On the “Review and create” page, double check the Image URI, port mappings and environment variables and then click “Create”

You have now created the task you assign ECS will execute to run the PCE.

Step 3: Create a Service to Run the Task​

Now return to your Cluster overview to create the service to run your PCE task.

  1. From cluster overview page in ECS for your PCE Cluster, click on “Create” in the Services section
  2. On the “Create” page, in the “Deployment configuration” section, under “Family” choose the task created above in Step 2 (e.g. “PCE-Task”)
  3. Assign a “Service Name” (e.g. “PCE-Service”)
  4. Under “Networking” if you will not need to access the PCE from outside your VPC, you can turn off “Public IP”; however, if you wish to be able to use your cache from devices/applications outside the VPC, leave this switched on.
  5. Accept all the other default values and click “Create” at the bottom of the page.

The process of running the PCE will now begin. Once startup is complete, under the Services section of the Cluster, it should indicate that the service (e.g. PCE-Service) is active. If you click on the “Tasks” tab, and then click on the Task name, you can then find the Private IP address you will use to connect to the PCE with your application. (For example 172.30.0.80)

Task IDTask ID
Private IP AddressSelect the Private IP Address

Step 4: Create a PolyScale cache​

A PolyScale account can have one or more caches defined. A cache simply identifies a database origin via a hostname and port that you wish to cache data for. Typically you create a cache per database for simplicity.

  1. To create a new cache, click the New Cache button in the upper right of the caches dashboard
  2. Give the cache a name, select the database type, and enter the hostname and port of the database you wish to connect to. (This will be the private IP address for your database that is accessible from within your VPC and the port on which your application currently accesses the database.) Note that if your database is not publicly accessible, the Network test that runs will fail, as it is testing access to your database from PolyScale’s public infrastructure. Assuming you have installed your PCE on the same VPC as your database and your security rules are set properly, your PCE should be able to access the database.
  3. When you have created your cache, you will be provided with a cache ID, as well as a new connection string. Save this for use in step 5 (though note the connection string is for use with the public SaaS endpoints and will need to be modified as described below).

You have now successfully created a cache.

Step 5: Connecting to the PolyScale PCE Cache​

To connect to your database via PolyScale, you will need to make the following changes to your connection string:

  • Update your host
  • Update the port
  • Pass in the PolyScale cache ID

The connection string provided in step 4 above is the easiest starting point. You simply make the following changes.

  1. Replace the psedge.global hostname with the Private IP address from Step 3 above if you will be accessing the cache from within the VPC. (Otherwise, use the Public IP address for the cache, located on the same page.)
  2. Replace the port in the connection string using the following port, based on which database you are using:
    • MySQL: 9000 (replaces 3306)
    • MariaDB: 9001 (replaces 3307)
    • PostgreSQL: 9010 (replaces 5432)
    • SQL Server: 9020 (replaces 1433)

So, for example, for a MySQL database, if the connection string provided when you created your cache was: mysql://POLYSCALE_CACHE_ID-USERNAME:PASSWORD@psedge.global:3306/DATABASE

And your private IP address was 172.30.0.80

To use this with the PCE, you would use a connection string in your application of: mysql://POLYSCALE_CACHE_ID-USERNAME:PASSWORD@172.30.0.80:9000/DATABASE

Alternatively, for a Postgres database, the PolyScale SaaS connection string of: postgres://USERNAME:PASSWORD@psedge.global:5432/DATABASE?application_name=POLYSCALE_CACHE_ID

Would instead become: postgres://USERNAME:PASSWORD@172.30.0.80:9010/DATABASE?application_name=POLYSCALE_CACHE_ID

For more details on connection strings, see the PolyScale documentation Getting Connected page.

You should now have a working cache running. If you have updated your connection string in your application as described above, you are now automatically caching all possible queries. That’s it! You can visit the PolyScale web user interface and see the queries PolyScale has cached for you.

PolyScale DashboardPolyScale Dashboard

Step 6: (Optional) Testing your Cache​

PolyScale provides an open source utility that can be used to test the latency for your cache. This Network Test Utility can be found at https://github.com/polyscale/ntu

This section will describe how to run this tool within your ECS Cluster to test the latency between an application in your VPC and your database via PolyScale. (The steps should be familiar, as we will be creating another Task, as in Step 2 above, this time to run the NTU.)

  1. From ECS, click on “Task definitions” on the left hand side
  2. Click “Create new task definition” on the top right of the Task definitions page
  3. Under “Task definition configuration” give the Task definition family a name, e.g. NTU
  4. Under “Container - 1” specify a name (NTU) and Image URI (ghcr.io/polyscale/ntu-worker) for the NTU Image.
  5. Under “Port mappings”, this time no changes are necessary
  6. Click “Add environment variable” to add the following environment variables:
    • PROTOCOL – the database type, eg mysql or postgres
    • TEST – latency
    • QUERY - the SQL query you want to run to test – eg Select * from employees limit 1;
    • SLACK_WEBHOOK - to get the results for the NTU test, you must have a Slack webhook configured, e.g. https://hooks.slack.com/services/SLACKTEAMINFO/SLACKCHANNELINFO
    • URL – the connection string for your database as discussed in step 5 above
  7. Click “Next”
  8. On the “Configure environment, storage, monitoring, and tags” page, accept the defaults and click “Next” at the bottom
  9. On the “Review and create” page, double check the Image URI, port mappings and environment variables and then click “Create”
  10. Now that the Task Definition is created, select “Deploy” and choose “Run task”
  11. From the Create screen, choose the Existing cluster you created above (e.g. PCE Cluster), and then leave the rest of the defaults. Click “Create” at the bottom of the page
  12. The NTU will then run 100 queries against your database via PolyScale and post a message to Slack that shows the distribution of latencies for the query

Shutting down and restarting the PCE​

If you want to shut down the running PCE, From PCE Cluster, click on the PCE Service and click “Update Service”. In the “Desired tasks” section, change the value from 1 to 0 and then click Update. This will scale the service down to 0, stopping the PCE from running.

To restart the PCE, return to the “Update Service” page and increase “Desired tasks” back to 1, and then click “Update”. Note that when restarting the service this way after stopping it, the private IP address may change, so you may need to update your connection string accordingly.

(There are workarounds to get a static IP address, either by using EC2 with a static IP address rather than Fargate or by using a load balancer, but that is outside the scope of this article.)

Launching the PCE Using CloudFormation​

If you are set up with the AWS Command Line Interface, you can alternatively use a CloudFormation template to install and launch the PCE. The template can be found in this repository.

To create and launch the PCE, simply type these two commands:

export PCE_API_KEY=<YOUR_PCI_API_KEY>
aws cloudformation create-stack \
        --capabilities CAPABILITY_NAMED_IAM \
        --stack-name pce-ecs-fargate-example \
        --parameters ParameterKey=PceApiKey,ParameterValue=$PCE_API_KEY \
        --template-body file://pce-ecs-fargate-example.yaml

You can then follow the instructions in Step 3 above to find the IP address for the PCE.