Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Private endpoints bring the Kubernetes Configuration service into your virtual network, so your cluster can communicate with extension services directly without using a public virtual IP address (VIP).
Note
This feature is currently in public preview. For more information, see Supplemental Terms of Use for Microsoft Azure Previews.
Quick reference
| Item | Value |
|---|---|
| Private Link Scope resource name | extension-pls |
| Private Link Scope resource group | Any resource group |
| Resource type | Microsoft.KubernetesConfiguration/privateLinkScopes |
| Target subresource | kubernetesconfiguration |
| DNS zone format | <region>.privatelink.dp.kubernetesconfiguration.azure.com |
Phase 1: Prerequisites
1.0 Authenticate to Azure
az login
This command opens a browser for interactive authentication. For service principal or device code flows, use az login --service-principal or az login --use-device-code.
1.1 Set the active subscription
# List available subscriptions.
az account list --output table
# Set the target subscription.
az account set --subscription <subscription-id>
Note
Provide the subscription ID that contains the AKS cluster and related resources.
| Field | Value |
|---|---|
| Subscription ID |
1.2 Check existing Private Link Scope resources (optional)
Check whether a Private Link Scope resource is already associated with the AKS cluster.
az network private-link-resource list --id <pls-resource-id>
The Private Link Scope resource ID uses the following format:
/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.KubernetesConfiguration/privateLinkScopes/extension-pls
| Field | Value |
|---|---|
| Private Link Scope resource ID |
1.3 Delete an existing Private Link Scope resource (optional)
If you need to remove an existing Private Link Scope resource before setting up a new one, delete it before continuing.
Caution
Confirm that you no longer need the existing resource before deleting it.
az resource delete --id <pls-resource-id>
| Field | Value |
|---|---|
| Private Link Scope resource ID to delete | |
| Deletion confirmed | ⬜ Yes / ⬜ No |
1.4 Create a Private Link Scope resource
Provide the following parameters:
| Parameter | Description | Value |
|---|---|---|
| Private Link Scope name | Name of the resource. The default is extension-pls. |
|
| Resource group | Any resource group. | |
| Location | Azure region. It must match the AKS cluster region. | |
| Cluster resource ID | ARM resource ID of the AKS cluster. | |
| Public network access | Enabled or Disabled. |
az resource create \
--name <pls-name> \
--resource-group <resource-group> \
--resource-type "Microsoft.KubernetesConfiguration/privateLinkScopes" \
--location <location> \
--properties '{"clusterResourceId":"<cluster-arm-id>","publicNetworkAccess":"<Enabled|Disabled>"}'
Example:
az resource create \
--name extension-pls \
--resource-group <resource-group> \
--resource-type "Microsoft.KubernetesConfiguration/privateLinkScopes" \
--location <location> \
--properties '{"clusterResourceId":"/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ContainerService/managedClusters/<cluster-name>","publicNetworkAccess":"Enabled"}'
| Field | Value |
|---|---|
| Creation confirmed | ⬜ Yes / ⬜ No |
| New Private Link Scope ARM resource ID |
1.5 Deploy the Flux extension on the AKS cluster
To deploy the Flux extension and configure GitOps on the AKS cluster, follow Tutorial: Deploy applications by using GitOps with Flux v2.
The tutorial includes the prerequisites and commands required to install the microsoft.flux cluster extension and create a Flux configuration.
Phase 2: Create a private endpoint
Scenario 1: Automatic approval workflow
2.1 Create a private endpoint in the Azure portal
Create a private endpoint by connecting to the Private Link Scope resource in your Azure directory.
In the Azure portal, go to Private endpoints, and then select Create.
On the Basics tab, enter the following values:
Field Value Subscription Same subscription as the AKS cluster. Resource group Any resource group. Name For example, <cluster-name>-pe.Region Must match the AKS cluster region. On the Resource tab, enter the following values:
Field Value Connection method Connect to an Azure resource in my directory Subscription AKS cluster subscription Resource type Microsoft.KubernetesConfiguration/privateLinkScopesResource Select extension-plsfrom its resource groupTarget subresource kubernetesconfigurationOn the Virtual Network tab, enter the following values:
Field Value Virtual network AKS virtual network or another connected virtual network Subnet An appropriate subnet for the private endpoint On the DNS tab, enter the following values:
Field Value Integrate with private DNS zone Yes Private DNS zone Create a new zone or select an existing zone Select Review + create, and then select Create.
| Validation | Result |
|---|---|
| Private endpoint name | |
| Private endpoint resource ID | |
| Connection status | Expected: Approved |
| Private IP address |
2.2 Validate the Private Link Scope configuration
Verify the Private Link Scope resource configuration and confirm that the automatically approved private endpoint connection appears on the resource.
az resource show --ids "<pls-resource-id>"
Example:
az resource show --ids "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.KubernetesConfiguration/privateLinkScopes/extension-pls"
Verify the following fields:
| Field | Expected value |
|---|---|
properties.clusterResourceId |
Matches the AKS cluster ARM resource ID |
properties.publicNetworkAccess |
Enabled or Disabled, as configured |
properties.provisioningState |
Succeeded |
properties.privateEndpointConnections |
Contains the private endpoint |
properties.privateEndpointConnections[].privateLinkServiceConnectionState.status |
Approved |
| Validation | Result |
|---|---|
| Cluster resource ID matches | ⬜ Yes / ⬜ No |
| Provisioning state | |
| Private endpoint connection status | Expected: Approved |
Scenario 2: Manual approval workflow
2.3 Create a private endpoint that requires manual approval
Create a private endpoint by specifying the Private Link Scope resource ID or alias. This workflow requires the private endpoint connection to be approved separately.
In the Azure portal, go to Private endpoints, and then select Create.
On the Basics tab, enter the following values:
Field Value Subscription Same subscription as the AKS cluster. Resource group Any resource group. Name For example, <cluster-name>-pe-manual.Region Must match the AKS cluster region. On the Resource tab, enter the following values:
Field Value Connection method Connect to an Azure resource by resource ID or alias Resource ID or alias Private Link Scope ARM resource ID Target subresource kubernetesconfigurationOn the Virtual Network tab, enter the following values:
Field Value Virtual network AKS virtual network or another connected virtual network Subnet An appropriate subnet for the private endpoint On the DNS tab, enter the following values:
Field Value Integrate with private DNS zone Yes Private DNS zone Create a new zone or select an existing zone Select Review + create, and then select Create.
Note
The private endpoint connection remains in the Pending state until it is approved.
| Validation | Result |
|---|---|
| Private endpoint name | |
| Private endpoint resource ID | |
| Connection status | Expected: Pending |
2.4 List pending private endpoint connections
List the private endpoint connections on the Private Link Scope resource to obtain the connection ID required for approval.
az network private-endpoint-connection list --id <pls-resource-id>
Example:
az network private-endpoint-connection list \
--id /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.KubernetesConfiguration/privateLinkScopes/extension-pls
Look for a connection where privateLinkServiceConnectionState.status is Pending:
[
{
"id": "/subscriptions/.../privateEndpointConnections/<connection-name>",
"name": "<connection-name>",
"properties": {
"privateLinkServiceConnectionState": {
"status": "Pending",
"description": "...",
"actionsRequired": "None"
}
}
}
]
Note
Copy the full connection id for use in the approval step.
| Validation | Result |
|---|---|
| Connection name | |
| Connection ID | |
| Connection status | Expected: Pending |
2.5 Approve the private endpoint connection
Approve the pending private endpoint connection to establish the private link.
az network private-endpoint-connection approve \
--id "<private-endpoint-connection-id>" \
--description "Approved from Azure CLI"
The connection ID uses the following format:
<pls-resource-id>/privateEndpointConnections/<connection-name>
The command should change privateLinkServiceConnectionState.status from Pending to Approved.
| Validation | Result |
|---|---|
| Connection ID | |
| Approval description | |
| Connection status after approval | Expected: Approved |
2.6 Manage private endpoint connections (optional)
Reject a pending or approved connection:
az network private-endpoint-connection reject \
--id "<private-endpoint-connection-id>" \
--description "Rejected"
Delete a private endpoint connection:
az network private-endpoint-connection delete \
--id "<private-endpoint-connection-id>"
Use reject to deny access while retaining the connection record. Use delete to remove the connection record.
Phase 3: Validate Flux pods and runtime traffic
3.1 Get AKS cluster credentials
Connect to the AKS cluster to validate Flux pods and extension agent traffic.
| Parameter | Description | Value |
|---|---|---|
| Resource group | Resource group that contains the AKS cluster | |
| Cluster name | Name of the AKS cluster |
az aks get-credentials --resource-group <resource-group> --name <cluster-name>
Example:
az aks get-credentials --resource-group <resource-group> --name <cluster-name>
Expected output:
Merged "<cluster-name>" as current context in C:\Users\<user>\.kube\config
3.2 Validate Flux agent communication with the data plane
Check the Flux agent logs to confirm successful communication with the Kubernetes Configuration data plane service.
Get the Flux agent pod name:
kubectl get pods -n flux-system
Review the Flux agent logs:
kubectl logs -n flux-system <fluxconfig-agent-pod-name> --since 5m
Example:
kubectl logs -n flux-system fluxconfig-agent-59cbf99d6f-v5zdg --since 5m
Look for log entries similar to the following:
{"Message":"URL:> https://<region>.dp.kubernetesconfiguration.azure.com/subscriptions/<subscription-id>/resourceGroups/<resource-group>/provider/Microsoft.ContainerService-managedclusters/clusters/<cluster-name>/configurations/getPendingConfigs?api-version=..."}
{"Message":"Successful DP call. Endpoint: getPendingConfigs, ResponseCode: 200"}
| Validation | Result |
|---|---|
| Fluxconfig agent pod name | |
| Data plane URL present in logs | ⬜ Yes / ⬜ No |
| Successful data plane call with HTTP 200 | ⬜ Yes / ⬜ No |
| Errors present in logs | ⬜ Yes / ⬜ No |
3.3 Verify DNS resolution to a private IP address
Confirm that the Kubernetes Configuration data plane endpoint resolves to a private IP address.
| Parameter | Description | Value |
|---|---|---|
| Fluxconfig agent pod name | Pod name from step 3.2 | |
| Region | AKS cluster region |
kubectl exec -it -n flux-system <fluxconfig-agent-pod-name> -c fluxconfig-agent -- \
timeout 5 openssl s_client -connect <region>.dp.kubernetesconfiguration.azure.com:443 -brief
Example:
kubectl exec -it -n flux-system fluxconfig-agent-59cbf99d6f-v5zdg -c fluxconfig-agent -- \
timeout 5 openssl s_client -connect centraluseuap.dp.kubernetesconfiguration.azure.com:443 -brief
Expected output includes a successful TLS connection:
CONNECTION ESTABLISHED
Protocol version: TLSv1.3
Ciphersuite: TLS_AES_256_GCM_SHA384
Peer certificate: ...
| Result | Meaning | Status |
|---|---|---|
Resolves to 10.x.x.x |
Private endpoint is working | |
| Resolves to a public IP address | Traffic isn't using the private endpoint |
| Validation | Result |
|---|---|
| Resolved IP address | |
Private IP address (10.x.x.x) |
⬜ Yes / ⬜ No |
3.4 Disable public network access on the Private Link Scope resource
After completing steps 3.1 through 3.3, disable public network access on the Private Link Scope resource to enforce private-only connectivity.
az resource update \
--ids "<pls-resource-id>" \
--set properties.publicNetworkAccess="Disabled"
Example:
az resource update \
--ids "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.KubernetesConfiguration/privateLinkScopes/extension-pls" \
--set properties.publicNetworkAccess="Disabled"
Expected results:
properties.publicNetworkAccessis set toDisabled.- Extension agent traffic routes through the private endpoint.
- Public network requests are blocked.
| Validation | Result |
|---|---|
| Private Link Scope resource ID | |
| Public network access | Expected: Disabled |
Troubleshooting
Private Link Scope resource isn't created
- Check whether hidden resource types are enabled in the Azure portal.
- Confirm that the
Microsoft.KubernetesConfigurationresource provider is registered. - Review the Azure CLI output for permission or resource property errors.
Private endpoint connection remains pending
- Check if manual approval is required.
- Verify your permissions on the Private Link Scope resource.
- Ensure you're using the correct connection ID in the approval command.
DNS doesn't resolve to a private IP address
- Verify that the private DNS zone is linked to the virtual network.
- Confirm that the required DNS
Arecord exists. - Review custom DNS settings for the virtual network.
Agent logs show errors
- Check the agent pod status.
- Verify that network policies allow required egress traffic.
- Confirm that the private endpoint connection is approved.
- Confirm that the data plane endpoint resolves through the private DNS zone.