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.
There is currently no document for the 2019-03-01-hybrid profile.
Azure Stack Hub works with very specific API Profiles - you need to use
2019-03-01-hybrid to interact with it. The biggest caveat is that it only supports a 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:
bash-5.0# az --version azure-cli 2.2.0 command-modules-nspkg 2.0.3 core 2.2.0 nspkg 3.0.4 telemetry 1.0.4 Python location '/usr/local/bin/python' Extensions directory '/root/.azure/cliextensions' Python (Linux) 3.6.9 (default, Nov 15 2019, 03:58:01) [GCC 8.3.0] Legal docs and information: aka.ms/AzureCliLegal Your CLI is up-to-date. Please let us know how we are doing: https://aka.ms/clihats
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 2019-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 firstname.lastname@example.org
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.
If the user is not present in the domain that you are attempting to login to, you must specify the
--tenantparameter. For example, if your guest user is
email@example.com the domain is
firstname.lastname@example.org command will be as follows:
az login --tenant email@example.com To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code xxxxxxxxx to authenticate.
At the user authentication page, sign in with your guest user
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.
bash-5.0# az cloud list --output table IsActive Name Profile ---------- ----------------- ----------------- False AzureCloud latest False AzureChinaCloud latest False AzureUSGovernment latest False AzureGermanCloud latest True AzureStackUser 2019-03-01-hybrid
The final line shows that the user profile has been updated and is active.
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 2019-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 image 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 image list -allcommand.
If you find a problem with this article, click Improve this Doc to make the change yourself or raise an issue in GitHub. If you have an idea for how we could improve any of our services, send an email to firstname.lastname@example.org.