Mejora de los parámetros y los nombres
Los parámetros son la forma más común de que los compañeros interactúen con nuestra plantilla. Así, cuando la implementan, deben especificar valores de los parámetros. Una vez creado, el nombre de un recurso proporciona información importante sobre su finalidad a cualquier persona que esté viendo el entorno de Azure.
En esta unidad, obtendrá información sobre algunas consideraciones clave a la hora de planear los parámetros de los archivos de Bicep y los nombres que se dan a los recursos.
¿En qué medida son comprensibles los parámetros?
Los parámetros contribuyen a que los archivos de Bicep sean reutilizables y flexibles. Es importante que la finalidad de cada parámetro esté clara para cualquiera que lo use. Cuando los compañeros trabajan con nuestra plantilla, usan parámetros para personalizar el comportamiento de su implementación.
Por ejemplo, supongamos que necesitamos implementar una cuenta de almacenamiento mediante un archivo de Bicep. Una de las propiedades obligatorias de una cuenta de almacenamiento es la referencia de almacén (SKU), que define el nivel de redundancia de los datos. La SKU tiene varias propiedades, de las que name es la más importante. Cuando cree un parámetro para establecer el valor de SKU de la cuenta de almacenamiento, use un nombre bien definido, como storageAccountSkuName. Si se usa este valor en lugar de un nombre genérico (como sku o skuName), los demás usuarios comprenderán mejor la finalidad del parámetro y los efectos de establecer su valor.
Los valores predeterminados son una forma primordial de que otros usuarios puedan usar la plantilla. Es importante usar valores predeterminados donde tengan sentido. Estos valores ayudan a los usuarios de la plantilla en dos sentidos:
- Los valores predeterminados simplifican el proceso de implementación de la plantilla. Si los parámetros tienen unos valores predeterminados en condiciones válidos para la mayoría de los usuarios de la plantilla, estos podrán obviar los valores de parámetro, en vez de tener que especificarlos cada vez que implementen la plantilla.
- Los valores predeterminados sirven de ejemplo de cómo se espera que se vea el valor del parámetro. Si los usuarios de la plantilla necesitan elegir un valor distinto, el valor predeterminado puede sugerir de forma práctica cuál debe ser ese valor.
Bicep también puede ayudar a validar la entrada que los usuarios proporcionan mediante decoradores de parámetro. Estos decoradores se pueden usar para proporcionar una descripción de los parámetros o para especificar qué tipos de valores se permiten. Bicep dispone de varios tipos de decoradores de parámetro:
Descripciones, que proporcionan información legible sobre la finalidad del parámetro y los efectos de establecer su valor.
Restricciones de valor, que imponen límites en cuanto a lo que se puede especificar como valor del parámetro. Para especificar una lista de valores permitidos concretos, se puede usar el decorador
@allowed(). Puede usar los decoradores@minValue()y@maxValue()para aplicar los valores mínimos y máximos para los parámetros numéricos, y puede usar los decoradores@minLength()y@maxLength()para aplicar la longitud de los parámetros de cadena y matriz.Sugerencia
Tenga cuidado al usar el decorador de parámetro
@allowed()para especificar SKU. Los servicios de Azure suelen agregar SKU nuevas y no conviene que la plantilla prohíba su uso innecesariamente. Considere la posibilidad de usar Azure Policy para imponer el uso de SKU específicas, y utilice el decorador@allowed()con SKU únicamente cuando haya motivos funcionales por los que los usuarios de la plantilla no deban seleccionar una SKU específica. Por ejemplo, puede que las características que nuestra plantilla necesite no estén disponibles en esa SKU. Explíquelo mediante un decorador@description()o un comentario donde el motivo esté claramente especificado para cualquier persona en el futuro.Metadatos, que, aunque no suelen usarse, se pueden aplicar para proporcionar más metadatos personalizados relativos al parámetro.
¿Qué flexibilidad debe tener un archivo de Bicep?
Uno de los objetivos de establecer una infraestructura como código es hacer que las plantillas sean reutilizables y flexibles. No es conveniente crear plantillas de un solo propósito que tengan una configuración codificada de forma rígida. Por otro lado, no tiene sentido exponer todas las propiedades de recurso como parámetros. Cree plantillas que encajen con su problema o solución empresarial específicos, no plantillas genéricas que deban encajar en cualquier situación. Tampoco quiere tener tantos parámetros que tardan mucho tiempo en escribir los valores antes de poder implementar la plantilla. Esto es especialmente importante al configurar las SKU y los recuentos de instancias de los recursos.
Al planear una plantilla, valore cómo conseguir un equilibrio entre la flexibilidad y la simplicidad. Existen dos formas habituales de proporcionar parámetros en las plantillas:
- Ofrecer opciones de configuración de forma libre
- Usar conjuntos de configuración predefinidos
Para analizar ambos métodos, vamos a usar un archivo de Bicep de ejemplo que implementa una cuenta de almacenamiento y un plan de Azure App Service.
Ofrecer opciones de configuración de forma libre
Tanto el plan de App Service como la cuenta de almacenamiento requieren que se especifiquen sus SKU correspondientes. Considere la posibilidad de crear un conjunto de parámetros para controlar cada una de las SKU y los recuentos de instancias de los recursos:
Esto tiene el siguiente aspecto en 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
}
}
Este formato reporta la máxima flexibilidad, ya que cualquier persona que use la plantilla puede especificar cualquier combinación de valores de parámetro. Sin embargo, a medida que vayamos agregando más recursos, necesitaremos más parámetros y, como resultado, la plantilla será cada vez más compleja. Además, puede que tengamos que restringir determinadas combinaciones de parámetros o asegurarnos de que, cuando se implemente un recurso específico mediante una SKU, deba implementarse otro recurso mediante otra SKU. Si proporcionamos demasiados parámetros independientes, será difícil cumplir estas reglas.
Sugerencia
Pensemos en las personas que van a trabajar con la plantilla. Si ven un sinfín de parámetros, podrían sentirse sobrepasados y dejar de usar la plantilla.
Para reducir el número de parámetros, podemos agrupar los que estén relacionados en forma de objeto de parámetros. Así:
param appServicePlanSku object = {
name: 'S1'
capacity: 2
}
Sin embargo, este método puede reducir nuestra capacidad para validar los valores de los parámetros, y no siempre es fácil que los usuarios de la plantilla sepan cómo definir el objeto.
Usar conjuntos de configuración predefinidos
Como alternativa, podemos proporcionar un conjunto de configuración, esto es, un único parámetro, cuyo valor es una lista restringida de valores permitidos (como, por ejemplo, una lista de tipos de entorno). Cuando los usuarios implementen nuestra plantilla, deberán seleccionar un solo valor, el de este parámetro. Si seleccionan un valor para el parámetro, la implementación hereda automáticamente un conjunto de configuración:
La definición del parámetro tiene un aspecto similar a este:
@allowed([
'Production'
'Test'
])
param environmentType string = 'Test'
Los conjuntos de configuración ofrecen una menor flexibilidad, ya que las personas que implementan la plantilla no pueden especificar tamaños para recursos individuales, pero puede validar cada conjunto de configuraciones y asegurarse de que se ajustan a sus requisitos. El uso de conjuntos de configuración reduce la necesidad de que los usuarios de la plantilla conozcan toda la variedad de opciones disponibles de cada recurso, aparte de que es más sencillo admitir y probar las plantillas y solucionar cualquier problema al respecto.
Cuando trabajamos con conjuntos de configuración, creamos una variable de asignación para definir las propiedades específicas que se establecerán en diferentes recursos según el valor del 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'
}
}
}
}
Tras ello, las definiciones de recursos emplean la asignación de configuración para definir las propiedades del recurso:
resource appServicePlan 'Microsoft.Web/serverfarms@2023-12-01' = {
name: appServicePlanName
location: location
sku: environmentConfigurationMap[environmentType].appServicePlan.sku
}
Los conjuntos de configuración pueden servir para hacer que las plantillas complejas sean más accesibles. También pueden ayudarnos a imponer nuestras propias reglas y a fomentar el uso de valores de configuración previamente validados.
Nota:
Este método se denomina en ocasiones tallaje de camiseta. Al comprar una camiseta, no hay mucha variedad en cuanto a la longitud, el ancho, las mangas, etc., simplemente elegimos entre tamaño pequeño, mediano y grande. El diseñador de camisetas ha predefinido esas medidas en función de esos tamaños.
¿Qué nombre debemos dar a los recursos?
En Bicep, es importante dar a los recursos nombres que tengan sentido. Los recursos de Bicep tienen dos nombres:
Nombres simbólicos, que se usan de manera interna en la plantilla de Bicep y que no aparecen en los recursos de Azure. Los nombres simbólicos ayudan a los usuarios que leen o modifican la plantilla a conocer la finalidad de un parámetro, una variable o una definición de recurso, así como a tomar decisiones fundamentadas sobre si la plantilla se debe cambiar.
Nombres de recurso, que son los nombres de los recursos que se crean en Azure. Muchos recursos presentan restricciones en cuanto al nombre, y otros muchos requieren que sus nombres sean únicos.
Nombres simbólicos
Es importante que pensemos bien los nombres simbólicos que aplicamos a los recursos. Supongamos que tenemos compañeros que necesitan modificar la plantilla. ¿Sabrán para qué sirve cada recurso?
Por ejemplo, imaginemos que queremos definir una cuenta de almacenamiento que va a contener manuales de producto para que los usuarios los descarguen desde nuestro sitio web. Podríamos dar al recurso un nombre simbólico (por ejemplo, storageAccount), pero si dicho recurso está en un archivo de Bicep que contiene otros muchos recursos, hasta otras cuentas de almacenamiento, ese nombre no será lo suficientemente descriptivo. En su lugar, podría asignarle un nombre simbólico que incluya información sobre su propósito, como productManualStorageAccount.
En Bicep, los nombres de los parámetros, las variables y los nombres simbólicos de los recursos suelen hacer un uso combinado de mayúsculas y minúsculas; es decir, empieza por minúscula la primera palabra y por mayúscula el resto de las palabras (como en el caso del ejemplo anterior, productManualStorageAccount). Usar este estilo no es obligatorio. Si decide usar otro, es importante acordar un estándar dentro del equipo y usarlo de forma coherente.
Nombres de recurso
Cada recurso de Azure tiene un nombre. Los nombres forman parte del identificador del recurso. En muchos casos, estos nombres son también los nombres de host que se usan para acceder al recurso. Por ejemplo, si creamos una aplicación de App Service llamada myapp, el nombre de host que se debe usar para acceder a esa aplicación será myapp.azurewebsites.net. No se puede cambiar el nombre de los recursos después de implementarlos.
Es importante prestar atención a cómo denominamos los recursos de Azure. Muchas organizaciones tienen establecida su propia convención de nomenclatura de recursos. Cloud Adoption Framework para Azure tiene instrucciones específicas que pueden ayudarnos a definir la nuestra. La finalidad de una convención de nomenclatura de recursos es ayudar a cualquier usuario de la organización a comprender para qué sirve cada recurso.
Además, cada recurso de Azure tiene unas determinadas reglas y restricciones de nomenclatura. Por ejemplo, hay restricciones relativas a la longitud de los nombres, los caracteres que se pueden usar y si los nombres deben ser únicos de manera global o únicamente dentro de un grupo de recursos.
Cumplir con todas las convenciones de nomenclatura de la organización y con los requisitos de nomenclatura de Azure puede no ser tarea fácil. Una plantilla de Bicep bien escrita debe evitar esta complejidad a los usuarios y determinar los nombres de los recursos automáticamente. Este es un ejemplo de un enfoque que se debe seguir:
Agregue un parámetro que sirva para crear un sufijo de unicidad. Esto ayuda a garantizar que los recursos tienen nombres únicos. Resulta buena idea usar la función
uniqueString()para generar un valor predeterminado. Quienes implementen la plantilla pueden reemplazarlo por un valor específico si quieren tener un nombre que tenga sentido. Asegúrese de usar el decorador@maxLength()para limitar la longitud de este sufijo, así los nombres de recurso no superarán la longitud máxima correspondiente.Sugerencia
Es mejor usar sufijos de unicidad que prefijos. Con este método resulta fácil ordenar y examinar rápidamente los nombres de los recursos. Además, algunos recursos de Azure tienen restricciones en cuanto al primer carácter del nombre, y a veces los nombres generados aleatoriamente pueden infringir estas restricciones.
Use variables para generar nombres de recursos dinámicamente. El código de Bicep puede hacer que los nombres que se generen cumplan la convención de nomenclatura de la organización, así como los requisitos de Azure. Incluya el sufijo de unicidad como parte del nombre del recurso.
Nota:
No todos los recursos requieren un nombre único global. Sopese si incluir el sufijo de unicidad en los nombres de todos los recursos o solo en los que lo necesiten.