Especificações de modelo do Azure Resource Manager em Bicep

  • Artigo

Uma especificação de modelo é um tipo de recurso usado para armazenar um modelo do ARM (modelo do Azure Resource Manager) para implantação posterior. Esse tipo de recurso permite que você compartilhe modelos do ARM com outros usuários em sua organização. Assim como qualquer outro recurso do Azure, você pode usar o RBAC do Azure (controle de acesso baseado em função do Azure) para compartilhar a especificação de modelo. Use a CLI do Azure ou o Azure PowerShell para criar especificações de modelo fornecendo arquivos Bicep. Os arquivos Bicep são transcompilados em modelos JSON do ARM antes de serem armazenados. Atualmente, não é possível importar um arquivo Bicep do portal do Azure para criar um recurso de especificação de modelo.

Microsoft. Resources/templateSpecs é o tipo de recurso para as especificações de modelo. Ele consiste em um modelo principal e qualquer número de modelos vinculados. O Azure armazena as especificações de modelo com segurança em grupos de recursos. O modelo principal e os modelos vinculados devem estar em JSON. As especificações de modelo dão suporte ao controle de versão.

Para implantar a especificação de modelo, você usa ferramentas padrão do Azure como o PowerShell, CLI do Azure, portal do Azure, REST e outros SDKs e clientes com suporte. Você usa os mesmos comandos usados para o modelo ou o arquivo Bicep.

Observação

Para usar as especificações de modelo em Bicep com o Azure PowerShell, você precisa instalar a versão 6.3.0 ou posterior. Para utilizá-lo com a CLI do Azure, use a versão 2.27.0 ou posterior.

Ao projetar sua implantação, sempre considere o ciclo de vida dos recursos e agrupe os recursos que compartilham ciclos de vida semelhantes em uma só especificação de modelo. Por exemplo, suas implantações incluem várias instâncias do Azure Cosmos DB com cada instância contendo os próprios bancos de dados e contêineres. Considerando que os bancos de dados e os contêineres não mudam muito, você deseja criar uma especificação de modelo para incluir uma instância do Cosmos DB e os bancos de dados e os contêineres subjacentes. Em seguida, você pode usar instruções condicionais no Bicep com loops de cópia para criar várias instâncias desses recursos.

Dica

A escolha entre o registro do módulo e as especificações de modelo é principalmente uma questão de preferência. Há algumas coisas a serem consideradas ao escolher entre os dois:

  • Só há suporte para o registro do módulo no Bicep. Se você ainda não estiver usando o Bicep, use as especificações de modelo.
  • O conteúdo do registro do módulo Bicep só pode ser implantado por meio de outro arquivo Bicep. As especificações de modelo podem ser implantadas diretamente por meio da API, do Azure PowerShell, da CLI do Azure e do portal do Azure. Você pode, até mesmo, usar UiFormDefinition para personalizar a experiência de implantação do portal.
  • O Bicep tem algumas funcionalidades limitadas para inserir outros artefatos de projeto (incluindo arquivos que não são do Bicep nem do modelo do ARM). Por exemplo, scripts do PowerShell, scripts da CLI e outros binários usando as funções loadTextContent e loadFileAsBase64. As especificações de modelo não podem empacotar esses artefatos.

Recursos de treinamento

Para saber mais sobre as especificações de modelo e obter diretrizes práticas, confira Publicar bibliotecas de código de infraestrutura reutilizável usando especificações de modelo.

Permissões necessárias

Há duas funções de build do Azure definidas para especificação de modelo:

Além disso, você também precisa das permissões para implantar um arquivo Bicep. Confira Implantar – CLI ou Implantar – PowerShell.

Por que usar as especificações de modelo?

As especificação de modelo oferecem os seguintes benefícios:

  • Você usa arquivos Bicep ou modelos do ARM padrão para sua especificação de modelo.
  • Você gerencia o acesso por meio do Azure RBAC, em vez de tokens SAS.
  • Os usuários podem implantar a especificação de modelo sem ter acesso de gravação ao arquivo Bicep.
  • Você pode integrar a especificação de modelo ao processo de implantação existente, como o script do PowerShell ou DevOps pipeline.

As especificações de modelo permitem que você crie modelos canônicos e compartilhe-os com equipes em sua organização. As especificações de modelo são seguras porque estão disponíveis para Azure Resource Manager para implantação, mas não podem ser acessadas por usuários sem a permissão correta. Os usuários precisam somente de acesso de leitura à especificação de modelo para implantar seu modelo, para que você possa compartilhar o modelo sem permitir que outras pessoas o modifiquem.

Se, no momento, você tiver seus modelos em um repositório GitHub ou em uma conta de armazenamento, você terá vários desafios ao tentar compartilhar e usar os modelos. Para implantar o modelo, você precisa tornar o modelo acessível publicamente ou gerenciar o acesso com tokens SAS. Para contornar essa limitação, os usuários podem criar cópias locais, que eventualmente divergem do modelo original. As especificações de modelo simplificam o compartilhamento de modelos.

Os modelos incluídos em uma especificação de modelo devem ser verificados pelos administradores em sua organização para seguir os requisitos e as diretrizes da organização.

Criar especificação de modelo

O exemplo a seguir mostra um arquivo Bicep simples para criar uma conta de armazenamento no 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'
}

Crie uma especificação de modelo usando:

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

Você também pode criar especificações de modelo usando arquivos Bicep. No entanto, o conteúdo de mainTemplate deve estar em JSON. O modelo a seguir cria uma especificação de modelo para implantar uma conta de armazenamento:

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\')]'
          }
        }
      ]
    }
  }
}

