Melhorar parâmetros e nomes
Os parâmetros são a forma mais comum de os seus colegas interagirem com o seu modelo. Quando eles implantam seu modelo, eles precisam especificar valores para os parâmetros. Depois de criado, o nome de um recurso fornece informações importantes sobre sua finalidade para qualquer pessoa que examine seu ambiente do Azure.
Nesta unidade, você aprenderá sobre algumas considerações importantes ao planejar os parâmetros para arquivos Bicep e os nomes que você dá aos seus recursos.
Quão compreensíveis são os parâmetros?
Os parâmetros ajudam a tornar os arquivos Bicep reutilizáveis e flexíveis. É importante que a finalidade de cada parâmetro seja clara para qualquer pessoa que o utilize. Quando seus colegas trabalham com seu modelo, eles usam parâmetros para personalizar o comportamento de sua implantação.
Por exemplo, suponha que você precise implantar uma conta de armazenamento usando um arquivo Bicep. Uma das propriedades necessárias da conta de armazenamento é a unidade de manutenção de estoque (SKU), que define o nível de redundância de dados. O SKU tem várias propriedades, sendo a mais importante .name Ao criar um parâmetro para definir o valor da SKU da conta de armazenamento, use um nome claramente definido, como storageAccountSkuName. Usar esse valor em vez de um nome genérico como sku ou skuName ajudará outras pessoas a entender a finalidade do parâmetro e os efeitos da definição de seu valor.
Os valores padrão são uma maneira importante de tornar seu modelo utilizável por outras pessoas. É importante usar valores padrão onde eles fizerem sentido. Eles ajudam os usuários do seu modelo de duas maneiras:
- Os valores padrão simplificam o processo de implantação do modelo. Se os parâmetros tiverem bons valores padrão que funcionem para a maioria dos usuários do modelo, os usuários poderão omitir os valores dos parâmetros em vez de especificá-los sempre que implantarem o modelo.
- Os valores padrão fornecem um exemplo de como você espera que o valor do parâmetro pareça. Se os usuários do modelo precisarem escolher um valor diferente, o valor padrão pode fornecer dicas úteis sobre como seu valor deve parecer.
O Bicep também pode ajudar a validar a entrada que os usuários fornecem através de decoradores de parâmetros. Você pode usar esses decoradores para fornecer uma descrição de parâmetro ou para declarar quais tipos de valores são permitidos. O Bicep fornece vários tipos de decoradores de parâmetros:
As descrições fornecem informações legíveis por pessoas sobre a finalidade do parâmetro e os efeitos da definição do seu valor.
As restrições de valor impõem limites sobre o que os usuários podem inserir para o valor do parâmetro. Você pode especificar uma lista de valores específicos permitidos usando o
@allowed()decorador. Você pode usar os@minValue()decoradores e@maxValue()para impor os valores mínimo e máximo para parâmetros numéricos, e você pode usar os@minLength()decoradores e@maxLength()para impor o comprimento dos parâmetros de cadeia de caracteres e matrizes.Gorjeta
Tenha cuidado ao usar o decorador de
@allowed()parâmetros para especificar SKUs. Os serviços do Azure geralmente adicionam novas SKUs e você não quer que seu modelo proíba desnecessariamente seu uso. Considere usar a Política do Azure para impor o uso de SKUs específicas e use o decorador@allowed()com SKUs somente quando houver razões funcionais pelas quais os usuários do seu modelo não devem selecionar uma SKU específica. Por exemplo, os recursos de que seu modelo precisa podem não estar disponíveis nessa SKU. Explique isso usando um@description()decorador ou comentário que deixe as razões claras para qualquer pessoa no futuro.Os metadados, embora não sejam comumente usados, podem ser aplicados para fornecer metadados personalizados extras sobre o parâmetro.
Quão flexível deve ser um arquivo Bicep?
Um dos objetivos de definir sua infraestrutura como código é tornar seus modelos reutilizáveis e flexíveis. Você não deseja criar modelos de finalidade única que tenham uma configuração codificada. Por outro lado, não faz sentido expor todas as propriedades do recurso como parâmetros. Crie modelos que funcionem para o seu problema ou solução de negócios específicos, não modelos genéricos que precisam funcionar para todas as situações. Você também não quer ter tantos parâmetros que leva muito tempo para inserir os valores antes de implantar o modelo. Isso é particularmente importante quando você configura as SKUs e as contagens de instâncias de recursos.
Ao planejar um modelo, considere como você equilibrará flexibilidade com simplicidade. Há duas maneiras comuns de fornecer parâmetros em modelos:
- Fornecer opções de configuração de forma livre
- Usar conjuntos de configurações predefinidos
Vamos considerar ambas as abordagens usando um arquivo Bicep de exemplo que implanta uma conta de armazenamento e um plano do Serviço de Aplicativo do Azure.
Fornecer opções de configuração de forma livre
Tanto o plano do Serviço de Aplicativo quanto a conta de armazenamento exigem que você especifique suas SKUs. Você pode considerar a criação de um conjunto de parâmetros para controlar cada uma das SKUs e contagens de instâncias para os recursos:
Veja como isso fica no Bicep:
param appServicePlanSkuName string
param appServicePlanSkuCapacity int
param storageAccountSkuName string
resource appServicePlan 'Microsoft.Web/serverfarms@2023-12-01' = {
name: appServicePlanName
location: location
sku: {
name: appServicePlanSkuName
capacity: appServicePlanSkuCapacity
}
}
resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' = {
name: storageAccountSkuName
location: location
sku: {
name: storageAccountSkuName
}
}
Esse formato fornece a maior flexibilidade, porque qualquer pessoa que usa o modelo pode especificar qualquer combinação de valores de parâmetro. No entanto, à medida que você adiciona mais recursos, você precisa de mais parâmetros. Como resultado, seu modelo se torna mais complicado. Além disso, talvez seja necessário restringir certas combinações de parâmetros ou garantir que, quando um recurso específico é implantado usando uma SKU, outro recurso precisa ser implantado usando uma SKU diferente. Se você fornecer muitos parâmetros separados, é difícil aplicar essas regras.
Gorjeta
Pense nas pessoas que trabalharão com seu modelo. Ver dezenas de parâmetros pode sobrecarregá-los e fazer com que abandonem o uso do seu modelo.
Talvez seja possível reduzir o número de parâmetros agrupando parâmetros relacionados na forma de um objeto de parâmetro, da seguinte forma:
param appServicePlanSku object = {
name: 'S1'
capacity: 2
}
No entanto, essa abordagem pode reduzir sua capacidade de validar os valores de parâmetro, e nem sempre é fácil para os usuários do modelo entender como definir o objeto.
Usar conjuntos de configurações predefinidos
Como alternativa, você pode fornecer um conjunto de configurações: um único parâmetro, cujo valor é uma lista restrita de valores permitidos, como uma lista de tipos de ambiente. Quando os usuários implantam seu modelo, eles precisam selecionar um valor apenas para esse parâmetro. Quando eles selecionam um valor para o parâmetro, a implantação herda automaticamente um conjunto de configurações:
A definição do parâmetro tem esta aparência:
@allowed([
'Production'
'Test'
])
param environmentType string = 'Test'
Os conjuntos de configurações oferecem menor flexibilidade, porque as pessoas que implantam seu modelo não podem especificar tamanhos para recursos individuais, mas você pode validar cada conjunto de configurações e garantir que eles atendam às suas necessidades. O uso de conjuntos de configurações reduz a necessidade de os usuários do seu modelo entenderem todas as diferentes opções disponíveis para cada recurso, e fica mais fácil dar suporte, testar e solucionar problemas de seus modelos.
Ao trabalhar com conjuntos de configurações, você cria uma variável de mapa para definir as propriedades específicas a serem definidas em vários recursos, com base no valor do parâmetro:
var environmentConfigurationMap = {
Production: {
appServicePlan: {
sku: {
name: 'P2V3'
capacity: 3
}
}
storageAccount: {
sku: {
name: 'ZRS'
}
}
}
Test: {
appServicePlan: {
sku: {
name: 'S2'
capacity: 1
}
}
storageAccount: {
sku: {
name: 'LRS'
}
}
}
}
Em seguida, as definições de recursos usam o mapa de configuração para definir as propriedades do recurso:
resource appServicePlan 'Microsoft.Web/serverfarms@2023-12-01' = {
name: appServicePlanName
location: location
sku: environmentConfigurationMap[environmentType].appServicePlan.sku
}
Os conjuntos de configurações podem ajudá-lo a tornar os modelos complexos mais facilmente acessíveis. Eles também podem ajudá-lo a aplicar suas próprias regras e incentivar o uso de valores de configuração pré-validados.
Nota
Essa abordagem às vezes é chamada de dimensionamento de camisetas. Quando você compra uma camiseta, você não tem muitas opções de comprimento, largura, mangas e assim por diante. Você simplesmente escolhe entre tamanhos pequenos, médios e grandes, e o designer de camisetas predefiniu essas medidas com base nesse tamanho.
Como são nomeados os seus recursos?
No Bicep, é importante dar nomes significativos aos seus recursos. Os recursos no Bicep têm dois nomes:
Os nomes simbólicos são usados apenas dentro do arquivo Bicep e não aparecem em seus recursos do Azure. Os nomes simbólicos ajudam os usuários que leem ou modificam seu modelo a entender a finalidade de um parâmetro, variável ou definição de recurso, e ajudam os usuários a tomar decisões informadas sobre se devem alterar o modelo.
Nomes de recursos são os nomes dos recursos criados no Azure. Muitos recursos têm restrições em seus nomes, e muitos exigem que seus nomes sejam exclusivos.
Nomes simbólicos
É importante pensar nos nomes simbólicos que você aplica aos seus recursos. Imagine que você tem colegas que precisam modificar o modelo. Será que eles vão entender para que serve cada recurso?
Por exemplo, suponha que você queira definir uma conta de armazenamento que conterá manuais de produtos para os usuários baixarem do seu site. Você pode dar ao recurso um nome simbólico de (por exemplo) storageAccount, mas se ele estiver em um arquivo Bicep que contém muitos outros recursos, e talvez até mesmo outras contas de armazenamento, esse nome não é suficientemente descritivo. Em vez disso, você pode dar a ele um nome simbólico que inclua algumas informações sobre sua finalidade, como productManualStorageAccount.
No Bicep, você normalmente usa o estilo de maiúsculas camelCase para os nomes de parâmetros, variáveis e nomes simbólicos de recursos. Isso significa que você usa uma primeira letra minúscula para a primeira palavra e, em seguida, coloca em maiúscula a primeira letra das outras palavras (como no exemplo anterior, productManualStorageAccount). Você não é obrigado a usar camelCase. Se você optar por usar um estilo diferente, é importante concordar com um padrão dentro da sua equipe e usá-lo de forma consistente.
Nomes de recursos
Cada recurso do Azure tem um nome. Os nomes fazem parte do identificador do recurso. Em muitos casos, eles também são representados como os nomes de host que você usa para acessar o recurso. Por exemplo, quando você cria um aplicativo do Serviço de Aplicativo chamado myapp, o nome do host usado para acessar o aplicativo será myapp.azurewebsites.net. Não é possível renomear recursos depois que eles são implantados.
É importante considerar como você nomeia seus recursos do Azure. Muitas organizações definem sua própria convenção de nomenclatura de recursos. O Cloud Adoption Framework for Azure tem orientações específicas que podem ajudá-lo a definir o seu. O objetivo de uma convenção de nomenclatura de recursos é ajudar todos na sua organização a entender para que serve cada recurso.
Além disso, cada recurso do Azure tem determinadas regras e restrições de nomenclatura. Por exemplo, há restrições em torno do comprimento dos nomes, dos caracteres que eles podem incluir e se os nomes precisam ser globalmente exclusivos ou apenas exclusivos dentro de um grupo de recursos.
Pode ser complexo seguir todas as convenções de nomenclatura para sua organização, bem como os requisitos de nomenclatura para o Azure. Um modelo Bicep bem escrito deve ocultar essa complexidade de seus usuários e determinar os nomes dos recursos automaticamente. Aqui está um exemplo de uma abordagem a seguir:
Adicione um parâmetro usado para criar um sufixo de exclusividade. Isso ajuda a garantir que seus recursos tenham nomes exclusivos. É uma boa ideia usar a
uniqueString()função para gerar um valor padrão. As pessoas que implantam seu modelo podem substituí-lo por um valor específico se quiserem ter um nome significativo. Certifique-se de usar o@maxLength()decorador para limitar o comprimento desse sufixo para que seus nomes de recursos não excedam seus comprimentos máximos.Gorjeta
É melhor usar sufixos de exclusividade em vez de prefixos. Essa abordagem facilita a classificação e a verificação rápida dos nomes dos recursos. Além disso, alguns recursos do Azure têm restrições sobre o primeiro caractere do nome, e nomes gerados aleatoriamente às vezes podem violar essas restrições.
Use variáveis para construir nomes de recursos dinamicamente. Seu código Bicep pode garantir que os nomes gerados sigam a convenção de nomenclatura da sua organização, bem como os requisitos do Azure. Inclua o sufixo de exclusividade como parte do nome do recurso.
Nota
Nem todos os recursos requerem um nome globalmente exclusivo. Considere se você inclui o sufixo de exclusividade nos nomes de cada recurso ou apenas daqueles que precisam dele.