AWS PrivateLink
This page is part of MariaDB's Documentation.
The parent of this page is: Private Connections
Topics on this page:
Overview
By default, client traffic to SkySQL services may transit the public internet and is protected with TLS and a firewall configured by IP allowlist.
Some customers may have regulatory requirements or information security policies that prohibit the default database connections over the public internet.
Options are available to enable private connections between VPC (Virtual Private Clouds) and supported cloud provider services such as SkySQL.
For SkySQL services on AWS, AWS PrivateLink is supported.
For detailed information about AWS PrivateLink, see "AWS PrivateLink" (Amazon documentation).
Requirements
AWS PrivateLink is used for private connections within the same AWS region.
Prior to configuring AWS PrivateLink on a SkySQL service, you must have created a VPC with a private subnet that will be used to communicate with private IP addresses.
Endpoint Choices
The default endpoint mechanism is "nlb", which supports accessing the SkySQL service via the public internet.
Use of AWS PrivateLink occurs when the endpoint mechanism is changed to "privateconnect".
AWS PrivateLink can be enabled using the SkySQL Portal, SkySQL DBaaS API, or SkySQL Terraform Provider.
Implementation Steps
Review the details of this page, including Requirements, Controls, and Connectivity
Enable AWS PrivateLink on your SkySQL service using one of the available interfaces for your use case:
Use Case
Method
Launch a new service
Modify an existing service
Perform AWS Endpoint Setup
Portal
AWS PrivateLink can be enabled with a web browser using the SkySQL Portal:
Enable AWS PrivateLink on Service Launch
To enable AWS PrivateLink when launching a new service via the SkySQL Portal:
Initiate service launch using the procedure at "Service Launch".
When you get to the final "Security" section, select "Enable Private Link".
For the next step, see the Connectivity, Controls, & AWS Endpoint Setup sections on this page.
Enable AWS PrivateLink on Existing SkySQL Service
To enable AWS PrivateLink for an existing service via the SkySQL Portal:
Log in to the Portal.
Click the "MANAGE" button (at right) for the desired service.
In the context menu, choose the "Set up Private Link" menu item.
In the popup window, add one or more AWS account IDs.
Click the "OK" button to confirm this operation.
For the next step, see the Connectivity, Controls, & AWS Endpoint Setup sections on this page.
Disable AWS PrivateLink
To disable AWS PrivateLink via the SkySQL Portal:
Visit the SkySQL Portal
Find the service that you would like to modify.
Click "MANAGE" on the far right side of the service listing.
In the context menu, select "Manage PrivateLink".
In the popup window, click "I want to disconnect my Private Link".
In the popup window, select "Disconnect".
After the service restarts, PrivateLink is disabled.
Since the service's allowlist was cleared when AWS PrivateLink was previously enabled, you will need to update the allowlist to allow clients to connect after disabling PrivateLink.
SkySQL DBaaS API
AWS PrivateLink can be enabled with a REST client using the SkySQL DBaaS API:
For general instructions on using the SkySQL DBaaS API, see "DBaaS API Launch Walkthrough".
Enable AWS PrivateLink on Service Launch
To enable AWS PrivateLink when launching a new service via the SkySQL DBaaS API:
Initiate service launch using the procedure at "DBaaS API Launch Walkthrough".
When you are creating the request, add the
"endpoint_mechanism"and"endpoint_allowed_accounts"attributes to the JSON payload:"endpoint_mechanism": "privateconnect", "endpoint_allowed_accounts": [ "AWS-ACCOUNT-ID-1", "AWS-ACCOUNT-ID-2" ]
Set
"endpoint_mechanism"to"privateconnect"Set
"endpoint_allowed_accounts"to a JSON array of one or more customer account IDs in AWS that will be allowed to establish a private connection to the SkySQL service
For the next step, see the Connectivity, Controls, & AWS Endpoint Setup sections on this page.
Enable AWS PrivateLink on Existing SkySQL Service
To enable AWS PrivateLink on an existing service via the SkySQL DBaaS API, create a JSON payload such as:
[
{
"mechanism": "privateconnect",
"allowed_accounts": [
"AWS-ACCOUNT-ID-1",
"AWS-ACCOUNT-ID-2"
]
}
]
Set
"mechanism"to"privateconnect"Set
"allowed_accounts"to a JSON array of one or more customer account IDs in AWS that will be allowed to establish a private connection to the SkySQL service.
And then use the API to update the endpoints information of the service. The following example of using curl expects the above payload to be in a file named data.json and also expects the variables API_KEY and SERVICE_ID to be set:
$ curl -H "Authorization: Bearer ${API_KEY}" \
-X PATCH -d @data.json \
https://api.mariadb.com/provisioning/v1/services/${SERVICE_ID}/endpoints \
| jq .
We will need the endpoint's service name later on in the setup, so use the API to query the endpoint once the service has finished its modifications and is back to "ready":
$ curl -H "Authorization: Bearer ${API_KEY}" -X GET \
https://api.mariadb.com/provisioning/v1/services/${SERVICE_ID} \
| jq '.status,.endpoints[0].ports,.endpoints[0].endpoint_service'
Note that the jq command is filtering the returned JSON data to extract three things (which are separated by commas in the command above):
The status of the service, which must be "ready" for the other values to be available.
The "
ready" status means that the PrivateLink endpoint setup is complete.A status of "
pending_upgrade" is reflected while PrivateLink endpoint setup is in-progress.
The "ports" data for the first item in the
endpointsarray.Some topologies include multiple port options, including ports for read/write and read-only connections, or for connections to the NoSQL listener.
Choose the desired port, such as "
readwrite".
The
endpoint_servicevalue for the first item in theendpointsarray.
The output will look something like this, though your values will vary:
"ready"
[
{
"name": "readwrite",
"port": 3306,
"purpose": "readwrite"
}
]
"com.amazonaws.vpce.AWS_REGION.vpce-svc-AWS_SERVICE_ID"
If you are not using jq, scan (or parse) the full returned JSON data to ensure the service status is "ready" and find the associated values described above.
For the next step, see the Connectivity, Controls, & AWS Endpoint Setup sections on this page.
Disable AWS PrivateLink
To disable AWS PrivateLink via the SkySQL DBaaS API, create a JSON payload such as:
[
{
"mechanism": "nlb"
}
]
Set
"mechanism"to"nlb"
And then use the API to update the endpoints information of the service. The following example of using curl expects the above payload to be in a file named data.json and also expects the variables API_KEY and SERVICE_ID to be set:
$ curl -H "Authorization: Bearer ${API_KEY}" \
-X PATCH -d @data.json \
https://api.mariadb.com/provisioning/v1/services/${SERVICE_ID}/endpoints \
| jq .
We will need the endpoint's service name later on in the setup, so use the API to query the endpoint once the service has finished its modifications and is back to "ready":
$ curl -H "Authorization: Bearer ${API_KEY}" -X GET \
https://api.mariadb.com/provisioning/v1/services/${SERVICE_ID} \
| jq '.status,.endpoints[0].ports,.endpoints[0].endpoint_service'
Note that the jq command is filtering the returned JSON data to extract three things (which are separated by commas in the command above):
The status of the service, which must be "ready" for the other values to be available.
The "
ready" status means that the endpoint modification is complete.A status of "
pending_upgrade" is reflected while PrivateLink is being disabled.
The "ports" data for the first item in the
endpointsarray.Some topologies include multiple port options, including ports for read/write and read-only connections, or for connections to the NoSQL listener.
Choose the desired port, such as "
readwrite".
The
endpoint_servicevalue for the first item in theendpointsarray.
The output will look something like this, though your values will vary:
"ready"
[
{
"name": "readwrite",
"port": 3306,
"purpose": "readwrite"
}
]
"com.amazonaws.vpce.AWS_REGION.vpce-svc-AWS_SERVICE_ID"
If you are not using jq, scan (or parse) the full returned JSON data to ensure the service status is "ready" and find the associated values described above.
Since the service's allowlist was cleared when AWS PrivateLink was previously enabled, you will need to update the allowlist to allow clients to connect after disabling PrivateLink.
To add an address to the allowlist via the SkySQL DBaaS API, create a JSON payload such as:
{
"ip_address": "192.0.2.10/32"
}
And then use the API to update the allowlist information of the service. The following example of using curl expects the above payload to be in a file named data.json and also expects the variables API_KEY and SERVICE_ID to be set:
$ curl -H "Authorization: Bearer ${API_KEY}" \
-X POST -d @data.json \
https://api.mariadb.com/provisioning/v1/services/${SERVICE_ID}/security/allowlist \
| jq .
Terraform Provider
AWS PrivateLink can be enabled with Terraform using the SkySQL Terraform provider:
For general instructions on using the SkySQL Terraform Provider, see "Terraform Launch Walkthrough".
For an example Terraform configuration that enables AWS PrivateLink, see "https://github.com/mariadb-corporation/terraform-provider-skysql/tree/main/examples/privateconnect".
Enable AWS PrivateLink on Service Launch
To enable AWS PrivateLink when launching a new service via the SkySQL Terraform provider:
Initiate service launch using the procedure at "Terraform Launch Walkthrough".
When you are configuring the
skysql_serviceresource, add theendpoint_mechanismandendpoint_allowed_accountsattributes.For example, the attributes can be placed after
ssl_enabled:ssl_enabled = var.ssl_enabled endpoint_mechanism = "privateconnect" endpoint_allowed_accounts = ["AWS-ACCOUNT-ID-1","AWS-ACCOUNT-ID-2"]
Set
endpoint_mechanismto"privateconnect"Set
endpoint_allowed_accountsto a comma-separated list of one or more customer account IDs in AWS that will be allowed to establish a private connection to the SkySQL service
Continue the rest of the procedure.
For the next step, see the Connectivity, Controls, & AWS Endpoint Setup sections on this page.
Enable AWS PrivateLink on Existing SkySQL Service
To enable AWS PrivateLink for an existing service via the SkySQL Terraform provider:
Alter the
skysql_serviceresource configuration by adding theendpoint_mechanismandendpoint_allowed_accountsattributes.For example, the attributes can be placed after
ssl_enabled:ssl_enabled = var.ssl_enabled endpoint_mechanism = "privateconnect" endpoint_allowed_accounts = ["AWS-ACCOUNT-ID-1","AWS-ACCOUNT-ID-2"]
Set
endpoint_mechanismto"privateconnect"Set
endpoint_allowed_accountsto a comma-separated list of one or more customer account IDs in AWS that will be allowed to establish a private connection to the SkySQL service
Execute the
terraform applycommand:$ terraform apply -var-file="skysql-nr-quickstart.tfvars"
For the next step, see the Connectivity, Controls, & AWS Endpoint Setup sections on this page.
Disable AWS PrivateLink
To disable AWS PrivateLink via the SkySQL Terraform provider:
Alter the
skysql_serviceresource configuration by doing the following:Changing the
endpoint_mechanismattribute to"nlb"Removing the
endpoint_allowed_accountsattributeAdding the
allow_listattribute
For example, if you started with the following attributes after
ssl_enabled:ssl_enabled = var.ssl_enabled endpoint_mechanism = "privateconnect" endpoint_allowed_accounts = ["AWS-ACCOUNT-ID-1","AWS-ACCOUNT-ID-2"]
You could disable AWS PrivateLink by changing the attributes to the following:
ssl_enabled = var.ssl_enabled endpoint_mechanism = "nlb" allow_list = [ { "ip" : var.ip_address, "comment" : var.ip_address_comment } ]
Execute the
terraform applycommand:$ terraform apply -var-file="skysql-nr-quickstart.tfvars"
Connectivity
When a SkySQL service has the privateconnect endpoint mechanism, public endpoints are disabled and connections can only occur through private endpoints.
Client connections can originate from private IP addresses in the linked VPC.
For topologies with MariaDB MaxScale, client connections occur through MaxScale.
Replication can be configured with private IP addresses in the linked VPC.
AWS PrivateLink supports DNS propagation which can be configured to resolve the Database FQDN to the private IP for an internal DNS request. The private DNS names feature must be enabled on the customer's VPC.
Controls
The SkySQL IP Allowlist is not used with the privateconnect endpoint mechanism.
With AWS PrivateLink, connections are restricted to the list of allowed accounts that were specified when configuring the SkySQL endpoint.
Further restrictions are controlled through the customer's AWS account. VPC security group policies apply. For detailed information, see "Control traffic to resources using security groups" (Amazon documentation).
Some customers using AWS PrivateLink may choose to disable TLS, but MariaDB recommends keeping TLS enabled for extra security.
Endpoint changes can be destructive, resulting in downtime. When you change the connection type from private to public, or public to private, the endpoint must be destroyed and recreated. Changing the SkySQL endpoint between nlb and privateconnect will result in a service interruption.
Connections to SkySQL services by features such as SkySQL backups, and monitoring do not depend on AWS PrivateLink.
Query Editor is not supported when AWS PrivateLink is enabled.
AWS Endpoint Setup
In addition to switching the SkySQL service to the privateconnect endpoint mechanism, an AWS Endpoint must be created using the customer's AWS account in order for the SkySQL service to become accessible.
Log in to the AWS console.
Confirm the correct region is selected.
Navigate to the "VPC" page, then the "Endpoint" section.
Click the "Create Endpoint" button.
Fill in the name to help you to identify it. (This is optional.)
Set the Service category to "Other endpoint services".
The value for the "Service name" field must be set to the value of the
endpoint_servicethat was queried from the SkySQL DBaaS API (as detailed earlier).Click "Verify service". AWS should find the service and auto-populate the rest of the form.
In the VPC search field, find the VPC that you want to use for the interconnect between the clients and the SkySQL service.
In the Subnets section, it is suggested that you select all the Availability Zones in the list, entering the proper subnet ID for each one. If you are unsure, view the details of your running instances to see the Subnet ID that they have configured.
Select IPv4 for "IP address type".
For the "Security Groups" section, we suggest that you create a new security group that will regulate which instances can make a connection to the database.
In a new browser tab, use the AWS console to visit the "Security Groups" settings (under Network & Security).
Click on the "Create security group" button.
Fill in the group's name and (optionally) its description.
Under "Inbound rules" click the "Add rule" button.
Set the value for the "Port range" to be the port number that the API revealed for the "
readwrite" endpoint.Set the Source to either a list of private (internal) IPv4 addresses that you want to authorize (adding a "/32" suffix to each one), or set it to an existing security group name that can be used to authorize all instances that have that security group in their configuration.
Press the "Create security group" button.
Back on the endpoint tab, click the refresh button on the "Security Groups" section and choose the newly created security group.
Optionally add a "Name" tag for easy identification.
Press the "Create endpoint" button. Endpoint creation may take several minutes. When complete, status will change from "Pending" to "Available".
In the details of the new endpoint will be a list of DNS names. Copy the first name in the list and use that as the hostname for your clients to use when they connect.
The newly created endpoint now authorizes the internal IPs or security groups that you specified in the Source values to access the SkySQL service's connection port. When testing a client connection, ensure that the client host is authorized by the security group's Source settings and that you're using the "readwrite" port plus the appropriate username and password (either the default values or the value for any user you have created).