Aprimorar parâmetros e nomes
Os parâmetros são a maneira mais comum pela qual seus colegas vão interagir com o modelo. Quando eles implantam o modelo, precisam especificar valores para os parâmetros. Após a criação dele, o nome de um recurso fornece informações importantes sobre a finalidade dele a 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ê fornece aos seus recursos.
Qual o nível de compreensão dos 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 use. Quando seus colegas trabalharem com seu modelo, eles usarão parâmetros para personalizar o comportamento da implantação.
Por exemplo, suponha que você precise implantar uma conta de armazenamento usando um arquivo Bicep. Uma das propriedades obrigatórias da conta de armazenamento é o SKU (unidade de manutenção de estoque), que define o nível de redundância dos dados. O SKU tem várias propriedades, sendo name a mais importante. Quando você criar um parâmetro para definir o valor para o SKU da conta de armazenamento, use um nome claramente definido, como storageAccountSkuName. O uso desse 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 de definir o valor dele.
Os valores padrão são uma forma importante de tornar o modelo utilizável por outras pessoas. É importante usar valores padrão quando eles fazem sentido. Eles ajudam os usuários do modelo de duas maneiras:
- Os valores padrão simplificam o processo de implantação do modelo. Se os parâmetros tiverem valores padrão adequados que funcionam para a maioria dos usuários do modelo, os usuários poderão omitir os valores de parâmetros em vez de especificá-los sempre que implantarem o modelo.
- Os valores padrão fornecem um exemplo de como você espera que seja a aparência do valor do parâmetro. Se os usuários do modelo precisarem escolher outro valor, o valor padrão poderá fornecer dicas úteis sobre a aparência do valor.
O Bicep também pode ajudar a validar a entrada que os usuários fornecem por meio de decoradores de parâmetro. Você pode usar esses decoradores para fornecer uma descrição do parâmetro ou para declarar os tipos de valores permitidos. O Bicep fornece vários tipos de decoradores de parâmetro:
As descrições fornecem informações legíveis sobre a finalidade do parâmetro e os efeitos de definir o valor dele.
As restrições de valor impõem limites sobre o que os usuários podem inserir como o valor do parâmetro. Especifique uma lista de valores permitidos específicos usando o decorador
@allowed(). Você pode usar os decoradores@minValue()e@maxValue()para impor os valores mínimos e máximos para parâmetros numéricos, e os decoradores@minLength()e@maxLength()para impor o comprimento dos parâmetros de cadeia de caracteres e matriz.Dica
Tenha cuidado ao usar o decorador de parâmetro
@allowed()para especificar SKUs. Os serviços do Azure geralmente adicionam novos SKUs, e você não quer que o seu modelo proíba desnecessariamente o uso deles. Considere o uso do Azure Policy para impor o uso de SKUs específicos e use o decorador@allowed()com SKUs somente quando houver motivos funcionais pelos quais os usuários do modelo não devem escolher um SKU específico. Por exemplo, os recursos dos quais o modelo precisa podem não estar disponíveis nesse SKU. Explique isso usando um decorador@description()ou um comentário que esclareça os motivos para qualquer pessoa no futuro.Os metadados, embora não usados normalmente, podem ser aplicados para fornecer metadados personalizados extras sobre o parâmetro.
Qual nível de flexibilidade deve ter um arquivo Bicep?
Uma das metas de definir sua infraestrutura como código é tornar os modelos reutilizáveis e flexíveis. Você não quer criar modelos de finalidade única que tenham uma configuração embutida em código. Por outro lado, não faz sentido expor todas as propriedades de recurso como parâmetros. Crie modelos que funcionem para sua solução ou seu problema comercial específico, não modelos genéricos que precisam funcionar para cada situação. Você também não deseja ter parâmetros em excesso, de modo a levar muito tempo para inserir os valores antes de implantar o modelo. Isso é particularmente importante quando você configura os SKUs e as contagens de instâncias de recursos.
Quando estiver planejando um modelo, considere como você equilibrará a flexibilidade com simplicidade. Há duas maneiras comuns de fornecer parâmetros em modelos:
- Fornecer opções de configuração com forma livre
- Usar conjuntos de configurações predefinidos
Vamos considerar as duas 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 com forma livre
O Plano do Serviço de Aplicativo e a conta de armazenamento exigem a especificação dos respectivos SKUs. Você pode considerar a criação de um conjunto de parâmetros para controlar cada um dos SKUs e cada uma das contagens de instâncias para os recursos:
Veja como isso ficará 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 mais flexibilidade, pois qualquer pessoa que use o modelo pode especificar qualquer combinação de valores de parâmetros. No entanto, à medida que você adiciona mais recursos, mais parâmetros são necessários. Como resultado, o modelo passa a ser mais complicado. Além disso, talvez seja necessário restringir determinadas combinações de parâmetros ou garantir que, quando um recurso específico for implantado usando um SKU, outro recurso precise ser implantado usando outro SKU. Se você fornecer muitos parâmetros separados, será difícil impor essas regras.
Dica
Pense nas pessoas que trabalharão com o modelo. Ver dezenas de parâmetros poderá sobrecarregá-las e fazer com que deixem de usar seu modelo.
Você poderá reduzir o número de parâmetros agrupando os parâmetros relacionados na forma de um objeto de parâmetro, desta maneira:
param appServicePlanSku object = {
name: 'S1'
capacity: 2
}
No entanto, essa abordagem pode reduzir sua capacidade de validar os valores de parâmetros, e nem sempre é fácil para os usuários do modelo entenderem como definir o objeto.
Usar conjuntos de configurações predefinidos
Como alternativa, você pode fornecer um conjunto de configuração: um só parâmetro, cujo valor é uma lista restrita de valores permitidos, como uma lista de tipos de ambientes. Quando os usuários implantarem seu modelo, eles precisarão escolher um valor somente para esse único parâmetro. Quando eles selecionarem um valor para o parâmetro, a implantação herdará automaticamente um conjunto de configurações:
A definição de parâmetro é parecida com esta:
@allowed([
'Production'
'Test'
])
param environmentType string = 'Test'
Os conjuntos de configuração oferecem menor flexibilidade, pois 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 elas se ajustem aos seus requisitos. O uso de conjuntos de configurações reduz a necessidade de os usuários do modelo entenderem todas as diferentes opções disponíveis para cada recurso e facilita o suporte, o teste e a solução de problemas dos modelos.
Ao trabalhar com os 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'
}
}
}
}
Suas definições de recurso 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 ajudar você a fazer os modelos complexos ficarem mais facilmente acessíveis. Eles também podem ajudar você a impor suas regras e incentivar o uso de valores de configuração pré-validados.
Observação
Essa abordagem, às vezes, é chamada de dimensionamento de camiseta. Ao comprar uma camiseta, você não tem muitas opções de tamanho, largura, mangas etc. Basta escolher entre os tamanhos pequeno, médio e grande, e o designer da camiseta predefiniu essas medidas com base nesse tamanho.
Como os recursos são nomeados?
No Bicep, é importante fornecer nomes significativos aos seus recursos. Os recursos do Bicep têm dois nomes:
Os nomes simbólicos são usados somente no arquivo Bicep e não são exibidos nos recursos do Azure. Eles ajudam os usuários que leem ou modificam seu modelo a entender a finalidade de um parâmetro, uma variável ou uma definição de recurso e ajudam os usuários a tomar decisões informadas sobre a possibilidade de alterar o modelo.
Os nomes de recursos são os nomes dos recursos que são criados no Azure. Muitos recursos têm restrições em relação aos nomes e exigem que eles sejam exclusivos.
Nomes simbólicos
É importante refletir sobre os nomes simbólicos que você aplica aos seus recursos. Imagine que você tenha colegas que precisam modificar o modelo. Eles compreenderão 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 no seu site. Você pode dar ao recurso um nome simbólico (por exemplo), storageAccount, mas se ele estiver em um arquivo Bicep que contiver muitos outros recursos e talvez até mesmo outras contas de armazenamento, esse nome não será suficientemente descritivo. Em vez disso, você pode dar a ele um nome simbólico que inclua algumas informações sobre a finalidade, como productManualStorageAccount.
No Bicep, normalmente, é usado o estilo de uso de maiúsculas camelCase para nomes de parâmetros, variáveis e nomes simbólicos de recursos. Isso significa que você usa minúsculas na primeira letra da primeira palavra e, depois, coloca a primeira letra das outras palavras em maiúsculas (como no exemplo anterior productManualStorageAccount). Você não é obrigado a usar o estilo camelCase. Se você optar por usar outro estilo, será importante concordar com um padrão na sua equipe e usá-lo de modo consistente.
Nomes de recurso
Cada recurso do Azure tem um nome. Os nomes formam uma 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ê criar 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 os recursos do Azure são nomeados. Muitas organizações definem sua própria convenção de nomenclatura de recursos. O Cloud Adoption Framework para o Azure tem diretrizes específicas que podem ajudar você a definir a sua. A finalidade de uma convenção de nomenclatura de recursos é ajudar todos da 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 relação ao tamanho dos nomes, aos 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 da sua organização, bem como os requisitos de nomenclatura do Azure. Um modelo Bicep bem escrito deve ocultar essa complexidade dos usuários e determinar os nomes dos recursos automaticamente. Este é um exemplo de uma abordagem a seguir:
Adicione um parâmetro que seja usado para criar um sufixo de exclusividade. Isso ajuda a garantir que os seus recursos tenham nomes exclusivos. É uma boa ideia usar a função
uniqueString()para gerar um valor padrão. As pessoas que implantam seu modelo podem substituir isso por um valor específico se desejam ter um nome significativo. Lembre-se de usar o decorador@maxLength()para limitar o tamanho desse sufixo, de modo que os nomes dos recursos não excedam o tamanho máximo.Dica
É melhor usar sufixos de exclusividade em vez de prefixos. Essa abordagem facilita a classificação e a verificação rápida dos nomes de recursos. Além disso, alguns recursos do Azure têm restrições em relação ao primeiro caractere do nome, e os nomes gerados aleatoriamente podem violar essas restrições.
Use variáveis para construir nomes de recursos dinamicamente. O código Bicep pode garantir que os nomes gerados por ele 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.
Observação
Nem todos os recursos exigem um nome globalmente exclusivo. Considere se você inclui o sufixo de exclusividade nos nomes de cada recurso ou apenas aqueles que precisam dele.