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, escreva um modelo do Azure Resource Manager (modelo ARM) exatamente como faz normalmente. Você pode incluir parâmetros, variáveis, recursos e saídas.

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

É importante que seu modelo seja fácil de entender e usar para qualquer pessoa em sua organização, especialmente seus parâmetros. Certifique-se de usar nomes de parâmetros claros e compreensíveis. Use propriedades de parâmetros 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 do modelo usam as propriedades allowedValues, maxValuee description para deixar claro para que servem os parâmetros e qual é o efeito da definição de 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 de entender e usar para qualquer pessoa em sua organização, especialmente os parâmetros. Certifique-se de usar nomes de parâmetros claros e compreensíveis. Use decoradores de parâmetros 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 do modelo usam os decoradores de @allowed, @maxValuee @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 de secure para indicar que o parâmetro key contém dados secretos.

Quando alguém implanta um modelo de especificação 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ê definir.

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 do modelo no Azure

Depois que o modelo for escrito, em vez de enviá-lo ao 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 para JSON remove algumas das informações do 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 facilmente publicar um arquivo Bicep como uma especificação de modelo e, em seguida, obter o arquivo Bicep original de volta (também chamado de ida e volta). É uma boa ideia manter uma cópia do seu código Bicep original em um repositório de código 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 seu 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

Vejamos cada um dos parâmetros:

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

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 seu 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

Vejamos cada um dos argumentos:

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

Dica

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