Especificaciones de plantilla de Azure Resource Manager en Bicep

Artículo
10/20/2023

Una especificación de plantilla es un tipo de recurso para almacenar una plantilla de Azure Resource Manager (plantilla de ARM) para su posterior implementación. Este tipo de recurso permite compartir plantillas de ARM con otros usuarios de la organización. Al igual que cualquier otro recurso de Azure, puede usar el control de acceso basado en roles de Azure (RBAC de Azure) para compartir la especificación de plantilla. Puede usar la CLI de Azure o Azure PowerShell para crear especificaciones de plantilla mediante el suministro de archivos Bicep. Los archivos Bicep se transpilan en plantillas JSON de ARM antes de almacenarse. Actualmente, no puede importar un archivo Bicep desde Azure Portal para crear un recurso de especificación de plantilla.

Microsoft.Resources/templateSpecs es el tipo de recurso para las especificaciones de plantilla. Consta de una plantilla principal y un número indefinido de plantillas vinculadas. Azure almacena de forma segura las especificaciones de plantilla en grupos de recursos. Tanto la plantilla principal como las plantillas vinculadas deben estar en JSON. Las especificaciones de plantilla son compatibles con el control de versiones.

Para implementar la especificación de plantilla, use herramientas estándar de Azure como PowerShell, la CLI de Azure, Azure Portal, REST, y otros SDK y clientes compatibles. Utilice los mismos comandos que utilizaría para la plantilla o el archivo Bicep.

Nota:

Para usar especificaciones de plantilla en Bicep con Azure PowerShell, debe instalar la versión 6.3.0 o posterior. Para usarlas con la CLI de Azure, utilice la versión 2.27.0 o posterior.

Al diseñar la implementación, tenga en cuenta siempre el ciclo de vida de los recursos y agrupe los recursos que compartan un ciclo de vida similar en una sola especificación de plantilla. Por ejemplo, si las implementaciones incluyen varias instancias de Azure Cosmos DB y cada instancia contiene sus propias bases de datos y contenedores. Dado que las bases de datos y los contenedores no cambian mucho, seguramente quiera crear una especificación de plantilla para incluir una instancia de Cosmos DB y sus bases de datos y contenedores subyacentes. A continuación, puede usar las instrucciones condicionales en Bicep junto con bucles de copia para crear varias instancias de estos recursos.

Sugerencia

La elección entre el registro del módulo y las especificaciones de plantilla es principalmente una cuestión de preferencia. Hay algunas cosas que debe tener en cuenta al elegir entre ambas opciones:

Solo Bicep admite el registro de módulos. Si aún no usa Bicep, utilice las especificaciones de plantilla.
El contenido del registro del módulo de Bicep solo se puede implementar desde otro archivo Bicep. Las especificaciones de plantilla se pueden implementar directamente desde la API, Azure PowerShell, la CLI de Azure y Azure Portal. Incluso puede usar para UiFormDefinition personalizar la experiencia de implementación del portal.
Bicep tiene algunas funcionalidades limitadas para insertar otros artefactos de proyecto (incluidos los archivos de plantilla que no son de Bicep y que no son de ARM. Por ejemplo, scripts de PowerShell, scripts de la CLI y otros archivos binarios) mediante las funciones loadTextContent y loadFileAsBase64. Las especificaciones de plantilla no pueden empaquetar estos artefactos.

Recursos de aprendizaje

Para más información sobre las especificaciones de plantilla e instrucciones prácticas, consulte Publicación de bibliotecas de código de infraestructura reutilizable mediante especificaciones de plantilla.

Permisos necesarios

Hay dos roles integrados de Azure definidos para la especificación de plantilla:

Además, también necesita los permisos para implementar un archivo de Bicep. Consulte Implementación: CLI o Implementación: PowerShell.

¿Por qué usar especificaciones de plantilla?

Las especificaciones de plantilla ofrecen las ventajas siguientes:

Puede usar plantillas de ARM estándar o archivos Bicep para la especificación de la plantilla.
Puede administrar el acceso a través de Azure RBAC, en lugar de tokens de SAS.
Los usuarios pueden implementar la especificación de plantilla sin tener acceso de escritura al archivo Bicep.
Puede integrar la especificación de plantilla en el proceso de implementación existente, como el script de PowerShell o la canalización de DevOps.

