Implementación de recursos con las plantillas de Resource Manager y Azure PowerShell

En este artículo, se explica cómo se utiliza Azure PowerShell con plantillas de Azure Resource Manager para implementar recursos en Azure. Si no está familiarizado con los conceptos de implementación y administración de las soluciones de Azure, vea Información general sobre plantillas.

Sugerencia

Se recomienda Bicep porque ofrece las mismas funcionalidades que las plantillas de ARM y la sintaxis es más fácil de usar. Para obtener más información, consulte Cómo implementar recursos con Bicep y Azure PowerShell.

Requisitos previos

Necesita una plantilla para implementar. Si aún no tiene ninguna, descargue una plantilla de ejemplo desde el repositorio Azure Quickstart Templates y guárdela. El nombre de archivo local que se utiliza en este artículo es C:\MyTemplates\azuredeploy.json.

Debe instalar Azure PowerShell y conectarse a Azure:

• Instale los cmdlets de Azure PowerShell en el equipo local. Para más información, consulte el artículo de introducción a Azure PowerShell.
• Conéctese a Azure utilizando Connect-AZAccount . Si tiene varias suscripciones de Azure, es posible que también tenga que ejecutar Set-AzContext. Para más información, consulte Use multiple Azure subscriptions (Uso de varias suscripciones de Azure).

Si no tiene instalado PowerShell, puede usar Azure Cloud Shell. Para obtener más información, vea Implementación de plantillas de Resource Manager desde Cloud Shell.

Permisos necesarios

