Instalación de la CLI de Azure en Azure Stack Hub

  • Artículo

Puede instalar la CLI de Azure para administrar Azure Stack Hub con una máquina Windows o Linux. Este artículo le guía por los pasos necesarios para instalar y configurar la CLI de Azure.

Instalación de la CLI de Azure

  1. Inicie sesión en la estación de trabajo de desarrollo e instale la CLI. Azure Stack Hub requiere la versión 2.0 o superior de la CLI de Azure.

    Importante

    Debido a un CVE que afecta a las versiones de la CLI de Azure anteriores a la versión 2.40.0, ya no se recomienda usar la CLI de Azure 2.29.2 para AD FS en Azure Stack Hub. Puede actualizar a la CLI de Azure 2.40.0 o posterior. Sin embargo, los clientes de AD FS pueden encontrar problemas con los comandos de la CLI de Azure que interactúan con los puntos de conexión de Microsoft Graph. Esto se debe a que Microsoft Graph no es compatible con AD FS. Para obtener soluciones alternativas a los problemas de Microsoft Graph, consulte la sección Problemas conocidos generales .

  2. Puede instalar la CLI mediante los pasos descritos en el artículo Instalación de la CLI de Azure.

  3. Para comprobar si la instalación se realizó correctamente, abra un terminal o una ventana del símbolo del sistema y ejecute el siguiente comando:

    az --version

    Debería ver la versión de la CLI de Azure y otras bibliotecas dependientes instaladas en su equipo.

    CLI de Azure en la ubicación de Python de Azure Stack Hub

  4. Tome nota de la ubicación de Python de la CLI.

Agregar certificado

Exporte e importe el certificado de Azure Stack Hub para los sistemas integrados desconectados y para el ASDK. En el caso de los sistemas integrados, el certificado está firmado públicamente y este paso no es necesario. Para obtener instrucciones, consulte Configuración de certificados para la CLI de Azure en el Kit de desarrollo de Azure Stack.

Conexión con la CLI de Azure

En esta sección se explica cómo configurar la CLI si usa Microsoft Entra id. como servicio de administración de identidades y usa la CLI en un equipo Windows.

Conexión a Azure Stack Hub

  1. Si va a utilizar el ASDK, confíe en el certificado raíz de la entidad de certificación de Azure Stack Hub. Para obtener instrucciones, consulte Confiar en el certificado.

  2. Registre el entorno de Azure Stack Hub. Para ello, ejecute el comando az cloud register.

  3. Registre su entorno. Utilice los siguientes parámetros cuando ejecute az cloud register:

    Valor Ejemplo Descripción
    Nombre del entorno AzureStackUser Use AzureStackUser para el entorno de usuario. Si es operador, especifique AzureStackAdmin.
    Punto de conexión de Resource Manager https://management.contoso.onmicrosoft.com El valor de ResourceManagerUrl del ASDK es el siguiente: https://management.local.azurestack.external/ El valor de ResourceManagerUrl en los sistemas integrados es: https://management.<region>.<fqdn>/ Si tiene alguna pregunta sobre el punto de conexión del sistema integrado, póngase en contacto con su operador de nube.
    Punto de conexión de Storage local.contoso.onmicrosoft.com local.azurestack.external es para el ASDK. Para un sistema integrado, utilice un punto de conexión del sistema.
    Sufijo de Key Vault .vault.contoso.onmicrosoft.com .vault.local.azurestack.external es para el ASDK. Para un sistema integrado, utilice un punto de conexión del sistema.
    Identificador de recurso de grafo de Active Directory de punto de conexión https://graph.windows.net/ El identificador de recurso de Active Directory. 
    az cloud register `
    -n <environmentname> `
    --endpoint-resource-manager "https://management.<region>.<fqdn>" `
    --suffix-storage-endpoint "<fqdn>" `
    --suffix-keyvault-dns ".vault.<fqdn>"

    Puede encontrar una referencia del register en la documentación de referencia de la CLI de Azure.

  4. Establezca el entorno activo mediante los comandos siguientes.

    az cloud set -n <environmentname>

  5. Actualice la configuración del entorno para usar el perfil de la versión de API específico de Azure Stack Hub. Para actualizar la configuración, ejecute el comando siguiente:

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

  6. Inicie sesión en el entorno de Azure Stack Hub. Para ello, use el comando az login.

    Puede iniciar sesión en el entorno de Azure Stack Hub con sus credenciales de usuario o con una entidad de servicio (SPN) proporcionada por el operador en la nube.

    • Iniciar sesión como usuario:

      puede especificar el nombre de usuario y la contraseña directamente en el comando az login o autenticarse utilizando un explorador. Tendrá que hacer esto último si la cuenta tiene habilitada la autenticación multifactor:

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

      Nota

      Si su cuenta de usuario tiene habilitada la autenticación multifactor, use el comando az login sin indicar el parámetro -u. Al ejecutar este comando, se le proporciona una URL y un código que debe usar para la autenticación.

    • Inicie sesión como una entidad de servicio:

      Antes de iniciar sesión, cree una entidad de servicio en Azure Portal o mediante la CLI y asígnele un rol. Ahora, inicie sesión con el siguiente 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. Compruebe que el entorno esté configurado correctamente y que el entorno sea la nube activa.

        az cloud list --output table

    Debería ver que el entorno aparece en la lista y que el valor de IsActive es true. Por ejemplo:

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

Prueba de la conectividad

Con todo configurado, vamos a usar la CLI para crear recursos en Azure Stack Hub. Por ejemplo, puede crear un grupo de recursos para una aplicación y agregar una máquina virtual. Use el comando siguiente para crear un grupo de recursos denominado "MyResourceGroup":

az group create -n MyResourceGroup -l local

Si el grupo de recursos se crea correctamente, el comando anterior da como resultado las siguientes propiedades del recurso recién creado:

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

Problemas conocidos generales

La corrección general de la mayoría de los problemas es usar el az rest comando que usa el contexto actual de Azure Stack para realizar una llamada a la API REST para el comando asociado al problema. Por lo general, las soluciones alternativas de la lista de problemas siguientes se pueden adaptar a otros problemas de la CLI de Azure, siempre que estos problemas se deban a la CLI de Azure y no a proveedores de recursos de Azure Stack Hub u otros servicios de Azure Stack Hub.

Problemas de Microsoft Graph

Estos son los problemas conocidos de Microsoft Graph para la CLI de Azure 2.40.0 o superior para Azure Stack Hub. Esto afecta principalmente a los entornos de ADFS, ya que no admite Microsoft Graph.

  • az keyvault create interactúa con Microsoft Graph. A continuación se muestra una solución alternativa de ejemplo para ADFS. Principalmente, la solución alternativa usa Azure AD Graph para recuperar información de usuario como , objectId en lugar de 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 obtener más información sobre Key Vault API REST, consulte la referencia de la API de REST de Key Vault.

Otros problemas

Los siguientes son problemas no limitados a versiones o intervalos específicos de versiones de la CLI de Azure.

  • az role assignment create actualmente no es compatible con la CLI de Azure para Azure Stack Hub debido a un problema de API anterior. Se requiere la siguiente solución alternativa para Microsoft Entra id. o 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 obtener más información sobre la API REST de asignación de roles, consulte el artículo Asignaciones de roles.

Pasos siguientes