Compartir a través de

Implementación de archivos Bicep con la CLI de Azure

  • Artículo

En este artículo, se explica cómo usar 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, vea ¿Qué es Bicep?.

Requisitos previos

Necesita un archivo Bicep para implementarlo y el archivo debe ser local. También 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.
  • Use az login para conectarse a Azure. 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 (cmd), es posible que necesite cambiar elementos del script.

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

Implementación de un archivo Bicep local

Puede implementar un archivo Bicep desde la máquina local o una externa. En esta sección se describe cómo implementar 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 y no puede terminar en 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 siguiente:

"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 Bicep en una plantilla JSON y luego cargar el archivo JSON en una ubicación remota. Para más información, veaImplementació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 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 va a usar la CLI de Azure con el símbolo del sistema de Windows o PowerShell, pase la matriz con el formato exampleArray="['value1','value2']".

También puede obtener el contenido del archivo para proporcionarlo como un parámetro en línea. Anteponga @ al nombre de archivo:

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, use JSON (por ejemplo, al establecer etiquetas). El archivo Bicep podría incluir un parámetro como este:

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

Como se muestra en el siguiente script de Bash, también puede pasar una cadena JSON para establecer el parámetro. Use comillas dobles alrededor del código JSON que quiera pasar al objeto:

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

Si va a usar la CLI de Azure con el símbolo del sistema de Windows o PowerShell, pase el objeto con el formato siguiente:

$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. Establezca la variable en todos los valores de parámetro en el script de Bash y agréguelo al comando de implementación:

params="prefix=start suffix=end"

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

Pero si va a usar la CLI de Azure con el símbolo del sistema 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 los 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 asignar los parámetros de manera adecuada, se recomienda proporcionar inicialmente el archivo de parámetros y, después, usar la sintaxis KEY=VALUE para invalidar de forma selectiva parámetros específicos. Si va a proporcionar un archivo de parámetros .bicepparam, solo puede usar este argumento 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 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, ya que la CLI de Azure no admite archivos de parámetros externos. Para más información sobre los archivos de parámetros, vea Creación de archivos de parámetros para la implementación de Bicep.

Puede usar un archivo de parámetros de Bicep para implementar un archivo Bicep con la CLI de Azure versión 2.53.0 o posterior, y la CLI de Bicep versión 0.22.X o posterior. Con la instrucción using que hay 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 --parameters. Al incluir 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á en el mismo directorio donde se ejecuta el comando:

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

Archivo de parámetros JSON

En el ejemplo siguiente, se muestra un archivo de parámetros denominado storage.parameters.json. El archivo está 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'

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 proporciona archivos Bicep para ayudar a crear especificaciones de plantilla. Pero puede crear un archivo 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 Bicep. También puede compilar el archivo 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 Bicep. Por ejemplo, si implementa un archivo 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:

deploymentName='ExampleDeployment'$RANDOM

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

Pero si ejecuta una implementación denominada newStorage que implementa una cuenta de almacenamiento con el nombre storage1 e inmediatamente después ejecuta otra implementación denominada newStorage que implementa una cuenta de almacenamiento con el nombre storage2 cuando finaliza 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 denominada newStorage1 que implementa una cuenta de almacenamiento con el nombre storage1 y, al mismo tiempo, ejecuta otra implementación denominada newStorage2 que implementa una cuenta de almacenamiento con el nombre 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 entender cómo definir parámetros en el archivo, consulte Nociones sobre la estructura y la sintaxis de los archivos Bicep.