Edit

Install Azure CLI on Azure Stack Hub

  • Article
  • 13 minutes to read

You can install the Azure CLI to manage Azure Stack Hub with a Windows or Linux machines. This article walks you through the steps of installing and setting up Azure CLI.

Install Azure CLI

  1. Sign in to your development workstation and install CLI. Azure Stack Hub requires version 2.0 or later of Azure CLI.

Important

You must use Azure CLI version 2.29.2 or earlier with Azure Stack Hub. Microsoft has discovered an issue with Azure Stack Hub that prevents using Azure CLI version 2.30.0 or newer.

  1. You can install the CLI by using the steps described in the Install the Azure CLI article.

  2. 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.

    Azure CLI on Azure Stack Hub Python location

  3. Make a note of the CLI's Python location.

Add certificate

Export and then import Azure Stack Hub certificate for disconnected integrated systems and for the ASDK. For connected integrated systems, the certificate is publicly signed and this step isn't necessary. You can find instructions at Setting up certificates for Azure CLI on Azure Stack Development Kit.

Connect with Azure CLI

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.

Connect to Azure Stack Hub

  1. If you are using the ASDK, trust the Azure Stack Hub CA root certificate. For instruction, see Trust the certificate.

  2. Register your Azure Stack Hub environment by running the az cloud register command.

  3. Register your environment. Use the following parameters when running az cloud register:

    Value Example Description
    Environment name AzureStackUser Use AzureStackUser for the user environment. If you're operator, specify AzureStackAdmin.
    Resource Manager endpoint https://management.contoso.onmicrosoft.com 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.contoso.onmicrosoft.com local.azurestack.external is for the ASDK. For an integrated system, use an endpoint for your system.
    Keyvault suffix .vault.contoso.onmicrosoft.com .vault.local.azurestack.external is for the ASDK. For an integrated system, use an endpoint for your system.
    Endpoint active directory graph resource ID https://graph.windows.net/ The Active Directory resource ID. 
    az cloud register `
    -n <environmentname> `
    --endpoint-resource-manager "https://management.<region>.<fqdn>" `
    --suffix-storage-endpoint "<fqdn>" `
    --suffix-keyvault-dns ".vault.<fqdn>"

    You can find a reference for the register command in the Azure CLI reference documentation.

  4. Set the active environment by using the following commands.

    az cloud set -n <environmentname>

  5. 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 2020-09-01-hybrid

  6. Sign in to your Azure Stack Hub environment by using the az login command.

    You can sign in to the Azure Stack Hub environment using your user credentials, or with a service principal (SPN) provided to you by your cloud operator.

    • 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 multifactor authentication enabled:

      az login -u "user@contoso.onmicrosoft.com" -p 'Password123!' --tenant contoso.onmicrosoft.com

      Note

      If your user account has multifactor 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:

      Before you sign in, create a service principal through the Azure portal or CLI and assign it a role. Now, sign in by using the following command:

      az login `
  --tenant <Azure Active Directory Tenant name. `
            For example: myazurestack.onmicrosoft.com> `
--service-principal `
  -u <Application Id of the Service Principal> `
  -p <Key generated for the Service Principal>

  7. Verify that your environment is set correctly and that your environment is the active cloud.

        az cloud list --output table

You should see that your environment is listed and IsActive is true. For example:

IsActive    Name               Profile
----------  -----------------  -----------------
False       AzureCloud         2020-09-01-hybrid
False       AzureChinaCloud    latest
False       AzureUSGovernment  latest
False       AzureGermanCloud   latest
True        AzureStackUser     2020-09-01-hybrid

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:

{
  "id": "/subscriptions/84edee99-XXXX-4f5c-b646-5cdab9759a03/resourceGroups/RGCL11",
  "location": "local",
  "name": "RGCLI1",
  " properties ": {
    "provisioningState": "Succeeded"
  },
  "tags ": null
}

Next steps