Efetuar lint do código Bicep e validá-lo

  • 5 minutos

Agora que você sabe para que servem os trabalhos de fluxo de trabalho, considere o primeiro conjunto de etapas de validação que você pode adicionar ao fluxo de trabalho de implantação do Bicep. Nesta unidade, você aprenderá sobre a validação de modelos do Bicep. Você também aprenderá sobre as duas atividades de validação comumente usadas: lint e validação de comprovação.

O que é um arquivo Bicep válido?

Um arquivo Bicep válido não contém erros de sintaxe. Além disso, as definições dos recursos do Azure que você planeja implantar são válidas. Quando os recursos definidos no arquivo são implantados, eles permanecem dentro das cotas e dos limites que existem em sua assinatura do Azure.

Algumas das verificações são executadas no arquivo Bicep isoladamente, como verificações de erros de sintaxe, definições de recursos válidas do Azure e qualidade do código. Essas etapas fazem parte de um processo chamado lint. Para verificar se há outros problemas, você precisa solicitar que o serviço do Azure Resource Manager valide o modelo e leve o ambiente do Azure em consideração.

Um modelo Bicep válido tem maior possibilidade de ser implantado com êxito. Você recebe comentários sem, de fato, implantar o modelo Bicep. A validação é uma boa prática porque se você implantar um arquivo Bicep não válido, o Azure será capaz de implantar ou alterar apenas um subconjunto dos recursos descritos em seu modelo. Uma implantação parcial pode significar que o estado do ambiente é inconsistente e pode não se comportar da maneira esperada.

Como compilar o código Bicep e efetuar lint dele

Quando você implanta um arquivo Bicep, as ferramentas do Bicep executam primeiro algumas etapas básicas de validação. Essas etapas são as mesmas de quando você modifica o arquivo usando o Visual Studio Code. Elas verificam se você usou as palavras-chave da linguagem do Bicep corretamente e se definiu os recursos do Azure de acordo com os requisitos de cada tipo de recurso.

Além disso, o Bicep executa um linter nos arquivos. Lint é o processo de verificar o código em relação a um conjunto de recomendações. O linter do Bicep analisa seu arquivo e verifica se você seguiu as melhores práticas de facilidade de manutenção, exatidão, flexibilidade e extensibilidade.

Um linter contém um conjunto predefinido de regras para cada uma dessas categorias. Regras de exemplo de linter incluem:

  • Parâmetros não usados. O linter examina os parâmetros que não são usados em nenhum lugar no arquivo Bicep. Ao eliminar parâmetros não utilizados, você facilita a implantação do modelo porque não precisa fornecer valores desnecessários. Você também reduz a confusão quando alguém tenta trabalhar com o arquivo Bicep.
  • Interpolação de cadeia de caracteres. O linter verifica se o arquivo usa a função concat() em vez da interpolação de cadeia de caracteres do Bicep. A interpolação de cadeia de caracteres torna os arquivos Bicep mais legíveis.
  • Valores padrão para parâmetros seguros. O linter fornece um aviso se você define valores padrão para os parâmetros marcados com o decorador @secure(). Definir padrões para parâmetros seguros é uma prática inadequada, pois dará ao parâmetro seguro um valor legível por pessoas, que talvez não seja alterado antes da implantação.

O linter do Bicep é executado automaticamente quando você usa as ferramentas do Bicep. Sempre que você compila um arquivo Bicep, o linter o verifica em relação às melhores práticas. Essa verificação acontece automaticamente quando você implanta um arquivo Bicep no Azure.

Em um fluxo de trabalho, no entanto, o ideal é executar as etapas de validação e lint antes de implantar o arquivo. Você pode dizer ao Bicep para verificar o arquivo Bicep criando-o manualmente por meio da CLI do Bicep:

az bicep build --file main.bicep

bicep build main.bicep

Observação

Quando você executa o comando build, o Bicep também transcompila o código Bicep para um modelo do ARM JSON. Em geral, você não precisa do arquivo gerado, portanto, pode ignorá-lo.

Como você quer que os modelos Bicep passem por lint sempre que alguém faz check-in de códigos no repositório, pode adicionar um trabalho de lint ao fluxo de trabalho:

Diagrama que mostra um fluxo de trabalho com um trabalho de lint que contém um trabalho que executa o linter no arquivo.

Você expressa essa adição no arquivo YAML do fluxo de trabalho como mostrado abaixo:

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - script: |
        az bicep build --file deploy/main.bicep

Avisos e erros do linter

Por padrão, o linter emite um aviso quando descobre que um arquivo Bicep viola uma regra. Os avisos emitidos pelo linter do Bicep não são tratados como erros. Portanto, não interrompem a execução do fluxo de trabalho nem a execução dos trabalhos seguintes.

Altere esse comportamento configurando o Bicep para tratar as violações de regra do linter como erros em vez de avisos. Realize essa configuração adicionando um arquivo bicepconfig.json à pasta que contém o arquivo Bicep. Você pode decidir quais problemas do linter devem ser tratados como erros e quais devem permanecer como avisos. Você configurará o linter mais adiante neste módulo.

Dica

O arquivo bicepconfig.json também controla como o Visual Studio Code mostra os erros e os avisos no editor. Ele exibe linhas onduladas vermelhas e amarelas nas partes configuradas incorretamente no modelo Bicep. Esses indicadores fornecem comentários ainda mais rápido quando você está escrevendo o código Bicep, reduzindo ainda mais a chance de um erro.

Depois de reconfigurar o linter para emitir erros, sempre que ele detecta um problema, o fluxo de trabalho para de ser executado e os trabalhos subsequentes não são iniciados. Essa configuração ajuda a garantir que um código Bicep com problemas não seja implantado.

Validação de simulação

Você também deve verificar se o modelo Bicep provavelmente será implantado no seu ambiente do Azure com êxito. Esse processo é chamado validação de simulação e executa verificações que fazem com que o Azure forneça informações. Esses tipos de verificações incluem:

  • Os nomes que você especificou para os recursos do Bicep são válidos?
  • Os nomes que você especificou para os recursos do Bicep já foram usados?
  • As regiões em que você está implantando os recursos são válidas?

A validação de simulação exige comunicação com o Azure, mas, na verdade, não implanta nenhum recurso.

Diagrama que mostra um fluxo de trabalho com trabalhos de lint e validação, cada um contendo um trabalho. O trabalho validado se comunica com o Azure.

Para enviar um arquivo Bicep para validação de comprovação, você usa a ação arm-deploy e define deploymentMode como Validate:

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - uses: azure/login@v1
      with:
        client-id: ${{ secrets.AZURE_CLIENT_ID }}
        tenant-id: ${{ secrets.AZURE_TENANT_ID }}
        subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
    - uses: azure/arm-deploy@v1
      name: Run preflight validation
      with:
        resourceGroupName: ${{ env.AZURE_RESOURCEGROUP_NAME }}
        template: ./deploy/main.bicep
        deploymentMode: Validate

Você também pode usar o comando az deployment group validate da CLI do Azure.

A validação de comprovação é semelhante a uma implantação normal, mas não implanta nenhum recurso. Ela executa verificações extras nos recursos sendo usados no modelo.

Por exemplo, suponha que o arquivo Bicep contenha uma conta de armazenamento. A validação de simulação verifica se outra conta de armazenamento já usou o nome escolhido. Também verifica se o nome que você escolheu para a conta de armazenamento está em conformidade com as convenções de nomenclatura.

O comando de validação de simulação também executa o linter do Bicep. No entanto, em geral, é uma boa ideia executar o linter separadamente. Dessa forma, se houver erros no linter, você os detectará rapidamente, em vez de aguardar a conclusão do processo de validação. A validação leva mais tempo.

Importante

Quando você executa uma validação de comprovação, cada um dos provedores de recursos do Azure executa as próprias verificações. Alguns provedores de recursos executam muitas verificações, outros não. Portanto, você não pode confiar na validação de comprovação para ter certeza de que seu arquivo é válido. Apesar disso, ela representa uma ferramenta útil e vale a pena incluí-la no fluxo de trabalho.

Ao adicionar trabalhos de validação ao fluxo de trabalho para executar o linter e uma validação de comprovação, você terá mais confiança para implantar o arquivo Bicep.