How to configure the Azure Stack 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. Azure CLI can be used to manage resources such as create virtual machines, deploy Azure Resource Manager templates, etc.
Azure Stack 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 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 DNS Suffix||The DNS suffix for Azure Stack (<region>.<External Domain Name>)|
|Username||Your AAD username|
|Password||Your AAD password|
Connect to Azure Stack
Use the following steps to connect to Azure Stack:
Register your Azure Stack 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 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 environment by using the
az logincommand. You can sign in to the Azure Stack 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 - 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 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. 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:
The CLI interactive mode i.e the
az interactivecommand is not yet supported in Azure Stack.
To get the list of virtual machine images available in Azure Stack, 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 environment.
Virtual machine image aliases that are available in Azure may not be applicable to Azure Stack. 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.