Deploy a Kubernetes cluster with the AKS engine on Azure Stack Hub

You can deploy a Kubernetes cluster on Azure Stack Hub from a client VM running the AKS engine. In this article, we look at writing a cluster specification, deploying a cluster with the apimodel.json file, and checking your cluster by deploying MySQL with Helm.

Define a cluster specification

You can specify a cluster specification in a document file using the JSON format called the API model. The AKS engine uses a cluster specification in the API model to create your cluster.

Update the API model

This section looks at creating an API model for your cluster.

  1. Start by using an Azure Stack Hub example API Model file and make a local copy for your deployment. From the machine, you installed AKS engine, run:

    curl -o kubernetes-azurestack.json


    If you are disconnected, you can download the file and manually copy it to the disconnected machine where you plan to edit it. You can copy the file to your Linux machine using tools such as PuTTY or WinSCP.

  2. To open API model in an editor, you can use nano:

    nano ./kubernetes-azurestack.json


    If you don't have nano installed, you can install nano on Ubuntu: sudo apt-get install nano.

  3. In the kubernetes-azurestack.json file, find orchestratorRelease and orchestratorVersion. Select one of the supported Kubernetes versions. For example, for orchestratorRelease use 1.14 or 1.15 and for orchestratorVersion use 1.14.7 or 1.15.10 respectively. Specify the orchestratorRelease as x.xx and orchestratorVersion as x.xx.x. For a list of current versions, see Supported AKS engine Versions

  4. Find customCloudProfile and provide the URL to the tenant portal. For example, https://portal.local.azurestack.external.

  5. Add "identitySystem":"adfs" if you're using AD FS. For example,

        "customCloudProfile": {
            "portalURL": "https://portal.local.azurestack.external",
            "identitySystem": "adfs"


    If you're using Azure AD for your identity system, you don't need to add the identitySystem field.

  6. Find portalURL and provide the URL to the tenant portal. For example, https://portal.local.azurestack.external.

  7. In masterProfile, set the following fields:

    Field Description
    dnsPrefix Enter a unique string that will serve to identify the hostname of VMs. For example, a name based on the resource group name.
    count Enter the number of masters you want for your deployment. The minimum for an HA deployment is 3, but 1 is allowed for non-HA deployments.
    vmSize Enter a size supported by Azure Stack Hub, example Standard_D2_v2.
    distro Enter aks-ubuntu-16.04.
  8. In agentPoolProfiles update:

    Field Description
    count Enter the number of agents you want for your deployment. The maximum count of nodes to use per subscription is 50. If you are deploying more than one cluster per subscription ensure that the total agent count doesn't go beyond 50. Make sure to use the configuration items specified in the sample API model JSON file.
    vmSize Enter a size supported by Azure Stack Hub, example Standard_D2_v2.
    distro Enter aks-ubuntu-16.04.
  9. In linuxProfile update:

    Field Description
    adminUsername Enter the VM admin user name.
    ssh Enter the public key that will be used for SSH authentication with VMs. Use ssh-rsa and then the key. For instructions on creating a public key, see Create an SSH key for Linux.

    If you are deploying to a custom virtual network, you can find instructions on finding and adding the required key and values to the appropriate arrays in the API Model in Deploy a Kubernetes cluster to a custom virtual network.


    The AKS engine for Azure Stack Hub doesn't allow you to provide your own certificates for the creation of the cluster.

More information about the API model

Deploy a Kubernetes cluster

After you have collected all the required values in your API model, you can create your cluster. At this point you should:

Ask your Azure Stack Hub operator to:

  • Verify the health of the system, suggest running Test-AzureStack and your OEM vendor's hardware monitoring tool.
  • Verify the system capacity including resources such as memory, storage, and public IPs.
  • Provide details of the quota associated with your subscription so that you can verify that there is still enough space for the number of VMs you plan to use.

Proceed to deploy a cluster:

  1. Review the available parameters for AKS engine on Azure Stack Hub CLI flags.

    Parameter Example Description
    azure-env AzureStackCloud To indicate to AKS engine that your target platform is Azure Stack Hub use AzureStackCloud.
    identity-system adfs Optional. Specify your identity management solution if you are using Active Directory Federated Services (AD FS).
    location local The region name for your Azure Stack Hub. For the ASDK, the region is set to local.
    resource-group kube-rg Enter the name of a new resource group or select an existing resource group. The resource name needs to be alphanumeric and lowercase.
    api-model ./kubernetes-azurestack.json Path to the cluster configuration file, or API model.
    output-directory kube-rg Enter the name of the directory to contain the output file apimodel.json as well as other generated files.
    client-id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Enter the service principal GUID. The Client ID identified as the Application ID when your Azure Stack Hub administrator created the service principal.
    client-secret xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Enter the service principal secret. You set up the client secret when creating your service.
    subscription-id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Enter your Subscription ID. For more information, see Subscribe to an offer

    Here is an example:

    aks-engine deploy \
    --azure-env AzureStackCloud \
    --location <for asdk is local> \
    --resource-group kube-rg \
    --api-model ./kubernetes-azurestack.json \
    --output-directory kube-rg \
    --client-id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
    --client-secret xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
    --subscription-id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
    --identity-system adfs # required if using AD FS
  2. If for some reason the execution fails after the output directory has been created, you can correct the issue and rerun the command. If you are rerunning the deployment and had used the same output directory before, the AKS engine will return an error saying that the directory already exists. You can overwrite the existing directory by using the flag: --force-overwrite.

  3. Save the AKS engine cluster configuration in a secure, encrypted location.

    Locate the file apimodel.json. Save it to a secure location. This file will be used as input in all of your other AKS engine operations.

    The generated apimodel.json contains the service principal, secret, and SSH public key you use in the input API model. It also has all the other metadata needed by the AKS engine to perform all other operations. If you lose it, the AKS engine won't be able configure the cluster.

    The secrets are unencrypted. Keep the file in an encrypted, secure place.

Verify your cluster

Verify your cluster by deploying MySql with Helm to check your cluster.

  1. Get the public IP address of one of your master nodes using the Azure Stack Hub portal.

  2. From a machine with access to your Azure Stack Hub instance, connect via SSH into the new master node using a client such as PuTTY or MobaXterm.

  3. For the SSH username, you use "azureuser" and the private key file of the key pair you provided for the deployment of the cluster.

  4. Run the following commands to create a sample deployment of a Redis master (for connected stamps only):

    kubectl apply -f
    1. Query the list of pods:

      kubectl get pods
    2. The response should be similar to the following:

      NAME                            READY     STATUS    RESTARTS   AGE
      redis-master-1068406935-3lswp   1/1       Running   0          28s
    3. View the deployment logs:

      kubectl logs -f <pod name>

    For a complete deployment of a sample PHP app that includes the Redis master, follow the instructions here.

  5. For a disconnected stamp, the following commands should be sufficient:

    1. First check that the cluster endpoints are running:

      kubectl cluster-info

      The output should look similar to the following:

      Kubernetes master is running at
      CoreDNS is running at
      kubernetes-dashboard is running at
      Metrics-server is running at
    2. Then, review node states:

      kubectl get nodes

      The output should be similar to the following:

      k8s-linuxpool-29969128-0   Ready      agent    9d    v1.15.5
      k8s-linuxpool-29969128-1   Ready      agent    9d    v1.15.5
      k8s-linuxpool-29969128-2   Ready      agent    9d    v1.15.5
      k8s-master-29969128-0      Ready      master   9d    v1.15.5
      k8s-master-29969128-1      Ready      master   9d    v1.15.5
      k8s-master-29969128-2      Ready      master   9d    v1.15.5
  6. To clean up the redis POD deployment from the previous step, run the following command:

    kubectl delete deployment -l app=redis

Next steps