Manage and deploy resources to Azure Stack Hub with Azure CLI

In this article

Follow the steps in this article to set up the Azure Command-Line Interface (CLI) to manage Azure Stack Development Kit (ASDK) resources from Linux, Mac, and Windows client platforms.

Prepare for Azure CLI

If you're using the ASDK, you need the CA root certificate for Azure Stack Hub to use Azure CLI on your development machine. You use the certificate to manage resources through the CLI.

The Azure Stack Hub CA root certificate is required if you're using the CLI from a workstation outside the ASDK.

The virtual machine aliases endpoint provides an alias, like "UbuntuLTS" or "Win2012Datacenter." This alias references an image publisher, offer, SKU, and version as a single parameter when deploying VMs.

The following sections describe how to get these values.

Export the Azure Stack Hub CA root certificate

If you're using an integrated system, you don't need to export the CA root certificate. If you're using the ASDK, export the CA root certificate on an ASDK.

Set up the virtual machine aliases endpoint

You can set up a publicly accessible endpoint that hosts a VM alias file. The VM alias file is a JSON file that provides a common name for an image. You use the name when you deploy a VM as an Azure CLI parameter.

If you publish a custom image, make note of the publisher, offer, SKU, and version information that you specified during publishing. If it's an image from the marketplace, you can view the information by using the Get-AzureVMImage cmdlet.

Create a storage account in Azure Stack Hub. When that's done, create a blob container. Set the access policy to "public."

Upload the JSON file to the new container. When that's done, you can view the URL of the blob. Select the blob name and then selecting the URL from the blob properties.

Install or upgrade CLI

Sign in to your development workstation and install CLI. Azure Stack Hub requires version 2.0 or later of Azure CLI. The latest version of the API Profiles requires a current version of the CLI. You install the CLI by using the steps described in the Install the Azure CLI article.

To verify whether the installation was successful, open a terminal or command prompt window and run the following command:

az --version

You should see the version of Azure CLI and other dependent libraries that are installed on your computer.

Make a note of the CLI's Python location. If you're running the ASDK, you need to use this location to add your certificate.

Windows (Azure AD)

This section walks you through setting up CLI if you're using Azure AD as your identity management service, and are using CLI on a Windows machine.

Trust the Azure Stack Hub CA root certificate

If you're using the ASDK, you need to trust the CA root certificate on your remote machine. This step isn't needed with the integrated systems.

To trust the Azure Stack Hub CA root certificate, append it to the existing Python certificate store for the Python version installed with the Azure CLI. You may be running your own instance of Python. Azure CLI includes its own version of Python.

Find the certificate store location on your machine. You can find the location by running the command az --version.

Navigate to the folder that contains your CLI Python app. You want to run this version of python. If you've set up Python in your system PATH, running Python will execute your own version of Python. Instead, you want to run the version used by CLI and add your certificate to that version. For example, your CLI Python may be at: C:\Program Files (x86)\Microsoft SDKs\Azure\CLI2\.

The ResourceManagerUrl in the ASDK is: https://management.local.azurestack.external/ The ResourceManagerUrl in integrated systems is: https://management.<region>.<fqdn>/ If you have a question about the integrated system endpoint, contact your cloud operator.

Storage endpoint

local.azurestack.external

local.azurestack.external is for the ASDK. For an integrated system, use an endpoint for your system.

Keyvault suffix

.vault.local.azurestack.external

.vault.local.azurestack.external is for the ASDK. For an integrated system, use an endpoint for your system.

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

Note

If you're running a version of Azure Stack Hub before the 1808 build, you must use the API version profile 2017-03-09-profile rather than the API version profile 2019-03-01-hybrid. You also need to use a recent version of the Azure CLI.

Sign in to your Azure Stack Hub environment by using the az login command. 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 login command, or authenticate by using a browser. You must do the latter if your account has multi-factor authentication enabled:

If your user account has multi-factor authentication enabled, use the az login command without providing the -u parameter. Running this command gives you a URL and a code that you must use to authenticate.

Test the connectivity

With everything set up, use CLI to create resources within Azure Stack Hub. For example, you can create a resource group for an app and add a VM. Use the following command to create a resource group named "MyResourceGroup":

az group create -n MyResourceGroup -l local

If the resource group is created successfully, the previous command outputs the following properties of the newly created resource:

Windows (AD FS)

This section walks you through setting up CLI if you're using Active Directory Federated Services (AD FS) as your identity management service, and are using CLI on a Windows machine.

Trust the Azure Stack Hub CA root certificate

If you're using the ASDK, you need to trust the CA root certificate on your remote machine. This step isn't needed with the integrated systems.

Find the certificate location on your machine. The location may vary depending on where you've installed Python. Open a cmd prompt or an elevated PowerShell prompt, and type the following command:

python -c "import certifi; print(certifi.where())"

Make a note of the certificate location. For example, ~/lib/python3.5/site-packages/certifi/cacert.pem. Your particular path depends on your OS and the version of Python that you've installed.

Trust the Azure Stack Hub CA root certificate by appending it to the existing Python certificate.

The ResourceManagerUrl in the ASDK is: https://management.local.azurestack.external/ The ResourceManagerUrl in integrated systems is: https://management.<region>.<fqdn>/ If you have a question about the integrated system endpoint, contact your cloud operator.

Storage endpoint

local.azurestack.external

local.azurestack.external is for the ASDK. For an integrated system, use an endpoint for your system.

Keyvault suffix

.vault.local.azurestack.external

.vault.local.azurestack.external is for the ASDK. For an integrated system, use an endpoint for your system.

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

Note

