Connect to a PrivateLink Valkey Cluster

Overview

This page describes the steps that need to be taken to connect clients in one VPC to a PrivateLink enabled Instaclustr for Valkey cluster in another VPC. In short, customers need to create a security group, an endpoint with the endpoint service name of the created Valkey PrivateLink cluster, and a Route 53 record to the endpoint created.

Retrieve Required Cluster Connection Information

1. For instructions on how to create a Valkey PrivateLink cluster, please read Creating a Valkey PrivateLink cluster.
2. Login to the console, click the created cluster and enter the Connection Info
   
3. The Connection Info page contains the specific connection details for PrivateLink.
   
4. In the Connection Info page, identify the region of the created PrivateLink Valkey cluster. For instance, the page shows the region is US_EAST_1, hence you need to access the AWS VPC Endpoint console in the US_EAST_1 region: https://us-east-1.console.aws.amazon.com/vpc/home?region=us-east-1#Endpoints
5. If the PrivateLink Valkey cluster and client are in different AWS accounts, please ensure the AWS Principal of the client AWS account is added to allow cross-account access to the endpoint. For more info, please read Managing Principal ARNs of a PrivateLink Cluster.

Create an Endpoint Security Group

A security group is required to allow traffic from your VPC to the PrivateLink endpoint. Your Valkey cluster already has a security group applied to ensure the security of your cluster, but an AWS Endpoint cannot be created without having an associated security group. Therefore, the security group being created here can be as permissive or as strict as you require. These steps will outline the recommended security group configuration.

1. In the AWS Console, select the appropriate region for your VPC and navigate to the Security Groups page.
2. Click “Create security group”.
3. Under the heading “Security group name”, enter a name for the security group. For example, companyName-valkey-privatelink-group. The name cannot be edited after creation; thus, it is recommended to use a naming convention which allows easy identification of the PrivateLink endpoint and destination cluster it will be associated with.
4. Under the heading “Description”, enter a short description of the security group. For example, “Allows access to Valkey cluster via PrivateLink”.
5. Under the heading “VPC”, search for and select the VPC which will connect to the Valkey cluster via PrivateLink.
   
6. Under the Inbound rules heading, click “Add rule”. The rules created here permit traffic outbound from your VPC, inbound to the Valkey cluster over PrivateLink.
   
7. Select Custom TCP in the “Type” field. Enter 6379-6379+n in the “Port range”, where n is the number of nodes in your Valkey cluster. For example, if you are using a 6 node Valkey cluster, the port range should be 6379-6385. If the number of nodes in the Valkey cluster is increased in the future, this port range will need to be extended to match the new number of nodes in the cluster.
8. Click “Create security group”, the security group should be created successfully. Take note of the security group name, as it will be required when creating the Endpoint in the following steps.

Create Endpoint and Route 53 Record

1. On the AWS VPC Endpoint services page, find the endpoint service name in your PrivateLink Valkey cluster.
   
2. Switch to the AWS VPC Endpoint Console page, click “Create endpoint”.
   
3. On the creation page under “Service category”, select “Endpoint services that use NLBs and GWLBs”
4. In “Service Settings”, paste the endpoint service name from step 1 to the “Service name” field. Click “Verify service” and a green box will appear.
5. For “VPC”, select the client’s VPC that will connect to the PrivateLink Valkey cluster. Note, the VPC of the client and PrivateLink Valkey cluster should be in the same region as we do not support inter-region access via PrivateLink.
6. The configuration would then be as follows:
   
7. For “Subnets”, please select one “Subnet ID” for each “Availability Zone”.
8. Select the security group that you created earlier. You will get the following configurations. Once done, click “Create endpoint”.
   
9. You will be redirected to the main VPC endpoint page which will specifically show the created endpoint. Once the Status of the endpoint reaches Available, copy the first DNS under the “DNS names”.
   
10. Head to the Route 53 record home page, enter Hosted Zone and select “Create hosted zones”. https://us-east-1.console.aws.amazon.com/route53/v2/hostedzones?region=us-east-1#
    
11. Find the “URL” in Retrieve Required Cluster Connection Information step 2. Under “Hosted zone configuration”, enter the “URL” without the port and first part of the hostname into “Domain name”. For example for test.com:6379, enter test.com.
12. Select “Private hosted zone” as “Type”.
13. Select the corresponding region and VPC of the client used in step 4.
14. Ensure you have the following configurations, click “Create hosted zone”.
    
15. You will be redirected to the created private hosted zone.
16. Select “Create record”.
    
17. Under “Record name”, place the rest of the “URL” from step 2 without 6379. For instance, the “URL” is test.com:6379 and we entered test.com in step 14. Thus, the remaining URL to be entered is valkey.
18. Click the toggle “Alias” and select “Alias to VPC endpoint” from the dropdown box.
19. Select the same region as the one in step 3 in the next dropdown box.
20. In the last field, paste the endpoint DNS name from step 9.
    
21. The newly created record will be in the hosted zone. You can now connect to the cluster with test.instaclustr-privatelink.com:6379.