Use Azure Command-Line Interface for disconnected operations on Azure Local (preview)

This article explains how to install and configure the Azure Command-Line Interface (CLI) and its extensions for disconnected operations on Azure Local. It provides an overview of CLI, supported versions, installation steps, and how to set up the CLI for disconnected operations.

About Azure CLI

CLI is a versatile, cross-platform command line interface that lets you create and manage Azure resources for Azure Local disconnected operations. For more information, see What is Azure CLI.

Supported versions for CLI and extension

In this preview, the supported version of Azure CLI for Azure Local disconnected operations is 2.71.0. For more information, see Azure CLI release notes. To find your installed version and see if you need to update, run az version:

az version  

For more information, see Azure CLI commands.

Install Azure CLI

To install the 32-bit version of CLI, follow these steps:

1. Download version 2.71.0.
2. Install the CLI locally on Linux, macOS, or Windows computers.

Configure certificates for Azure CLI

To use CLI, you must trust the certificate authority (CA) root certificate on your machine.

For disconnected operations:

1. Understand public key infrastructure (PKI) for Azure Local with disconnected operations (preview)

2. Set up and configure the certificate trusts for Azure CLI using PowerShell.

   Here's an example script you can run in PowerShell:

       # Define the helper method
       function UpdatePythonCertStore
       {
           [CmdletBinding()]
           param (
               [Parameter(Mandatory = $false)]
               [ValidateScript({Test-Path $_})]
               [string]
               $ApplianceRootCertPath = "$env:APPDATA\Appliance\applianceRoot.cer"
           )
   
           Write-Verbose "[START] Updating CLI cert store with Appliance root cert at $ApplianceRootCertPath"
           $cerFile = $ApplianceRootCertPath
           Write-Verbose "Updating Python cert store with $cerFile"
   
           # C:\Program Files\Microsoft SDKs\Azure\CLI2
           $azCli2Path = Split-Path -Path (Split-Path -Path (Get-Command -Name az).Source -Parent) -Parent
           $pythonCertStore = "${azCli2Path}\Lib\site-packages\certifi\cacert.pem"
   
           Write-Verbose "Python cert store ___location $pythonCertStore"
   
           $root = [System.Security.Cryptography.X509Certificates.X509Certificate2]::new()
   
           if(Test-Path $cerFile)
           {
               $root.Import($cerFile)
               Write-Verbose "$(Get-Date) Extracting required information from the cert file"
               $md5Hash    = (Get-FileHash -Path $cerFile -Algorithm MD5).Hash.ToLower()
               $sha1Hash   = (Get-FileHash -Path $cerFile -Algorithm SHA1).Hash.ToLower()
               $sha256Hash = (Get-FileHash -Path $cerFile -Algorithm SHA256).Hash.ToLower()
               $issuerEntry  = [string]::Format("# Issuer: {0}", $root.Issuer)
               $subjectEntry = [string]::Format("# Subject: {0}", $root.Subject)
               $labelEntry   = [string]::Format("# Label: {0}", $root.Subject.Split('=')[-1])
               $serialEntry  = [string]::Format("# Serial: {0}", $root.GetSerialNumberString().ToLower())
               $md5Entry     = [string]::Format("# MD5 Fingerprint: {0}", $md5Hash)
               $sha1Entry    = [string]::Format("# SHA1 Fingerprint: {0}", $sha1Hash)
               $sha256Entry  = [string]::Format("# SHA256 Fingerprint: {0}", $sha256Hash)
               $certText = (Get-Content -Path $cerFile -Raw).ToString().Replace("`r`n","`n")
               $rootCertEntry = "`n" + $issuerEntry + "`n" + $subjectEntry + "`n" + $labelEntry + "`n" + `
                               $serialEntry + "`n" + $md5Entry + "`n" + $sha1Entry + "`n" + $sha256Entry + "`n" + $certText
               Write-Verbose "Adding the certificate content to Python Cert store"
               Add-Content $pythonCertStore $rootCertEntry
               Write-Verbose "Python Cert store was updated to allow the Azure Stack CA root certificate"
           }
           else
           {
               $errorMessage = "$cerFile required to update CLI was not found."
               Write-Verbose "ERROR: $errorMessage"
               throw "UpdatePythonCertStore: $errorMessage"
           }
   
           Write-Verbose "[END] Updating CLI cert store"
       }
   
       # Run the helper method in PowerShell:
       UpdatePythonCertStore -ApplianceRootCertPath C:\AzureLocalDisconnectedOperations\applianceRoot.cer
   

Set up Azure CLI for disconnected operations

To set up Azure CLI for disconnected operations on Azure Local, follow these steps:

1. Run the Get-ApplianceAzCliCloudConfig function to generate the JSON file that contains the required cloud endpoints.

   Here's an example script:

   function Get-ApplianceAzCliCloudConfig
   {
       [CmdletBinding()]
       [OutputType([String])]
       param (
       [Parameter(Position = 0, Mandatory = $true)]
       [string]
       $fqdn,
       [Parameter(Position = 1, Mandatory = $false)]
       [string]
       $exportToFile
       )
   
   $cloudConfig = @"
   {
       "suffixes":  {
                       "keyvaultDns":  ".vault.autonomous.cloud.private",
                       "storageEndpoint":  "autonomous.cloud.private",
                       "acrLoginServerEndpoint":  ".edgeacr.autonomous.cloud.private"
                   },
       "endpoints":  {
                       "activeDirectory":  "https://login.autonomous.cloud.private/adfs",
                       "activeDirectoryGraphResourceId":  "https://graph.autonomous.cloud.private",
                       "resourceManager":  "https://armmanagement.autonomous.cloud.private",
                       "microsoftGraphResourceId":  "https://graph.autonomous.cloud.private",
                       "activeDirectoryResourceId":  "https://armmanagement.autonomous.cloud.private"
                   }
   }
   "@ -replace "autonomous.cloud.private", $fqdn
   
   if ($exportToFile)
   {
       $cloudConfig | Set-Content -Path "$exportToFile"
   }
   return $cloudConfig
   }
   

   Use this helper method to get the endpoints and create a cloudConfig file for CLI:

   az config set core.enable_broker_on_windows=false
   az config set core.instance_discovery=false
   $fqdn = "autonomous.cloud.private"
   $cloudConfigJson = Get-ApplianceAzCliCloudConfig -fqdn $fqdn
   
   # Write the content to a file cloudConfig.json
   $cloudConfigJson | Out-File -FilePath cloudConfig.json
   

   Here's an example of content in the cloudconfig.json file:

   { 
       "suffixes":  {
                     "keyvaultDns":  ".vault.autonomous.cloud.private",
                     "storageEndpoint":  "autonomous.cloud.private",
                     "acrLoginServerEndpoint":  ".edgeacr.autonomous.cloud.private"
                 },
        "endpoints":  {
                      "activeDirectory":  "https://login.autonomous.cloud.private/adfs",
                      "activeDirectoryGraphResourceId":  "https://graph.autonomous.cloud.private",
                      "resourceManager":  "https://armmanagement.autonomous.cloud.private",
                      "microsoftGraphResourceId":  "https://graph.autonomous.cloud.private",
                      "activeDirectoryResourceId":  "https://armmanagement.autonomous.cloud.private"
                  }
   }
   

2. Register the cloud configuration with CLI using the cloudConfig.json file.

   az cloud register -n 'azure.local' --cloud-config '@cloudconfig.json'
   az cloud set -n azure.local
   

Extensions for Azure CLI

CLI extensions are Python wheels that aren't shipped with CLI but run as CLI commands. Extensions let you access experimental and prerelease commands and create your own CLI interfaces. The first time you use an extension, you get a prompt to install it.

To get a list of available extensions, run this command:

az extension list-available --output table  

Learn more in How to install and manage Azure CLI extensions.

To install a specific version of an extension, run this command:

az extension add --name anextension --version 1.0.0

The following table lists the CLI extensions supported on Azure Local disconnected operations, the maximum extension version supported, and installation information.

This feature is available only in Azure Local 2506.