Gerenciar uma especificação de modelo

  • 4 minutos

As especificações de modelo fornecem uma maneira conveniente de publicar e compartilhar modelos em sua organização. À medida que você usa mais especificações de modelo, torna-se importante entender como gerenciá-las.

Nesta unidade, você aprenderá sobre controle de versão, como modificar e excluir especificações de modelo e como controlar o acesso às especificações de modelo.

Observação

Os comandos nesta unidade são mostrados para ilustrar conceitos. Não execute os comandos ainda. Você praticará o que aprendeu aqui em breve.

Adicionar versões

Você aprendeu que uma única especificação de modelo pode ter várias versões. Uma especificação de modelo atua como um contêiner para uma ou mais versões, e cada versão é associada a um arquivo de modelo. Ao implantar uma especificação de modelo, você precisa especificar a versão que deseja usar, para que o Azure Resource Manager saiba qual arquivo de modelo recuperar.

O CLI do Azure e o Azure PowerShell facilitam o trabalho com várias versões. Na verdade, você já trabalhou com versões quando implantou a especificação do modelo no exercício anterior.

É uma boa ideia planejar cuidadosamente como você fará a versão das suas especificações de modelo. Duas decisões importantes a serem tomadas são o esquema de conversão e a política de conversão a serem usados.

Esquemas de controle de versão

Seu esquema de controle de versão determina como você gera números de versão. Os esquemas de controle de versão comuns incluem:

  • Os inteiros básicos podem ser usados como números de versão. Por exemplo, sua primeira versão pode ser chamada 1, sua segunda versão 2, e assim por diante.
  • As datas também fazem bons números de versão. Por exemplo, se você publicar a primeira versão da especificação do modelo em 16 de janeiro de 2021, poderá nomear a versão 2021-01-16 (usando o formato aaaa-mm-dd). Quando você publicar outra versão em 3 de março, poderá nomeá-la 2021-03-03.
  • O controle de versão semântico é um sistema de controle de versão geralmente usado em software, em que um único número de versão contém várias partes. Cada parte sinaliza informações diferentes sobre a natureza da alteração.

Embora você possa usar qualquer esquema de controle de versão que desejar, é uma boa ideia escolher algo que possa ser classificado em uma ordem significativa, como números e datas.

Observação

O Azure armazena a data em que cada versão é criada. Mesmo que você não use o controle de versão baseado em data, ainda poderá ver essas informações.

Políticas de controle de versão

As especificações de modelo oferecem a flexibilidade para escolher quando criar novas versões ou para atualizar uma versão existente. Por exemplo, você pode recusar efetivamente o controle de versão criando e publicando uma única versão chamada latest. Sempre que você precisar alterar a especificação do modelo, basta atualizar essa versão. Embora essa política funcione, não é uma boa prática.

Por outro lado, se você fizer uma pequena alteração em um modelo existente que não afete seu uso, criar uma nova versão provavelmente não será uma boa ideia. Você precisaria comunicar o novo número de versão para qualquer pessoa que usa a especificação do modelo.

Aqui está uma política de controle de versão que geralmente funciona bem:

  • Sempre que você fizer alterações significativas em uma especificação de modelo, crie uma nova versão. As alterações significativas na especificação do modelo incluem qualquer coisa que possa fazer diferença para o usuário que o implantar. Os exemplos incluem adicionar outro recurso ao modelo ou alterar as propriedades de um recurso.
  • Sempre que você fizer pequenas alterações em uma especificação de modelo, que às vezes são chamadas de hotfix, atualize a versão de especificação de modelo existente.
  • Exclua versões antigas quando elas não forem mais relevantes ou quando você não quiser que ninguém as use.

Dica

Considere os usuários de sua especificação de modelo e não se esqueça de pensar no que eles esperam que aconteça. Se um usuário implantar a especificação do modelo várias vezes e obtiver um resultado e, em seguida, implantá-lo novamente após um hotfix e obtiver um resultado diferente, provavelmente ficará surpreso. Tente minimizar a probabilidade de que os usuários obtenham um resultado que eles não esperam.

Descrições de versão

Ao criar uma nova versão de uma especificação de modelo, você pode, opcionalmente, fornecer uma descrição de versão. Fornecer uma descrição da versão é uma boa prática, mesmo que não seja obrigatório. A descrição da versão resume as alterações que você fez, para ajudar qualquer pessoa que use suas especificações de modelo a selecionar a versão que melhor atenda às suas necessidades.

Fazendo alterações em uma especificação de modelo

