Procedimientos para el uso de plantillas de implementación de Azure Resource Manager (ARM) con la CLI de Azure

  • Artículo

En este artículo, se explica el uso de la CLI de Azure con plantillas de Azure Resource Manager (ARM) para implementar los 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.

Los comandos de implementación cambiaron en la CLI de Azure, versión 2.2.0. Los ejemplos de este artículo requieren la CLI de Azure, versión 2.20.0 o posterior.

Para ejecutar este ejemplo, instale la versión más reciente de la CLI de Azure. Para empezar, ejecute az login para crear una conexión con Azure.

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 obtener más información, vea Implementación de plantillas de Resource Manager desde Cloud Shell.

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 CLI de Azure.

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 plantilla de implementación de Azure 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 la plantilla debe tener permisos para crear recursos.

Implementar una plantilla local

Puede implementar una plantilla de ARM 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.

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

Para implementar una plantilla local, use el parámetro --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-template> \
  --parameters storageAccountType=Standard_GRS

El valor del parámetro --template-file debe ser un archivo de Bicep o un archivo .json o .jsonc. La extensión de archivo .jsonc indica que el archivo puede contener comentarios de estilo de //. El sistema ARM acepta comentarios de // en archivos .json. No tiene en cuenta la extensión del archivo. Para obtener más información sobre comentarios y metadatos, consulte Nociones sobre la estructura y la sintaxis de las plantillas de Azure Resource Manager.

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

"provisioningState": "Succeeded",

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.

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

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

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-uri "https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.storage/storage-account-create/azuredeploy.json" \
  --parameters storageAccountType=Standard_GRS

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 query-string para especificar el token de SAS:

az deployment group create \
  --name linkedTemplateWithRelativePath \
  --resource-group myResourceGroup \
  --template-uri "https://stage20210126.blob.core.windows.net/template-staging/mainTemplate.json" \
  --query-string $sasToken

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

Nombre de la plantilla de implementación de Azure

Al implementar una plantilla de ARM, puede asignarle un nombre a la plantilla de implementación de Azure. 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.

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

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.

az ts create \
  --name storageSpec \
  --version "1.0" \
  --resource-group templateSpecRG \
  --location "westus2" \
  --template-file "./mainTemplate.json"

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

id = $(az ts show --name storageSpec --resource-group templateSpecRG --version "1.0" --query "id")

az deployment group create \
  --resource-group demoRG \
  --template-spec $id

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

Vista previa de los cambios

Antes de implementar la plantilla de ARM, puede obtener una vista previa de los cambios que la plantilla realiza 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.

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 una plantilla en un shell de Bash, use:

az deployment group create \
  --resource-group testgroup \
  --template-file <path-to-template> \
  --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.

az deployment group create \
  --resource-group testgroup \
  --template-file <path-to-template> \
  --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, la plantilla 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 $templateFile \
--parameters resourceName=abcdef4556 resourceTags="$tags"

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

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-template> \
  --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\"} }'.

Archivos de parámetros JSON

En lugar de pasar parámetros como valores insertados en el script, puede resultarle más fácil usar un archivo de parámetros, ya sea un archivo de .bicepparam 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.

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-file storage.json \
  --parameters 'storage.parameters.json'

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

Archivos de parámetros de Bicep

Con la versión 2.53.0 o posterior de la CLI de Azure y la versión 0.22.6 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".

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

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.

Comentarios y el formato JSON extendido

Puede incluir comentarios de estilo de // en el archivo de parámetros, pero debe asignar un nombre al archivo con una extensión .jsonc.

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-file storage.json \
  --parameters '@storage.parameters.jsonc'

Para obtener más información sobre comentarios y metadatos, consulte Nociones sobre la estructura y la sintaxis de las plantillas de Azure Resource Manager.

Si usa la versión 2.3.0 u otra anterior de la CLI de Azure, debe usar el conmutador --handle-extended-json-format para implementar una plantilla con cadenas o comentarios multilínea. Por ejemplo:

{
  "type": "Microsoft.Compute/virtualMachines",
  "apiVersion": "2018-10-01",
  "name": "[variables('vmName')]", // to customize name, change it in variables
  "location": "[
    parameters('location')
    ]", //defaults to resource group location
  /*
    storage account and network interface
    must be deployed first
  */
  "dependsOn": [
    "[resourceId('Microsoft.Storage/storageAccounts/', variables('storageAccountName'))]",
    "[resourceId('Microsoft.Network/networkInterfaces/', variables('nicName'))]"
  ],

Pasos siguientes