Tutorial: Deploy a workload cluster on AKS enabled by Arc

Article
01/05/2024

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

Kubernetes provides a distributed platform for containerized applications.

In this tutorial, part three of seven, a Kubernetes cluster is deployed on AKS on Azure Stack HCI. You'll learn how to:

Deploy an AKS cluster on Azure Stack HCI
Install the Kubernetes CLI (kubectl)
Configure kubectl to connect to your workload cluster

In later tutorials, the Azure Vote application is deployed to the cluster, scaled, and updated.

Before you begin

In previous tutorials, a container image was created and uploaded to an Azure Container Registry instance. If you haven't done these steps, start at Tutorial 1 - Create container images.

This tutorial uses the AksHci PowerShell module.

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

Note

If you are using remote PowerShell, you must use CredSSP.

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

Install the Azure Kubernetes Service host

First, configure your registration settings.

Set-AksHciRegistration -subscription mysubscription -resourceGroupName myresourcegroup

You must customize these values according to your Azure subscription and resource group name.

Then, run the following command to ensure that all requirements on each physical node are met to install AKS on Azure Stack HCI:

Initialize-AksHciNode

Next, create a virtual network. You will need the names of your available external switches:

Get-VMSwitch

Sample output:

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

Run the following command to create a virtual network with static IP:

$vnet = New-AksHciNetworkSetting -name myvnet -vSwitchName "extSwitch" -macPoolName myMacPool -k8sNodeIpPoolStart "172.16.10.0" -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

Then, configure your deployment with the following command.

Set-AksHciConfig -imageDir c:\clusterstorage\volume1\Images -cloudConfigLocation c:\clusterstorage\volume1\Config -vnet $vnet -cloudservicecidr "172.16.10.10/16"

Now, you are ready to install the AKS host:

Install-AksHCi

Create a Kubernetes cluster

Create a Kubernetes cluster using the command New-AksHciCluster. The following example creates a cluster named mycluster with one Linux node pool called linuxnodepool, which has a node count of 1:

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

To verify that deployment was successful, run the following command.

Get-AksHcicluster -name mycluster

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

Note

If you use the new parameter sets in New-AksHciCluster to deploy a cluster, and then you run Get-AksHciCluster to get the cluster information, the fields WindowsNodeCount and LinuxNodeCount in the output return 0. To get the accurate number of nodes in each node pool, use the command Get-AksHciNodePool with the specified cluster name.

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

Install the Kubernetes CLI

To connect to the Kubernetes cluster from your local computer, use kubectl, the Kubernetes command-line client.

Connect to cluster using kubectl

To configure kubectl to connect to your Kubernetes cluster, use the Get-AksHciCredential command. The following example gets credentials for the cluster named mycluster:

Get-AksHciCredential -name mycluster

To verify the connection to your cluster, run the kubectl get nodes command to return a list of the cluster nodes:

kubectl get nodes

NAME              STATUS   ROLES                  AGE     VERSION
moc-lbs6got5dqo   Ready    <none>                 6d20h   v1.20.7
moc-lel7tzxdt30   Ready    control-plane,master   6d20h   v1.20.7

Next steps

In this tutorial, a Kubernetes cluster was deployed in AKS, and you configured kubectl to connect to it. You learned how to:

Deploy an AKS cluster on Azure Stack HCI
Install the Kubernetes CLI (kubectl)
Configure kubectl to connect to your AKS cluster

Advance to the next tutorial to learn how to deploy an application to the cluster.

Deploy application in Kubernetes