Instalar a CLI do Azure no Azure Stack Hub

  • Artigo

Pode instalar a CLI do Azure para gerir o Azure Stack Hub com computadores Windows ou Linux. Este artigo explica-lhe os passos para instalar e configurar a CLI do Azure.

Instalar a CLI do Azure

  1. Inicie sessão na estação de trabalho de desenvolvimento e instale a CLI. O Azure Stack Hub requer a versão 2.0 ou posterior da CLI do Azure.

    Importante

    Devido a um CVE que afeta as versões da CLI do Azure anteriores à versão 2.40.0, já não é recomendado que utilize a CLI 2.29.2 do Azure para o AD FS no Azure Stack Hub. Pode atualizar para a CLI 2.40.0 ou superior do Azure. No entanto, os clientes do AD FS podem encontrar problemas com comandos da CLI do Azure que interagem com pontos finais do Microsoft Graph. Isto acontece porque o Microsoft Graph não é suportado para o AD FS. Para obter soluções para problemas do Microsoft Graph, veja a secção Problemas conhecidos gerais .

  2. Pode instalar a CLI com os passos descritos no artigo Instalar a CLI do Azure .

  3. Para verificar se a instalação foi bem-sucedida, abra uma janela de terminal ou linha de comandos e execute o seguinte comando:

    az --version

    Deverá ver a versão da CLI do Azure e outras bibliotecas dependentes que estão instaladas no seu computador.

    CLI do Azure na localização python do Azure Stack Hub

  4. Anote a localização python da CLI.

Adicionar um certificado

Exporte e importe o certificado do Azure Stack Hub para sistemas integrados desligados e para o ASDK. Para sistemas integrados ligados, o certificado é assinado publicamente e este passo não é necessário. Para obter instruções, veja Configurar certificados para a CLI do Azure no Development Kit do Azure Stack.

Ligar à CLI do Azure

Esta secção orienta-o ao longo da configuração da CLI se estiver a utilizar Microsoft Entra ID como o seu serviço de gestão de identidades e estiver a utilizar a CLI num computador Windows.

Ligar ao Azure Stack Hub

  1. Se estiver a utilizar o ASDK, confie no certificado de raiz da AC do Azure Stack Hub. Para obter instruções, veja Confiar no certificado.

  2. Registe o ambiente do Azure Stack Hub ao executar o az cloud register comando .

  3. Registe o seu ambiente. Utilize os seguintes parâmetros ao executar az cloud register:

    Valor Exemplo Descrição
    Nome do ambiente AzureStackUser Utilize AzureStackUser para o ambiente de utilizador. Se for operador, especifique AzureStackAdmin.
    ponto final Resource Manager https://management.contoso.onmicrosoft.com O ResourceManagerUrl no ASDK é: https://management.local.azurestack.external/ O ResourceManagerUrl em sistemas integrados é: https://management.<region>.<fqdn>/ se tiver uma pergunta sobre o ponto final do sistema integrado, contacte o operador da cloud.
    Ponto final de armazenamento local.contoso.onmicrosoft.com local.azurestack.external é para o ASDK. Para um sistema integrado, utilize um ponto final para o seu sistema.
    Sufixo keyvault .vault.contoso.onmicrosoft.com .vault.local.azurestack.external é para o ASDK. Para um sistema integrado, utilize um ponto final para o seu sistema.
    ID de recurso do grafo do Active Directory do ponto final https://graph.windows.net/ O ID de recurso do Active Directory. 
    az cloud register `
    -n <environmentname> `
    --endpoint-resource-manager "https://management.<region>.<fqdn>" `
    --suffix-storage-endpoint "<fqdn>" `
    --suffix-keyvault-dns ".vault.<fqdn>"

    Pode encontrar uma referência para o comando registar na documentação de referência da CLI do Azure.

  4. Defina o ambiente ativo com os seguintes comandos.

    az cloud set -n <environmentname>

  5. Atualize a configuração do ambiente para utilizar o perfil de versão de API específico do Azure Stack Hub. Para atualizar a configuração, execute o seguinte comando:

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

  6. Inicie sessão no ambiente do Azure Stack Hub com o az login comando .

    Pode iniciar sessão no ambiente do Azure Stack Hub com as suas credenciais de utilizador ou com um principal de serviço (SPN) fornecido pelo operador da cloud.

    • Inicie sessão como utilizador:

      Pode especificar o nome de utilizador e a palavra-passe diretamente no az login comando ou autenticar através de um browser. Tem de efetuar este último procedimento se a sua conta tiver a autenticação multifator ativada:

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

      Nota

      Se a sua conta de utilizador tiver a autenticação multifator ativada, utilize o az login comando sem fornecer o -u parâmetro . A execução deste comando fornece-lhe um URL e um código que tem de utilizar para autenticar.

    • Inicie sessão como um principal de serviço:

      Antes de iniciar sessão, crie um principal de serviço através do portal do Azure ou da CLI e atribua-lhe uma função. Agora, inicie sessão com o seguinte comando:

      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. Verifique se o ambiente está definido corretamente e se o seu ambiente é a cloud ativa.

        az cloud list --output table

    Deverá ver que o seu ambiente está listado e o IsActive é true. Por exemplo:

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

Testar a conectividade

Com tudo configurado, utilize a CLI para criar recursos no Azure Stack Hub. Por exemplo, pode criar um grupo de recursos para uma aplicação e adicionar uma VM. Utilize o seguinte comando para criar um grupo de recursos com o nome "MyResourceGroup":

az group create -n MyResourceGroup -l local

Se o grupo de recursos for criado com êxito, o comando anterior produz as seguintes propriedades do recurso recém-criado:

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

Problemas gerais conhecidos

A correção geral para a maioria dos problemas é utilizar o az rest comando que utiliza o contexto atual do Azure Stack, para fazer uma chamada à API REST para o comando associado ao problema. Geralmente, as soluções na lista de problemas seguintes podem ser adaptadas para outros problemas da CLI do Azure, desde que estes problemas sejam causados pela CLI do Azure e não por fornecedores de recursos do Azure Stack Hub ou outros serviços do Azure Stack Hub.

Problemas do Microsoft Graph

Estes são os problemas conhecidos do Microsoft Graph para a CLI 2.40.0 do Azure ou superior para o Azure Stack Hub. Isto afeta principalmente os ambientes do ADFS, uma vez que não suporta o Microsoft Graph.

  • az keyvault create interage com o Microsoft Graph. Segue-se uma solução de exemplo para o ADFS. Principalmente, a solução utiliza o Graph Azure AD para obter informações de utilizador, como o objectId em vez do 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

    Para obter mais informações sobre Key Vault API REST, veja a referência da API REST Key Vault.

Outros problemas

Seguem-se problemas não limitados a versões ou intervalos específicos de versões da CLI do Azure.

  • az role assignment create Atualmente, a CLI do Azure para o Azure Stack Hub não é suportada devido a um problema antigo da API. A seguinte solução é necessária para 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"
    Para obter mais informações sobre a API REST de atribuição de funções, veja o artigo atribuições de funções.

Passos seguintes