As especificações de modelo são recursos do Azure, para que você possa gerenciá-las como qualquer outro recurso. Isso significa que você pode visualizar os detalhes de uma especificação de modelo, atualizá-la e excluí-la, como de costume.

Por exemplo, para listar as versões de uma especificação de modelo, use o cmdlet Get-AzTemplateSpec:

Get-AzTemplateSpec `
  -ResourceGroupName MyResourceGroup `
  -Name MyTemplateSpec

O mesmo cmdlet é usado para exibir uma versão de especificação de modelo. Adicione o parâmetro -Version para obter os detalhes de uma versão:

Get-AzTemplateSpec `
  -ResourceGroupName MyResourceGroup `
  -Name MyTemplateSpec `
  -Version 1.0

Você pode acessar o modelo JSON lendo a propriedade MainTemplate de dentro da matriz Versions:

(Get-AzTemplateSpec `
  -ResourceGroupName MyResourceGroup `
  -Name MyTemplateSpec `
  -Version 1.0 `
).Versions[0].MainTemplate

Por exemplo, para listar as versões de uma especificação de modelo, use o comando az ts show:

az ts show \
  --resource-group MyResourceGroup \
  --name MyTemplateSpec

O mesmo comando é usado para exibir uma versão de especificação de modelo. Adicione o argumento --version para obter os detalhes de uma versão:

az ts show \
  --resource-group MyResourceGroup \
  --name MyTemplateSpec \
  --version 1.0

O modelo JSON é incluído na saída.

Observação

Quando você publica um arquivo Bicep em uma especificação de modelo, ele é convertido em JSON. Você não pode ver o arquivo bicep original, portanto, é uma boa ideia manter isso em outro lugar.

Para atualizar uma especificação de modelo existente, use o cmdlet Set-AzTemplateSpec. Por exemplo, você pode usar esse cmdlet para aplicar um hotfix a uma versão já publicada:

Set-AzTemplateSpec `
  -ResourceGroupName MyResourceGroup `
  -Name MyTemplateSpec `
  -Version 1.0 `
  -TemplateFile azuredeploy.json

E você pode excluir uma versão de especificação de modelo usando o cmdlet Remove-AzTemplateSpec:

Remove-AzTemplateSpec `
  -ResourceGroupName MyResourceGroup `
  -Name MyTemplateSpec `
  -Version 1.0

Para atualizar uma especificação de modelo existente, use o comando az ts update. Por exemplo, você pode usar esse comando para aplicar um hotfix a uma versão já publicada:

az ts update \
  --resource-group MyResourceGroup \
  --name MyTemplateSpec \
  --version 1.0 \
  --template-file azuredeploy.json

E você pode excluir uma versão de especificação de modelo usando o comando az ts delete:

az ts delete \
  --resource-group MyResourceGroup \
  --name MyTemplateSpec \
  --version 1.0

Exportar uma especificação de modelo

Depois de publicar um modelo como uma especificação de modelo, você pode exportá-lo. A exportação de uma especificação de modelo baixa o arquivo de modelo para o computador local. Lá, você pode editar o arquivo de modelo ou apenas inspecioná-lo para que possa entender o que ele faz.

Dica

Se a especificação de modelo incluir modelos vinculados, a exportação de uma especificação de modelo também baixará os modelos vinculados. Ele mantém até mesmo a estrutura de pastas.

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 exportar uma especificação de modelo, use o cmdlet Export-AzTemplateSpec. Use o valor -OutputFolder para especificar onde você deseja salvar os arquivos de modelo:

Export-AzTemplateSpec `
  -ResourceGroupName MyResourceGroup `
  -Name MyTemplateSpec `
  -Version 1.0 `
  -OutputFolder ./mytemplate

Para exportar uma especificação de modelo, use o comando az ts export. Use o valor --output-folder para especificar onde você deseja salvar os arquivos de modelo:

az ts export \
  --resource-group MyResourceGroup \
  --name MyTemplateSpec \
  --version 1.0 \
  --output-folder ./mytemplate

Controlar o acesso a uma especificação de modelo

Como as especificações de modelo são recursos do Azure, elas usam IAM (Gerenciamento de Identidades e Acesso) do Azure. Quando um usuário implanta uma especificação de modelo, o Azure verifica se o usuário tem acesso para ler a especificação do modelo primeiro.

Observação

Para implantar uma especificação de modelo, um usuário precisa de:

  • Acesso para ler a especificação do modelo.
  • Acesso para implantar no grupo de recursos ou outro escopo no qual ele está solicitando a implantação.

O Azure verifica as duas condições antes do início da implantação.