If you're running a version of Azure Stack Hub before the 1808 build, you must use the API version profile 2017-03-09-profile rather than the API version profile 2019-03-01-hybrid. You also need to use a recent version of the Azure CLI.

Sign in to your Azure Stack Hub environment by using the az login command. 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 login command, or authenticate by using a browser. You must do the latter if your account has multi-factor authentication enabled:

If your user account has multi-factor authentication enabled, use the az login command without providing the -u parameter. Running this command gives you a URL and a code that you must use to authenticate.

Sign in as a service principal:

Prepare the .pem file to be used for service principal login.

On the client machine where the principal was created, export the service principal certificate as a pfx with the private key located at cert:\CurrentUser\My. The cert name has the same name as the principal.

Test the connectivity

With everything set up, use CLI to create resources within Azure Stack Hub. For example, you can create a resource group for an app and add a VM. Use the following command to create a resource group named "MyResourceGroup":

az group create -n MyResourceGroup -l local

If the resource group is created successfully, the previous command outputs the following properties of the newly created resource:

Linux (Azure AD)

This section walks you through setting up CLI if you're using Azure AD as your identity management service, and are using CLI on a Linux machine.

Trust the Azure Stack Hub CA root certificate

If you're using the ASDK, you need to trust the CA root certificate on your remote machine. This step isn't needed with the integrated systems.

Trust the Azure Stack Hub CA root certificate by appending it to the existing Python certificate.

Find the certificate location on your machine. The location may vary depending on where you've installed Python. You need to have pip and the certifi module installed. Use the following Python command from the bash prompt:

az --version

Make a note of the certificate location. For example, ~/lib/python3.5/site-packages/certifi/cacert.pem. Your specific path depends on your operating system and the version of Python that you've installed.

The ResourceManagerUrl in the ASDK is: https://management.local.azurestack.external/ The ResourceManagerUrl in integrated systems is: https://management.<region>.<fqdn>/ If you have a question about the integrated system endpoint, contact your cloud operator.

Storage endpoint

local.azurestack.external

local.azurestack.external is for the ASDK. For an integrated system, use an endpoint for your system.

Keyvault suffix

.vault.local.azurestack.external

.vault.local.azurestack.external is for the ASDK. For an integrated system, use an endpoint for your system.

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

Note

If you're running a version of Azure Stack Hub before the 1808 build, you must use the API version profile 2017-03-09-profile rather than the API version profile 2019-03-01-hybrid. You also need to use a recent version of the Azure CLI.

Sign in to your Azure Stack Hub environment by using the az login command. 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 login command, or authenticate by using a browser. You must do the latter if your account has multi-factor authentication enabled:

If your user account has multi-factor authentication enabled, you can use the az login command without providing the -u parameter. Running this command gives you a URL and a code that you must use to authenticate.

Test the connectivity

With everything set up, use CLI to create resources within Azure Stack Hub. For example, you can create a resource group for an app and add a VM. Use the following command to create a resource group named "MyResourceGroup":

az group create -n MyResourceGroup -l local

If the resource group is created successfully, the previous command outputs the following properties of the newly created resource:

Linux (AD FS)

This section walks you through setting up CLI if you're using Active Directory Federated Services (AD FS) as your management service, and are using CLI on a Linux machine.

Trust the Azure Stack Hub CA root certificate

If you're using the ASDK, you need to trust the CA root certificate on your remote machine. This step isn't needed with the integrated systems.

Trust the Azure Stack Hub CA root certificate by appending it to the existing Python certificate.

Find the certificate location on your machine. The location may vary depending on where you've installed Python. You need to have pip and the certifi module installed. Use the following Python command from the bash prompt:

az --version

Make a note of the certificate location. For example, ~/lib/python3.5/site-packages/certifi/cacert.pem. Your specific path depends on your operating system and the version of Python that you've installed.

The ResourceManagerUrl in the ASDK is: https://management.local.azurestack.external/ The ResourceManagerUrl in integrated systems is: https://management.<region>.<fqdn>/ If you have a question about the integrated system endpoint, contact your cloud operator.

Storage endpoint

local.azurestack.external

local.azurestack.external is for the ASDK. For an integrated system, use an endpoint for your system.

Keyvault suffix

.vault.local.azurestack.external

.vault.local.azurestack.external is for the ASDK. For an integrated system, use an endpoint for your system.

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

Note

If you're running a version of Azure Stack Hub before the 1808 build, you must use the API version profile 2017-03-09-profile rather than the API version profile 2019-03-01-hybrid. You also need to use a recent version of the Azure CLI.

Sign in to your Azure Stack Hub environment by using the az login command. You can sign in to the Azure Stack Hub environment either as a user or as a service principal.

Sign in:

As a user using a web browser with a device code:

az login --use-device-code

Note

Running the command gives you a URL and a code that you must use to authenticate.

As a service principal:

Prepare the .pem file to be used for service principal login.

On the client machine where the principal was created, export the service principal certificate as a pfx with the private key located at cert:\CurrentUser\My. The cert name has the same name as the principal.

Test the connectivity

With everything set up, use CLI to create resources within Azure Stack Hub. For example, you can create a resource group for an app and add a VM. Use the following command to create a resource group named "MyResourceGroup":

az group create -n MyResourceGroup -l local

If the resource group is created successfully, the previous command outputs the following properties of the newly created resource:

Known issues

To get the list of VM images available in Azure Stack Hub, use the az vm image list --all command instead of the az vm image list command. Specifying the --all option ensures that the response returns only the images that are available in your Azure Stack Hub environment.

VM image aliases that are available in Azure may not be applicable to Azure Stack Hub. When using VM 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 list command.