How to configure the Azure Stack Hub user's Azure CLI environment
In this article, we will guide you through the process of installing and using the Azure command-line interface (CLI) to manage Azure Stack Hub. Azure CLI can be used to manage resources such as create virtual machines, deploy Azure Resource Manager templates, etc.
Azure Stack Hub works with very specific API Profiles - you need to use
2018-03-01-hybrid in order to interact with it. The biggest caveat is that it only support as small subset of commands from the
Sign in to your development workstation and install CLI. Azure Stack Hub requires at least version 2.0 of Azure CLI. You can install that by using the steps described in the Install Azure CLI 2.0 article. To verify if the installation was successful, open a terminal or a command prompt window and run the following command:
You should see the version of Azure CLI and other dependent libraries that are installed on your computer.
Enter details below to provide values for the variables in the scripts in this article:
|Azure Stack Hub DNS Suffix||The DNS suffix for Azure Stack Hub (<region>.<External Domain Name>)|
|Username||Your AAD username|
|Password||Your AAD password|
Connect to Azure Stack Hub
Use the following steps to connect to Azure Stack Hub:
Register your Azure Stack Hub environment by running the
az cloud registercommand.
To register the user environment, use:
az cloud register \ -n "AzureStackUser" \ --endpoint-resource-manager "https://management." \ --suffix-storage-endpoint "" \ --suffix-keyvault-dns ".vault." \ --endpoint-active-directory-graph-resource-id "https://graph.windows.net/"
To register the user environment - One Liner:
az cloud register -n AzureStackUser --endpoint-resource-manager "https://management." --suffix-storage-endpoint "" --suffix-keyvault-dns ".vault." --endpoint-active-directory-graph-resource-id "https://graph.windows.net/"
Set the active environment by using the following commands.
For the user environment, use:
az cloud set -n AzureStackUser
Update your environment configuration to use the Azure Stack Hub specific API version profile. To update the configuration, run the following command:
az cloud update --profile 2018-03-01-hybrid
Sign in to your Azure Stack Hub environment by using the
az logincommand. You can sign in to the Azure Stack Hub environment either as a user or as a service principal.
Sign in as a user: You can either specify the username and password directly within the
az logincommand or authenticate by using a browser. You have to do the latter if your account has multi-factor authentication enabled.
Example of username: Active directory global administrator or user account i.e. username@<aadtenant>.onmicrosoft.com or email@example.com
az login -u "" -p ''
If your user account has multi-factor authentication enabled, you can use the
az logincommand without providing the
-uparameter. Running the command gives you a URL and a code that you must use to authenticate.
az login \ --tenant <Azure Active Directory Tenant name. For example: contoso.onmicrosoft.com> \ --service-principal \ -u <Application Id of the Service Principal> \ -p <Key generated for the Service Principal>
Verify that your environment is set correctly and that AzureStackUser is the active cloud.
az cloud list --output table
To list command subgroups run:
To list commands for specific subgroup run:
az <subgroupname> --help
Connect to Azure Stack Hub - Quick Reference Guide
# Create your environment az cloud register -n AzureStackUser --endpoint-resource-manager "https://management." --suffix-storage-endpoint "" --suffix-keyvault-dns ".vault." --endpoint-active-directory-graph-resource-id "https://graph.windows.net/" --profile 2018-03-01-hybrid # Set your environment az cloud set -n AzureStackUser # Log in to Azure Stack Hub with user credentials az login -u "" -p ''
Test the connectivity
Now that we've got everything setup, let's use CLI to create resources within Azure Stack Hub. For example, you can create a resource group for an application and add a virtual machine. Use the following command to create a resource group named "MyResourceGroup":
az group create -n MyResourceGroup -l frn00006
If the resource group is created successfully, the previous command outputs the following properties of the newly created resource:
There are some known issues that you must be aware of when using CLI in Azure Stack Hub:
The CLI interactive mode i.e the
az interactivecommand is not yet supported in Azure Stack Hub.
To get the list of virtual machine images available in Azure Stack Hub, use the
az vm images list --allcommand instead of the
az vm image listcommand. Specifying the
--alloption makes sure that response returns only the images that are available in your Azure Stack Hub environment.
Virtual machine image aliases that are available in Azure may not be applicable to Azure Stack Hub. When using virtual machine images, you must use the entire URN parameter (Canonical:UbuntuServer:14.04.3-LTS:1.0.0) instead of the image alias. This URN must match the image specifications as derived from the
az vm images listcommand.