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.
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.
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
If you are using the ASDK, trust the Azure Stack Hub CA root certificate. For instruction, see Trust the certificate.
Register your Azure Stack Hub environment by running the az cloud register
command.
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.
Set the active environment by using the following commands.
az cloud set -n <environmentname>
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
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>
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
}
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.
Connect to Azure Stack Hub
If you are using the ASDK, trust the Azure Stack Hub CA root certificate. For instruction, see Trust the certificate.
Register your Azure Stack Hub environment by running the az cloud register
command.
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.local.azurestack.external |
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. |
VM image alias doc endpoint- |
https://raw.githubusercontent.com/Azure/azure-rest-api-specs/master/arm-compute/quickstart-templates/aliases.json |
URI of the document, which contains VM image aliases. For more info, see Set up the virtual machine alias endpoint. |
az cloud register -n <environmentname> --endpoint-resource-manager "https://management.local.azurestack.external" --suffix-storage-endpoint "local.azurestack.external" --suffix-keyvault-dns ".vault.local.azurestack.external" --endpoint-vm-image-alias-doc <URI of the document which contains VM image aliases>
Set the active environment by using the following commands.
az cloud set -n <environmentname>
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
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 2020-09-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 multifactor authentication enabled:
az cloud register -n <environmentname> --endpoint-resource-manager "https://management.local.azurestack.external" --suffix-storage-endpoint "local.azurestack.external" --suffix-keyvault-dns ".vault.local.azurestack.external" --endpoint-vm-image-alias-doc <URI of the document which contains VM image aliases> --profile "2020-09-01-hybrid"
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.
Convert the pfx to pem (use the OpenSSL utility).
Sign in to the CLI:
az login --service-principal \
-u <Client ID from the Service Principal details> \
-p <Client secret (password), or certificate's fully qualified name, such as, C:\certs\spn.pem>
--tenant <Tenant ID> \
--debug
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
}
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.
Connect to Azure Stack Hub
Use the following steps to connect to Azure Stack Hub:
If you are using the ASDK, trust the Azure Stack Hub CA root certificate. For instruction, see Trust the certificate.
Register your Azure Stack Hub environment by running the az cloud register
command.
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.local.azurestack.external |
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. |
VM image alias doc endpoint- |
https://raw.githubusercontent.com/Azure/azure-rest-api-specs/master/arm-compute/quickstart-templates/aliases.json |
URI of the document, which contains VM image aliases. For more info, see Set up the virtual machine alias endpoint. |
az cloud register -n <environmentname> --endpoint-resource-manager "https://management.local.azurestack.external" --suffix-storage-endpoint "local.azurestack.external" --suffix-keyvault-dns ".vault.local.azurestack.external" --endpoint-vm-image-alias-doc <URI of the document which contains VM image aliases>
Set the active environment.
az cloud set -n <environmentname>
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
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 2020-09-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 multifactor authentication enabled:
az login \
-u <Active directory global administrator or user account. For example: username@<aadtenant>.onmicrosoft.com> \
--tenant <Azure Active Directory Tenant name. For example: myazurestack.onmicrosoft.com>
Note
If your user account has multifactor 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.
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>
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
}
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.
Connect to Azure Stack Hub
Use the following steps to connect to Azure Stack Hub:
If you are using the ASDK, trust the Azure Stack Hub CA root certificate. For instruction, see Trust the certificate.
Register your Azure Stack Hub environment by running the az cloud register
command.
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.local.azurestack.external |
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. |
VM image alias doc endpoint- |
https://raw.githubusercontent.com/Azure/azure-rest-api-specs/master/arm-compute/quickstart-templates/aliases.json |
URI of the document, which contains VM image aliases. For more info, see Set up the virtual machine alias endpoint. |
az cloud register -n <environmentname> --endpoint-resource-manager "https://management.local.azurestack.external" --suffix-storage-endpoint "local.azurestack.external" --suffix-keyvault-dns ".vault.local.azurestack.external" --endpoint-vm-image-alias-doc <URI of the document which contains VM image aliases>
Set the active environment.
az cloud set -n <environmentname>
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
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 2020-09-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.
Convert the pfx to pem (use the OpenSSL utility).
Sign in to the CLI:
az login --service-principal \
-u <Client ID from the Service Principal details> \
-p <Client secret (password), or certificate's fully qualified name, such as, C:\certs\spn.pem>
--tenant <Tenant ID> \
--debug
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
}
Known issues
There are known issues when using CLI in Azure Stack Hub:
- The CLI interactive mode. For example, the
az interactive
command, isn't yet supported in Azure Stack Hub.
- 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.