Freigeben über

Installieren der Azure CLI in Azure Stack Hub

  • Artikel

Sie können die Azure CLI zum Verwalten von Azure Stack Hub mit Windows- oder Linux-Computern installieren. Dieser Artikel führt Sie durch die Schritte zum Installieren und Einrichten der Azure CLI.

Installieren der Azure-Befehlszeilenschnittstelle

  1. Melden Sie sich an Ihrer Entwicklungsarbeitsstation an und installieren die CLI. Für Azure Stack Hub wird Version 2.0 oder höher der Azure CLI benötigt.

    Wichtig

    Da sich ein CVE auf Azure CLI-Versionen vor 2.40.0 auswirkt, wird die Verwendung der Azure CLI 2.29.2 für AD FS in Azure Stack Hub nicht mehr empfohlen. Sie können auf Azure CLI 2.40.0 oder höher aktualisieren. Bei AD FS-Kunden können jedoch Probleme mit Azure CLI-Befehlen auftreten, die mit Microsoft Graph-Endpunkten interagieren. Dies liegt daran, dass Microsoft Graph für AD FS nicht unterstützt wird. Problemumgehungen für Microsoft Graph-Probleme finden Sie im Abschnitt Allgemeine bekannte Probleme .

  2. Mit den im Artikel Installieren der Azure CLI beschriebenen Schritten können Sie die CLI installieren.

  3. Öffnen Sie ein Terminal oder ein Eingabeaufforderungsfenster, und führen Sie den folgenden Befehl aus, um zu überprüfen, ob die Installation erfolgreich war:

    az --version

    Daraufhin sollten die Version der Azure-CLI und die anderen abhängigen Bibliotheken angezeigt werden, die auf Ihrem Computer installiert sind.

    Azure CLI am Python-Speicherort von Azure Stack Hub

  4. Notieren Sie sich den Python-Speicherort der CLI.

Zertifikat hinzufügen

Exportieren und importieren Sie das Azure Stack Hub-Zertifikat für getrennte integrierte Systeme und für das ASDK. Bei verbundenen integrierten Systemen ist das Zertifikat öffentlich signiert, sodass dieser Schritt nicht erforderlich ist. Anweisungen finden Sie unter Einrichten von Zertifikaten für die Azure CLI im Azure Stack Development Kit.

Verbinden mit der Azure CLI

Dieser Abschnitt führt Sie durch das Einrichten der CLI, wenn Sie Microsoft Entra ID als Identitätsverwaltungsdienst verwenden und die CLI auf einem Windows-Computer verwenden.

Herstellen einer Verbindung mit Azure Stack Hub

  1. Wenn Sie das ASDK verwenden, müssen Sie das Stammzertifikat der Azure Stack Hub-Zertifizierungsstelle als vertrauenswürdig einstufen. Anweisungen hierzu finden Sie unter Vertrauen des Zertifikats.

  2. Registrieren Sie Ihre Azure Stack Hub-Umgebung, indem Sie den Befehl az cloud register ausführen.

  3. Registrieren Sie Ihre Umgebung. Verwenden Sie beim Ausführen von az cloud register die folgenden Parameter:

    Wert Beispiel BESCHREIBUNG
    Umgebungsname AzureStackUser Verwenden Sie AzureStackUser für die Benutzerumgebung. Geben Sie AzureStackAdmin an, falls Sie der Betreiber der Umgebung sind.
    Resource Manager-Endpunkt https://management.contoso.onmicrosoft.com Die ResourceManagerUrl im ASDK lautet: https://management.local.azurestack.external/ Der ResourceManagerUrl-Wert in integrierten Systemen lautet: https://management.<region>.<fqdn>/ Wenn Sie eine Frage zum integrierten Systemendpunkt haben, können Sie sich an Ihren Cloudbetreiber wenden.
    Speicherendpunkt local.contoso.onmicrosoft.com local.azurestack.external ist für das ASDK bestimmt. Bei einem integrierten System verwenden Sie einen Endpunkt für Ihr System.
    Key Vault-Suffix .vault.contoso.onmicrosoft.com .vault.local.azurestack.external ist für das ASDK bestimmt. Bei einem integrierten System verwenden Sie einen Endpunkt für Ihr System.
    Ressourcen-ID des Active Directory-Endpunktgraphen https://graph.windows.net/ Active Directory-Ressourcen-ID 
    az cloud register `
    -n <environmentname> `
    --endpoint-resource-manager "https://management.<region>.<fqdn>" `
    --suffix-storage-endpoint "<fqdn>" `
    --suffix-keyvault-dns ".vault.<fqdn>"

    In der Azure CLI-Referenzdokumentation finden Sie einen Verweis auf den register-Befehl.

  4. Legen Sie die aktive Umgebung mithilfe der folgenden Befehle fest.

    az cloud set -n <environmentname>

  5. Aktualisieren Sie Ihre Umgebungskonfiguration so, dass das spezifische API-Versionsprofil für Azure Stack Hub verwendet wird. Führen Sie den folgenden Befehl aus, um die Konfiguration zu aktualisieren:

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

  6. Melden Sie sich bei Ihrer Azure Stack Hub-Umgebung an, indem Sie den Befehl az login ausführen.

    Sie können sich mit Ihren Benutzeranmeldeinformationen oder mit einem vom Cloudoperator bereitgestellten Dienstprinzipalnamen (SPN) bei der Azure Stack Hub-Umgebung anmelden.

    • Anmelden als Benutzer:

      Sie können entweder den Benutzernamen und das Kennwort direkt im Befehl az login eingeben oder die Authentifizierung über einen Browser ausführen. Sie müssen das letztgenannte Verfahren wählen, wenn für Ihr Konto die mehrstufige Authentifizierung aktiviert ist:

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

      Hinweis

      Wenn für Ihr Benutzerkonto die mehrstufige Authentifizierung aktiviert ist, verwenden Sie den Befehl az login, ohne den Parameter -u anzugeben. Durch die Ausführung des Befehls erhalten Sie eine URL und einen Code für die Authentifizierung.

    • Melden Sie sich als Dienstprinzipal an:

      Erstellen Sie einen Dienstprinzipal über das Azure-Portal oder die CLI, und weisen Sie ihm eine Rolle zu, bevor Sie sich anmelden. Melden Sie sich anschließend mit dem folgenden Befehl an:

      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. Vergewissern Sie sich, dass Ihre Umgebung ordnungsgemäß festgelegt ist und es sich Ihrer Umgebung um die aktive Cloud handelt.

        az cloud list --output table

    Ihre Umgebung sollte aufgeführt sein, und IsActive sollte true sein. Beispiel:

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

