Installer Azure CLI sur Azure Stack Hub

  • Article

Vous pouvez installer Azure CLI pour gérer Azure Stack Hub avec un ordinateur Windows ou Linux. Cet article vous guide tout au long de la procédure d’installation et de configuration d’Azure CLI.

Installation de l’interface de ligne de commande Azure

  1. Connectez-vous à votre station de travail de développement et installez l’interface CLI. Azure Stack Hub nécessite la version 2.0 ou ultérieure d'Azure CLI.

    Important

    En raison d’un CVE affectant les versions d’Azure CLI antérieures à 2.40.0, il n’est plus recommandé d’utiliser Azure CLI 2.29.2 pour AD FS dans Azure Stack Hub. Vous pouvez effectuer une mise à jour vers Azure CLI 2.40.0 ou une version ultérieure. Toutefois, les clients AD FS peuvent rencontrer des problèmes avec les commandes Azure CLI qui interagissent avec les points de terminaison Microsoft Graph. Cela est dû au fait que Microsoft Graph n’est pas pris en charge pour AD FS. Pour obtenir des solutions de contournement aux problèmes liés à Microsoft Graph, consultez la section Problèmes connus généraux .

  2. Vous pouvez l’installer en utilisant la procédure décrite dans l’article Installer Azure CLI.

  3. Pour vérifier que l’installation a réussi, ouvrez un terminal ou une fenêtre d’invite de commandes, puis exécutez la commande suivante :

    az --version

    Vous devriez voir la version d’Azure CLI et d’autres bibliothèques dépendantes installées sur votre ordinateur.

    Azure CLI sur l'emplacement Python Azure Stack Hub

  4. Prenez note de l’emplacement Python de l’interface CLI.

Ajouter un certificat

Exportez, puis importez le certificat Azure Stack Hub pour les systèmes intégrés déconnectés et pour l’ASDK. Pour les systèmes intégrés connectés, le certificat étant signé publiquement, cette étape n’est pas nécessaire. Pour obtenir des instructions, consultez Configuration de certificats pour Azure CLI sur le Kit de développement Azure Stack.

Se connecter avec Azure CLI

Cette section vous guide tout au long de la configuration de l’interface CLI si vous utilisez Microsoft Entra ID comme service de gestion des identités et que vous utilisez l’interface CLI sur un ordinateur Windows.

