Install AKS engine on Windows in Azure Stack Hub

Article
05/17/2023

Binary downloads for the latest version of AKS Engine are available on Github. Download the package for your operating system, and extract the aks-engine file for AKS Engine versions 0.73.0 and below. For AKS Engine versions 0.75.3 and above, extract the aks-engine-azurestack file (and optionally add it to your $PATH environment variable for more convenient CLI usage).

Prepare the client VM

The AKS engine is a command-line tool used to deploy and manage your Kubernetes cluster. You can run the engine on a machine in your Azure Stack Hub. From this machine, execute the AKS engine to deploy the IaaS resources and software needed to run your cluster. You can then use the machine running the engine to perform management tasks on your cluster.

When choosing your client machine, consider:

Whether the client machine should be recoverable in a disaster.
How you will connect to the client machine, and how the machine will interact with your cluster?

Install AKS Engine in a connected environment

You can install the client VM to manage your Kubernetes cluster on an Azure Stack Hub connected to the Internet.

Create a Windows VM in your Azure Stack Hub. For instructions, see Quickstart: Create a Windows server VM by using the Azure Stack Hub portal.
Connect to your VM.
Install Chocolatey using the PowerShell instructions..

According to the Chocolatey website: Chocolatey is a package manager for Windows, like apt-get or yum but for Windows. It was designed to be a decentralized framework for quickly installing applications and tools that you need. It is built on the NuGet infrastructure currently using PowerShell as its focus for delivering packages from the distros to your door, err, computer.
Install Azure CLI. Select the download link, and choose "Run". Choose the setup steps as needed.
Find the version of AKS engine in the AKS engine and Azure Stack version mapping table table. The AKS Base Engine must be available in your Azure Stack Hub Marketplace. When running the command, you must specify the version --version v0.xx.x. If you don't specify the version, the command installs the latest version, which may need a VHD image that is not available in your marketplace.

Note

You can find the mapping of Azure Stack Hub to AKS engine version number in the AKS engine release notes.
Run the following command from an elevated prompt and include the version number:

Note

For AKSe version 0.75.3 and above, the command to install AKS engine is choco install aks-engine-azurestack.
```
    choco install aks-engine --version 0.xx.x -y
```
Note

If this method for installation fails, you can try the steps for a disconnected environment below.

Install AKS Engine in a disconnected environment

You can install the client VM to manage your Kubernetes cluster on an Azure Stack Hub disconnected from the Internet.

From a machine with access to the Internet, go to GitHub Azure/aks-engine. Download an archive (*.tar.gz) for a Windows machine, for example, aks-engine-v0.xx.x-windows-amd64.tar.gz. Find the version of AKS engine in the Supported Kubernetes Versions table.
Create a storage account in your Azure Stack Hub instance to upload the archive file (*.tar.gz) with the AKS engine binary. For instructions on using the Azure Storage Explorer, see Azure Storage Explorer with Azure Stack Hub.
Create a Windows VM in your Azure Stack Hub. For instructions, see Quickstart: Create a Windows server VM by using the Azure Stack Hub portal
From the Azure Stack Hub storage account blob URL where you uploaded the archive file (*.tar.gz), download the file to your management VM. Extract the archive to a directory that you have access to from your command prompt.
Connect to your VM.
Install Chocolatey using the PowerShell instructions..
Run the following command from an elevated prompt. Include the right version number:

Note

For AKSe version 0.75.3 and above, the command to install AKS engine is choco install aks-engine-azurestack.
```
    choco install aks-engine --version 0.xx.x -y
```

Verify the installation

Once your client VM is set up, check that you have installed AKS engine.

Connect to your client VM.
Run the following command:

Note

For AKSe version 0.75.3 and above, the command to check the current version of your AKS engine is aks-engine-azurestack version.
```
aks-engine version
```

If you are unable to verify that you have installed AKS engine on your client VM, see Troubleshoot AKS engine install.

ASDK installation

You need to add a certificate when running the client VM for the AKS engine on the ASDK on a machine outside of the ASDK. If you're using a Windows VM within the ASDK environment itself, the machine already trusts the ASDK certificate. If your client machine is outside of the ASDK, you need to extract the certificate from the ASDK and add it to your Windows machine.

When you are using an ASDK your Azure Resource Manager endpoint is using a self-signed certificate, you need to explicitly add this certificate to the machine's trusted certificate store. You can find the ASDK root certificate in any VM you deploy in the ASDK.

Export the CA root certificate. For instructions, see Export the Azure Stack Hub CA root certificate.
Trust the Azure Stack Hub CA root certificate. For instructions, see Trust the Azure Stack Hub CA root certificate.

Next steps

Deploy a Kubernetes cluster with AKS engine on Azure Stack Hub