Installare l'interfaccia della riga di comando di Azure nell'hub di Azure Stack

  • Articolo

È possibile installare l'interfaccia della riga di comando di Azure per gestire l'hub di Azure Stack con computer Windows o Linux. Questo articolo illustra i passaggi per installare e configurare l'interfaccia della riga di comando di Azure.

Installare l'interfaccia da riga di comando di Azure

  1. Accedere alla workstation di sviluppo e installare l'interfaccia della riga di comando. L'hub di Azure Stack richiede la versione 2.0 o successiva dell'interfaccia della riga di comando di Azure.

    Importante

    A causa di un CVE che interessa le versioni dell'interfaccia della riga di comando di Azure precedenti alla versione 2.40.0, non è più consigliabile usare l'interfaccia della riga di comando di Azure 2.29.2 per AD FS nell'hub di Azure Stack. È possibile eseguire l'aggiornamento all'interfaccia della riga di comando di Azure 2.40.0 o versione successiva. Tuttavia, i clienti di AD FS potrebbero riscontrare problemi con i comandi dell'interfaccia della riga di comando di Azure che interagiscono con gli endpoint di Microsoft Graph. Ciò è dovuto al fatto che Microsoft Graph non è supportato per AD FS. Per le soluzioni alternative ai problemi di Microsoft Graph, vedere la sezione Problemi noti generali .

  2. È possibile installare l'interfaccia della riga di comando seguendo la procedura descritta nell'articolo Installare l'interfaccia della riga di comando di Azure.

  3. Per verificare se l'installazione è riuscita, aprire una finestra del terminale o del prompt dei comandi ed eseguire il comando seguente:

    az --version

    Verrà visualizzata la versione dell'interfaccia della riga di comando di Azure e altre librerie dipendenti installate nel computer.

    Interfaccia della riga di comando di Azure nel percorso Python dell'hub di Azure Stack

  4. Prendere nota del percorso Python dell'interfaccia della riga di comando.

Aggiunta del certificato

Esportare e quindi importare il certificato dell'hub di Azure Stack per sistemi integrati disconnessi e per ASDK. Per i sistemi integrati connessi, il certificato viene firmato pubblicamente e questo passaggio non è necessario. Per istruzioni, vedere Configurazione dei certificati per l'interfaccia della riga di comando di Azure in Azure Stack Development Kit.

Connettersi con l'interfaccia della riga di comando di Azure

Questa sezione illustra come configurare l'interfaccia della riga di comando se si usa Microsoft Entra ID come servizio di gestione delle identità e si usa l'interfaccia della riga di comando in un computer Windows.

Connettersi all'hub di Azure Stack

  1. Se si usa ASDK, considerare attendibile il certificato radice della CA dell'hub di Azure Stack. Per istruzioni, vedere Considerare attendibile il certificato.

  2. Registrare l'ambiente dell'hub di Azure Stack eseguendo il az cloud register comando .

  3. Registrare l'ambiente. Usare i parametri seguenti durante l'esecuzione az cloud registerdi :

    Valore Esempio Descrizione
    Nome ambiente AzureStackUser Usare AzureStackUser per l'ambiente utente. Se si è un operatore, specificare AzureStackAdmin.
    L'endpoint di Resource Manager https://management.contoso.onmicrosoft.com ResourceManagerUrl in ASDK è: https://management.local.azurestack.external/ResourceManagerUrl nei sistemi integrati è: https://management.<region>.<fqdn>/ se si ha una domanda sull'endpoint di sistema integrato, contattare l'operatore cloud.
    Endpoint di archiviazione local.contoso.onmicrosoft.com local.azurestack.external è per l'ASDK. Per un sistema integrato, usare un endpoint per il sistema.
    Suffisso Keyvault .vault.contoso.onmicrosoft.com .vault.local.azurestack.external è per l'ASDK. Per un sistema integrato, usare un endpoint per il sistema.
    ID risorsa graph di Endpoint Active Directory https://graph.windows.net/ ID risorsa di Active Directory. 
    az cloud register `
    -n <environmentname> `
    --endpoint-resource-manager "https://management.<region>.<fqdn>" `
    --suffix-storage-endpoint "<fqdn>" `
    --suffix-keyvault-dns ".vault.<fqdn>"

    È possibile trovare un riferimento per il comando register nella documentazione di riferimento dell'interfaccia della riga di comando di Azure.

  4. Impostare l'ambiente attivo usando i comandi seguenti.

    az cloud set -n <environmentname>

  5. Aggiornare la configurazione dell'ambiente per usare il profilo di versione dell'API specifico dell'hub di Azure Stack. Per aggiornare la configurazione, eseguire il comando seguente:

    az cloud update --profile 2020-09-01-hybrid

  6. Accedere all'ambiente dell'hub di Azure Stack usando il az login comando .

    È possibile accedere all'ambiente dell'hub di Azure Stack usando le credenziali utente o con un'entità servizio (SPN) fornita dall'operatore cloud.

    • Accedere come utente:

      È possibile specificare il nome utente e una password direttamente all'interno del comando az login oppure eseguire l'autenticazione tramite un browser. È necessario eseguire quest'ultima operazione se l'account dispone dell'autenticazione a più fattori abilitata:

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

      Nota

      Se l'account utente ha abilitato l'autenticazione a più fattori, usare il az login comando senza specificare il -u parametro . L'esecuzione di questo comando fornisce un URL e un codice da usare per l'autenticazione.

    • Accedere come entità servizio:

      Prima di accedere, creare un'entità servizio tramite il portale di Azure o l'interfaccia della riga di comando e assegnargli un ruolo. A questo momento, accedere usando il comando seguente:

      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. Verificare che l'ambiente sia impostato correttamente e che l'ambiente sia il cloud attivo.

        az cloud list --output table

    Si noterà che l'ambiente è elencato e IsActive è true. Ad esempio:

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

