Set up a private link on AWS

Overview

This guide shows how to set up a private link on AWS, connecting a deployed LiveKit agent to a private service in your AWS network over AWS PrivateLink. To learn more, see Private Links.

You expose your service in AWS, then create the private link with the LiveKit CLI.

Prerequisites

Before you begin, make sure you have the following:

• A LiveKit Cloud project linked to the LiveKit CLI.
• A deployed agent in a supported LiveKit region.
• AWS permissions to create endpoint services and approve connection requests.
• An AWS Network Load Balancer (NLB)  in front of your service, with healthy targets.
• The TCP port your agent needs to reach. This is the port configured for your NLB listener.

Your NLB must meet the following requirements:

• A listener for the required TCP or TLS port.
• A target group whose targets are all healthy.
• At least two Availability Zones.
• A subnet in the supported Availability Zone for the AWS region of your endpoint service. If your targets are in other Availability Zones, turn on cross-zone load balancing.
• Security groups and network ACLs that permit the expected traffic.

Find the supported zone name

AWS maps Availability Zone names, such as us-east-1a, to Availability Zone IDs differently for each account, so the same name can be a different zone in your account. The supported zone for each region is an ID, such as use1-az1. To find the name that maps to the supported ID for your region, run the following command:

aws ec2 describe-availability-zones \
  --region <AWS_REGION> \
  --query "AvailabilityZones[?ZoneId=='<SUPPORTED_AZ_ID>'].ZoneName" \
  --output text

Step 1: Create an endpoint service

Private Links connect to an AWS endpoint service backed by a Network Load Balancer (NLB).

Step 2: Create a private link in LiveKit

Create a link with the LiveKit CLI or the LiveKit Cloud dashboard. For all CLI options, see the private-link create reference.

lk --project <LIVEKIT_PROJECT> agent private-link create \
  --name <LINK_NAME> \
  --region <LIVEKIT_AGENT_REGION> \
  --port <TCP_PORT> \
  --endpoint '<AWS_ENDPOINT_SERVICE_NAME>'

LiveKit derives the AWS region from the endpoint service name, so you don't need to pass it separately. Your endpoint service doesn't need to be in the same region as your agent, but using the same region reduces latency. For a list of supported regions, see Supported providers and regions.

For example, the following command creates a private link named customer-redis to an endpoint service in the us-east-1 AWS region:

lk --project production agent private-link create \
  --name customer-redis \
  --region us-east \
  --port 6379 \
  --endpoint 'com.amazonaws.vpce.us-east-1.vpce-svc-0a1b2c3d4e5f67890'

Save the private link ID and the generated *.link hostname for later use.

Step 3: Approve the connection in AWS

After you create the link, LiveKit requests a connection to your endpoint service. You must approve the request in AWS. The request comes from the LiveKit AWS account, 266092630715.

The connection can take a few minutes to appear while LiveKit provisions resources.

Step 4: Confirm the link is healthy

Check the link status before you connect from your agent. The link moves through PROVISIONING and PENDING_APPROVAL states before reaching HEALTHY. Wait for a HEALTHY status before you connect. For the full list of statuses, see Status values.

Check the link status using the CLI or the LiveKit Cloud dashboard:

lk --project <LIVEKIT_PROJECT> agent private-link health-status \
  --id <PRIVATE_LINK_ID>

Step 5: Test from your agent

The *.link hostname resolves only from a deployed agent, so run any connectivity test from within your agent runtime, not locally.

The following Python code opens 20 connections in a row and fails if any of them don't succeed:

import socket

host = "<GENERATED_HOSTNAME>.link"
port = <TCP_PORT>
attempts = 20
successes = 0

for attempt in range(1, attempts + 1):
    try:
        # The .link hostname resolves only inside the agent runtime.
        with socket.create_connection((host, port), timeout=10):
            successes += 1
            print(f"success: {attempt}/{attempts}")
    except Exception as error:
        print(f"failure: {attempt}/{attempts}: {error}")

if successes != attempts:
    raise RuntimeError(f"Private Links test failed: {successes}/{attempts} succeeded")

After you confirm TCP connectivity, send a real request to your service (for example, a Redis PING or a database query) to verify authentication, TLS, and end-to-end behavior.

Troubleshooting

Use the following sections to diagnose problems when you set up a private link on AWS.

Common issues

The following table includes common issues that can occur when setting up a private link on AWS.

Link stays in provisioning

A link that stays in the PROVISIONING status with no connection request on the Endpoint connections tab of your endpoint service usually means your endpoint service has no Availability Zone in common with LiveKit. LiveKit reaches your endpoint service through one Availability Zone for each AWS region, listed in Supported providers and regions, so your NLB must include a subnet in that zone.

To fix the problem, do the following:

1. Find the name of the supported Availability Zone in your account. For example, use1-az1 for us-east-1.

2. Enable the zone on your NLB:

   1. In the AWS Console, select EC2 → Load Balancers and select your NLB.
   2. On the Network mapping tab, select Edit subnets.
   3. Select the supported Availability Zone and a subnet in it. If your VPC doesn't have a subnet in that zone, create one first.
   4. Select Save changes.

3. If your targets are in other Availability Zones, turn on cross-zone load balancing so the NLB can reach them from the supported zone:

   1. In the AWS Console, select EC2 → Load Balancing → Target Groups and select each target group your NLB forwards to.
   2. On the Attributes tab, select Edit.
   3. For Cross-zone load balancing, select On, then select Save changes.

   If your NLB forwards to an Application Load Balancer, the target group type is alb and the target group has no cross-zone setting of its own. Turn on cross-zone load balancing on the Attributes tab of your NLB instead. To learn more, see Cross-zone load balancing  in the AWS documentation.

   AWS charges for data transfer between Availability Zones when cross-zone load balancing is on. To learn more, see Cross-zone load balancing for target groups  in the AWS documentation.

4. Wait a few minutes for the NLB changes to propagate, then refresh your endpoint service configuration:

   aws ec2 modify-vpc-endpoint-service-configuration \
     --region <AWS_REGION> \
     --service-id <SERVICE_ID>

   Run the command once for each endpoint service, not once for each private link. For example, if two private links share one endpoint service, run it once.

5. Confirm the zones your endpoint service covers:

   aws ec2 describe-vpc-endpoint-service-configurations \
     --region <AWS_REGION> \
     --service-ids <SERVICE_ID> \
     --query "ServiceConfigurations[].{Service:ServiceId,NLBs:NetworkLoadBalancerArns,Zones:AvailabilityZones,ZoneIds:AvailabilityZoneIds}" \
     --output json

   Check that the supported Availability Zone ID for your region appears in the ZoneIds list.

LiveKit retries provisioning automatically, so you don't need to create a new private link. After the retry succeeds, the link moves to PENDING_APPROVAL and the connection request appears on your endpoint service. To approve it, see Approve the connection in AWS.

Additional resources

The following topics provide additional information about Private Links.