Gerenciar uma especificação de modelo

Concluído

As especificações de modelo fornecem uma maneira conveniente de publicar e compartilhar modelos em sua organização. À medida que você usa mais as 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 a especificações de modelo.

Nota

Os comandos nesta unidade são mostrados para ilustrar conceitos. Não execute os comandos ainda. Você vai praticar o que você aprende 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.

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

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

Esquemas de controle de versão

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

• Inteiros básicos podem ser usados como números de versão. Por exemplo, sua primeira versão pode ser chamada 1de , sua segunda versão 2e 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, você pode nomeá-lo 2021-03-03.
• O versionamento semântico é um sistema de versionamento frequentemente usado em software, onde um único número de versão contém várias partes. Cada parte sinaliza informações diferentes sobre a natureza da mudança.

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.

Nota

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 do modelo oferecem a flexibilidade de escolher quando criar novas versões ou atualizar uma versão existente. Por exemplo, você pode efetivamente desativar o controle de versão criando e publicando uma única versão chamada latest. Sempre que precisar alterar a especificação do modelo, basta atualizar essa versão. Embora esta 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 é uma boa ideia. Você precisaria comunicar o novo número de versão para qualquer pessoa que use 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. Alterações significativas na especificação do modelo incluem qualquer coisa que possa fazer a diferença para o usuário que o implanta. 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.

Gorjeta

Considere os usuários da especificação do seu modelo e certifique-se de pensar sobre o que eles esperam que aconteça. Se um usuário implantar sua especificação de 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 seus usuários obtenham um resultado que eles não esperam.

Descrições das versões

Ao criar uma nova versão de uma especificação de modelo, você pode, opcionalmente, dar-lhe uma descrição da 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 feitas para ajudar qualquer pessoa que use sua especificação de modelo a selecionar a versão que melhor atende à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 é normal.

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

Get-AzTemplateSpec `
  -ResourceGroupName MyResourceGroup `
  -Name MyTemplateSpec

O mesmo cmdlet é usado para exibir uma versão de especificação de modelo. Adicione o -Version parâmetro 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 MainTemplate propriedade de dentro da Versions matriz:

(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 az ts show comando:

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

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

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

O modelo JSON está incluído na saída.

Nota

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, então é uma boa ideia mantê-lo em outro lugar.

Para atualizar uma especificação de modelo existente, use o Set-AzTemplateSpec cmdlet. Por exemplo, você pode usar este 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 Remove-AzTemplateSpec cmdlet:

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

Para atualizar uma especificação de modelo existente, use o az ts update comando. Por exemplo, você pode usar este 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 az ts delete comando:

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 entender o que ele faz.

Gorjeta

Se a especificação do modelo incluir modelos vinculados, a exportação de uma especificação de modelo também baixará os modelos vinculados. Ele ainda mantém 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 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 roundtripping). É 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 exportar uma especificação de modelo, use o Export-AzTemplateSpec cmdlet. Use o -OutputFolder valor para especificar onde 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 az ts export comando. Use o --output-folder valor para especificar onde 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 o gerenciamento de identidade e acesso (IAM) 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 de modelo primeiro.

Nota

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

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

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