Partilhar via

Instalar a CLI do Azure no Azure Stack Hub

Você pode instalar a CLI do Azure para gerenciar o Azure Stack Hub com máquinas Windows ou Linux. Este artigo orienta você pelas etapas para instalar e configurar a CLI do Azure.

Instalar a CLI do Azure

  1. Entre 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 uma CVE que afeta as versões da CLI do Azure anteriores à 2.40.0, não é mais recomendado que você use a CLI do Azure 2.29.2 para 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 Azure CLI que interagem com endpoints do Microsoft Graph. Isso ocorre porque o Microsoft Graph não é suportado para AD FS. Para obter soluções alternativas para problemas do Microsoft Graph, consulte a seção Problemas gerais conhecidos .

  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 no seu computador.

    Localização do Python para o Azure CLI no Azure Stack Hub

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

Adicionar certificado

Exporte e importe o certificado do Azure Stack Hub para sistemas integrados desconectados. Para sistemas integrados conectados, o certificado é assinado publicamente e esta etapa não é necessária.

Conecte-se com a CLI do Azure

Esta seção orienta você na configuração da CLI se você estiver usando o Microsoft Entra ID como seu serviço de gerenciamento de identidades e estiver usando a CLI em uma máquina Windows.

Conectar-se ao Azure Stack Hub

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

  2. Registe o 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 em sistemas integrados é: https://management.<region>.<fqdn>/. Se você tiver alguma dúvida sobre o endpoint do sistema integrado, entre em contato com seu operador de nuvem.
    Ponto final de armazenamento local.contoso.onmicrosoft.com Para um sistema integrado, use um ponto de extremidade para o seu sistema.
    Sufixo de Keyvault .vault.contoso.onmicrosoft.com Para um sistema integrado, use um ponto de extremidade para o seu sistema.
    ID do recurso de gráfico do Active Directory do endpoint https://graph.microsoft.com/ O ID do 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>"

    Para obter mais informações, consulte o comando register na documentação de referência da CLI do Azure.

  3. Defina o ambiente ativo usando os seguintes comandos.

    az cloud set -n <environmentname>

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

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

  5. Entre em seu 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 entidade de serviço (SPN) fornecida a você pelo seu operador de nuvem.

    • Inicie sessão como utilizador:

    Você pode especificar o nome de usuário e a senha diretamente no az login comando ou autenticar usando um navegador. Você deve autenticar usando um navegador 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. A execução deste comando fornece uma URL e um código que você deve usar para autenticar.

    • Inicie sessão como entidade de serviço:

      Antes de entrar, crie uma entidade de serviço por meio do portal do Azure ou da CLI e atribua-lhe uma função. 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>

  6. 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/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/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 de API REST para o comando associado ao 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 pelos provedores 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 do Azure 2.40.0, ou superior, para o Azure Stack Hub. Isso afeta principalmente os ambientes AD FS, pois eles não oferecem suporte ao Microsoft Graph.

  • az keyvault create interage com o Microsoft Graph. Segue-se um exemplo de solução alternativa para o AD FS. Principalmente, a solução alternativa usa o Azure AD Graph para recuperar informações do usuário, como o objectId, em vez de usar 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 a API REST do Cofre da Chave, consulte a Referência da API REST do Cofre da Chave.

Outras questões

A seguir estão os problemas não limitados a versões específicas ou intervalos de versões da CLI do Azure.

  • az role assignment create atualmente não é suportado pela CLI do Azure para o Azure Stack Hub devido a um problema de API antigo. A seguinte solução alternativa é necessária para o Microsoft Entra ID ou o AD FS.

    # 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óximos passos

  • Last updated on