Compartir a través de

Especificaciones de plantilla de Azure Resource Manager en Bicep

  • Artículo

Una especificación de plantilla es un tipo de recurso para almacenar una plantilla de Azure Resource Manager (plantilla de ARM) para implementarla más adelante. 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 ser almacenados. No se puede importar un archivo de Bicep desde Azure Portal para crear un recurso de especificación de plantilla en este momento.

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 UiFormDefinition para personalizar la experiencia de implementación de Azure 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.

Permisos necesarios

Dos roles están integrados en Azure y se definen para las especificaciones de plantilla:

Además, también necesita los permisos para implementar un archivo de Bicep. Consulte Implementación de archivos de Bicep con la CLI de Azure o Azure 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 RBAC de Azure en lugar de tokens de firma de acceso compartido.
  • 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 un proceso de implementación existente, como una secuencia de comandos de PowerShell o una 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@2023-04-01' = {
  name:  'store${uniqueString(resourceGroup().id)}'
  location: resourceGroup().location
  sku: {
    name: storageAccountType
  }
  kind:'StorageV2'
}

Cree una especificación de plantilla mediante:

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

También puede usar archivos de Bicep para crear especificaciones de plantilla. Sin embargo, el contenido de mainTemplate 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@2022-02-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@2022-02-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': '2023-04-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 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 variables definidos en mainTemplate, todavía debe usar la sintaxis de la plantilla de 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 se limita a aproximadamente 2 megabytes. Si un tamaño de especificación de plantilla supera el límite, obtendrá 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:

Get-AzTemplateSpec

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

Get-AzTemplateSpec -ResourceGroupName templateSpecsRG -Name storageSpec

Implementación de la especificación de plantilla

Una vez creada la especificación de plantilla, los usuarios con el rol Lector de Especificación de Plantilla pueden implementarla. Recuerde que necesita los permisos adecuados para implementar una plantilla de ARM.

Las especificaciones de plantilla se pueden implementar a través de Azure Portal, PowerShell, 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).

Para implementar una especificación de plantilla, proporcione su identificador de recurso en lugar de pasarlo en una ruta de acceso o URI para un archivo de Bicep. El id. de recurso tiene el siguiente formato; observe que incluye un nombre de versión para la especificación de plantilla:

/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}

Puede implementar una especificación de plantilla con los siguientes comandos:

$id = "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/templateSpecsRG/providers/Microsoft.Resources/templateSpecs/storageSpec/versions/1.0a"

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

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.

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

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

También puede implementar una especificación de plantilla abriendo una dirección URL en el formato siguiente:

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 una especificación de plantilla es similar a pasar parámetros a un archivo de Bicep. Agregue los valores de los parámetros insertados o en un archivo de parámetros.

Parámetros en línea

Para pasar un parámetro insertado, use:

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

Archivos de parámetros

  • Use archivos de parámetros de Bicep.

    Debe especificar la instrucción using para crear un archivo de parámetros de Bicep. Por ejemplo:

    using 'using 'ts:<subscription-id>/<resource-group-name>/<template-spec-name>:<tag>'

param StorageAccountType = 'Standard_GRS'

    Para obtener más información, consulte Crear archivos de parámetros para la implementación de Bicep.

    Pase los archivos de parámetros con:

    No puede usar PowerShell para implementar una especificación de plantilla con un .bicepparam archivo en este momento.

  • Use archivos 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"
    }
  }
}

    También puede pasar un archivo de parámetros con:

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

Control de versiones

Cuando se crea una especificación de plantilla, se le asigna un nombre de versión. 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 especificaciones de plantillas pueden proporcionar el nombre de la versión que desean utilizar al implementarla y pueden tener un número ilimitado de versiones.

Usar etiquetas

Etiquetas le ayudan a organizar lógicamente los recursos. Puede usar Azure PowerShell o la CLI de Azure para agregar etiquetas a las especificaciones de plantilla. En el ejemplo siguiente se muestra cómo especificar etiquetas al crear la especificación de plantilla:

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

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

Set-AzTemplateSpec `
  -Name storageSpec `
  -Version 1.0a `
  -ResourceGroupName templateSpecsRg `
  -Location westus2 `
  -TemplateFile ./mainTemplate.bicep `
  -Tag @{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

  • 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 obtener más información, consulte Ruta de acceso a un módulo.

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

Pasos siguientes

Consulte el módulo de Learn Publicar bibliotecas de código de infraestructura reutilizable mediante especificaciones de plantilla para obtener más información y una guía práctica sobre las especificaciones de plantilla.