Testare la connettività

Con tutti gli elementi configurati, usare l'interfaccia della riga di comando per creare risorse all'interno dell'hub di Azure Stack. Ad esempio, è possibile creare un gruppo di risorse per un'app e aggiungere una macchina virtuale. Usare il comando seguente per creare un gruppo di risorse denominato "MyResourceGroup":

az group create -n MyResourceGroup -l local

Se il gruppo di risorse viene creato correttamente, il comando precedente restituisce le proprietà seguenti della risorsa appena creata:

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

Problemi noti generali

La correzione generale per la maggior parte dei problemi consiste nell'usare il comando che usa il az rest contesto di Azure Stack corrente, per effettuare una chiamata API REST per il comando associato al problema. Le soluzioni alternative nell'elenco dei problemi seguenti possono essere in genere adattate per altri problemi dell'interfaccia della riga di comando di Azure, purché questi problemi vengano causati dall'interfaccia della riga di comando di Azure e non dai provider di risorse dell'hub di Azure Stack o da altri servizi dell'hub di Azure Stack.

Problemi di Microsoft Graph

Si tratta dei problemi noti di Microsoft Graph per l'interfaccia della riga di comando di Azure 2.40.0 o versione successiva per l'hub di Azure Stack. Ciò influisce principalmente sugli ambienti ADFS perché non supporta Microsoft Graph.

  • az keyvault create interagisce con Microsoft Graph. Di seguito è riportata una soluzione alternativa di esempio per ADFS. In primo luogo, la soluzione alternativa usa Azure AD Graph per recuperare le informazioni utente, ad esempio, objectId anziché Microsoft Graph.

    # First, sign into Azure CLI account you want to create the Key Vault from.
