Creación y publicación de una especificación de plantilla

Completado

Echemos un vistazo a cómo crear y publicar una especificación de plantilla.

Creación de una plantilla

Para crear una plantilla para usarla como especificación de plantilla, escriba una plantilla de Azure Resource Manager (plantilla de ARM) como lo haría normalmente. Puede incluir parámetros, variables, recursos y salidas.

Puede usar plantillas vinculadas, que le permiten definir partes de la implementación en archivos independientes. Cuando se trabaja con especificaciones de plantilla, las plantillas vinculadas se pueden insertar en la especificación de plantilla y se hace referencia a ellas desde la plantilla principal.

Es importante que la plantilla sea fácil de entender y usar para cualquier persona de la organización, especialmente sus parámetros. Asegúrese de usar nombres de parámetros claros y comprensibles. Use propiedades de parámetro y metadatos de plantilla para proporcionar información sobre los valores que espera que incluyan los parámetros, como en este ejemplo:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "environmentType": {
      "type": "string",
      "allowedValues": [
        "Production",
        "NonProduction"
      ],
      "metadata": {
        "description": "The type of the environment to deploy. This will determine the SKUs and cost of the resources."
      }
    },
    "key": {
      "type": "secureString",
      "metadata": {
        "description": "The secret key to use."
      }
    },
    "location": {
      "type": "string",
      "metadata": {
        "description": "The Azure region into which the resources should be deployed."
      }
    },
    "sqlServerCount": {
      "type": "int",
      "maxValue": 5,
      "metadata": {
        "description": "The number of Azure SQL logical servers to create."
      }
    }
  },
  "resources": []
}

En el ejemplo, los parámetros de plantilla usan las propiedades allowedValues, maxValue y description para dejar claro para qué son los parámetros y cuál es la repercusión de establecer sus valores. La plantilla también incluye el tipo secureString para indicar que el parámetro key contiene datos secretos.

Es importante que la plantilla sea fácil de entender y usar para cualquier persona de la organización, especialmente los parámetros. Asegúrese de usar nombres de parámetros claros y comprensibles. Use decoradores de parámetro para proporcionar información sobre los valores que espera que incluyan los parámetros, como en este ejemplo:

@description('The type of the environment to deploy. This will determine the SKUs and cost of the resources.')
@allowed([
  'Production'
  'NonProduction'
])
param environmentType string

@secure()
@description('The secret key to use.')
param key string

@description('The Azure region into which the resources should be deployed.')
param location string

@description('The number of Azure SQL logical servers to create.')
@maxValue(5)
param sqlServerCount int

En el ejemplo, los parámetros de plantilla usan los decoradores @allowed, @maxValue y @description para dejar claro para qué son los parámetros y cuál es la repercusión de establecer sus valores. La plantilla también incluye el decorador secure para indicar que el parámetro key contiene datos secretos.

Cuando alguien implementa una especificación de plantilla mediante Azure Portal, el portal:

• Muestra el nombre y la descripción del parámetro.
• Oculta la entrada de texto para los parámetros seguros.
• Aplica los valores permitidos, los límites de longitud y los límites de valor que defina.

En esta captura de pantalla, se muestra la entrada de los valores del parámetro:

Es importante pensar en cómo usan los usuarios la especificación de plantilla y asegurarse de que los parámetros sean claros y comprensibles.

Publicación de la especificación de plantilla en Azure

Una vez escrita la plantilla, en lugar de enviarla a Azure para su implementación, publique la especificación de plantilla.

Importante

Al publicar un archivo de Bicep como especificación de plantilla, el código de Bicep se convierte en una plantilla JSON. El proceso de conversión del código de Bicep a JSON quita parte de la información del archivo de Bicep. Por ejemplo, los comentarios, los nombres simbólicos de los recursos y el orden en que se definen los recursos podrían faltar o ser diferentes en formato JSON. Esto significa que no puede publicar fácilmente un archivo de Bicep como especificación de plantilla y, a continuación, obtener el archivo de Bicep original (también llamado ida y vuelta). Es una buena idea mantener una copia del código de Bicep original en un repositorio de código como Git, especialmente cuando se trabaja con especificaciones de plantilla.

Para crear una especificación de plantilla, use el cmdlet New-AzTemplateSpec. En el ejemplo siguiente, se muestra cómo puede crear una especificación de plantilla para la plantilla de la cuenta de almacenamiento:

New-AzTemplateSpec `
  -Name StorageWithoutSAS `
  -Location westus `
  -DisplayName 'Storage account with SAS disabled' `
  -Description 'This template spec creates a storage account, which is preconfigured to disable SAS authentication.' `
  -Version '1.0' `
  -TemplateFile main.bicep

New-AzTemplateSpec `
  -Name StorageWithoutSAS `
  -Location westus `
  -DisplayName 'Storage account with SAS disabled' `
  -Description 'This template spec creates a storage account, which is preconfigured to disable SAS authentication.' `
  -Version '1.0' `
  -TemplateFile azuredeploy.json

Echemos un vistazo a cada uno de los parámetros:

• -Name es el nombre del recurso de la especificación de plantilla, que no puede incluir espacios.
• -Location es la ubicación en la que se deben crear los metadatos de la especificación de plantilla. Sin embargo, puede implementar la especificación de plantilla en cualquier región.
• -DisplayName es un nombre legible, que puede incluir espacios.
• -Description es una descripción legible, que puede usar para proporcionar detalles sobre el contenido de la especificación de plantilla y cuándo alguien podría usarla.
• -Version es la versión de la especificación de plantilla. Más adelante en este módulo obtendrá información sobre las versiones.
• -TemplateFile es la ruta de acceso a la plantilla de ARM para la que se va a crear la especificación de plantilla.

Para crear una especificación de plantilla, use el comando az ts create. En el ejemplo siguiente, se muestra cómo puede crear una especificación de plantilla para la plantilla de la cuenta de almacenamiento:

az ts create \
  --name StorageWithoutSAS \
  --location westus \
  --display-name "Storage account with SAS disabled" \
  --description "This template spec creates a storage account, which is preconfigured to disable SAS authentication." \
  --version 1.0 \
  --template-file main.bicep

az ts create \
  --name StorageWithoutSAS \
  --location westus \
  --display-name "Storage account with SAS disabled" \
  --description "This template spec creates a storage account, which is preconfigured to disable SAS authentication." \
  --version 1.0 \
  --template-file azuredeploy.json

Echemos un vistazo a cada uno de los argumentos:

• --name es el nombre del recurso de la especificación de plantilla, que no puede incluir espacios.
• --location es la ubicación en la que se deben crear los metadatos de la especificación de plantilla. Sin embargo, puede implementar la especificación de plantilla en cualquier región.
• --display-name es un nombre legible, que puede incluir espacios.
• --description es una descripción legible, que puede usar para proporcionar detalles sobre el contenido de la especificación de plantilla y cuándo alguien podría usarla.
• --version es la versión de la especificación de plantilla. Más adelante en este módulo obtendrá información sobre las versiones.
• --template-file es la ruta de acceso a la plantilla de ARM para la que se va a crear la especificación de plantilla.

Sugerencia

También puede definir una especificación de plantilla dentro de una plantilla de ARM. Dado que una especificación de plantilla es en sí misma un recurso de Azure, puede implementar una plantilla que defina un recurso con el tipo Microsoft.Deployments/templateSpecs.