Las especificaciones de plantilla permiten crear plantillas canónicas y compartirlas con los equipos de la organización. Las especificaciones de plantilla son seguras porque están disponibles para la implementación en Azure Resource Manager, pero no para los usuarios sin el permiso correcto. Los usuarios solo necesitan acceso de lectura a la especificación de plantilla para implementar su plantilla, por lo que puede compartir la plantilla sin permitir que otros la modifiquen.

Si actualmente tiene sus plantillas en un repositorio de GitHub o una cuenta de almacenamiento, se enfrenta a varios desafíos al intentar compartir y usar las plantillas. Para implementar la plantilla, debe hacer que sea accesible públicamente o administrar el acceso con tokens de SAS. Para evitar esta limitación, los usuarios pueden crear copias locales, que con el tiempo divergen de la plantilla original. Las especificaciones de plantilla simplifican el uso compartido de plantillas.

Los administradores de la organización deben comprobar las plantillas que se incluyen en una especificación de plantilla para seguir los requisitos y las instrucciones de la organización.

Crear una especificación de plantilla

En el ejemplo siguiente se muestra un archivo Bicep sencillo para crear una cuenta de almacenamiento en Azure.

@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_ZRS'
  'Premium_LRS'
])
param storageAccountType string = 'Standard_LRS'

resource stg 'Microsoft.Storage/storageAccounts@2021-04-01' = {
  name:  'store${uniqueString(resourceGroup().id)}'
  location: resourceGroup().location
  sku: {
    name: storageAccountType
  }
  kind:'StorageV2'
}

Cree una especificación de plantilla mediante:

PowerShell
CLI

New-AzTemplateSpec -Name storageSpec -Version 1.0a -ResourceGroupName templateSpecsRg -Location westus2 -TemplateFile ./mainTemplate.bicep

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

También puede crear especificaciones de plantilla con archivos Bicep. Sin embargo, el contenido mainTemplate de debe estar en JSON. La siguiente plantilla crea una especificación de plantilla para implementar una cuenta de almacenamiento:

param templateSpecName string = 'CreateStorageAccount'
param templateSpecVersionName string = '0.1'
param location string = resourceGroup().location

resource createTemplateSpec 'Microsoft.Resources/templateSpecs@2021-05-01' = {
  name: templateSpecName
  location: location
  properties: {
    description: 'A basic templateSpec - creates a storage account.'
    displayName: 'Storage account (Standard_LRS)'
  }
}

resource createTemplateSpecVersion 'Microsoft.Resources/templateSpecs/versions@2021-05-01' = {
  parent: createTemplateSpec
  name: templateSpecVersionName
  location: location
  properties: {
    mainTemplate: {
      '$schema': 'https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#'
      'contentVersion': '1.0.0.0'
      'parameters': {
        'storageAccountType': {
          'type': 'string'
          'defaultValue': 'Standard_LRS'
          'allowedValues': [
            'Standard_LRS'
            'Standard_GRS'
            'Standard_ZRS'
            'Premium_LRS'
          ]
        }
      }
      'resources': [
        {
          'type': 'Microsoft.Storage/storageAccounts'
          'apiVersion': '2019-06-01'
          'name': 'store$uniquestring(resourceGroup().id)'
          'location': resourceGroup().location
          'kind': 'StorageV2'
          'sku': {
            'name': '[parameters(\'storageAccountType\')]'
          }
        }
      ]
    }
  }
}

La plantilla JSON incrustada en el archivo Bicep debe realizar estos cambios:

Quite las comas al final de las líneas.
Reemplace las comillas dobles por comillas simples.
Escape de las comillas simples dentro de las expresiones. Por ejemplo, "name": "[parámetros(\"storageAccountType\")]".
Para obtener acceso a los parámetros y las variables definidos en el archivo Bicep, puede usar directamente los nombres de los parámetros y de las variables. Para acceder a los parámetros y las variables definidos en mainTemplate, aún debe usar la sintaxis de plantilla JSON de ARM. Por ejemplo, "name": "[parámetros(\"storageAccountType\")]".
Use la sintaxis de Bicep para llamar a las funciones Bicep. Por ejemplo, "location": resourceGroup().location.

