LiveKit docs › Manage & Deploy › Agent deployment › Private Links › Set up on Azure

---

# Set up a private link on Azure

> Connect a deployed LiveKit agent to a private service in your Azure network using Azure Private Link.

## 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](https://docs.livekit.io/deploy/agents/private-links.md).

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](https://learn.microsoft.com/en-us/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](https://docs.livekit.io/reference/developer-tools/livekit-cli.md#add-a-project).
- A [deployed agent](https://docs.livekit.io/deploy/agents.md) in a [supported LiveKit region](https://docs.livekit.io/deploy/agents/private-links.md#providers-regions).
- 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:

**Web**:

1. From the [Microsoft Azure portal](https://portal.azure.com/#home), select **All resources**.
2. Select the private link service or Azure service.
3. Select **JSON View**. Copy the `id` value and note the `location` value for the Azure region.

---

**CLI**:

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

```

For the full reference, see [`az resource show`](https://learn.microsoft.com/en-us/cli/azure/resource?view=azure-cli-latest#az-resource-show).

The Resource ID has the following form:

**Azure PaaS resource**:

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

```

---

**Private Link Service**:

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

```

For a Private Link Service, `--endpoint` also accepts its alias instead of the Resource ID. Azure generates the alias when the service is created, in the form `<PLS_NAME>.<GENERATED_ID>.<AZURE_REGION>.azure.privatelinkservice`. Copy it from the service's `alias` property in JSON view, or run `az network private-link-service show -g <RESOURCE_GROUP> -n <PRIVATE_LINK_SERVICE_NAME> --query alias -o tsv`.

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](https://docs.livekit.io/reference/developer-tools/livekit-cli/agent/deployment/private-links.md#create).

**Web**:

1. Navigate to your project **Settings** page (https://cloud.livekit.io/projects/p_/settings/private-links) → **Private links**.
2. Select **Create new private link**.
3. Enter a name for the link and complete all other fields:
   - For **LiveKit region**, select the region your agent is deployed to.
   - For **Cloud provider**, select **Azure**.
   - For **Cloud region**, enter the Azure region your resource lives in. For example, `eastus`.
   - The **Port** field must match the secure TCP port your service listens on.
   - For **Endpoint**, enter the Azure Resource ID of your Private Link Service or Azure PaaS resource.
4. Select **Create**.

---

**CLI**:

```shell
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>'

```

Replace the following:

- <LIVEKIT_PROJECT>: Name of the project you want to create the link in.
- <LINK_NAME>: Name of the link you want to create.
- <LIVEKIT_AGENT_REGION>: Region your LiveKit agent is deployed to.
- <AZURE_REGION>: Azure region the resource lives in.
- <TCP_PORT>: Port your agent needs to reach. It must match the secure TCP port your service listens on.
- <AZURE_RESOURCE_ID>: Resource ID of the Azure Private Link Service or Azure PaaS resource.

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](https://docs.livekit.io/deploy/agents/private-links.md#providers-regions).

For example, the following command creates a private link named `customer-redis` to an Azure Managed Redis resource in the `eastus` Azure region:

```shell
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`.

> ℹ️ **Links must be in pending approval state to approve**
> 
> Wait for the private link status to reach `PENDING_APPROVAL` before you approve the request in Azure. To view the status, see [Confirm the link is healthy](#confirm-healthy).

**Azure PaaS resource**:

1. From the Microsoft Azure portal, select **All resources**.
2. Select your resource, and select **Administration** → **Networking**.
3. Select the **Private endpoint** tab.
4. Find the pending connection and verify the description is `LiveKit Cloud Agents private link connection`.
5. Select the connection and select **Approve**.

---

**Private Link Service**:

1. From the Microsoft Azure portal, select **All resources**.
2. Select your Private Link Service, and select **Settings** → **Private endpoint connections**.
3. Find the pending connection and verify the description is `LiveKit Cloud Agents private link connection`.
4. Select the connection and select **Approve**.

### 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](#resource-id). For the full CLI reference, see [`az resource`](https://learn.microsoft.com/en-us/cli/azure/resource?view=azure-cli-latest).

1. List the pending connections on your resource. Verify the description is `LiveKit Cloud Agents private link connection` and copy its `id`:

   ```shell
   az resource show --ids "<AZURE_RESOURCE_ID>" \
   --query "properties.privateEndpointConnections[?properties.privateLinkServiceConnectionState.status=='Pending'].{name:name, id:id, description:properties.privateLinkServiceConnectionState.description}" \
   -o json

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

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

   ```

## 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](https://docs.livekit.io/deploy/agents/private-links/monitoring.md#status-values).

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

**Web**:

View the link status on the [**Private links**](https://cloud.livekit.io/projects/p_/settings/private-links) page in the **Status** column.

---

**CLI**:

```shell
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:

```python
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

| Issue | Resolution |
| --- | --- |
| Stuck in pending approval | Approve the connection in Azure. |
| Unhealthy | Verify the Azure load-balancer backend health. |
| Connection timeout | Check the port configuration and Azure network security rules. |
| DNS failure in the agent | Confirm the agent uses the same LiveKit region as the link and the generated `*.link` hostname. |

## Additional resources

The following topics provide additional information about Private Links.

- **[Private Links](https://docs.livekit.io/deploy/agents/private-links.md)**: How Private Links work, supported regions, and limitations.

- **[Azure Private Link service](https://learn.microsoft.com/en-us/azure/private-link/private-link-service-overview)**: Learn more about the Azure Private Link service.

- **[Monitor and manage Private Links](https://docs.livekit.io/deploy/agents/private-links/monitoring.md)**: Check link status and manage links programmatically.

- **[Private Links CLI reference](https://docs.livekit.io/reference/developer-tools/livekit-cli/agent/deployment/private-links.md)**: Reference for the private link commands in the LiveKit CLI.

- **[Set up on AWS](https://docs.livekit.io/deploy/agents/private-links/aws.md)**: Connect through AWS PrivateLink using a Network Load Balancer endpoint service.

---

This document was rendered at 2026-11-14T15:31:17.064Z.
For the latest version of this document, see [https://docs.livekit.io/deploy/agents/private-links/azure.md](https://docs.livekit.io/deploy/agents/private-links/azure.md).

To explore all LiveKit documentation, see [llms.txt](https://docs.livekit.io/llms.txt).