Last Updated: 2024-02-09


AWS PrivateLink allows private connectivity between virtual private clouds (VPC), supported AWS services, and on-premises networks. This connection does not expose traffic to the public internet, making it a great choice for data federation across cloud and on-prem networks and other use cases.

Starburst Galaxy extends support for AWS PrivateLink across certain catalogs. This tutorial will guide you through configuring PrivateLink for an Amazon RDS instance.

Scope of tutorial

In this tutorial, you will learn how to configure AWS PrivateLink for an Amazon RDS instance.

Learning objectives

Once you've completed this tutorial, you will be able to:


About Starburst tutorials

Starburst tutorials are designed to get you up and running quickly by providing bite-sized, hands-on educational resources. Each tutorial explores a single feature or topic through a series of guided, step-by-step instructions.

As you navigate through the tutorial you should follow along using your own Starburst Galaxy account. This will help consolidate the learning process by mixing theory and practice.


If you are configuring PrivateLink for the first time you are encouraged to work with a Starburst technical resource. This individual will work with you to set up the environment needed to complete the tutorial.

Contacting your technical resource

To be assigned this resource, you should reach out to your regular Starburst account team for assistance.

Working together

Once assigned, your Starburst technical resource will work with you to set up an environment where you can complete the tutorial.

Please review the following overview of this process before beginning the tutorial.

Your responsibilities:


Understanding the AWS PrivateLink RDS architecture is important when completing the steps in this tutorial. In this section you will learn about this architecture and the way that Starburst Galaxy uses it to securely connect private clouds.

This tutorial also follows corresponding AWS documentation on the topic. It is recommended that you consult this documentation if you want to learn more about AWS PrivateLink in general.

Reference architecture

The following diagram illustrates a PrivateLink connection between the Starburst Galaxy VPC and the Amazon RDS VPC.

Review the diagram and corresponding notes below for more information.

  1. Once the PrivateLink configuration is complete, an endpoint is created in the Starburst Galaxy VPC (Source).

    This endpoint connects to a Network Load Balancer located inside an endpoint service situated in the RDS instance VPC (Destination).

    This establishes a private connection between Starburst Galaxy and the RDS instance, enabling PrivateLink functionality.
  2. In this reference architecture, the Starburst Galaxy VPC is the source.
  3. In this reference architecture, the RDS instance VPC is the destination.


It's time to get started. In this section, you'll begin by obtaining some key information about your Amazon RDS instance, including:

You'll need this information to create a target group and load balancer in the next sections of this tutorial.

Step 1: Sign in to AWS console

You're going to start by signing in to your AWS console. Remember that this should be the AWS account containing the RDS instance that you would like to connect using PrivateLink, so if you use multiple AWS accounts, ensure that you pick the correct one.

Step 2: Select RDS instance

Now it's time to find the right RDS instance. Depending on your workflow, you might have multiple instances in the same AWS account, so make sure you select the correct one.

Step 3: Record RDS details

Now it's time to record details about your RDS instance. This includes the RDS endpoint, port, and availability zone.

Step 4: Record RDS IP address

Next, you will use your RDS endpoint to determine your RDS IP address.

To do this, you'll use a terminal window. Again, you will be copying information into your text editor.

Note: The command you choose will depend on your operating system. Be sure to replace [rds-endpoint] with your actual RDS endpoint.


Now it's time to set up a target group. In the context of AWS, a target group is responsible for directing incoming traffic from a load balancer to designated targets, such as cloud instances, containers, or IP addresses.

In this tutorial, the target group you create will play a crucial role in routing traffic to your RDS instance's IP address. This ensures efficient communication between the load balancer and RDS instance, optimizing performance and reliability.

Step 1: Start the target group wizard

Step 2: Provide a target group name

In this step, AWS will ask you to select a target type and provide a name.

Step 3: Configure the target group

Next, you're going to configure your target group for use with your RDS instance. To do this, you're going to use some of the details that you copied into your text editor earlier in this tutorial.

Step 4: Complete configuration process

Almost there! For the final step, you're going to finish the configuration process and create the target group.


Now it's time to create a network load balancer. In AWS, a Network Load Balancer (NLB) is a service that automatically distributes incoming network traffic across multiple targets based on IP protocol data. This includes Amazon EC2 instances, containers, and IP addresses. Load balancers are also configurable across either a single AWS Availability Zone or multiple Availability Zones.

After configuring PrivateLink, an endpoint in the Starburst Galaxy VPC will connect to your Network Load Balancer using a service located in the RDS instance VPC.

Step 1: Start the load balancer wizard

Step 2: Select load balancer type

AWS load balancers come in several different types. These include Application Load Balancers, Network Load Balancers, and Gateway Load Balancers.

For this tutorial, you're going to select the Network Load Balancer.

Step 3: Name your load balancer

It's time to start configuring your new load balancer, starting with a name.

Step 4: Configure the load balancer

Next, you're going to configure your load balancer for use with your RDS instance.

Step 5: Select the AWS availability zone and subnet(s)

Now it's time to select an AWS availability zone (AZ) for your load balancer. This will be the same AZ that you recorded for your RDS instance earlier in this tutorial.

Step 6: Configure security group