Se connecter à Azure Stack Hub

  1. Si vous utilisez le kit ASDK, approuvez le certificat racine de l’autorité de certification Azure Stack Hub. Pour obtenir des instructions, consultez Approuver le certificat.

  2. Inscrivez votre environnement Azure Stack Hub en exécutant la commande az cloud register.

  3. Inscrivez votre environnement. Utilisez les paramètres suivants lors de l’exécution de az cloud register :

    Valeur Exemple Description
    Nom de l’environnement AzureStackUser Pour l’environnement utilisateur, utilisez AzureStackUser. Si vous êtes un opérateur, spécifiez AzureStackAdmin.
    Point de terminaison Resource Manager https://management.contoso.onmicrosoft.com La propriété ResourceManagerUrl dans l’ASDK est : https://management.local.azurestack.external/ResourceManagerUrl dans les systèmes intégrés est : https://management.<region>.<fqdn>/ Si vous avez une question sur le point de terminaison du système intégré, contactez votre opérateur cloud.
    Point de terminaison de stockage local.contoso.onmicrosoft.com local.azurestack.external concerne l’ASDK. Pour un système intégré, utilisez un point de terminaison pour votre système.
    Suffixe du coffre de clés .vault.contoso.onmicrosoft.com .vault.local.azurestack.external concerne l’ASDK. Pour un système intégré, utilisez un point de terminaison pour votre système.
    ID de ressource de graphique Active Directory du point de terminaison https://graph.windows.net/ L’ID de ressource Active Directory. 
    az cloud register `
    -n <environmentname> `
    --endpoint-resource-manager "https://management.<region>.<fqdn>" `
    --suffix-storage-endpoint "<fqdn>" `
    --suffix-keyvault-dns ".vault.<fqdn>"

    Vous trouverez une référence pour la commande register dans la documentation de référence d’Azure CLI.

  4. Définissez l’environnement actif avec les commandes suivantes.

    az cloud set -n <environmentname>

  5. Mettez à jour la configuration de votre environnement pour utiliser le profil de version des API propre à Azure Stack Hub. Pour mettre à jour la configuration, exécutez la commande suivante :

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

  6. Connectez-vous à votre environnement Azure Stack Hub à l'aide de la commande az login.

    Vous pouvez vous connecter à l’environnement Azure Stack Hub à l’aide de vos informations d’identification de l’utilisateur ou avec un principal de service (SPN) qui vous est fourni par votre opérateur cloud.

    • Connectez-vous en tant qu’utilisateur :

      Vous pouvez spécifier directement le nom d’utilisateur et le mot de passe dans la commande az login, ou vous authentifier avec un navigateur. Vous devez choisir cette dernière solution si l’authentification multifacteur est activée sur votre compte :

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

      Notes

      Si l’authentification multifacteur est activée sur votre compte d’utilisateur, utilisez la commande az login sans fournir le paramètre -u. L’exécution de cette commande vous donne une URL et un code à utiliser pour vous authentifier.

    • Connectez-vous en tant que principal de service :

      avant de vous connecter, créez un principal de service avec le portail Azure ou l’interface CLI, et attribuez-lui un rôle. Ensuite, connectez-vous avec la commande suivante :

      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. Vérifiez que votre environnement est correctement défini et que votre environnement est le cloud actif.

        az cloud list --output table

    Votre environnement doit être listé et IsActive doit être true. Par exemple :

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

Tester la connectivité

Lorsque tout est configuré, utilisez l'interface CLI pour créer des ressources dans Azure Stack Hub. Par exemple, vous pouvez créer un groupe de ressources pour une app et ajouter une machine virtuelle. Utilisez la commande suivante pour créer le groupe de ressources nommé « myResourceGroup » :

az group create -n MyResourceGroup -l local

Si la création du groupe de ressources réussit, la commande précédente affiche les propriétés suivantes pour la ressource créée :

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

Problèmes généraux connus

Le correctif général pour la plupart des problèmes consiste à utiliser la az rest commande qui utilise le contexte Azure Stack actuel pour effectuer un appel d’API REST pour la commande associée au problème. Les solutions de contournement de la liste des problèmes suivantes peuvent généralement être adaptées pour d’autres problèmes Azure CLI tant que ces problèmes sont causés par Azure CLI et non par des fournisseurs de ressources Azure Stack Hub ou d’autres services Azure Stack Hub.

Problèmes liés à Microsoft Graph

Il s’agit des problèmes connus de Microsoft Graph pour Azure CLI 2.40.0 ou version ultérieure pour Azure Stack Hub. Cela affecte principalement les environnements ADFS, car il ne prend pas en charge Microsoft Graph.

  • az keyvault create interagit avec Microsoft Graph. Voici un exemple de solution de contournement pour ADFS. Principalement, la solution de contournement utilise Azure AD Graph pour récupérer des informations utilisateur telles que le objectId plutôt que 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

    Pour plus d’informations sur Key Vault API REST, consultez les informations de référence sur l’API REST Key Vault.

Autres problèmes

Les problèmes suivants ne se limitent pas à des versions spécifiques ou à des plages de versions d’Azure CLI.

  • az role assignment create n’est actuellement pas pris en charge par Azure CLI pour Azure Stack Hub en raison d’un ancien problème d’API. La solution de contournement suivante est requise pour Microsoft Entra ID ou ADFS. 
    # 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"
    Pour plus d’informations sur l’API REST d’attribution de rôle, consultez l’article Attributions de rôles.

Étapes suivantes