# TODO: change the principal name to name of principal you want to create the key vault with.
$principalNameLike = "CloudUser*"
# TODO: change location to your preference.
$location = "local"
$aadGraph = az cloud show --query endpoints.activeDirectoryGraphResourceId --output tsv
$tenantId = az account show --query tenantId --output tsv
if ($aadGraph[-1] -ne '/')
{
    $aadGraph += '/'
}
$userObject = az rest --method get --url "${aadGraph}${tenantId}/users?api-version=1.6" `
    | ConvertFrom-Json `
    | Select-Object -ExpandProperty value `
    | Where-Object {$_.userPrincipalName -like $principalNameLike}
$body = '{
  "location": "' + $location + '",
  "properties": {
    "tenantId": "' + $tenantId + '",
    "sku": {
      "family": "A",
      "name": "standard"
    },
    "accessPolicies": [
      {
        "tenantId": "' + $tenantId + '",
        "objectId": "' + $userObject.objectId + '",
        "permissions": {
          "keys": [
            "get",
            "create",
            "delete",
            "list",
            "update",
            "import",
            "backup",
            "restore",
            "recover"
          ],
          "secrets": [
            "get",
            "list",
            "set",
            "delete",
            "backup",
            "restore",
            "recover"
          ],
          "certificates": [
            "get",
            "list",
            "delete",
            "create",
            "import",
            "update",
            "managecontacts",
            "getissuers",
            "listissuers",
            "setissuers",
            "deleteissuers",
            "manageissuers",
            "recover"
          ],
          "storage": [
            "get",
            "list",
            "delete",
            "set",
            "update",
            "regeneratekey",
            "setsas",
            "listsas",
            "getsas",
            "deletesas"
          ]
        }
      }
    ],
    "enabledForDeployment": true,
    "enabledForTemplateDeployment": true
  }
}'
$body | Out-File -FilePath (Join-Path -Path "." -ChildPath "body.json")
$resourceGroupName = "testrg123"
az group create -n $resourceGroupName -l $location
$armEndpoint = az cloud show --query endpoints.resourceManager --output tsv
if ($armEndpoint[-1] -ne '/')
{
    $armEndpoint += '/'
}
$subscriptionId = az account show --query id --output tsv
$keyVaultName = "testkv123"
az rest --method put --url "${armEndpoint}subscriptions/${subscriptionId}/resourceGroups/${resourceGroupName}/providers/Microsoft.KeyVault/vaults/${keyVaultName}?api-version=2016-10-01" --body `@body.json
# OPTIONAL: test access to the Key Vault.
# az keyvault secret set --name MySecretName --vault-name $keyVaultName --value MySecret

    Per altre informazioni sull'API REST Key Vault, vedere informazioni di riferimento sull'API REST Key Vault.

Altri problemi

Di seguito sono riportati problemi non limitati a versioni o intervalli specifici di versioni dell'interfaccia della riga di comando di Azure.

  • az role assignment create non è attualmente supportato dall'interfaccia della riga di comando di Azure per l'hub di Azure Stack a causa di un problema di API precedente. Per Microsoft Entra ID o ADFS è necessaria la soluzione alternativa seguente. 
    # First, sign into account with access to the resource that is being given access or a role to another user.
# TODO: change the principal name to name of principal you want to assign the role to.
$principalNameLike = "CloudUser*"
# TODO: change role name to your preference.
$roleName = "Owner"
# TODO: change location to your preference.
$location = "local"
$aadGraph = az cloud show --query endpoints.activeDirectoryGraphResourceId --output tsv
$tenantId = az account show --query tenantId --output tsv
if ($aadGraph[-1] -ne '/')
{
    $aadGraph += '/'
}
$userObject = az rest --method get --url "${aadGraph}${tenantId}/users?api-version=1.6" `
    | ConvertFrom-Json `
    | Select-Object -ExpandProperty value `
    | Where-Object {$_.userPrincipalName -like $principalNameLike}
$roleDefinitionId = az role definition list --query "[?roleName=='${roleName}'].id" --output tsv
$body = @{
    properties = @{
        roleDefinitionId = $roleDefinitionId
        principalId = $userObject.objectId
    }
}
$body | ConvertTo-Json | Out-File -FilePath (Join-Path -Path "." -ChildPath "body.json")
$resourceGroupName = "testrg123"
az group create -n $resourceGroupName -l $location
$armEndpoint = az cloud show --query endpoints.resourceManager --output tsv
if ($armEndpoint[-1] -ne '/')
{
    $armEndpoint += '/'
}
$scope =  az group show --name $resourceGroupName --query id --output tsv
$guid = (New-Guid).ToString()
az rest --method put --url "${armEndpoint}${scope}/providers/Microsoft.Authorization/roleAssignments/${guid}?api-version=2015-07-01" --body `@body.json
# OPTIONAL: test access to the resource group, or use the portal.
# az login -u <assigned user name> -p <assigned user password> --tenant $tenantId
# Test a resource creation command in the resource group:
# az network dns zone create -g $resourceGroupName -n "www.mysite.com"
    Per altre informazioni sull'API REST per l'assegnazione di ruoli, vedere l'articolo Assegnazioni di ruolo.

Passaggi successivi