Especificações de modelo do Azure Resource Manager no Bicep
Uma especificação de modelo é um tipo de recurso para armazenar um modelo do Azure Resource Manager (modelo ARM) para implantação posterior. Esse tipo de recurso permite que você compartilhe modelos ARM com outros usuários em sua organização. Assim como qualquer outro recurso do Azure, você pode usar o controle de acesso baseado em função do Azure (Azure RBAC) para compartilhar a especificação do modelo. Você pode usar a CLI do Azure ou o Azure PowerShell para criar especificações de modelo fornecendo arquivos Bicep. Os arquivos Bicep são transempilhados em modelos JSON 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 especificações de modelo. Ele consiste em um modelo principal e qualquer número de modelos vinculados. O Azure armazena com segurança especificações de modelo em grupos de recursos. Tanto o modelo principal quanto os modelos vinculados devem estar em JSON. As especificações do modelo suportam o controle de versão.
Para implantar a especificação de modelo, use ferramentas padrão do Azure como PowerShell, CLI do Azure, portal do Azure, REST e outros SDKs e clientes com suporte. Você usa os mesmos comandos que usaria para o modelo ou o arquivo Bicep.
Nota
Para usar especificações de modelo no Bicep com o Azure PowerShell, você deve instalar a versão 6.3.0 ou posterior. Para usá-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 um ciclo de vida semelhante em uma única especificação de modelo. Por exemplo, suas implantações incluem várias instâncias do Azure Cosmos DB com cada instância contendo seus próprios bancos de dados e contêineres. Como 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 Cosmo DB e seus bancos de dados e contêineres subjacentes. Em seguida, você pode usar instruções condicionais em seu Bicep junto com loops de cópia para criar várias instâncias desses recursos.
Gorjeta
A escolha entre o registro do módulo e as especificações do modelo é principalmente uma questão de preferência. Há algumas coisas a considerar quando você escolhe entre os dois:
- O registro do módulo só é suportado pelo Bicep. Se você ainda não estiver usando o Bicep, use as especificações do modelo.
- O conteúdo no registro do módulo Bicep só pode ser implantado a partir de outro arquivo Bicep. As especificações de modelo podem ser implantadas diretamente da API, do Azure PowerShell, da CLI do Azure e do portal do Azure. Você pode até usar
UiFormDefinitionpara personalizar a experiência de implantação do portal. - O Bicep tem alguns recursos limitados para incorporar outros artefatos do projeto (incluindo arquivos não-Bicep e não-ARM-template. Por exemplo, scripts do PowerShell, scripts da CLI e outros binários) usando as
loadTextContentfunções eloadFileAsBase64. As especificações do modelo não podem empacotar esses artefatos.
Recursos de formação
Para saber mais sobre especificações de modelo e para obter orientação prática, consulte Publicar bibliotecas de código de infraestrutura reutilizável usando especificações de modelo.
Permissões obrigatórias
Há duas funções internas do Azure definidas para a especificação do modelo:
Além disso, você também precisa das permissões para implantar um arquivo Bicep. Consulte Implantar - CLI ou Implantar - PowerShell.
Por que usar especificações de modelo?
As especificações do modelo oferecem os seguintes benefícios:
- Você usa modelos ARM padrão ou arquivos Bicep para sua especificação de modelo.
- Você gerencia o acesso por meio do RBAC do Azure, em vez de tokens SAS.
- Os usuários podem implantar a especificação do modelo sem ter acesso de gravação ao arquivo Bicep.
- Você pode integrar a especificação do modelo ao processo de implantação existente, como script do PowerShell ou pipeline de DevOps.
As especificações de modelo permitem criar modelos canônicos e compartilhá-los com as equipes da sua organização. As especificações de modelo são seguras porque estão disponíveis para o Azure Resource Manager para implantação, mas não acessíveis aos usuários sem a permissão correta. Os usuários só precisam de acesso de leitura à especificação do modelo para implantar seu modelo, para que você possa compartilhá-lo sem permitir que outras pessoas o modifiquem.
Se você atualmente tem seus modelos em uma conta de repositório ou armazenamento do GitHub, você se depara com vários desafios ao tentar compartilhar e usar os modelos. Para implantar o modelo, você precisa torná-lo 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 seu modelo original. As especificações de modelo simplificam o compartilhamento de modelos.
Os modelos que você inclui em uma especificação de modelo devem ser verificados pelos administradores em sua organização para seguir os requisitos e orientações 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@2023-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 do 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@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\')]'
}
}
]
}
}
}
O modelo JSON incorporado no arquivo Bicep precisa fazer estas alterações:
- Remova as vírgulas no final das linhas.
- Substitua aspas duplas por aspas simples.
- Fuja das aspas simples dentro das expressões. Por exemplo, 'name': '[parameters(\'storageAccountType\')]'.
- Para acessar os parâmetros e variáveis definidos no arquivo Bicep, você pode usar diretamente os nomes dos parâmetros e os nomes das variáveis. Para acessar os parâmetros e variáveis definidos no
mainTemplate, você ainda precisa usar a sintaxe do modelo JSON 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 o tamanho de uma especificação de modelo exceder o limite, você receberá o código de erro TemplateSpecTooLarge . A mensagem de erro diz:
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 visualizar todas as especificações de modelo em sua assinatura usando:
Get-AzTemplateSpec
Você pode visualizar 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 do modelo, os usuários com a função Leitor de Especificações do Modelo podem implantá-la. Além disso, você também precisa das permissões para implantar um modelo ARM. Consulte Implantar - CLI ou Implantar - PowerShell.
As especificações de modelo podem ser implantadas por meio do portal, PowerShell, 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 passar um caminho ou URI para um arquivo Bicep, você implanta uma especificação de modelo fornecendo sua ID de recurso. O 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 o ID do recurso inclui um nome de versão para a especificação do modelo.
Por exemplo, você implanta uma especificação de modelo com o comando a seguir.
$id = "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/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 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 do modelo é semelhante a passar parâmetros para um arquivo Bicep. Adicione os valores de parâmetro embutidos ou em um arquivo de parâmetros.
Parâmetros em linha
Para passar um parâmetro embutido, use:
New-AzResourceGroupDeployment `
-TemplateSpecId $id `
-ResourceGroupName demoRG `
-StorageAccountType Standard_GRS
Arquivos de parâmetros
Usar arquivo de parâmetros Bicep
Para criar um arquivo de parâmetros Bicep, você deve especificar a
usinginstrução. Eis um exemplo:using 'using 'ts:<subscription-id>/<resource-group-name>/<template-spec-name>:<tag>' param StorageAccountType = 'Standard_GRS'Para obter mais informações, consulte Arquivo de parâmetros do Bicep.
Para passar o arquivo de parâmetros com:
Atualmente, não é possível implantar uma especificação de modelo com um arquivo .bicepparam usando o Azure PowerShell.
Usar 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âmetros com:
New-AzResourceGroupDeployment ` -TemplateSpecId $id ` -ResourceGroupName demoRG ` -TemplateParameterFile ./mainTemplate.parameters.json
Controlo de Versão
Ao criar uma especificação de modelo, você fornece um nome de versão para ela. À medida que você itera no 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 texto. Você pode optar por seguir qualquer sistema de controle de versão, incluindo o 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á-la. Você pode ter um número ilimitado de versões.
Utilizar etiquetas
As tags 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 exemplo a seguir mostra como especificar tags ao criar a especificação do 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 tags 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"}
Tanto o modelo quanto suas versões podem ter tags. As tags são aplicadas ou herdadas dependendo dos parâmetros especificados.
| Especificação do modelo | Versão | Parâmetro de versão | Parâmetro da tag | Valores de tag |
|---|---|---|---|---|
| Exists | N/A | Não especificado | Especificado | aplicado à especificação do modelo |
| Exists | Novo | Especificado | Não especificado | herdada da especificação do modelo para a versão |
| Novo | Novo | Especificado | Especificado | aplicado às especificações e à versão do modelo |
| Exists | Novo | Especificado | Especificado | aplicado à versão |
| Exists | Exists | Especificado | Especificado | aplicado à versão |
Link para especificações do modelo
Depois de criar uma especificação de modelo, você pode vincular a essa especificação de modelo em um módulo Bicep. A especificação do modelo é implantada quando você implanta o arquivo Bicep que contém esse módulo. Para obter mais informações, consulte Arquivo na especificação do modelo.
Para criar aliases para especificações de modelo destinadas à vinculação de módulos, consulte Aliases para módulos.
Próximos passos
Para saber mais sobre especificações de modelo e para obter orientação prática, consulte Publicar bibliotecas de código de infraestrutura reutilizável usando especificações de modelo.