Compartilhar via

Melhores práticas para o Bicep

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.

Parâmetros

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

  • Pense com cuidado nos parâmetros que seu modelo usa. Tente usar parâmetros para configurações que mudam entre implantações. Variáveis e valores codificados podem ser usados para configurações que não mudam entre implantações.

  • Cuidado com os valores padrão que utilizar. Verifique se os valores padrão são seguros para qualquer pessoa implantar. 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 esse decorador de forma muito ampla, 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 na produção, mas impede que você use o mesmo modelo em ambientes de não produção.

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

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

  • Você pode colocar declarações de parâmetro em qualquer lugar no arquivo de modelo, embora geralmente seja uma boa ideia colocá-las na parte superior do arquivo para que o código Bicep seja fácil de ler.

  • É uma boa prática especificar o comprimento mínimo e máximo do caractere 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, consulte 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 a partir do valor resolvido.

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

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

Para obter mais informações sobre variáveis Bicep, consulte 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, ele retorna a mesma cadeia de caracteres todas as vezes. 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)}'

    Usar 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 breve descritor do projeto ou nome 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 de recursos, você reduz a probabilidade de reutilizar um nome de recurso existente.

    • Às vezes, a uniqueString() função 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 qualquer pessoa que 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-11-15' = {

    Use:

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

  • Evite distinguir 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 facilita a leitura e a compreensão do arquivo Bicep. Isso evita que suas definições de recursos fiquem sobrecarregadas com lógica.

  • Tente usar propriedades de recurso 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 os recursos mudam a maneira como funcionam. É mais seguro permitir que o recurso declare suas próprias propriedades.

  • É uma boa ideia usar uma versão recente da API para cada recurso. Os novos recursos nos serviços do Azure às vezes estão disponíveis apenas em versões de API mais recentes.

  • Quando possível, evite usar as funções de referência e resourceId no 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 sua ID de recurso usando a expressão toyDesignDocumentsStorageAccount.id. Usando o nome simbólico, você cria uma dependência implícita entre recursos.

  • Prefira usar dependências implícitas em vez de dependências explícitas. Embora a dependsOn propriedade de recurso permita que você declare uma dependência explícita entre 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 existing palavra-chave.

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.

outputs

  • Marque dados confidenciais em saídas usando o decorador @secure(), que impede que saídas confidenciais sejam registradas ou exibidas. Caso contrário, os valores de saída podem ser acessados por qualquer pessoa que tenha acesso ao histórico de implantação.

  • 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 prática recomendada 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 conceder acesso ou aplicar políticas em toda a sua organização, poderá implantar esses recursos no grupo de gerenciamento raiz.

Próximas etapas

  • Last updated on