Melhores práticas para o Bicep

  • Artigo

Este artigo recomenda as práticas a serem seguidas ao desenvolver seus arquivos Bicep. Essas práticas facilitam a compreensão e o uso do arquivo Bicep.

Recursos de treinamento

Se preferir aprender sobre as melhores práticas do Bicep com diretrizes passo a passo, confira Estruturar seu código Bicep para colaboração.

Parâmetros

  • Use uma boa nomenclatura para declarações de parâmetro. Nomes adequados facilitam a leitura e a compreensão dos modelos. Verifique se você está usando nomes descritivos e claros e seja consistente em sua nomenclatura.

  • Pense cuidadosamente nos parâmetros usados pelo seu modelo. Tente usar parâmetros para configurações que mudam entre implantações. Variáveis e valores em código podem ser usados em configurações que não mudam entre implantações.

  • Cuidado com os valores padrão que você utiliza. Verifique se os valores padrão são seguros para implantação por qualquer pessoa. Por exemplo, considere o uso de SKUs e tipos de preço baratos para que a pessoa que implantar o modelo em um ambiente de teste não incorra em um custo grande desnecessariamente.

  • Use o decorador @allowed com moderação. Se você usar muito esse decorador, poderá bloquear implantações válidas. À medida que os serviços do Azure adicionam SKUs e tamanhos, sua lista de permissões pode não estar atualizada. Por exemplo, permitir apenas SKUs Premium v3 pode fazer sentido em produção, mas impede que você use o mesmo modelo em ambientes de não produção.

  • É uma boa prática fornecer descrições para os parâmetros. Tente tornar as descrições úteis e forneça informações importantes sobre o que o modelo precisa para os valores de parâmetro.

    Você também pode usar os comentários do // para adicionar anotações nos arquivos do Bicep.

  • É possível colocar as declarações de parâmetro m qualquer lugar no arquivo de modelo, embora geralmente seja uma boa ideia colocá-las na parte superior do arquivo para facilitar a leitura do código Bicep.

  • É uma boa prática especificar o comprimento mínimo e máximo de caracteres para parâmetros que controlam a nomenclatura. Essas limitações ajudam a evitar erros posteriormente durante a implantação.

Para obter mais informações sobre parâmetros do Bicep, confira Parâmetros no Bicep.

Variáveis

  • Quando você define uma variável, o tipo de dados não é necessário. As variáveis inferem o tipo do valor de resolução.

  • Você pode usar as funções Bicep para criar uma variável.

  • Depois que uma variável é definida no arquivo Bicep, você faz referência ao valor usando o nome da variável.

Para obter mais informações sobre variáveis do Bicep, confira Variáveis no Bicep.

Nomes

  • Use minúsculas concatenadas para nomes, como myVariableName ou myResource.

  • A função uniqueString() é útil para criar nomes de recursos exclusivos. Quando você fornece os mesmos parâmetros, ela retorna a mesma cadeia de caracteres a cada vez. A passagem da ID do grupo de recursos significa que a cadeia de caracteres é a mesma em todas as implantações para o mesmo grupo de recursos, mas diferente quando você implanta em diferentes grupos de recursos ou assinaturas.

  • É uma boa prática usar expressões de modelo para criar nomes de recursos, como neste exemplo:

    param shortAppName string = 'toy'
