I’ve been testing AKS HCI for a couple of months now, and I’m really excited about it as a platform and the possibilities it unlocks.

In the course of my testing, I’ve encountered some problems and undocumented steps that need to be configured to unsure that when you deploy your cluster, you are more likely to have success. Here’s a list in no particular order:

I’ll try and add to the list as and when I come across other gotchas

Using the PowerShell module is more efficient than using Windows Admin Center

I’ve tested deployments using both WAC and the PowerShell module and I’ve found using the latter gives the more consistent experience.

When first setting up AKS on the HCI cluster via WAC, a number of binaries / agents / scripts / OS images are downloaded to a working directory on the system running WAC before being copied to a CSV on the cluster. If you restart the wizard for whatever reason, all the contents of this working directory are wiped and downloaded again. I’ve found that with WAC, all the possible K8s Linux images are downloaded (at approx. 4 - 4.5 GB per image):

As you can see above, the Windows image is even larger. You may not want to run Windows workloads at the moment, but you’ve got to get the image no matter what.

The PowerShell module is more efficient, as it only downloads the image you require at that time. You can also specify an image store directory for the images when deploying to a cluster. This directory is persistent, so if you need to re-run installations due to failures, at least the time taken to download the images is saved.

Make sure your HCI Cluster has the correct rights in AD

On a couple of occasions, I’ve come across issues which have been resolved by making sure that the Azure Stack HCI Cluster has been correctly configured within Active Directory. As the AKS HCI installer (both PowerShell and WAC based) creates a generic service on the cluster to run the ‘Cloud Agent’ which is required as part of the deployment, the cluster computer object needs the rights to create (and delete) Computer objects at least.

Here’s an example of an error I encountered when it wasn’t configured:

For anyone interested, this is how to configure AD to resolve the problem:

Open dsa.msc (Active Directory Users and Computers) as a user with rights to modify security on the OU that the cluster computer object is located in.

Make sure the ‘Advanced Features’ option is selected within the View menu, to expose the Security tab within the OU properties.

Navigate to the OU where the HCI Cluster computer object is located in (in the example above, it is in the default Computer OU). Right click and select Properties.

From the resultant window, click on the Security tab, then Advanced

Click on Add

Click on Add, then Select a principal (1). Make sure you add the Computer Object type (2), enter the name of the HCI Cluster in the object name, chcek it is valid and click OK (3).

Make sure that the Create and Delete Computer Objects permissions are selected and then click OK. on the open windows to assign the permission.

Currently, you can only run the PowerShell modules directly on a HCI Node

This is for awareness, but you must run the AKS HCI PowerShell modules on a HCI node, PowerShell remoting is not supported currently. So you will need to RDP to the server to do this.

Pre-create a WSSD directory on your CSV

For version 0.2.8 of the AksHci PowerShell Module, I found that the kube-config yaml file attempts to be stored in a directory called wssd on the CSV that you specify when setting the config (e.g. if you specify the following: Set-AksHciConfig -deploymentType MultiNode -wssdImageDir 'C:\ClusterStorage\Volume01\wssdImages' -cloudConfigLocation C:\ClusterStorage\Volume01\aks-clus01-config -vnetName Computeswitch, the install routine would attempt to store the kube-config file in C:\ClusterStorage\Volume01\wssd).

If the wssd directory does not exist prior to installation, the routine will error. To get around this, create the directory beforehand.