Set up a private link on Azure

Overview

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

A private link connects to one of two kinds of Azure resource types, and this guide covers both:

• Azure PaaS resource: an Azure service that supports Private Link, such as Azure Managed Redis or Azure SQL Database. This guide uses "Azure PaaS resource" for this option throughout. For the services that support Private Link, see Azure Private Link availability .
• Azure Private Link Service: a service you expose yourself, behind a Standard Load Balancer.

Where a step differs between the two, select the matching tab.

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.
• An Azure Private Link Service with a healthy load-balancer backend in front of your service, or an Azure PaaS resource.
• The TCP port your agent needs to reach.
• Azure permissions to approve private endpoint connections.

Step 1: Get your resource ID

Private Links connect to an Azure resource by its Resource ID. The resource is either an Azure Private Link Service with a healthy load-balancer backend, or an Azure PaaS resource.

Get the full Resource ID from the Azure portal or the CLI:

az resource show -g <RESOURCE_GROUP> -n <RESOURCE_NAME> \
  --resource-type <RESOURCE_TYPE> \
  --query "{id:id, location:location}" -o json

The Resource ID has the following form:

/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/<RESOURCE_TYPE>/<RESOURCE_NAME>

/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.Network/privateLinkServices/<PRIVATE_LINK_SERVICE_NAME>

Use the Resource ID, not an IP address or existing private endpoint ID. For an Azure PaaS resource, use the ID for the resource itself, not the ID of a Private Link Service unless you created a custom one.

Step 2: Create the link in LiveKit

Create the 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> \
  --cloud-region <AZURE_REGION> \
  --port <TCP_PORT> \
  --endpoint '<AZURE_RESOURCE_ID>'

Your Azure resource 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 Azure Managed Redis resource in the eastus Azure region:

lk --project my-livekit-project agent private-link create \
  --name customer-redis \
  --region us-east \
  --cloud-region eastus \
  --port 10000 \
  --endpoint '<AZURE_RESOURCE_ID>'

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

Step 3: Approve the connection

After you create the link, LiveKit requests a connection to your resource. You must approve the request in Azure. After you approve, the connection can take a few minutes to appear while LiveKit provisions resources.

Approve using the Azure portal

Use the Azure portal to approve the connection request. The subscription ID for the LiveKit principal in Azure is 62efb9e1-9210-4ce9-a84c-f56616ff0def.

Approve using the CLI

The az resource commands work with any resource type that supports Private Link, including both an Azure PaaS resource and a Private Link Service, and resolve the correct API version from the resource ID. Use the Resource ID you retrieved in Step 1. For the full CLI reference, see az resource .

1. List the connections on your resource and find the one whose status is Pending. Copy its id:

   az resource show --ids "<AZURE_RESOURCE_ID>" \
     --query "properties.privateEndpointConnections" -o json

2. Approve the connection using its id from the previous step:

   az resource update --ids "<CONNECTION_ID>" \
     --set properties.privateLinkServiceConnectionState.status=Approved \
     --set properties.privateLinkServiceConnectionState.description="Approved" \
     -o none

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

Additional resources

The following topics provide additional information about Private Links.