Next, it's time to select a security group to control access to your load balancer. Without this security group, your network load balancer will accept all connections, representing a security concern in production environments.

Step 7: Configure port and target group

Step 8: Wait for load balancer to activate

That's it! Your load balancer is now being created. This process takes between three to five minutes.


Now it's time to create an endpoint service.

In the context of AWS PrivateLink, an endpoint service allows you to expose services running in your VPC to other accounts within the same AWS region using a private connection.

Step 1: Start the endpoint service wizard

Step 2: Name your endpoint service

It's time to start configuring your new endpoint service, starting with a name.

Step 3: Configure endpoint service

Now it's time to configure your endpoint service. You're going to make sure that it connects with your network load balancer and uses the correct IP address.


Time to switch gears. You've completed all of the steps required on your own. Now it's time to contact the Starburst support team to finish the last steps.

Step 1: Enter the Starburst Galaxy ARN

In the last section of this tutorial, you created your endpoint service. At the end of that process, you are directed to a page that displays the details of that service.

You're going to use this section to input the Starburst Galaxy Amazon Resource Name (ARN).

Step 2: Record Service name

Now it's time to locate and copy the service name for your endpoint service. This is one of the endpoint service details listed in AWS.

The Starburst support team will use it to create the endpoint in Starburst Galaxy.

Step 3: Open support ticket

You are going to use the automated assistant in Starburst Galaxy to open a support ticket and provide support with the Service name that you just copied. You will also need to provide the port your database is listening on and your preferred Starburst Galaxy PrivateLink configuration name.

Step 4: Select the Starburst Galaxy endpoint

Do not begin this step until you receive confirmation that the Starburst Galaxy endpoint has been created successfully.

Step 5: Accept the endpoint connection request

Now that you've selected the Starburst Galaxy endpoint, it's time to accept the connection request.

Step 6: Confirm endpoint connection

That's it. The connection is now being created. This process takes between 1 to 3 minutes to complete.

When this process is complete, you are finished and ready to start using PrivateLink.


If your database is either MySQL or MariaDB, you will likely run into an error when trying to connect to your database from Starburst Galaxy via PrivateLink.

Network load balancer health checks

MySQL and MariaDB count the health checks performed by a network load balancer as connection errors. The network load balancer you created in this tutorial will perform health checks at a default interval of 30 seconds, with each check resulting in approximately 6 errors. This means that, if all default settings are enabled, you will exceed the maximum allowed connection errors in under 10 minutes. Once this limit is exceeded your network load balancer will be blocked.

The PrivateLink connection goes through the network load balancer so when it is blocked, connectivity from Starburst Galaxy to your database over PrivateLink is blocked.

Resulting error in Starburst Galaxy

Here are the errors you will see in Starburst Galaxy when the network load balancer is blocked.

Error listing schemas for catalog pl_mysql_extpartner: java.sql.SQLNonTransientConnectionException: Could not create connection to database server. Attempted reconnect 3 times, Giving up.

There are steps you can take to resolve this error, which are outlined below and also covered in this AWS Database Blog.

Step 1: Confirm issue

One easy way to confirm that you're hitting the health check issue is to run a SQL query that shows which IPs are registering connection errors.

FROM performance_schema.host_cache

Step 2: Temporarily resolve issue

You can reset the error counters by running the FLUSH HOSTS; command in the MySQL CLI, MySQL Workbench, or DBeaver. However, this is only a temporary fix because you will quickly hit the limit again and thus be blocked yet again.

Step 3: Increase health check interval

To permanently resolve the issue, you will have to complete three steps. The first step is to increase the health check interval. The default value for this interval is 30 seconds, and the maximum value is 300 seconds.

Step 4: Increase max_connect_errors

You are going to increase the value of max_connect_errors from the default value of 100 to 5000. With the health check interval set to 300 seconds, you should register approximately 72 errors per hour. Allowing 5000 errors should give you just over 69 hours before the network load balancer will be blocked and in turn block Starburst Galaxy's access.

SHOW GLOBAL VARIABLES LIKE 'max_connect_errors';

Step 5: Schedule FLUSH HOSTS command

The third and final step is to schedule the FLUSH HOSTS; command to run at an interval less than 69 hours. There are multiple ways to accomplish this. Please choose the best approach for your environment.

Tutorial complete

Congratulations! You have reached the end of this tutorial, and the end of this stage of your journey.

You're all set! Now you can use PrivateLink to configure access to data in your Amazon RDS instance.

Continuous learning

At Starburst, we believe in continuous learning. This tutorial provides the foundation for further training available on this platform, and you can return to it as many times as you like. Future tutorials will make use of the concepts used here.

Next steps

Starburst has lots of other tutorials to help you get up and running quickly. Each one breaks down an individual problem and guides you to a solution using a step-by-step approach to learning.

Tutorials available

Visit the Tutorials section to view the full list of tutorials and keep moving forward on your journey!

Start Free with
Starburst Galaxy

Up to $500 in usage credits included

  • Query your data lake fast with Starburst's best-in-class MPP SQL query engine
  • Get up and running in less than 5 minutes
  • Easily deploy clusters in AWS, Azure and Google Cloud
For more deployment options:
Download Starburst Enterprise

Please fill in all required fields and ensure you are using a valid email address.