Criar uma estratégia de fluxo de trabalho e controle de versão
Quando você começa a publicar o código Bicep reutilizável, geralmente usa uma abordagem manual. Você consegue determinar facilmente qual arquivo Bicep precisa publicar e provavelmente usa um processo manual para incrementar o número de versão.
Ao automatizar o processo de publicação, você precisa considerar como automatizar essas etapas. Nesta unidade, você aprenderá a adotar um sistema de controle de versão que comunica as alterações feitas no código. Você também aprenderá a definir o escopo dos fluxos de trabalho para publicar apenas o código esperado.
Números de versão
Nos módulos de treinamento anteriores do Microsoft Learn, você aprendeu sobre a importância do controle de versão para especificações de modelo e módulos de bíceps. Você pode escolher entre várias abordagens de controle de versão diferentes. Em muitas situações, uma boa prática é usar um sistema de controle de versão de várias partes. Um sistema de controle de versão de várias partes consiste em uma versão principal, uma versão secundária e um número de revisão, como no seguinte exemplo:
No exemplo anterior, a versão principal é 1, a versão secundária é 4 e o número de revisão é 106.
Alterações em diferentes partes dos números de versão comunicam informações importantes sobre os tipos de alterações no código:
Sempre que você fizer uma alteração interruptiva, deverá incrementar o número de versão principal. Por exemplo, suponha que você adicione um novo parâmetro obrigatório ou remova um parâmetro do arquivo Bicep. Esses são exemplos de alterações interruptivas, pois o Bicep requer que os parâmetros obrigatórios sejam especificados no momento da implantação e não permite definir valores para parâmetros inexistentes. Portanto, você atualizaria o número de versão principal.
Sempre que você adicionar algo novo ao código, mas não for uma alteração interruptiva, incremente o número de versão secundária. Por exemplo, suponha que você adicione um novo parâmetro opcional com um valor padrão. Os parâmetros opcionais não são alterações interruptivas, portanto, você deve atualizar o número de versão secundária.
Sempre que você fizer correções de bug compatíveis com versões anteriores ou outras alterações que não afetem o modo de funcionamento do código, incremente o número de revisão. Por exemplo, suponha que você refatore o código Bicep para usar variáveis e expressões de uma forma melhor. Se a refatoração não alterar o comportamento do código Bicep, atualize o número de revisão.
O fluxo de trabalho também pode definir automaticamente o número de revisão. O número da execução do fluxo de trabalho pode ser usado como o número de revisão. Essa convenção ajuda a garantir que os números de versão sejam sempre exclusivos, mesmo que você não atualize os outros componentes dos números de versão.
Por exemplo, suponha que você esteja usando um módulo Bicep que outra pessoa publicou. O módulo tem o número de versão 2.0.496. Você verá que uma nova versão do módulo estará disponível com o número de versão 2.1.502. A única alteração interruptiva é no número de versão secundária, o que indica que não ocorrerá uma alteração interruptiva quando você usar a nova versão.
Observação
O controle de versão semântico é uma estrutura de controle de versão formalizada semelhante ao controle de versão de várias partes. O controle de versão semântico inclui componentes adicionais no número de versão, juntamente com regras rígidas que indicam quando você deve definir ou redefinir cada componente. Há links para mais informações sobre o controle de versão semântico no resumo.
Sua equipe precisa decidir como definir uma alteração interruptiva visando o controle de versão. Por exemplo, suponha que você tenha um arquivo Bicep que implante uma conta de armazenamento. Agora você está atualizando o arquivo Bicep para habilitar pontos de extremidade privados na conta de armazenamento. Ao mesmo tempo, você está adicionando uma zona DNS privada ao arquivo Bicep.
Nesse exemplo, você pode fazer a alteração sem afetar os parâmetros ou as saídas do arquivo Bicep. Dessa forma, a pessoa que implantar o arquivo talvez não perceba que há algo diferente. Mas essa alteração apresenta uma diferença significativa no comportamento de seus recursos. Portanto, você pode decidir tratá-la como uma atualização de versão principal.
Você também pode usar uma estratégia de controle de versão mais simples, por exemplo, usar apenas o número de build do fluxo de trabalho como o número de versão. Embora essa abordagem seja mais fácil de ser implementada, ela significa que você não pode comunicar efetivamente as diferenças entre as versões às pessoas que usam o código.
Versões e fluxos de trabalho
Ao publicar o código interativamente, por exemplo, usando a CLI do Azure, você provavelmente pensa no número de versão que atribui à especificação de modelo ou ao módulo durante a publicação. Mas em um fluxo de trabalho de implantação automatizado, você precisa mudar a abordagem de atribuição de números de versão. O fluxo de trabalho não consegue detectar alterações interruptivas automaticamente nem informar quando você deve incrementar os números de versão principal ou secundária. Considere o controle de versão com atenção antes de publicar a especificação de modelo ou o módulo.
Uma abordagem é armazenar um arquivo de metadados com o código Bicep, conforme a ilustração no seguinte diagrama:
Sempre que você atualiza o código Bicep, as informações de versão são atualizadas no arquivo de metadados correspondente. Identifique corretamente as alterações interruptivas e sem interrupção para que você possa incrementar os números de versão corretamente.
Dica
Se a equipe examina o código Bicep usando solicitações de pull, peça aos revisores que validem se as alterações no código exigem a alteração dos números de versão principal ou secundária.
Você verá como usar um arquivo de metadados no próximo exercício.
Quantos fluxos de trabalho?
É comum criar uma coleção de especificações de modelo e de módulos. Muitas vezes, faz sentido colocá-los no mesmo repositório Git.
Usando filtros de caminho no GitHub Actions, você pode criar fluxos de trabalho separados para cada módulo ou especificação de modelo no repositório. Essa abordagem ajuda você a evitar a publicação de uma nova versão de cada arquivo Bicep no repositório sempre que altera um arquivo. Você pode usar modelos de fluxo de trabalho para definir as etapas do fluxo de trabalho em um arquivo centralizado, deixando leve o fluxo de trabalho de cada módulo e especificação de modelo.
Por exemplo, suponha que você tenha uma estrutura de arquivo semelhante à ilustrada anteriormente. Você pode configurar três fluxos de trabalho separados, um para cada arquivo Bicep. Selecione cada guia para ver a definição de fluxo de trabalho correspondente e o filtro de caminho:
name: 'publish-module-1'
on:
push:
branches:
- main
paths:
- 'module-1/**'
jobs:
publish:
uses: ./.github/workflows/publish-module.yml
with:
path: 'module-1/main.bicep'
Suponha que você altere apenas o arquivo module-2/main.bicep. Somente o fluxo de trabalho do módulo 2 é executado. Mas se você alterar vários arquivos no mesmo commit, cada um dos fluxos de trabalho relevantes será disparado.
Observação
A abordagem de criar um fluxo de trabalho para cada um dos arquivos Bicep reutilizáveis é simples e flexível. Mas ela pode ficar complicada quando você tem um grande número de arquivos Bicep ou não quer manter fluxos de trabalho separados para cada módulo e especificação de modelo.
Você também pode escrever scripts no fluxo de trabalho para localizar o código que foi alterado e publicar apenas esses arquivos. Essa é uma abordagem mais complexa e está fora do escopo deste módulo de treinamento do Microsoft Learn.
Ambientes para o código Bicep reutilizável
Ao implantar no Azure usando o Bicep, é comum usar vários ambientes para ajudá-lo a validar e testar seu código antes de publicar o código em um ambiente de produção. Nos módulos de treinamento anteriores do Microsoft Learn, você aprendeu a trabalhar com vários ambientes usando um fluxo de trabalho de implantação.
Algumas organizações aplicam os mesmos princípios a módulos Bicep e especificações de modelo. Por exemplo, você pode primeiro publicar novas versões dos módulos em um registro que não seja de produção para que os usuários de cada módulo possam experimentar as novas versões. Depois que eles as aprovarem, você poderá publicar os módulos no registro de produção da organização.
Assim como nas implantações regulares, você pode usar trabalhos e fluxo de trabalhos reutilizáveis para definir a sequência de implantação nos ambientes. Neste módulo de treinamento do Microsoft Learn, publicamos em um só ambiente para simplificar o fluxo de trabalho.
Ao consumir módulos de um registro ou usar uma especificação de modelo como um módulo Bicep, você pode usar aliases. Em vez de especificar o nome do registro ou a localização da especificação de modelo toda vez que definir um módulo, use um alias.
Usando aliases, você pode fazer com que o processo de implantação funcione em vários ambientes. Por exemplo, ao definir um módulo, você pode usar um alias em vez de um nome de registro. Depois, você pode criar um fluxo de trabalho de implantação para configurar o alias a ser mapeado para:
- Um registro de módulo de desenvolvimento, quando você está fazendo a implantação em um ambiente de área restrita.
- Um registro de produção, quando você está fazendo a implantação em outros ambientes.
Observação
Os aliases não se aplicam quando você faz a publicação. Eles funcionam somente quando você usa especificações de modelo ou módulos em um arquivo Bicep.