Implementación de recursos con Bicep y la CLI de Azure

  • Artículo

En este artículo, se explica el uso de la CLI de Azure con archivos Bicep para implementar recursos en Azure. Si no conoce los conceptos de implementación y administración de las soluciones de Azure, consulte Introducción a Bicep.

Requisitos previos

Necesita un archivo de Bicep para implementarlo. El archivo debe ser local.

Necesita la CLI de Azure y estar conectado a Azure:

  • Instale los comandos de la CLI de Azure en el equipo local. Para implementar archivos Bicep, necesita la CLI de Azure, versión 2.20.0 o posterior.
  • Conéctese a Azure mediante az login . Si tiene varias suscripciones de Azure, es posible que también tenga que ejecutar az account set.

Los ejemplos de la CLI de Azure están escritos para el shell bash. Para ejecutar este ejemplo en Windows PowerShell o en el símbolo del sistema, es posible que necesite cambiar algunos elementos del script.

Si no tiene instalada la CLI de Azure, puede usar Azure Cloud Shell. Para más información, consulte Implementación de archivos Bicep desde 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. Según el ámbito de la implementación, usará comandos diferentes.

Para cada ámbito, el usuario que implementa el archivo Bicep debe tener los permisos necesarios para crear recursos.

Implementación de un archivo Bicep local

Puede implementar un archivo Bicep desde la máquina local o una que esté almacenada externamente. En esta sección se describe la implementación de un archivo Bicep 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.

az group create --name ExampleGroup --location "Central US"

Para implementar un archivo Bicep, use el conmutador --template-file en el comando de implementación. En el ejemplo siguiente también se muestra cómo establecer un valor de parámetro.

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-file <path-to-bicep> \
  --parameters storageAccountType=Standard_GRS

La implementación puede demorar unos minutos en completarse. Cuando termine, verá un mensaje que incluye el resultado:

"provisioningState": "Succeeded",

Implementación de un archivo Bicep remoto

Actualmente, la CLI de Azure no admite la implementación de archivos Bicep remotos. Puede usar la CLI de Bicep para compilar el archivo de Bicep en una plantilla JSON y luego cargue el archivo JSON en la ubicación remota. Para más información, consulte Implementación de plantillas JSON de ARM 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 valores en parameters. Por ejemplo, para pasar una cadena y una matriz a un archivo Bicep en un shell de Bash, use:

az deployment group create \
  --resource-group testgroup \
  --template-file <path-to-bicep> \
  --parameters exampleString='inline string' exampleArray='["value1", "value2"]'

Si usa la CLI de Azure con el símbolo del sistema de Windows (CMD) o PowerShell, pase la matriz con el formato exampleArray="['value1','value2']".

También puede obtener el contenido del archivo y proporcionar ese contenido como un parámetro en línea. Preparación del nombre de archivo con @.

az deployment group create \
  --resource-group testgroup \
  --template-file <path-to-bicep> \
  --parameters exampleString=@stringContent.txt exampleArray=@arrayContent.json

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.

El formato de arrayContent.json es:

[
  "value1",
  "value2"
]

Para pasar un objeto, por ejemplo, para establecer etiquetas, use JSON. Por ejemplo, el archivo Bicep podría incluir un parámetro como este:

"resourceTags": {
  "type": "object",
  "defaultValue": {
    "Cost Center": "IT Department"
  }
}

En este caso, puede pasar una cadena JSON para establecer el parámetro como se muestra en el siguiente script de Bash:

tags='{"Owner":"Contoso","Cost Center":"2345-324"}'
az deployment group create --name addstorage  --resource-group myResourceGroup \
--template-file $bicepFile \
--parameters resourceName=abcdef4556 resourceTags="$tags"

Use comillas dobles alrededor del código JSON que desee pasar al objeto.

Si usa la CLI de Azure con el símbolo del sistema de Windows (CMD) o PowerShell, pase el objeto con el formato siguinete:

$tags="{'Owner':'Contoso','Cost Center':'2345-324'}"
az deployment group create --name addstorage  --resource-group myResourceGroup \
--template-file $bicepFile \
--parameters resourceName=abcdef4556 resourceTags=$tags

Puede usar una variable para contener los valores de parámetro. En Bash, establezca la variable en todos los valores de parámetro y agréguela al comando de implementación.

params="prefix=start suffix=end"

az deployment group create \
  --resource-group testgroup \
  --template-file <path-to-bicep> \
  --parameters $params

Sin embargo, si usa CLI de Azure con el símbolo del sistema (CMD) de Windows o PowerShell, establezca la variable en una cadena JSON. Incluya las comillas: $params = '{ \"prefix\": {\"value\":\"start\"}, \"suffix\": {\"value\":\"end\"} }'.

La evaluación de parámetros sigue un orden secuencial, lo que significa que si se asigna un valor varias veces, solo se usa el último valor asignado. Para garantizar la asignación adecuada de parámetros, se recomienda proporcionar inicialmente el archivo de parámetros e invalidar de forma selectiva parámetros específicos mediante la sintaxis KEY=VALUE. Es importante mencionar que, si proporciona un archivo de parámetros bicepparam, puede usar este argumento solo una vez.

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, o 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 debe ser un archivo local. No se admiten los archivos de parámetros externos con la CLI de Azure. Para más información sobre el archivo de parámetros, consulte Creación de un archivo de parámetros de Resource Manager.

Con la versión 2.53.0 o posterior de la CLI de Azure y la versión 0.22 o posterior de la CLI de Bicep, puede implementar un archivo de Bicep 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 --template-file al especificar un archivo de parámetros de Bicep para el modificador de --parameters. Si se incluye el modificador --template-file, se producirá el error "Solo se permite una plantilla .bicep con un archivo .bicepparam".

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.

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --parameters storage.bicepparam

Archivos de parámetros JSON

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

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-file storage.bicep \
  --parameters '@storage.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.

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

Actualmente, la CLI de Azure no admite la creación de especificaciones de plantilla mediante archivos Bicep. Pero puede crear un archivo de Bicep con el recurso Microsoft.Resources/templateSpecs para implementar una especificación de plantilla. En el ejemplo Creación de una 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 Bicep en JSON mediante la CLI de Bicep y luego crear una especificación de plantilla con la plantilla JSON.

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 especifica un nombre para la implementación, se utilizará el nombre del archivo Bicep. Por ejemplo, si implementa un archivo Bicep llamado main.bicep y no especifica ningún nombre para la implementación, se le asignará 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.

deploymentName='ExampleDeployment'$RANDOM

También puede agregar un valor de fecha.

deploymentName='ExampleDeployment'$(date +"%d-%b-%Y")

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 sean únicas, asigne un nombre diferente a cada implementación.

Pasos siguientes