Edit

Connect an Azure Kubernetes Service cluster to Azure Arc

  • Article

Applies to: AKS on Azure Stack HCI 22H2, AKS on Windows Server

When an Azure Kubernetes Service (AKS) cluster is attached to Azure Arc, it gets an Azure Resource Manager representation. Clusters are attached to standard Azure subscriptions, are located in a resource group, and can receive tags just like any other Azure resource. Also the Kubernetes representation allows you to extend the following capabilities onto your Kubernetes cluster:

  • Management services: configurations (GitOps), Azure Monitor for containers, Azure Policy (Gatekeeper).
  • Data services: SQL Managed Instance, PostgreSQL Hyperscale.
  • Application services: App Service, Functions, Event Grid, Logic Apps, API Management.

To connect a Kubernetes cluster to Azure, the cluster administrator must deploy agents. These agents run in a Kubernetes namespace named azure-arc and are standard Kubernetes deployments. The agents are responsible for connectivity to Azure, collecting Azure Arc logs and metrics, and enabling the previously mentioned scenarios on the cluster.

AKS supports industry-standard SSL to secure data in transit. Also, data is stored encrypted at rest in an Azure Cosmos DB database to ensure data confidentiality.

The following steps describe how to connect AKS clusters to Azure Arc in AKS enabled by Arc. You can skip these steps if you've already connected your Kubernetes cluster to Azure Arc using Windows Admin Center.

Before you begin

Verify that you have the following requirements:

  • An AKS cluster with at least one Linux worker node that's up and running.
  • Install the AksHci PowerShell module.
  • The following access level on your Azure subscription:
    • A user account with the built-in Owner role. You can check your access level by navigating to your subscription, selecting "Access control (IAM)" on the left hand side of the Azure portal, and then clicking on View my access.
    • A service principal with the built-in Owner role.
  • Run the commands in this article in a PowerShell administrative window.
  • Ensure that you have met the network requirements of AKS.

Step 1: Sign in to Azure

To sign in to Azure, run the Connect-AzAccount PowerShell command:

Connect-AzAccount $tenantId

If you want to switch to a different subscription, run the Set-AzContext PowerShell command:

Set-AzContext -Subscription $subscriptionId

Step 2: Register the two providers for AKS

You can skip this step if you've already registered the two providers for AKS on your subscription. Registration is an asynchronous process and needs to occur once per subscription. Registration can take approximately 10 minutes:

Register-AzResourceProvider -ProviderNamespace Microsoft.Kubernetes
Register-AzResourceProvider -ProviderNamespace Microsoft.KubernetesConfiguration
Register-AzResourceProvider -ProviderNamespace Microsoft.ExtendedLocation

You can check if you're registered with the following commands:

Get-AzResourceProvider -ProviderNamespace Microsoft.Kubernetes
Get-AzResourceProvider -ProviderNamespace Microsoft.KubernetesConfiguration
Get-AzResourceProvider -ProviderNamespace Microsoft.ExtendedLocation

Step 3: Connect to Azure Arc using the Aks-Hci PowerShell module

Connect your AKS cluster to Kubernetes using the Enable-AksHciArcConnection PowerShell command. This step deploys Azure Arc agents for Kubernetes into the azure-arc namespace:

Enable-AksHciArcConnection -name $clusterName

Connect your AKS cluster to Azure Arc using a service principal

If you don't have access to a subscription on which you're an "Owner", you can connect your AKS cluster to Azure Arc using a service principal.

The first command prompts for service principal credentials and stores them in the credential variable. Enter your application ID for the username and then use the service principal secret as the password when prompted. Make sure you get these values from your subscription admin. The second command connects your cluster to Azure Arc using the service principal credentials stored in the credential variable:

$Credential = Get-Credential
Enable-AksHciArcConnection -name $clusterName -subscriptionId $subscriptionId -resourceGroup $resourceGroup -credential $Credential -tenantId $tenantId -location $location

Make sure the service principal used in the command above has the "Owner" role assigned to it and that it has scope over the subscription ID used in the command. For more information about service principals, see Create a service principal with Azure PowerShell.

Connect your AKS cluster to Azure Arc and enable custom locations

If you want to enable custom locations on your cluster along with Azure Arc, run the following command to get the object ID of the custom location application, and then connect to Azure Arc using a service principal:

$objectID = (Get-AzADServicePrincipal -ApplicationId "bc313c14-388c-4e7d-a58e-70017303ee3b").Id
Enable-AksHciArcConnection -name $clusterName -subscriptionId $subscriptionId -resourceGroup $resourceGroup -credential $Credential -tenantId $tenantId -location -customLocationsOid $objectID

Verify the connected cluster

You can view your Kubernetes cluster resource on the Azure portal. Once you open the portal in your browser, navigate to the resource group and the AKS resource that's based on the resource name and resource group name inputs used in the enable-akshciarcconnection PowerShell command.

Note

After you connect the cluster, it can take a maximum of approximately five to ten minutes for the cluster metadata (cluster version, agent version, number of nodes) to surface on the overview page of the AKS resource in Azure portal.

Azure Arc agents for Kubernetes

AKS deploys a few operators into the azure-arc namespace. You can view these deployments and pods with kubectl, as shown in the following example:

kubectl -n azure-arc get deployments,pods

AKS consists of a few agents (operators) that run in your cluster deployed to the azure-arc namespace. For more information about these agents, see this overview.

Disconnect your AKS cluster from Azure Arc

If you want to disconnect your cluster from AKS, run the Disable-AksHciArcConnection PowerShell command. Make sure you sign in to Azure before running the command:

Disable-AksHciArcConnection -Name $clusterName

Next steps