Especificações de modelo do Azure Resource Manager
Uma especificação de modelo é um tipo de recurso para armazenar um modelo do Azure Resource Manager (modelo ARM) no Azure 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.
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. 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.
Nota
Para usar a especificação de modelo com o Azure PowerShell, você deve instalar a versão 5.0.0 ou posterior. Para usá-lo com a CLI do Azure, use a versão 2.14.2 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 Cosmos DB e seus bancos de dados e contêineres subjacentes. Em seguida, você pode usar instruções condicionais em seus modelos junto com loops de cópia para criar várias instâncias desses recursos.
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.
Gorjeta
Recomendamos o Bicep porque ele oferece os mesmos recursos que os modelos ARM e a sintaxe é mais fácil de usar. Para saber mais, consulte Especificações de modelo do Azure Resource Manager no Bicep.
Por que usar especificações de modelo?
As especificações do modelo oferecem os seguintes benefícios:
- Você usa modelos ARM padrão 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 modelo.
- 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.
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.
Criar especificação de modelo
O exemplo a seguir mostra um modelo simples para criar uma conta de armazenamento no Azure.
{
"$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": "[concat('store', uniquestring(resourceGroup().id))]",
"location": "[resourceGroup().location]",
"kind": "StorageV2",
"sku": {
"name": "[parameters('storageAccountType')]"
}
}
]
}
Quando você cria a especificação de modelo, os comandos do PowerShell ou da CLI passam o arquivo de modelo principal. Se o modelo principal fizer referência a modelos vinculados, os comandos os localizarão e empacotarão para criar a especificação do modelo. Para saber mais, consulte Criar uma especificação de modelo com modelos vinculados.
Crie uma especificação de modelo usando:
New-AzTemplateSpec -Name storageSpec -Version 1.0a -ResourceGroupName templateSpecsRg -Location westus2 -TemplateFile ./mainTemplate.json
Você também pode criar especificações de modelo usando modelos ARM. O modelo a seguir cria uma especificação de modelo para implantar uma conta de armazenamento:
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"parameters": {
"templateSpecName": {
"type": "string",
"defaultValue": "CreateStorageAccount"
},
"templateSpecVersionName": {
"type": "string",
"defaultValue": "0.1"
},
"location": {
"type": "string",
"defaultValue": "[resourceGroup().location]"
}
},
"resources": [
{
"type": "Microsoft.Resources/templateSpecs",
"apiVersion": "2021-05-01",
"name": "[parameters('templateSpecName')]",
"location": "[parameters('location')]",
"properties": {
"description": "A basic templateSpec - creates a storage account.",
"displayName": "Storage account (Standard_LRS)"
}
},
{
"type": "Microsoft.Resources/templateSpecs/versions",
"apiVersion": "2021-05-01",
"name": "[format('{0}/{1}', parameters('templateSpecName'), parameters('templateSpecVersionName'))]",
"location": "[parameters('location')]",
"dependsOn": [
"[resourceId('Microsoft.Resources/templateSpecs', parameters('templateSpecName'))]"
],
"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": "[concat('store', uniquestring(resourceGroup().id))]",
"location": "[resourceGroup().location]",
"kind": "StorageV2",
"sku": {
"name": "[parameters('storageAccountType')]"
}
}
]
}
}
}
]
}
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 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 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 modelo vinculado 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 modelo, 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 é exatamente como passar parâmetros para um modelo ARM. Adicione os valores de parâmetro embutidos ou em um arquivo de parâmetro.
Para passar um parâmetro embutido, use:
New-AzResourceGroupDeployment `
-TemplateSpecId $id `
-ResourceGroupName demoRG `
-StorageAccountType Standard_GRS
Para criar um arquivo de parâmetro local, use:
{
"$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
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 tags às especificações de modelo usando o Azure PowerShell e a CLI do Azure:
New-AzTemplateSpec `
-Name storageSpec `
-Version 1.0a `
-ResourceGroupName templateSpecsRg `
-Location westus2 `
-TemplateFile ./mainTemplate.json `
-Tag @{Dept="Finance";Environment="Production"}
Set-AzTemplateSpec `
-Name storageSpec `
-Version 1.0a `
-ResourceGroupName templateSpecsRg `
-Location westus2 `
-TemplateFile ./mainTemplate.json `
-Tag @{Dept="Finance";Environment="Production"}
Ao criar ou modificar uma especificação de modelo com o parâmetro version especificado, mas sem o parâmetro tag/tags:
- Se a especificação do modelo existir e tiver tags, mas a versão não existir, a nova versão herdará as mesmas tags que a especificação do modelo existente.
Ao criar ou modificar uma especificação de modelo com o parâmetro tag/tags e o parâmetro version especificado:
- Se a especificação do modelo e a versão não existirem, as tags serão adicionadas à nova especificação do modelo e à nova versão.
- Se a especificação do modelo existir, mas a versão não existir, as tags serão adicionadas apenas à nova versão.
- Se a especificação do modelo e a versão existirem, as tags só se aplicarão à versão.
Ao modificar um modelo com o parâmetro tag/tags especificado, mas sem o parâmetro version especificado, as tags são adicionadas apenas à especificação do modelo.
Criar uma especificação de modelo com modelos vinculados
Se o modelo principal para sua especificação de modelo fizer referência a modelos vinculados, os comandos PowerShell e CLI poderão localizar e empacotar automaticamente os modelos vinculados de sua unidade local. Você não precisa configurar manualmente contas de armazenamento ou repositórios para hospedar as especificações do modelo - tudo é independente no recurso de especificação do modelo.
O exemplo a seguir consiste em um modelo principal com dois modelos vinculados. O exemplo é apenas um trecho do modelo. Observe que ele usa uma propriedade nomeada relativePath para vincular aos outros modelos. Você deve usar apiVersion ou 2020-06-01 posterior para o recurso de implantações.
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
...
"resources": [
{
"type": "Microsoft.Resources/deployments",
"apiVersion": "2020-06-01",
...
"properties": {
"mode": "Incremental",
"templateLink": {
"relativePath": "artifacts/webapp.json"
}
}
},
{
"type": "Microsoft.Resources/deployments",
"apiVersion": "2020-06-01",
...
"properties": {
"mode": "Incremental",
"templateLink": {
"relativePath": "artifacts/database.json"
}
}
}
],
"outputs": {}
}
Quando o comando PowerShell ou CLI para criar a especificação de modelo é executado para o exemplo anterior, o comando localiza três arquivos - o modelo principal, o modelo de aplicativo Web () e o modelo de banco de dados (webapp.jsondatabase.json) - e os empacota na especificação do modelo.
Para obter mais informações, consulte Tutorial: Criar uma especificação de modelo com modelos vinculados.
Implantar especificação de modelo como um modelo vinculado
Depois de criar uma especificação de modelo, é fácil reutilizá-la a partir de um modelo ARM ou outra especificação de modelo. Você vincula a uma especificação de modelo adicionando sua ID de recurso ao modelo. A especificação do modelo vinculado é implantada automaticamente quando você implanta o modelo principal. Esse comportamento permite desenvolver especificações de modelo modular e reutilizá-las conforme necessário.
Por exemplo, você pode criar uma especificação de modelo que implanta recursos de rede e outra especificação de modelo que implanta recursos de armazenamento. Nos modelos ARM, você vincula essas duas especificações de modelo sempre que precisar configurar recursos de rede ou armazenamento.
O exemplo a seguir é semelhante ao exemplo anterior, mas você usa a propriedade para vincular a uma especificação de modelo em vez da relativePath propriedade para vincular a id um modelo local. Use 2020-06-01 para a versão da API para o recurso de implantações. No exemplo, as especificações do modelo estão em um grupo de recursos chamado templateSpecsRG.
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
...
"resources": [
{
"type": "Microsoft.Resources/deployments",
"apiVersion": "2020-06-01",
"name": "networkingDeployment",
...
"properties": {
"mode": "Incremental",
"templateLink": {
"id": "[resourceId('templateSpecsRG', 'Microsoft.Resources/templateSpecs/versions', 'networkingSpec', '1.0a')]"
}
}
},
{
"type": "Microsoft.Resources/deployments",
"apiVersion": "2020-06-01",
"name": "storageDeployment",
...
"properties": {
"mode": "Incremental",
"templateLink": {
"id": "[resourceId('templateSpecsRG', 'Microsoft.Resources/templateSpecs/versions', 'storageSpec', '1.0a')]"
}
}
}
],
"outputs": {}
}
Para obter mais informações sobre como vincular especificações de modelo, consulte Tutorial: Implantar uma especificação de modelo como um modelo vinculado.
Próximos passos
Para criar e implantar uma especificação de modelo, consulte Guia de início rápido: criar e implantar especificações de modelo.
Para obter mais informações sobre como vincular modelos em especificações de modelo, consulte Tutorial: Criar uma especificação de modelo com modelos vinculados.
Para obter mais informações sobre como implantar uma especificação de modelo como um modelo vinculado, consulte Tutorial: Implantar uma especificação de modelo como um modelo vinculado.