El tamaño de una especificación de plantilla está limitado a 2 MB aproximadamente. Si un tamaño de especificación de plantilla supera el límite, recibirá el código de error TemplateSpecTooLarge. Si un mensaje de error indica lo siguiente:

The size of the template spec content exceeds the maximum limit. For large template specs with many artifacts, the recommended course of action is to split it into multiple template specs and reference them modularly via TemplateLinks.

Puede ver todas las especificaciones de plantilla de su suscripción mediante:

PowerShell
CLI

Get-AzTemplateSpec

az ts list

Puede ver los detalles de una especificación de plantilla, incluidas sus versiones con:

PowerShell
CLI

Get-AzTemplateSpec -ResourceGroupName templateSpecsRG -Name storageSpec

az ts show \
    --name storageSpec \
    --resource-group templateSpecRG \
    --version "1.0a"

Implementación de la especificación de plantilla

Después de crear la especificación de plantilla, los usuarios con el rol de lector de especificaciones de plantilla pueden implementarla. Además, también necesita los permisos para implementar una plantilla de ARM. Consulte Implementación: CLI o Implementación: PowerShell.

Las especificaciones de plantilla se pueden implementar a través del portal, de PowerShell, de la CLI de Azure o como un módulo de Bicep en una implementación de plantilla más grande. Los usuarios de una organización pueden implementar una especificación de plantilla en cualquier ámbito de Azure (grupo de recursos, suscripción, grupo de administración o inquilino).

En lugar de pasar una ruta de acceso o un archivo Bicep, para implementar una especificación de plantilla puede proporcionar su identificador de recurso. El identificador de recurso tiene el formato siguiente:

/subscriptions/{id-de-suscripción}/resourceGroups/{grupo-de-recursos}/providers/Microsoft.Resources/templateSpecs/{nombre-de-especificación-de-plantilla}/versions/{versión-de-especificación-de-plantilla}

Observe que el identificador de recurso incluye un nombre de versión para la especificación de plantilla.

Por ejemplo, puede implementar una especificación de plantilla mediante el siguiente comando.

PowerShell
CLI

$id = "/subscriptions/11111111-1111-1111-1111-111111111111/resourceGroups/templateSpecsRG/providers/Microsoft.Resources/templateSpecs/storageSpec/versions/1.0a"

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

id = "/subscriptions/11111111-1111-1111-1111-111111111111/resourceGroups/templateSpecsRG/providers/Microsoft.Resources/templateSpecs/storageSpec/versions/1.0a"

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

En la práctica, normalmente ejecutará Get-AzTemplateSpec o az ts show para obtener el identificador de la especificación de plantilla que quiere implementar.

PowerShell
CLI

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

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

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

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

También puede abrir una dirección URL con el formato siguiente para implementar una especificación de plantilla:

https://portal.azure.com/#create/Microsoft.Template/templateSpecVersionId/%2fsubscriptions%2f{subscription-id}%2fresourceGroups%2f{resource-group-name}%2fproviders%2fMicrosoft.Resources%2ftemplateSpecs%2f{template-spec-name}%2fversions%2f{template-spec-version}

Parámetros

Pasar parámetros a la especificación de plantilla es similar a pasar parámetros a un archivo Bicep. Agregue los valores de parámetro insertados o en un archivo de parámetros.

Parámetros en línea

Para pasar un parámetro insertado, use:

PowerShell
CLI

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

az deployment group create \
  --resource-group demoRG \
  --template-spec $id \
  --parameters storageAccountType='Standard_GRS'

Archivos de parámetros

Uso del archivo de parámetros de Bicep

Para crear un archivo de parámetros de Bicep, debe especificar la instrucción using. A continuación se muestra un ejemplo:
```
using 'using 'ts:<subscription-id>/<resource-group-name>/<template-spec-name>:<tag>'

param StorageAccountType = 'Standard_GRS'
```
Para más información, consulte el archivo de parámetros de Bicep.