Para implementar un archivo de Bicep o una plantilla de ARM, se necesita acceso de escritura en los recursos que implementa y acceso a todas las operaciones del tipo de recurso Microsoft.Resources/deployments. Por ejemplo, para implementar una máquina virtual, necesita los permisos Microsoft.Compute/virtualMachines/write y Microsoft.Resources/deployments/*. La operación what-if tiene los mismos requisitos de permisos.

Para obtener una lista de roles y permisos, consulte Roles integrados de Azure.

Ámbito de la implementación

La implementación puede tener como destino un grupo de recursos, una suscripción, un grupo de administración o un inquilino. Según el ámbito de la implementación, usará comandos diferentes.

• Para implementar en un grupo de recursos, utilice New-AzResourceGroupDeployment:

  New-AzResourceGroupDeployment -ResourceGroupName <resource-group-name> -TemplateFile <path-to-template>
  

• Para hacer la implementación en una suscripción, use New-AzSubscriptionDeployment, que es un alias del cmdlet New-AzDeployment:

  New-AzSubscriptionDeployment -Location <location> -TemplateFile <path-to-template>
  

  Para más información sobre las implementaciones en el nivel de suscripción, consulte Creación de grupos de recursos y otros recursos en el nivel de suscripción.

• Para hacer la implementación en un grupo de administración, use New-AzManagementGroupDeployment.

  New-AzManagementGroupDeployment -Location <location> -TemplateFile <path-to-template>
  

  Para obtener más información sobre las implementaciones de nivel de grupo de administración, consulte Creación de recursos en el nivel de grupo de administración.

• Para hacer la implementación en un inquilino, use New-AzTenantDeployment.

  New-AzTenantDeployment -Location <location> -TemplateFile <path-to-template>
  

  Para más información sobre las implementaciones a nivel de inquilino, consulte Creación de recursos en el nivel de inquilino.

Para cada ámbito, el usuario que implementa la plantilla debe tener permisos para crear recursos.

Nombre de implementación

Al implementar una plantilla de Resource Manager, puede asignarle un nombre a la implementación. Este nombre puede ayudarle a recuperar la implementación del historial de implementaciones. Si no especifica un nombre para la implementación, se utilizará el nombre del archivo de la plantilla. Por ejemplo, si implementa una plantilla llamada azuredeploy.json y no especifica ningún nombre para la implementación, el nombre que se asignará será azuredeploy.

Cada vez que se ejecuta una implementación, se agrega una entrada al historial de implementación del grupo de recursos con el nombre de la implementación. Si ejecuta otra implementación y le asigna el mismo nombre, la entrada anterior se reemplazará por la implementación actual. Si desea que todas las entradas del historial de implementaciones sean diferentes, asigne un nombre único a cada implementación.

Para crear un nombre único, puede asignar un número aleatorio.

$suffix = Get-Random -Maximum 1000
$deploymentName = "ExampleDeployment" + $suffix

También puede agregar un valor de fecha.

$today=Get-Date -Format "MM-dd-yyyy"
$deploymentName="ExampleDeployment"+"$today"

Si ejecuta implementaciones simultáneas en el mismo grupo de recursos utilizando el mismo nombre de implementación, solo se completará la última implementación. Aquellas implementaciones que tengan el mismo nombre y no hayan finalizado se sustituirán por la última implementación. Por ejemplo, si ejecuta una implementación llamada newStorage que implementa la cuenta de almacenamiento storage1 y, al mismo tiempo, ejecuta otra implementación llamada newStorage que implementa la cuenta de almacenamiento storage2, solo se implementará una única cuenta de almacenamiento. La cuenta de almacenamiento resultante será storage2.

Sin embargo, si ejecuta una implementación llamada newStorage que implementa la cuenta de almacenamiento storage1 e inmediatamente después ejecuta otra implementación llamada newStorage que implementa la cuenta de almacenamiento storage2, tendrá dos cuentas de almacenamiento. Una se llamará storage1 y la otra, storage2. Sin embargo, solo tendrá una entrada en el historial de implementaciones.

Si especifica un nombre único para cada implementación, podrá ejecutarlas simultáneamente sin conflictos. Si ejecuta una implementación llamada newStorage1 que implementa la cuenta de almacenamiento storage1 y, al mismo tiempo, ejecuta otra implementación llamada newStorage2 que implementa la cuenta de almacenamiento storage2, tendrá dos cuentas de almacenamiento y dos entradas en el historial de implementación.

Para evitar conflictos con las implementaciones simultáneas y garantizar que las entradas del historial de implementaciones son únicas, asigne un nombre diferente a cada implementación.

Implementar una plantilla local

Puede implementar una plantilla desde la máquina local o una que esté almacenada externamente. En esta sección se describe la implementación de una plantilla local.

Si va a realizar la implementación en un grupo de recursos que no existe, cree el grupo de recursos. El nombre del grupo de recursos solo puede incluir caracteres alfanuméricos, puntos, guiones bajos, guiones y paréntesis. Puede tener hasta 90 caracteres. El nombre no puede terminar con un punto.

New-AzResourceGroup -Name ExampleGroup -Location "Central US"

Para implementar una plantilla local, use el parámetro -TemplateFile en el comando de implementación. En el ejemplo siguiente también se muestra cómo establecer un valor de parámetro que procede de la plantilla.

New-AzResourceGroupDeployment `
  -Name ExampleDeployment `
  -ResourceGroupName ExampleGroup `
  -TemplateFile <path-to-template>

La implementación puede tardar unos minutos en finalizar.

Implementación de una plantilla remota

En lugar de almacenar las plantillas de ARM en el equipo local, quizás prefiera almacenarlas en una ubicación externa. Puede almacenar plantillas en un repositorio de control de código fuente (por ejemplo, GitHub). O bien, puede almacenarlas en una cuenta de Azure Storage para el acceso compartido en su organización.

Nota

Para implementar una plantilla o hacer referencia a una plantilla vinculada que se almacena en un repositorio de GitHub privado, consulte una solución personalizada documentada en Creación de una oferta de Azure Portal segura y personalizada. Puede crear una función de Azure que extraiga el token de GitHub de Azure Key Vault.

Si va a realizar la implementación en un grupo de recursos que no existe, cree el grupo de recursos. El nombre del grupo de recursos solo puede incluir caracteres alfanuméricos, puntos, guiones bajos, guiones y paréntesis. Puede tener hasta 90 caracteres. El nombre no puede terminar con un punto.

New-AzResourceGroup -Name ExampleGroup -Location "Central US"

Para implementar una plantilla externa, use el parámetro -TemplateUri.

New-AzResourceGroupDeployment `
  -Name remoteTemplateDeployment `
  -ResourceGroupName ExampleGroup `
  -TemplateUri https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.storage/storage-account-create/azuredeploy.json

En el ejemplo anterior, se requiere un identificador URI accesible públicamente para la plantilla, que funciona con la mayoría de los escenarios porque la plantilla no debe incluir datos confidenciales. Si tiene que especificar datos confidenciales (por ejemplo, una contraseña de administrador), pase ese valor como un parámetro seguro. Sin embargo, si quiere administrar el acceso a la plantilla, considere la posibilidad de usar especificaciones de plantilla.

Para implementar plantillas vinculadas remotas con una ruta de acceso relativa que estén almacenadas en una cuenta de almacenamiento, use QueryString para especificar el token de SAS:

New-AzResourceGroupDeployment `
  -Name linkedTemplateWithRelativePath `
  -ResourceGroupName "myResourceGroup" `
  -TemplateUri "https://stage20210126.blob.core.windows.net/template-staging/mainTemplate.json" `
  -QueryString "$sasToken"

Para obtener más información, vea Uso de rutas de acceso relativas para plantillas vinculadas.

Implementación de la especificación de plantilla

En lugar de implementar una plantilla local o remota, puede crear una especificación de plantilla. La especificación de plantilla es un recurso de su suscripción de Azure que contiene una plantilla de ARM. Facilita el uso compartido de la plantilla de forma segura con los usuarios de la organización. Use el control de acceso basado en rol de Azure (RBAC de Azure) para conceder acceso a la especificación de la plantilla. Esta funcionalidad actualmente está en su versión preliminar.

En los ejemplos siguientes se muestra cómo se crea e implementa una especificación de plantilla.

En primer lugar, proporcione la plantilla de Resource Manager para crear la especificación de plantilla.

New-AzTemplateSpec `
  -Name storageSpec `
  -Version 1.0 `
  -ResourceGroupName templateSpecsRg `
  -Location westus2 `
  -TemplateJsonFile ./mainTemplate.json

A continuación, obtenga el identificador de la especificación de plantilla e impleméntelo.

$id = (Get-AzTemplateSpec -Name storageSpec -ResourceGroupName templateSpecsRg -Version 1.0).Versions.Id

New-AzResourceGroupDeployment `
  -ResourceGroupName demoRG `
  -TemplateSpecId $id

Para más información, vea Especificaciones de plantilla de Azure Resource Manager.

Vista previa de los cambios

Antes de implementar la plantilla, puede obtener una vista previa de los cambios que la plantilla realizará en su entorno. Use la operación Y si para comprobar que la plantilla realiza los cambios esperados. La operación y si también valida que la plantilla no tenga errores.

Pase de valores de parámetros

Para pasar valores de parámetros, puede usar parámetros en línea o un archivo de parámetros. El archivo de parámetros puede ser un archivo de parámetros de Bicep o un archivo de parámetros JSON.

Parámetros en línea

Para pasar parámetros en línea, proporcione los nombres de parámetro con el comando New-AzResourceGroupDeployment. Por ejemplo, para pasar una cadena y una matriz a una plantilla, use:

$arrayParam = "value1", "value2"
New-AzResourceGroupDeployment -ResourceGroupName testgroup `
  -TemplateFile <path-to-template> `
  -exampleString "inline string" `
  -exampleArray $arrayParam

Puede usar el parámetro TemplateParameterObject para pasar a través de una tabla hash que contenga los parámetros de la plantilla.

$params = @{
  exampleString = "inline string"
  exampleArray = "value1", "value2"
}

New-AzResourceGroupDeployment -ResourceGroupName testgroup `
  -TemplateFile <path-to-bicep> `
  -TemplateParameterObject $params

También puede obtener el contenido del archivo y proporcionar ese contenido como un parámetro en línea.

$arrayParam = "value1", "value2"
New-AzResourceGroupDeployment -ResourceGroupName testgroup `
  -TemplateFile <path-to-template> `
  -exampleString $(Get-Content -Path c:\MyTemplates\stringcontent.txt -Raw) `
  -exampleArray $arrayParam

Obtener un valor de parámetro de un archivo es útil cuando se necesita proporcionar valores de configuración. Por ejemplo, puede proporcionar valores de cloud-init para una máquina virtual Linux.

Si necesita pasar una matriz de objetos, cree las tablas hash en PowerShell y agréguelas a una matriz. Pase esa matriz como un parámetro durante la implementación.

$hash1 = @{ Name = "firstSubnet"; AddressPrefix = "10.0.0.0/24"}
$hash2 = @{ Name = "secondSubnet"; AddressPrefix = "10.0.1.0/24"}
$subnetArray = $hash1, $hash2
New-AzResourceGroupDeployment -ResourceGroupName testgroup `
  -TemplateFile <path-to-template> `
  -exampleArray $subnetArray

Archivos de parámetros JSON

En lugar de pasar parámetros como valores en línea en el script, quizá le resulte más fácil usar un archivo JSON que contiene los valores de parámetro. El archivo de parámetros puede ser un archivo local o un archivo externo con un identificador URI accesible.

Para más información sobre el archivo de parámetro, consulte Creación de un archivo de parámetros de Resource Manager.

Para pasar un archivo de parámetros local, use el parámetro TemplateParameterFile:

New-AzResourceGroupDeployment `
  -Name ExampleDeployment `
  -ResourceGroupName ExampleResourceGroup `
  -TemplateFile <path-to-template> `
  -TemplateParameterFile c:\MyTemplates\storage.parameters.json

Para pasar un archivo de parámetros externo, use el parámetro TemplateParameterUri:

New-AzResourceGroupDeployment `
  -Name ExampleDeployment `
  -ResourceGroupName ExampleResourceGroup `
  -TemplateUri https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.storage/storage-account-create/azuredeploy.json `
  -TemplateParameterUri https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.storage/storage-account-create/azuredeploy.parameters.json

Para más información sobre el archivo de parámetros, consulte Creación de un archivo de parámetros de Resource Manager.

Archivos de parámetros de Bicep

Con Azure PowerShell versión 10.4.0 o posterior, y la CLI de Bicep versión 0.22.6 o posterior, puede implementar un archivo de plantilla de ARM mediante un archivo de parámetros de Bicep. Con la instrucción using dentro del archivo de parámetros de Bicep, no es necesario proporcionar el modificador -TemplateFile al especificar un archivo de parámetros de Bicep para el modificador de -TemplateParameterFile.

En el ejemplo siguiente, se muestra un archivo de parámetros denominado storage.bicepparam. El archivo está ubicado en el mismo directorio donde se ejecuta el comando.

New-AzResourceGroupDeployment `
  -Name ExampleDeployment `
  -ResourceGroupName ExampleResourceGroup `
  -TemplateParameterFile storage.bicepparam

Para obtener más información sobre el archivo de parámetros de Bicep, consulte Archivo de parámetros de Bicep.

Pasos siguientes

• Para revertir a una implementación correcta cuando se produce un error, consulte Revertir en caso de error a una implementación correcta.
• Para especificar cómo controlar los recursos que existen en el grupo de recursos, pero que no están definidos en la plantilla, consulte Modos de implementación de Azure Resource Manager.
• Para entender cómo definir parámetros en la plantilla, consulte Nociones sobre la estructura y la sintaxis de las plantillas de Azure Resource Manager.
• Para más información sobre la implementación de una plantilla que requiere un token de SAS, vea Implementación de una plantilla de Resource Manager privada con el token de SAS.