Instalar a CLI do Azure no Azure Stack Hub

  • Artigo

Você pode instalar a CLI do Azure para gerenciar o Azure Stack Hub com computadores Windows ou Linux. Este artigo orienta você pelas etapas de instalação e configuração da CLI do Azure.

Instalar a CLI do Azure.

  1. Entre em sua 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 uma CVE que afeta as versões da CLI do Azure anteriores à 2.40.0, não é mais recomendável que você use a CLI do Azure 2.29.2 para o AD FS no Azure Stack Hub. Você pode atualizar para a CLI do Azure 2.40.0 ou superior. No entanto, os clientes do AD FS podem encontrar problemas com os comandos da CLI do Azure que interagem com os pontos de extremidade do Microsoft Graph. Isso ocorre porque o Microsoft Graph não tem suporte para o AD FS. Para obter soluções alternativas para problemas do Microsoft Graph, consulte a seção Problemas conhecidos em geral .

  2. Você pode instalar a CLI usando as etapas descritas no artigo Instalar a CLI do Azure .

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

    az --version

    Você deve ver a versão da CLI do Azure e outras bibliotecas dependentes instaladas em seu computador.

    CLI do Azure no local do Python do Azure Stack Hub

  4. Anote a localização do Python da CLI.

Adicionar certificado

Exporte e importe o certificado do Azure Stack Hub para sistemas integrados desconectados e para o ASDK. Para sistemas integrados conectados, o certificado é assinado publicamente e essa etapa não é necessária. Para obter instruções, consulte Configurando certificados para a CLI do Azure no Azure Stack Development Kit.

Conectar-se à CLI do Azure

Esta seção orienta você pela configuração da CLI se você estiver usando Microsoft Entra ID como seu serviço de gerenciamento de identidade e estiver usando a CLI em um computador Windows.

Conectar-se ao Azure Stack Hub

  1. Se você estiver usando o ASDK, confie no certificado raiz de AC do Azure Stack Hub. Para obter instruções, consulte Confiar no certificado.

  2. Registre seu ambiente do Azure Stack Hub executando o az cloud register comando .

  3. Registre seu ambiente. Use os seguintes parâmetros ao executar az cloud register:

    Valor Exemplo Descrição
    Nome do ambiente AzureStackUser Use AzureStackUser para o ambiente do usuário. Se você for operador, especifique AzureStackAdmin.
    Ponto de extremidade do 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 você tiver uma pergunta sobre o ponto de extremidade integrado do sistema, entre em contato com o operador de nuvem.
    Ponto de extremidade de armazenamento local.contoso.onmicrosoft.com local.azurestack.external é para o ASDK. Para um sistema integrado, use um ponto de extremidade para seu sistema.
    Sufixo keyvault .vault.contoso.onmicrosoft.com .vault.local.azurestack.external é para o ASDK. Para um sistema integrado, use um ponto de extremidade para seu sistema.
    ID do recurso de grafo do Active Directory do ponto de extremidade https://graph.windows.net/ A 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>"

    Você pode encontrar uma referência para o comando register na documentação de referência da CLI do Azure.

  4. Defina o ambiente ativo usando os comandos a seguir.

    az cloud set -n <environmentname>

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

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

  6. Entre no ambiente do Azure Stack Hub usando o az login comando .

    Você pode entrar no ambiente do Azure Stack Hub usando suas credenciais de usuário ou com uma SPN ( entidade de serviço ) fornecida pelo operador de nuvem.

    • Entre como um usuário:

      Especifique o nome de usuário e a senha diretamente no comando az login ou autentique-se usando um navegador. Você deverá fazer o último se sua conta tiver a autenticação multifator habilitada:

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

      Observação

      Se sua conta de usuário tiver a autenticação multifator habilitada, use o az login comando sem fornecer o -u parâmetro . Executar esse comando fornece uma URL e um código que você deve usar para autenticar.

    • Entre como uma entidade de serviço:

      Antes de entrar, crie uma entidade de serviço por meio do portal do Azure ou da CLI e atribua uma função a ela. Agora, entre usando 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 ambiente é a nuvem ativa.

        az cloud list --output table

    Você deve ver que seu ambiente está listado e 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, use a CLI para criar recursos no Azure Stack Hub. Por exemplo, você pode criar um grupo de recursos para um aplicativo e adicionar uma VM. Use o seguinte comando para criar um grupo de recursos chamado "MyResourceGroup":

az group create -n MyResourceGroup -l local

Se o grupo de recursos for criado com êxito, o comando anterior produzirá 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 é usar o az rest comando que usa o contexto atual do Azure Stack para fazer uma chamada à API REST para o comando associado com o problema. As soluções alternativas na lista de problemas a seguir geralmente podem ser adaptadas para outros problemas da CLI do Azure, desde que esses problemas sejam causados pela CLI do Azure e não por provedores de recursos do Azure Stack Hub ou outros serviços do Azure Stack Hub.

Problemas do Microsoft Graph

Esses são os problemas conhecidos do Microsoft Graph para a CLI do Azure 2.40.0 ou superior para o Azure Stack Hub. Isso afeta principalmente ambientes do ADFS, pois não dá suporte ao Microsoft Graph.

  • az keyvault create interage com o Microsoft Graph. Veja a seguir uma solução alternativa de exemplo para o ADFS. Principalmente, a solução alternativa usa o Azure AD Graph para recuperar informações do usuário, como o objectId e não o 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, consulte a referência da API REST Key Vault.

Outros problemas

Veja a seguir problemas que não se limitam a versões ou intervalos específicos de versões da CLI do Azure.

  • az role assignment create Atualmente, não há suporte da CLI do Azure para o Azure Stack Hub devido a um problema antigo de API. A solução alternativa a seguir é 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ção, consulte o artigo atribuições de função.

Próximas etapas