Set up an Azure Kubernetes Service host on Azure Stack HCI and Windows Server and deploy a workload cluster using PowerShell

Applies to: Azure Stack HCI or Windows Server Datacenter

This quickstart guides you through setting up an Azure Kubernetes Service (AKS) host. You create Kubernetes clusters on Azure Stack HCI and Windows Server using PowerShell. To use Windows Admin Center instead, see Set up with Windows Admin Center.

Before you begin

• Make sure you have satisfied all the prerequisites in system requirements.
• Use an Azure account to register your AKS host for billing. For more information, see Azure requirements.

Install the AksHci PowerShell module

Follow these steps on all nodes in your Azure Stack HCI cluster or Windows Server cluster:

1. Close all open PowerShell windows, open a new PowerShell session as administrator, and run the following command on all nodes in your Azure Stack HCI or Windows Server cluster:

   Install-PackageProvider -Name NuGet -Force 
   Install-Module -Name PowershellGet -Force -Confirm:$false
   

   You must close all existing PowerShell windows again to ensure that loaded modules are refreshed. Don't continue to the next step until you close all open PowerShell windows.

2. Install the AKS-HCI PowerShell module by running the following command on all nodes in your Azure Stack HCI or Windows Server cluster:

   Install-Module -Name AksHci -Repository PSGallery -Force -AcceptLicense
   

   You must close all existing PowerShell windows again to ensure that loaded modules are refreshed. Don't continue to the next step until you close all open PowerShell windows.

You can use a helper script to delete old AKS-HCI PowerShell modules, to avoid any PowerShell version-related issues in your AKS deployment.

Validate your installation

Get-Command -Module AksHci

To view the complete list of AksHci PowerShell commands, see AksHci PowerShell.

Register the resource provider to your subscription

Before the registration process, enable the appropriate resource provider in Azure for AKS enabled by Arc registration. To do that, run the following PowerShell commands:

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

Connect-AzAccount

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

Set-AzContext -Subscription "xxxx-xxxx-xxxx-xxxx"

Run the following commands to register your Azure subscription to Azure Arc enabled Kubernetes resource providers. This registration process can take up to 10 minutes, but it only needs to be performed once on a specific subscription:

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

To validate the registration process, run the following PowerShell commands:

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

Step 1: Prepare your machine(s) for deployment

Run checks on every physical node to see if all the requirements to install AKS enabled by Arc are satisfied. Open PowerShell as an administrator and run the following Initialize-AksHciNode command on all nodes in your Azure Stack HCI and Windows Server cluster:

Initialize-AksHciNode

Step 2: Create a virtual network

Run the following commands on any one node in your Azure Stack HCI and Windows Server cluster.

To get the names of your available switches, run the following command. Make sure the SwitchType of your VM switch is "External":

Get-VMSwitch

Sample output:

Name        SwitchType     NetAdapterInterfaceDescription
----        ----------     ------------------------------
extSwitch   External       Mellanox ConnectX-3 Pro Ethernet Adapter

To create a virtual network for the nodes in your deployment to use, create an environment variable with the New-AksHciNetworkSetting PowerShell command. This virtual network 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 myvnet -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" -vlanId 9

Step 3: Configure your deployment

Run the following commands on any one node in your Azure Stack HCI and Windows Server cluster.

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

Configure your deployment with the following command:

$csvPath = 'C:\clusterstorage\volume01' # Specify your preferred CSV path
Set-AksHciConfig -imageDir $csvPath\Images -workingDir $csvPath\ImageStore -cloudConfigLocation $csvPath\Config -vnet $vnet

Step 4: Sign in to Azure and configure registration settings

Option 1: Use your Microsoft Entra account if you have "Owner" permissions

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

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

Option 2: Use an Azure service principal

If you don't have access to a subscription on which you're an "Owner", you can register your AKS host to Azure for billing using a service principal. For more information about how to use a service principal, see register AKS on Azure Stack HCI and Windows Server using a service principal.

Step 5: Start a new deployment

Run the following command on any one node in your Azure Stack HCI or Windows Server cluster.

After you configure your deployment, you must start it in order to install the AKS agents/services and the AKS host. To begin deployment, run the following command:

Install-AksHci

Step 6: Create a Kubernetes cluster

After you install your AKS host, you can deploy a Kubernetes cluster. Open PowerShell as an administrator and run the following New-AksHciCluster command. This example command creates a new Kubernetes cluster with one Linux node pool named linuxnodepool with a node count of 1.

For more information about node pools, see Use node pools in AKS.

New-AksHciCluster -name mycluster -nodePoolName linuxnodepool -nodeCount 1 -osType Linux

Check your deployed clusters

To get a list of your deployed Kubernetes clusters, run the following Get-AksHciCluster PowerShell command:

Get-AksHciCluster

ProvisioningState     : provisioned
KubernetesVersion     : v1.20.7
NodePools             : linuxnodepool
WindowsNodeCount      : 0
LinuxNodeCount        : 0
ControlPlaneNodeCount : 1
Name                  : mycluster

To get a list of the node pools in the cluster, run the following Get-AksHciNodePool PowerShell command:

Get-AksHciNodePool -clusterName mycluster

ClusterName  : mycluster
NodePoolName : linuxnodepool
Version      : v1.20.7
OsType       : Linux
NodeCount    : 1
VmSize       : Standard_K8S3_v1
Phase        : Deployed

Step 7: Connect your cluster to Arc-enabled Kubernetes

Connect your cluster to Arc-enabled Kubernetes by running the Enable-AksHciArcConnection command. The following example connects your Kubernetes cluster to Arc using the subscription and resource group details you passed in the Set-AksHciRegistration command:

Connect-AzAccount
Enable-AksHciArcConnection -name mycluster

Scale a Kubernetes cluster

If you need to scale your cluster up or down, you can change the number of control plane nodes by using the Set-AksHciCluster command. To change the number of Linux or Windows worker nodes in your node pool, use the Set-AksHciNodePool command.

To scale control plane nodes, run the following command:

Set-AksHciCluster -name mycluster -controlPlaneNodeCount 3

To scale the worker nodes in your node pool, run the following command:

Set-AksHciNodePool -clusterName mycluster -name linuxnodepool -count 3

To scale worker nodes in a node pool, use the Set-AksHciNodePool command.

Access your clusters using kubectl

To access your Kubernetes clusters using kubectl, run the Get-AksHciCredential PowerShell command. This will use the specified cluster's kubeconfig file as the default kubeconfig file for kubectl. You can also use kubectl to deploy applications using Helm:

Get-AksHciCredential -name mycluster

Delete a Kubernetes cluster

To delete a Kubernetes cluster, run the following command:

Remove-AksHciCluster -name mycluster

Get logs

To get logs from your all your pods, run the Get-AksHciLogs command. This command creates an output zipped folder called akshcilogs.zip in your working directory. The full path to the akshcilogs.zip folder is the output after running the following command:

Get-AksHciLogs

In this quickstart, you learned how to set up an AKS host and create Kubernetes clusters using PowerShell. You also learned how to use PowerShell to scale a Kubernetes cluster and to access clusters with kubectl.

Next steps

• Prepare an application
• Deploy a Windows application on your Kubernetes cluster
• Set up multiple administrators