Deploy an Azure Kubernetes Service host with pre-staged cluster service objects and DNS records using PowerShell

  • Article

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

This how-to guide describes how to use PowerShell to configure your AKS host deployment if you pre-staged cluster service objects and DNS records in AKS enabled by Azure Arc.

Before you begin

Step 1: Prepare your Active Directory and DNS server for deployment

If you can't enable dynamic DNS updates in your DNS environment to allow AKS enabled by Arc to register the cloud agent generic cluster name in Active Directory and the DNS system for discovery, you must pre-create the respective records in Active Directory and DNS.

Create a generic cluster service in Active Directory with the name ca-cloudagent (or a name of your choice that doesn't exceed 32 characters). Also, create an associated DNS record that points to the FQDN of the generic cluster service with the provided cloudservicecidr address. For more information about the steps in this process, see the failover clustering documentation.

The AKS deployment attempts to locate the specified clusterRoleName in Active Directory before proceeding with the deployment.

Note

Once AKS is deployed, this information cannot be changed.

Step 2: Prepare your machines for deployment

Run checks on every physical node to see if all the requirements are satisfied to install AKS Arc. Open PowerShell as an administrator and run the following Initialize-AksHciNode command:

Initialize-AksHciNode

Step 3: Create a virtual network

To create a virtual network for the nodes in your deployment to use, create an environment variable with the New-AksHciNetworkSetting PowerShell command. This variable is used later to configure a deployment that uses static IP. If you want to configure your AKS deployment with DHCP, see New-AksHciNetworkSetting for examples. You can also review some networking node concepts.

# static IP
$vnet = New-AksHciNetworkSetting -name mgmt-vnet -vSwitchName "extSwitch" -k8sNodeIpPoolStart "172.16.10.1" -k8sNodeIpPoolEnd "172.16.10.255" -vipPoolStart "172.16.255.0" -vipPoolEnd "172.16.255.254" -ipAddressPrefix "172.16.0.0/16" -gateway "172.16.0.1" -dnsServers "172.16.0.1"

Note

You must customize the values shown in this example command for your environment.

Step 4: Configure your deployment with the pre-staged cluster service objects and DNS records

Set the configuration settings for the AKS host using the Set-AksHciConfig command. You must specify the workingDir, cloudServiceCidr, cloudConfigLocation, and clusterRoleName parameters. If you want to reset your configuration details, run the command again with new parameters.

Configure your deployment with the following command:

Set-AksHciConfig -workingDir c:\ClusterStorage\Volume1\workingDir -cloudConfigLocation c:\clusterstorage\volume1\Config -vnet $vnet -cloudservicecidr "172.16.10.10/16" -clusterRoleName "ca-cloudagent"

Note

Customize the values shown in this example command for your environment.

Step 5: Sign in to Azure and configure registration settings

Run the following Set-AksHciRegistration PowerShell command with your subscription and resource group name to sign into Azure. You must have an Azure subscription, and an existing Azure resource group in the East US, Southeast Asia, or West Europe Azure regions to proceed:

Set-AksHciRegistration -subscriptionId "<subscriptionId>" -resourceGroupName "<resourceGroupName>"

Step 6: Start a new deployment

After you configure your deployment, you must start it. Starting the deployment installs the AKS agents/services and the AKS host. To begin the deployment, run the following command:

Install-AksHci

Warning

During installation of your AKS host, a Kubernetes - Azure Arc resource type is created in the resource group that's set during registration. Do not delete this resource, as it represents your Azure Kubernetes Service host. You can identify the resource by checking its distribution field for the aks_management value. Deleting this resource results in an out-of-policy deployment.

Next steps