Projetar um fluxo de trabalho e uma estratégia de controle de versão

• 7 minutos

Quando você começa a publicar código Bicep reutilizável, você provavelmente usa uma abordagem manual. É fácil para você determinar qual arquivo Bicep você precisa publicar, e você provavelmente tem um processo manual para incrementar o número da 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 seu código. Você também aprenderá como definir o escopo de seus fluxos de trabalho para publicar apenas o código esperado.

Números de versão

Em 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 do Bíceps. Você pode escolher entre muitas abordagens diferentes de controle de versão. Em muitas situações, é uma boa prática usar um sistema de controle de versão com várias partes . Um sistema de controle de versão com várias partes consiste em uma versão principal, uma versão secundária e um número de revisão, semelhante ao exemplo a seguir:

No exemplo anterior, a versão principal é 1, a versão secundária é 4 e o número de revisão é 106.

As 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 de quebra, você deve incrementar o número da versão principal. Por exemplo, suponha que você adicione um novo parâmetro obrigatório ou remova um parâmetro do arquivo Bicep. Estes são exemplos de alterações de quebra, porque o Bicep requer parâmetros obrigatórios a serem especificados no momento da implantação e não permite definir valores para parâmetros inexistentes. Então, você atualizaria o número da versão principal.

• Sempre que você adicionar algo novo ao código, mas não for uma alteração de quebra, você deve incrementar o número da 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 estão quebrando alterações, então você deve atualizar o número da versão secundária.

• Sempre que você fizer correções de bugs compatíveis com versões anteriores ou outras alterações que não afetem o funcionamento do código, você deve incrementar o número de revisão. Por exemplo, suponha que você refatore seu código Bicep para fazer melhor uso de variáveis e expressões. Se a refatoração não alterar o comportamento do código do Bíceps, atualize o número da revisão.

• Seu fluxo de trabalho também pode definir automaticamente o número da revisão. O número de execução do fluxo de trabalho pode ser usado como o número de revisão. Essa convenção ajuda a garantir que seus números de versão sejam sempre exclusivos, mesmo que você não atualize os outros componentes de seus números de versão.

Por exemplo, suponha que você esteja usando um módulo Bicep que outra pessoa publicou. O módulo tem um número de versão do 2.0.496. Você vê que uma nova versão do módulo está disponível com o número 2.1.502da versão . A única alteração significativa é no número da versão secundária, o que indica que você não deve esperar uma alteração significativa quando usar a nova versão.

Sua equipe precisa decidir como definir uma alteração de quebra para fins de controle de versão. Por exemplo, suponha que você tenha criado um módulo Bicep que implanta uma conta de armazenamento. Agora você está atualizando o arquivo Bicep para habilitar pontos de extremidade privados em sua conta de armazenamento. Você está adicionando uma zona DNS privada ao seu arquivo Bicep ao mesmo tempo.

Nesse exemplo, você pode fazer a alteração sem afetar os parâmetros ou saídas do arquivo Bicep. Dessa forma, qualquer pessoa que implante o arquivo pode não notar que algo é diferente. Mas essa alteração introduz uma diferença significativa no comportamento de seus recursos, então você pode decidir tratá-la como uma atualização de versão principal.

Você também pode optar por usar uma estratégia de controle de versão mais simples, como usar apenas o número de execução do fluxo de trabalho como seu número de versão. Embora essa abordagem seja mais fácil de implementar, isso significa que você não pode comunicar efetivamente as diferenças entre as versões para qualquer pessoa que use seu código.

Versões e fluxos de trabalho

Quando você publica seu código interativamente, como usando a CLI do Azure, provavelmente pensa no número da versão que atribui à especificação ou módulo do modelo à medida que o publica. Mas em um fluxo de trabalho de implantação automatizado, você precisa alterar sua abordagem para atribuir números de versão. Seu fluxo de trabalho não pode detetar automaticamente alterações de quebra ou aconselhá-lo quando você deve incrementar seus números de versão principais ou secundários. Considere cuidadosamente o controle de versão antes de publicar a especificação ou o módulo do modelo.

Uma abordagem é armazenar um arquivo de metadados com seu código Bicep, conforme ilustrado no diagrama a seguir:

Sempre que você atualizar seu código Bicep, você atualiza as informações de versão no arquivo de metadados correspondente. Certifique-se de identificar corretamente as alterações ininterruptas e ininterruptas para que você possa incrementar os números de versão corretamente.

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 e módulos de modelo. Muitas vezes, faz sentido mantê-los no mesmo repositório Git.

Usando filtros de caminho nas Ações do GitHub, você pode criar fluxos de trabalho separados para cada módulo ou especificação de modelo em seu repositório. Essa abordagem ajuda a evitar a publicação de uma nova versão de cada arquivo Bicep no repositório toda vez que você alterar um arquivo. Você pode usar fluxos de trabalho reutilizáveis para definir as etapas do fluxo de trabalho em um arquivo centralizado, o que mantém o fluxo de trabalho de cada módulo e especificação de modelo leve.

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 seu 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'

name: 'publish-module-2'

on:
  push:
    branches:
      - main
    paths:
      - 'module-2/**'

jobs:
  publish:
    uses: ./.github/workflows/publish-module.yml
    with:
      path: 'module-2/main.bicep'

name: 'publish-template-spec-1'

on:
  push:
    branches:
      - main
    paths:
      - 'template-spec-1/**'

jobs:
  publish:
    uses: ./.github/workflows/publish-template-spec.yml
    with:
      path: 'template-spec-1/main.bicep'

Suponha que você altere apenas o arquivo module-2/main.bicep . Apenas o fluxo de trabalho do módulo 2 é executado. Mas se você alterar vários arquivos na mesma confirmação, cada um dos fluxos de trabalho relevantes será acionado.

Ambientes para código Bicep reutilizável

Quando você implanta no Azure usando o Bicep, é comum usar vários ambientes para ajudá-lo a validar e testar seu código antes de publicá-lo em um ambiente de produção. Em módulos de treinamento anteriores do Microsoft Learn, você aprendeu a trabalhar com vários ambientes a partir de um fluxo de trabalho de implantação.

Algumas organizações aplicam os mesmos princípios aos módulos Bicep e especificações de modelo. Por exemplo, você pode primeiro publicar novas versões de seus 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. Em seguida, depois que eles forem aprovados, você poderá publicar os módulos no registro de produção da sua organização.

Como implantações regulares, você pode usar trabalhos e fluxos de trabalho reutilizáveis para definir a sequência de implantação em seus ambientes. Neste módulo de treinamento do Microsoft Learn, publicamos em um único ambiente para manter o fluxo de trabalho simples.

Quando você consome módulos de um registro ou usa uma especificação de modelo como um módulo Bicep, você pode usar aliases. Em vez de especificar o nome do Registro ou o local da especificação do modelo toda vez que você define um módulo, você usa seu alias.

Usando aliases, você pode fazer seu processo de implantação funcionar em vários ambientes. Por exemplo, ao definir um módulo, você pode usar um alias em vez de um nome do Registro. Em seguida, você pode projetar 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á implantando em um ambiente de área restrita.
• Um registro de produção quando você está implantando em outros ambientes.