Criar e publicar uma especificação de modelo

Concluído

Vamos ver como você cria e publica uma especificação de modelo.

Criar um modelo

Para criar um modelo para uso como uma especificação de modelo, você escreve um modelo do Azure Resource Manager (modelo do ARM), como normalmente. Você pode incluir parâmetros, variáveis, recursos e saídas.

Você pode usar modelos vinculados, que permitem definir partes da implantação em arquivos separados. Quando você trabalha com especificações de modelo, modelos vinculados podem ser inseridos na especificação de modelo e referenciados a partir do modelo principal.

É importante que seu modelo seja fácil para qualquer pessoa em sua organização entender e usar, especialmente seus parâmetros. Use nomes de parâmetro claros e compreensíveis. Use propriedades de parâmetro e metadados de modelo para fornecer informações sobre os valores que você espera que seus parâmetros incluam, como neste exemplo:

{
  "$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": []
}

No exemplo, os parâmetros de modelo usam as propriedades allowedValues, maxValue e description para deixar claro para que servem os parâmetros e qual é o efeito de definir seus valores. O modelo também inclui o tipo secureString para indicar que o parâmetro key contém dados secretos.

É importante que seu modelo seja fácil para qualquer pessoa em sua organização entender e usar, especialmente os parâmetros. Use nomes de parâmetro claros e compreensíveis. Use decoradores de parâmetro para fornecer informações sobre os valores que você espera que seus parâmetros incluam, como neste exemplo:

@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

No exemplo, os parâmetros de modelo usam os decoradores @allowed, @maxValue e @description para deixar claro para que servem os parâmetros e qual é o efeito de definir seus valores. O modelo também inclui o decorador secure para indicar que o parâmetro key contém dados secretos.

Quando alguém implanta uma especificação de modelo usando o portal do Azure, o portal:

• Mostra o nome e a descrição do parâmetro.
• Oculta a entrada de texto para parâmetros seguros.
• Impõe os valores permitidos, os limites de comprimento e os limites de valor que você define.

Esta captura de tela ilustra a entrada de valores de parâmetro:

É importante pensar em como os usuários usam sua especificação de modelo e garantir que seus parâmetros sejam claros e compreensíveis.

Publicar a especificação de modelo no Azure

Depois que o modelo for escrito, em vez de enviá-lo para o Azure para implantação, você publicará a especificação do modelo.

Importante

Quando você publica um arquivo Bicep como uma especificação de modelo, seu código Bicep é convertido em um modelo JSON. O processo de conversão do código Bicep em JSON remove algumas das informações em seu arquivo Bicep. Por exemplo, seus comentários, nomes simbólicos para recursos e a ordem na qual você define seus recursos podem estar ausentes ou diferentes em JSON. Isso significa que você não pode publicar facilmente um arquivo Bicep como uma especificação de modelo e, em seguida, obter o arquivo Bicep original de volta (também chamado de arredondamento). É uma boa ideia manter uma cópia do código Bicep original em um repositório de códigos como o Git, especialmente quando você trabalha com especificações de modelo.

Para criar uma especificação de modelo, use o cmdlet New-AzTemplateSpec. O exemplo a seguir mostra como você pode criar uma especificação de modelo para o modelo de conta de armazenamento:

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

Vamos examinar cada um dos parâmetros:

• -Name é o nome do recurso da especificação de modelo, que não pode incluir espaços.
• -Location é o local no qual os metadados de especificação de modelo devem ser criados. No entanto, você pode implantar a especificação de modelo em qualquer região.
• -DisplayName é um nome acessível por humanos, que pode incluir espaços.
• -Description é uma descrição acessível para humanos, que você pode usar para fornecer detalhes sobre o conteúdo da especificação de modelo e quando alguém pode usá-la.
• -Version é a versão da especificação de modelo. Você aprenderá sobre versões posteriormente neste módulo.
• -TemplateFile é o caminho para criar a especificação de modelo para o modelo do ARM.

Para criar uma especificação de modelo, use o comando az ts create. O exemplo a seguir mostra como você pode criar uma especificação de modelo para o modelo de conta de armazenamento:

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

Vamos examinar cada um dos argumentos:

• --name é o nome do recurso da especificação de modelo, que não pode incluir espaços.
• --location é o local no qual os metadados de especificação de modelo devem ser criados. No entanto, você pode implantar a especificação de modelo em qualquer região.
• --display-name é um nome acessível por humanos, que pode incluir espaços.
• --description é uma descrição acessível para humanos, que você pode usar para fornecer detalhes sobre o conteúdo da especificação de modelo e quando alguém pode usá-la.
• --version é a versão da especificação de modelo. Você aprenderá sobre versões posteriormente neste módulo.
• --template-file é o caminho para criar a especificação de modelo para o modelo do ARM.

Dica

Você também pode definir uma especificação de modelo dentro de um modelo do ARM! Como uma especificação de modelo é um recurso do Azure, você pode implantar um modelo que define um recurso com o tipo Microsoft.Deployments/templateSpecs.