O modelo JSON inserido no arquivo Bicep precisa destas alterações:

  • Remova as vírgulas no final das linhas.
  • Substitua aspas duplas por aspas simples.
  • Escape as aspas simples dentro das expressões. Por exemplo, 'name': '[parameters(\'storageAccountType\')]'.
  • Para acessar os parâmetros e variáveis definidos no arquivo Bicep, use diretamente os nomes de parâmetros e de variáveis. Para acessar os parâmetros e variáveis definidos em mainTemplate, você ainda precisa usar sintaxe de modelo JSON do ARM. Por exemplo, 'name': '[parameters(\'storageAccountType\')]'.
  • Use a sintaxe Bicep para chamar funções Bicep. Por exemplo, 'location': resourceGroup().location.

O tamanho de uma especificação de modelo é limitado a aproximadamente 2 MB. Se um tamanho de especificação de modelo exceder o limite, você receberá o código de erro TemplateSpecTooLarge. A mensagem de erro indica:

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.

Você pode exibir todas as especificações de modelo em sua assinatura usando:

Get-AzTemplateSpec

Você pode exibir detalhes de uma especificação de modelo, incluindo suas versões com:

Get-AzTemplateSpec -ResourceGroupName templateSpecsRG -Name storageSpec

Implantar especificação de modelo

Depois de criar a especificação de modelo, os usuários com a função de Leitor de Especificações de Modelo podem implantá-la. Além disso, você também precisa das permissões para implantar um modelo do ARM. Confira Implantar – CLI ou Implantar – PowerShell.

As especificações de modelo podem ser implantadas por meio do portal, do PowerShell, da CLI do Azure ou como um módulo Bicep em uma implantação de modelo maior. Os usuários em uma organização podem implantar uma especificação de modelo em qualquer escopo no Azure (grupo de recursos, assinatura, grupo de gerenciamento ou locatário).

Em vez de transmitir um caminho ou URI para um arquivo Bicep, você implanta uma especificação de modelo fornecendo a ID de recurso dela. A ID do recurso tem o seguinte formato:

/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.Resources/templateSpecs/{template-spec-name}/versions/{template-spec-version}

Observe que a ID do recurso inclui um nome de versão para a especificação de modelo.

Por exemplo, você implanta uma especificação de modelo com o comando a seguir.

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

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

Na prática, você normalmente executará Get-AzTemplateSpec ou az ts show para obter a ID da especificação de modelo que deseja implantar.

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

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

Você também pode abrir uma URL no seguinte formato para implantar uma especificação de modelo:

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

Passar parâmetros para a especificação de modelo é semelhante a passar parâmetros para um arquivo Bicep. Adicione os valores de parâmetro embutidos ou em um arquivo de parâmetro.

Parâmetros embutidos

Para passar um parâmetro embutido, use:

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

Arquivos de parâmetros

  • Usar o arquivo de parâmetros Bicep

    Para criar um arquivo de parâmetro Bicep, você deve especificar a instrução using. Veja um exemplo:

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

param StorageAccountType = 'Standard_GRS'

    Para obter mais informações, confira Arquivo de parâmetros do Bicep.

    Para passar o arquivo de parâmetro com:

    Atualmente, você não pode implantar uma especificação de modelo com um arquivo .bicepparam usando o Azure PowerShell.

  • Usar o arquivo de parâmetros JSON

    O JSON a seguir é um arquivo de parâmetros JSON de exemplo:

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

    E, passe esse arquivo de parâmetro com:

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

Controle de versão

Ao criar uma especificação de modelo, você fornece um nome de versão para ela. À medida que você itera o código do modelo, você pode atualizar uma versão existente (para hotfixes) ou publicar uma nova versão. A versão é uma cadeia de caracteres de texto. Você pode optar por seguir qualquer sistema de controle de versão, incluindo controle de versão semântico. Os usuários da especificação de modelo podem fornecer o nome da versão que desejam usar ao implantá-lo. Você pode ter um número ilimitado de versões.

Usar marcações

As marcas ajudam você a organizar logicamente seus recursos. Você pode adicionar marcas às especificações de modelo usando o Azure PowerShell e a CLI do Azure. O seguinte exemplo mostra como especificar marcas ao criar a especificação de modelo:

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

O próximo exemplo mostra como aplicar marcas ao atualizar uma especificação de modelo existente:

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

O modelo e suas versões podem ter marcas. As marcas são aplicadas ou herdadas dependendo dos parâmetros especificados.

Especificação de modelo Versão Parâmetro de versão Parâmetro de marca Valores de marca
Exists N/D Não especificado Especificado aplicado à especificação de modelo
Exists Novo Especificado Não especificado herdado da especificação de modelo para a versão
Novo Novo Especificado Especificado aplicado à especificação e à versão de modelo
Exists Novo Especificado Especificado aplicado à versão
Exists Exists Especificado Especificado aplicado à versão

Depois de criar uma especificação de modelo, você pode criar um vínculo para ela em um módulo Bicep. A especificação de modelo é implantada quando você implanta o arquivo Bicep que contém esse módulo. Para saber mais, confira Arquivo em uma especificação de modelo.

Para criar aliases para especificações de modelo destinadas à vinculação de módulo, consulte Aliases para módulos.

Próximas etapas

Para saber mais sobre as especificações de modelo e obter diretrizes práticas, confira Publicar bibliotecas de código de infraestrutura reutilizável usando especificações de modelo.