Melhores práticas para o Bicep

  • Artigo

Este artigo recomenda práticas a seguir ao desenvolver os seus ficheiros bicep. Estas práticas facilitam a compreensão e utilização do seu ficheiro Bicep.

Recursos de preparação

Se preferir saber mais sobre as melhores práticas do Bicep através da documentação de orientação passo a passo, consulte Estruturar o código bicep para colaboração.

Parâmetros

  • Utilize uma boa nomenclatura para declarações de parâmetros. Os bons nomes facilitam a leitura e compreensão dos seus modelos. Certifique-se de que está a utilizar nomes claros e descritivos e seja consistente na sua nomenclatura.

  • Pense cuidadosamente nos parâmetros que o modelo utiliza. Tente utilizar parâmetros para definições que mudam entre implementações. As variáveis e os valores hard-coded podem ser utilizados para definições que não mudam entre implementações.

  • Tenha em atenção os valores predefinidos que utiliza. Certifique-se de que os valores predefinidos são seguros para qualquer pessoa implementar. Por exemplo, considere utilizar escalões de preço e SKUs de baixo custo para que alguém que implemente o modelo num ambiente de teste não incorra num grande custo desnecessariamente.

  • Utilize o @allowed decorador com moderação. Se utilizar este decorador de forma demasiado ampla, poderá bloquear implementações válidas. À medida que os serviços do Azure adicionam SKUs e tamanhos, a lista permitida poderá não estar atualizada. Por exemplo, permitir apenas SKUs Premium v3 pode fazer sentido na produção, mas impede-o de utilizar o mesmo modelo em ambientes de não produção.

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

    Também pode utilizar // comentários para adicionar notas nos seus ficheiros do Bicep.

  • Pode colocar declarações de parâmetros em qualquer parte do ficheiro de modelo, embora, normalmente, seja boa ideia colocá-las na parte superior do ficheiro para que o código do Bicep seja fácil de ler.

  • É uma boa prática especificar o comprimento mínimo e máximo de carateres para parâmetros que controlam a nomenclatura. Estas limitações ajudam a evitar erros mais tarde durante a implementação.

Para obter mais informações sobre os parâmetros do Bicep, veja Parameters in Bicep (Parâmetros no Bicep).

Variáveis

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

  • Pode utilizar as funções bicep para criar uma variável.

  • Depois de definir uma variável no seu ficheiro Bicep, faz referência ao valor com o nome da variável.

Para obter mais informações sobre variáveis do Bicep, veja Variables in Bicep (Variáveis no Bicep).

Nomes

  • Utilize maiúsculas/minúsculas para nomes, como myVariableName ou myResource.

  • A função uniqueString() é útil para criar nomes de recursos exclusivos. Quando fornece os mesmos parâmetros, devolve sempre a mesma cadeia. Transmitir o ID do grupo de recursos significa que a cadeia é a mesma em todas as implementações para o mesmo grupo de recursos, mas diferente quando implementa em diferentes grupos de recursos ou subscrições.

  • É uma boa prática utilizar 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)}'

    Utilizar expressões de modelo para criar nomes de recursos dá-lhe várias vantagens:

    • As cadeias geradas por uniqueString() não têm significado. É útil utilizar uma expressão de modelo para criar um nome que inclua informações relevantes, como um breve descritor do nome do projeto ou do ambiente, bem como um componente aleatório para tornar o nome mais provável de ser exclusivo.

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

    • Por vezes, a uniqueString() função cria cadeias que começam com um número. Alguns recursos do Azure, como contas de armazenamento, não permitem que os respetivos nomes comecem com números. Este requisito significa que é uma boa ideia utilizar a interpolação de cadeias para criar nomes de recursos. Pode adicionar um prefixo à cadeia exclusiva.

    • Muitos tipos de recursos do Azure têm regras sobre os carateres permitidos e o comprimento dos respetivos nomes. Incorporar a criação de nomes de recursos no modelo significa que qualquer pessoa que utilize o modelo não tem de se lembrar de seguir estas regras.

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

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

    Utilizar:

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

  • Evite distinguir variáveis e parâmetros através da utilização de sufixos.

Definições de recursos

  • Em vez de incorporar expressões complexas diretamente em propriedades de recursos, utilize variáveis para conter as expressões. Esta abordagem facilita a leitura e compreensão do ficheiro Bicep. Evita a desorganização das definições de recursos com lógica.

  • Tente utilizar propriedades de recursos como saídas, em vez de fazer suposições sobre o comportamento dos recursos. Por exemplo, se precisar de enviar o URL para uma aplicação Serviço de Aplicações, utilize a propriedade defaultHostname da aplicação em vez de criar uma cadeia para o URL. Por vezes, estas suposições não estão corretas em ambientes diferentes ou os recursos mudam a forma como funcionam. É mais seguro que o recurso lhe diga as suas próprias propriedades.

  • Recomendamos que utilize uma versão recente da API para cada recurso. Por vezes, as novas funcionalidades nos serviços do Azure só estão disponíveis em versões de API mais recentes.

  • Sempre que possível, evite utilizar as funções de referência e resourceId no ficheiro Bicep. Pode aceder a qualquer recurso no Bicep com o nome simbólico. Por exemplo, se definir uma conta de armazenamento com o nome simbólico toyDesignDocumentsStorageAccount, pode aceder ao respetivo ID de recurso com a expressão toyDesignDocumentsStorageAccount.id. Ao utilizar o nome simbólico, cria uma dependência implícita entre recursos.

  • Prefere utilizar dependências implícitas em vez de dependências explícitas. Embora a dependsOn propriedade de recurso lhe permita declarar uma dependência explícita entre recursos, normalmente é possível utilizar as propriedades do outro recurso com o respetivo nome simbólico. Esta abordagem cria uma dependência implícita entre os dois recursos e permite ao Bicep gerir a própria relação.

  • Se o recurso não estiver implementado no ficheiro Bicep, ainda poderá obter uma referência simbólica ao recurso com a existing palavra-chave.

Recursos subordinados

  • Evite aninhar demasiadas camadas de profundidade. Demasiado aninhamento dificulta a leitura e o trabalho do seu código Bicep.

  • Evite construir nomes de recursos para recursos subordinados. Perde os benefícios que o Bicep proporciona quando compreende as relações entre os seus recursos. Em alternativa, utilize a parent propriedade ou aninhamento.

Saídas

  • Certifique-se de que não cria saídas para dados confidenciais. Os valores de saída podem ser acedidos por qualquer pessoa que tenha acesso ao histórico de implementações. Não são adequados para processar segredos.

  • Em vez de transmitir valores de propriedade através de saídas, utilize a palavra-chave existente para procurar propriedades de recursos que já existem. É uma melhor prática procurar chaves de outros recursos desta forma em vez de passá-las através de saídas. Obterá sempre os dados mais atualizados.

Para obter mais informações sobre as saídas do Bicep, veja Outputs in Bicep (Saídas no Bicep).

Âmbitos do inquilino

Não pode criar políticas ou atribuições de funções no âmbito do inquilino. No entanto, se precisar de conceder acesso ou aplicar políticas em toda a sua organização, pode implementar estes recursos no grupo de gestão de raiz.

Passos seguintes