param shortEnvironmentName string = 'prod'
param appServiceAppName string = '${shortAppName}-${shortEnvironmentName}-${uniqueString(resourceGroup().id)}'

    O uso de expressões de modelo para criar nomes de recursos oferece vários benefícios:

    • As cadeias de caracteres geradas por uniqueString() não são significativas. É útil usar uma expressão de modelo para criar um nome que inclua informações significativas, como um descritor curto do projeto ou nome do ambiente, bem como um componente aleatório para tornar o nome mais propenso a ser exclusivo.

    • A função uniqueString() não garante nomes exclusivos globalmente. Ao adicionar outro texto aos nomes de recursos, você reduz a probabilidade de reutilizar um nome de recurso existente.

    • Às vezes, a função uniqueString() cria cadeias de caracteres que começam com um número. Alguns recursos do Azure, como contas de armazenamento, não permitem que seus nomes comecem com números. Esse requisito significa que é uma boa ideia usar a interpolação de cadeia de caracteres para criar nomes de recursos. Você pode adicionar um prefixo à cadeia de caracteres exclusiva.

    • Muitos tipos de recursos do Azure têm regras sobre os caracteres permitidos e o comprimento de seus nomes. Incorporar a criação de nomes de recursos no modelo significa que quem usa o modelo não precisa se lembrar de seguir essas regras por conta própria.

  • Evite usar name em um nome simbólico. O nome simbólico representa o recurso, não o nome do recurso. Por exemplo, em vez da seguinte sintaxe:

    resource cosmosDBAccountName 'Microsoft.DocumentDB/databaseAccounts@2023-04-15' = {

    Use:

    resource cosmosDBAccount 'Microsoft.DocumentDB/databaseAccounts@2023-04-15' = {

  • Evite diferenciar variáveis e parâmetros pelo uso de sufixos.

Definições de recurso

  • Em vez de inserir expressões complexas diretamente nas propriedades do recurso, use variáveis para conter as expressões. Essa abordagem torna o arquivo Bicep mais fácil de ler e entender. Ela evita que a lógica congestione as definições de recursos.

  • Tente usar propriedades de recursos como saídas, em vez de fazer suposições sobre como os recursos se comportarão. Por exemplo, se você precisar gerar uma saída de URL para um aplicativo do Serviço de Aplicativo, use a propriedade defaultHostname do aplicativo em vez de criar uma cadeia de caracteres para a URL. Às vezes, essas suposições não estão corretas em ambientes diferentes ou a maneira como os recursos funcionam muda. É mais seguro que o recurso informe as próprias propriedades a você.

  • Convém usar uma versão de API recente para cada recurso. Os novos recursos nos serviços do Azure às vezes são disponibilizados apenas em versões mais recentes da API.

  • Quando possível, evite usar as funções reference e resourceId em seu arquivo Bicep. Você pode acessar qualquer recurso no Bicep usando o nome simbólico. Por exemplo, se você definir uma conta de armazenamento com o nome simbólico toyDesignDocumentsStorageAccount, poderá acessar a ID de recurso dessa conta usando a expressão toyDesignDocumentsStorageAccount.id. Usando o nome simbólico, você cria uma dependência implícita entre os recursos.

  • Prefira usar dependências implícitas em dependências explícitas. Embora a propriedade dependsOn de recurso permita que você declare uma dependência explícita entre os recursos, geralmente é possível usar as propriedades do outro recurso usando seu nome simbólico. Essa abordagem cria uma dependência implícita entre os dois recursos e permite que o Bicep gerencie o relacionamento em si.

  • Se o recurso não for implantado no arquivo Bicep, você ainda poderá obter uma referência simbólica ao recurso usando a palavra-chave existing.

Recursos filho

  • Evite aninhar muitas camadas de profundidade. Um excesso de aninhamento torna mais difícil ler o seu código Bicep e trabalhar com ele.

  • Evite a construção de nomes de recursos para recursos filho. Você perde os benefícios que o Bicep fornece quando ele entende as relações entre os seus recursos. Em vez disso, use a propriedade parent ou o aninhamento.

Saídas

  • Lembre-se de não criar saídas para dados confidenciais. Os valores de saída podem ser acessados por qualquer pessoa que tenha acesso ao histórico de implantação. Eles não são apropriados para lidar com segredos.

  • Em vez de passar valores de propriedade por meio de saídas, use a palavra-chave existente para pesquisar propriedades de recursos que já existem. É uma melhor prática procurar chaves de outros recursos dessa maneira, em vez de passá-las por meio de saídas. Você sempre obterá os dados mais atualizados.

Para obter mais informações, confira Saídas no Bicep.

Escopos de locatário

Não é possível criar políticas nem atribuições de função no escopo de locatário. No entanto, se você precisar permitir acesso ou aplicar políticas em toda a organização, poderá implantar esses recursos no grupo de gerenciamento raiz.

Próximas etapas