Para pasar el archivo de parámetros con:
- PowerShell
- CLI
Actualmente, no se puede implementar una especificación de plantilla con un archivo .bicepparam mediante Azure PowerShell.
```
az deployment group create \
  --resource-group demoRG \
  --parameters "./mainTemplate.bicepparam"
```
El motivo es la instrucción using en el archivo bicepparam. No es necesario especificar el parámetro --template-spec.

Uso del archivo de parámetros JSON

El siguiente código JSON es un ejemplo de archivo de parámetros de JSON:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "StorageAccountType": {
      "value": "Standard_GRS"
    }
  }
}

Y pase el archivo de parámetros con:

PowerShell
CLI

New-AzResourceGroupDeployment `
  -TemplateSpecId $id `
  -ResourceGroupName demoRG `
  -TemplateParameterFile ./mainTemplate.parameters.json

az deployment group create \
  --resource-group demoRG \
  --template-spec $id \
  --parameters "./mainTemplate.parameters.json"

Control de versiones

Cuando se crea una especificación de plantilla, se debe proporcionar un nombre de versión para ella. A medida que realiza la iteración en el código de plantilla, puede actualizar una versión existente (para revisiones) o publicar una nueva versión. La versión es una cadena de texto. Puede optar por seguir cualquier sistema de control de versiones, incluido el control de versiones semántico. Los usuarios de la especificación de plantilla pueden proporcionar el nombre de versión que quieren usar al implementarla. Puede tener un número ilimitado de versiones.

Usar etiquetas

Las etiquetas le ayudan a organizar los recursos de forma lógica. Puede agregar etiquetas a las especificaciones de plantilla mediante Azure PowerShell y la CLI de Azure. En el ejemplo siguiente se muestra cómo especificar etiquetas al crear la especificación de plantilla:

PowerShell
CLI

New-AzTemplateSpec `
  -Name storageSpec `
  -Version 1.0a `
  -ResourceGroupName templateSpecsRg `
  -Location westus2 `
  -TemplateFile ./mainTemplate.bicep `
  -Tag @{Dept="Finance";Environment="Production"}

az ts create \
  --name storageSpec \
  --version "1.0a" \
  --resource-group templateSpecRG \
  --location "westus2" \
  --template-file "./mainTemplate.bicep" \
  --tags Dept=Finance Environment=Production

En el ejemplo siguiente se muestra cómo aplicar etiquetas al actualizar una especificación de plantilla existente:

PowerShell
CLI

Set-AzTemplateSpec `
  -Name storageSpec `
  -Version 1.0a `
  -ResourceGroupName templateSpecsRg `
  -Location westus2 `
  -TemplateFile ./mainTemplate.bicep `
  -Tag @{Dept="Finance";Environment="Production"}

az ts update \
  --name storageSpec \
  --version "1.0a" \
  --resource-group templateSpecRG \
  --location "westus2" \
  --template-file "./mainTemplate.bicep" \
  --tags Dept=Finance Environment=Production

Tanto la plantilla como sus versiones pueden tener etiquetas. Las etiquetas se aplican o heredan en función de los parámetros que especifique.

Especificación de plantilla	Versión	Parámetro de versión	Parámetro de etiqueta	Valores de etiqueta
Exists	N/D	Sin especificar	Specified	aplicado a la especificación de plantilla
Exists	Nuevo	Specified	Sin especificar	heredado de la especificación de plantilla a la versión
Nuevo	Nuevo	Specified	Specified	se aplica a la especificación de plantilla y a la versión
Exists	Nuevo	Specified	Specified	aplicado a la versión
Exists	Exists	Specified	Specified	aplicado a la versión

Vínculo a especificaciones de plantilla

Después de crear una especificación de plantilla, puede vincularla en un módulo de Bicep. La especificación de plantilla se implementa al implementar el archivo de Bicep que contiene ese módulo. Para más información, consulte Archivo en especificación de plantilla.

Para crear alias para especificaciones de plantilla destinados a la vinculación de módulos, consulte Alias para módulos.