Testen der Konnektivität

Wenn alles eingerichtet ist, können Sie mit der CLI Ressourcen in Azure Stack Hub erstellen. Sie können beispielsweise eine Ressourcengruppe für eine App erstellen und einen virtuellen Computer hinzufügen. Verwenden Sie den folgenden Befehl, um eine Ressourcengruppe mit dem Namen „MyResourceGroup“ zu erstellen:

az group create -n MyResourceGroup -l local

Wenn die Ressourcengruppe erfolgreich erstellt wurde, werden mit dem vorherigen Befehl die folgenden Eigenschaften der neu erstellten Ressource ausgegeben:

{
  "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/RGCL11",
  "location": "local",
  "name": "RGCLI1",
  " properties ": {
    "provisioningState": "Succeeded"
  },
  "tags ": null
}

Allgemeine bekannte Probleme

Die allgemeine Lösung für die meisten Probleme besteht darin, den az rest Befehl zu verwenden, der den aktuellen Azure Stack-Kontext verwendet, um einen REST-API-Aufruf für den zugeordneten Befehl mit dem Problem auszuführen. Die Problemumgehungen in der folgenden Problemliste können im Allgemeinen für andere Probleme der Azure CLI angepasst werden, solange diese Probleme von der Azure CLI und nicht von Azure Stack Hub-Ressourcenanbietern oder anderen Azure Stack Hub-Diensten verursacht werden.

Microsoft Graph-Probleme

Dies sind die bekannten Microsoft Graph-Probleme für Azure CLI 2.40.0 oder höher für Azure Stack Hub. Dies wirkt sich in erster Linie auf AD FS-Umgebungen aus, da Microsoft Graph nicht unterstützt wird.

  • az keyvault create interagiert mit Microsoft Graph. Es folgt ein Beispiel für die Problemumgehung für AD FS. In erster Linie verwendet die Problemumgehung Azure AD Graph, um Benutzerinformationen wie die objectId von Microsoft Graph abzurufen.

    # 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

    Weitere Informationen zu Key Vault REST-API finden Sie in der referenz zur Key Vault REST-API.

Andere Probleme

Die folgenden Probleme sind nicht auf bestimmte Versionen oder Bereiche von Versionen der Azure CLI beschränkt.

  • az role assignment create wird derzeit aufgrund eines alten API-Problems nicht von der Azure CLI für Azure Stack Hub unterstützt. Die folgende Problemumgehung ist sowohl für Microsoft Entra-ID als auch für AD FS erforderlich. 
    # 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"
    Weitere Informationen zur REST-API für Rollenzuweisungen finden Sie im Artikel Rollenzuweisungen.

Nächste Schritte