Set up the prerequisites for the AKS engine on Azure Stack Hub

You can install the AKS engine on a virtual machines (VMs) in your environment, or any client machine with access to your Azure Stack Hub Resource Manager endpoint. You will need the following things in place before you run the engine: an AKS Base Ubuntu server and Linux custom script extension available in your subscription, a service principal identity that has been assigned to a contributor role, and a private/public key pair for SSH access to your Ubuntu server. In addition, if you are using the Azure Stack Development Kit, you will need to have your machine trust the appropriate certificates.

If you have your prerequisites, you can begin to define your cluster.

If you are the cloud operator for Azure Stack Hub and would like to offer the AKS engine, follow the instructions at Add the AKS engine to the Azure Stack Hub Marketplace.

Prerequisites for the AKS engine

To use the AKS engine, you need to have the following resources available. Keep in mind that the AKS engine is meant to be used by tenants of Azure Stack Hub to deploy Kubernetes clusters into their tenant subscription. The only part where involvement of the Azure Stack Hub operator may be required is for downloading Marketplace items and the creation of a service principal identity. You can find details in the following table.

Your cloud operator will need to have the following items in place.

Prerequisite Description Required Instructions
Azure Stack Hub 1910 or greater The AKS engine requires Azure Stack Hub 1910 or greater. Required If you are unsure of your version of Azure Stack Hub, contact your cloud operator.
Linux custom script extension Linux Custom Script extension 2.0
Offer: Custom Script for Linux 2.0
Version: 2.0.6 (or latest version)
Publisher: Microsoft Corp
Required If you do not have this item in your subscription, contact your cloud operator.
AKS Base Ubuntu Image AKS Base Ubuntu 16.04-LTS Image
See more information on the version dependency see Matching engine to base image version
Required If you don't have this item in your subscription, contact your cloud operator.
If you are the cloud operator for Azure Stack Hub and would like to offer the AKS engine, follow the instructions at Add the AKS engine to the Azure Stack Hub Marketplace.
Service principal identity (SPN) An application that needs to deploy or configure resources through Azure Resource Manager, must be represented by a service principal. Required You may need to contact your Azure Stack Hub operator for this item.
If an Azure Active Directory (Azure AD) Service Principal identity is used, Internet access is required from the VMs in the Kubernetes cluster so that the Service Principal can be authenticated with Azure AD. If there is no internet access, the Kubernetes cluster will not be functional.
For instructions see Use an app identity to access resources
(SPN) assigned Contributor role To allow an application to access resources in your subscription using its service principal, you must assign the service principal to a role for a specific resource. Required For instructions, see Assign a role

You can set the following items.

Prerequisite Description Required Instructions
Azure Stack Hub subscription You access offers in your Azure Stack Hub through subscriptions. The offer contains the services that are available to you. Required To be able to deploy any tenant workloads in Azure Stack Hub, you need to first get an Azure Stack Hub Subscription.
Resource group A resource group is a container that holds related resources for an Azure solution. If you don't specify an existing resource group the tool will create one for you. Optional Manage Azure Resource Manager resource groups by using the Azure portal
Private Public key To use an open SSH connection from your development machine to the server VM in your Azure Stack Hub instance that hosts your web app, you need to create a Secure Shell (SSH) public and private key pair. Required For instructions on generating a key, see SSH Key Generation.

Note

You can also create the prerequisites for the AKS engine with Azure CLI for Azure Stack Hub or Azure Stack Hub PowerShell.

Matching engine to base image version

The AKS engine deploys a customized Ubuntu Server OS to each cluster node image, the AKS Base Ubuntu 16.04-LTS Image Distro. Any AKS engine version is dependent on a specific image version made available in your Azure Stack Hub by your Azure Stack Hub operator. You can find a table listing the AKS engine versions and corresponding supported Kubernetes versions at Supported Kubernetes Versions. For example, AKS engine version v0.55.0 depends on version 2020.08.24 of the AKS Base Ubuntu 16.04-LTS Image Distro. Ask your Azure Stack Hub operator to download the specific image version from the Azure Marketplace to the Azure Stack Hub Marketplace.

You will trigger and error if the image is not available in your Azure Stack Hub Marketplace. For example, if you're currently using AKS engine version v0.55.0 and AKS Base Ubuntu 16.04-LTS Image Distro version 2020.08.24 isn't available, you will see the following error when running the AKS engine:

The platform image 'microsoft-aks:aks:aks-ubuntu-1604-202003:2020.08.24' is not available. 
Verify that all fields in the storage profile are correct.

You can check the current version of your AKS engine by running the following command:

$ aks-engine version
Version: v0.55.0
GitCommit: 44a35c00c
GitTreeState: clean

Next steps