Compartir a través de

Implementación de archivos de Bicep con Azure PowerShell

  • Artículo

En este artículo, se explica el uso de Azure PowerShell con archivos de Bicep para implementar recursos en Azure. Si no está familiarizado con la implementación y administración de las soluciones de Azure, consulte ¿Qué es Bicep?.

Requisitos previos

Necesita un archivo de Bicep para implementarlo y el archivo debe ser local. También necesita Azure PowerShell y estar conectado a Azure:

Si no tiene instalado PowerShell, puede usar Azure Cloud Shell. Para obtener más información, consulte Implementación de archivos de Bicep con Azure 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. En función del ámbito de la implementación, se usan comandos diferentes y el usuario que implemente el archivo de Bicep debe tener los permisos necesarios para crear recursos para cada ámbito.

Implementación de un archivo Bicep local

En esta sección, se describe cómo implementar un archivo de Bicep local. Puede implementar un archivo de Bicep desde la máquina local o una externa.

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 y no puede terminar en un punto.

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

Para implementar un archivo de Bicep local, use el conmutador -TemplateFile en el comando de implementación:

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

La implementación puede tardar unos minutos en finalizar.

Implementación de un archivo Bicep remoto

Actualmente, Azure PowerShell no admite la implementación de archivos de Bicep remotos. Puede usar la CLI de Bicep para compilar el archivo de Bicep en una plantilla JSON y luego cargar el archivo JSON en una ubicación remota. Para obtener más información, consulte Implementación de plantillas remotas.

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 un archivo de Bicep, use:

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

Puede usar el parámetro TemplateParameterObject para pasar 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 insertado:

$arrayParam = "value1", "value2"
New-AzResourceGroupDeployment -ResourceGroupName testgroup `
  -TemplateFile <path-to-bicep> `
  -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 tablas hash en Azure 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-bicep> `
  -exampleArray $subnetArray

Archivos de parámetros de Bicep

En lugar de pasar parámetros como valores insertados en el script, puede resultarle más fácil usar un archivo de parámetros de Bicep o un archivo de parámetros JSON que contenga los valores de los parámetros. El archivo de parámetros de Bicep debe ser un archivo local, mientras que el archivo de plantilla JSON se puede encontrar en algún lugar en línea. Para obtener más información sobre los archivos de parámetros, consulte Creación de archivos de parámetros para una implementación de Bicep.

Puede usar un archivo de parámetros de Bicep para implementar un archivo de Bicep con la versión 10.4.0 o posterior de Azure PowerShell y la versión 0.22.X o posterior de la CLI de Bicep. Con la instrucción using que hay 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 -TemplateParameterFile.

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

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

Archivo de parámetros JSON

El archivo de parámetros JSON puede ser local o externo con un identificador URI accesible.

Para pasar un archivo de parámetros local, use el modificador TemplateParameterFile con un archivo de parámetros JSON:

New-AzResourceGroupDeployment `
  -Name ExampleDeployment `
  -ResourceGroupName ExampleResourceGroup `
  -TemplateFile c:\BicepFiles\storage.bicep `
  -TemplateParameterFile c:\BicepFiles\storage.parameters.json

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

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

Dado que el parámetro TemplateParameterUri solo admite archivos de parámetros JSON, no admite archivos .bicepparam.

Puede usar parámetros en línea y un archivo de parámetros de ubicación en la misma operación de implementación. Para obtener más información, consulte Precedencia de parámetros.

Vista previa de los cambios

Antes de implementar el archivo Bicep, puede obtener una vista previa de los cambios que el archivo Bicep realizará en su entorno. Use la operación "what-if" para comprobar que la plantilla realiza los cambios esperados. La operación "what-if" también valida que el archivo Bicep no tenga errores.

Especificaciones de la implementación de la plantilla

Azure PowerShell no proporciona actualmente archivos de Bicep para ayudar a crear especificaciones de plantilla. Pero puede crear un archivo de Bicep con el recurso Microsoft.Resources/templateSpecs para implementar una especificación de plantilla. En el ejemplo Crear especificación de plantilla, se muestra cómo crear una especificación de plantilla en un archivo de Bicep. También puede compilar el archivo de Bicep en JSON mediante la CLI de Bicep y luego una plantilla JSON para crear una especificación de plantilla.

Nombre de implementación

Al implementar un archivo Bicep, puede asignarle un nombre a la implementación. Este nombre puede ayudarle a recuperar la implementación del historial de implementaciones. Si no proporciona un nombre para la implementación, su nombre se convierte en el del archivo de Bicep. Por ejemplo, si implementa un archivo de Bicep llamado main.bicep y no especifica un nombre de implementación, se le asigna el nombre main.

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

O bien, 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 una cuenta de almacenamiento llamada storage1 y, al mismo tiempo, ejecuta otra implementación llamada newStorage que implementa una cuenta de almacenamiento llamada storage2, solo se implementa una única cuenta de almacenamiento. La cuenta de almacenamiento resultante será storage2.

Pero si ejecuta una implementación llamada newStorage que implementa una cuenta de almacenamiento llamada storage1 e inmediatamente después ejecuta otra implementación llamada newStorage que implementa una cuenta de almacenamiento llamada storage2 cuando finalice la primera implementación, 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 una cuenta de almacenamiento llamada storage1 y, al mismo tiempo, ejecuta otra implementación llamada newStorage2 que implementa una cuenta de almacenamiento llamada storage2, tendrá dos cuentas de almacenamiento y dos entradas en el historial de implementaciones.

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

Pasos siguientes

Para obtener información sobre cómo definir parámetros en el archivo, consulte Descripción de la estructura y la sintaxis de los archivos de Bicep.