Améliorer les paramètres et les noms

8 minutes

Les paramètres constituent pour vos collègues le moyen le plus courant d’interagir avec votre modèle. En effet, au moment de déployer votre modèle, ils seront amenés à spécifier les valeurs des paramètres. Une fois créé, le nom d’une fournit des informations importantes sur sa fonction aux personnes qui voient votre environnement Azure.

Dans cette unité, vous allez découvrir des éléments importants à prendre en compte quand vous planifier les paramètres des fichiers Bicep et les noms que vous donnez à vos ressources.

Les paramètres sont-ils suffisamment compréhensibles ?

Les paramètres permettent de rendre les fichiers Bicep réutilisables et flexibles. Il est important que la fonction de chaque paramètre soit claire pour les utilisateurs. Quand vos collègues utiliseront votre modèle, c’est à partir des paramètres qu’ils personnaliseront le comportement de leur déploiement.

Par exemple, supposons que vous devez déployer un compte de stockage en utilisant un fichier Bicep. L’une des propriétés requises du compte de stockage est la référence SKU, qui définit le niveau de redondance des données. La référence SKU compte plusieurs propriétés, la plus importante étant name. Quand vous créez un paramètre pour définir la valeur de la référence SKU du compte de stockage, utilisez un nom clairement défini, tel que storageAccountSkuName. L’utilisation de cette valeur plutôt qu’un nom générique comme sku ou skuName permettra aux autres personnes de comprendre la fonction du paramètre ainsi que les effets de la définition de sa valeur.

Les valeurs par défaut offrent un bon moyen de rendre votre modèle utilisable par les autres. Il est important d’utiliser des valeurs par défaut quand cela se justifie. Cela aide les utilisateurs de votre modèle sur deux plans :

Les valeurs par défaut simplifient le déploiement de votre modèle. Si vos paramètres ont des valeurs par défaut appropriées qui conviennent à la plupart des utilisateurs de votre modèle, ceux-ci peuvent omettre les valeurs des paramètres et n’ont pas besoin de les spécifier à chaque déploiement du modèle.
Les valeurs par défaut offrent un point de repère pour ce qui est de la valeur des paramètres. Si les utilisateurs du modèle ont besoin de choisir une valeur différente, la valeur par défaut peut leur donner une indication utile de ce que doit être la valeur.

Un fichier Bicep peut aussi vous aider à valider les entrées que fournissent les utilisateurs au moyen d’éléments décoratifs de paramètres. Vous pouvez vous servir de ces éléments décoratifs pour décrire un paramètre ou indiquer les types de valeurs autorisés. Un fichier Bicep propose plusieurs types d’éléments décoratifs de paramètres :

Les descriptions fournissent des informations explicites sur la fonction du paramètre et les effets de la définition de sa valeur.
Les contraintes de valeur imposent des limites sur les valeurs de paramètres que les utilisateurs peuvent entrer. Vous pouvez définir une liste de valeurs autorisées spécifiques à l’aide de l’élément décoratif @allowed(). Vous pouvez utiliser les décorateurs @minValue() et @maxValue() pour appliquer les valeurs minimales et maximales pour des paramètres numériques, et vous pouvez utiliser les décorateurs @minLength() et @maxLength() pour appliquer la longueur des paramètres de chaîne et de tableau.

Conseil

Veillez à utilisez l’élément décoratif de paramètre @allowed() avec précaution pour spécifier des références SKU. Les services Azure ajoutent souvent de nouvelles références SKU et votre modèle ne doit pas inutilement interdire leur utilisation. Envisagez d’utiliser Azure Policy pour imposer l’utilisation de références SKU spécifiques, et utilisez l’élément décoratif @allowed() avec des références SKU uniquement lorsque vous devez empêcher les utilisateurs de votre modèle de sélectionner une référence SKU en particulier pour des raisons fonctionnelles. Par exemple, les fonctionnalités dont votre modèle a besoin pourraient ne pas être disponibles dans la référence SKU en question. Expliquez cela à l’aide d’un élément décoratif @description() ou d’un commentaire qui en décrive les raisons à quiconque dans l’avenir.
Même si cela n’est pas courant, il est possible d’appliquer des métadonnées afin de fournir des métadonnées personnalisées supplémentaires sur le paramètre.

Quel doit être le degré de flexibilité d’un fichier Bicep ?

La définition de votre infrastructure sous forme de code vise notamment à rendre vos modèles réutilisables et flexibles. Évitez de créer des modèles à usage unique qui ont une configuration codée de manière irréversible. D’un autre côté, il n’est pas judicieux d’exposer toutes les propriétés des ressources sous forme de paramètres. Créez des modèles en fonction de votre problème ou solution métier spécifique plutôt que des modèles génériques qui doivent fonctionner dans tous les cas. Vous ne voulez pas non plus avoir tant de paramètres que la saisie des valeurs prenne beaucoup de temps avant de pouvoir déployer le modèle. Cela est particulièrement important lorsque vous configurez les références SKU et le nombre d’instances de ressources.

Au moment de planifier un modèle, réfléchissez à la façon dont vous allez mettre en balance la flexibilité et la simplicité. Il existe deux façons courantes de fournir les paramètres dans les modèles :

Fournir des options de configuration de forme libre
Utiliser des jeux de configuration prédéfinis

Intéressons-nous aux deux approches à travers un exemple de fichier Bicep qui déploie un compte de stockage et un plan Azure App Service.

Fournir des options de configuration de forme libre

Le plan App Service et le compte de stockage vous imposent tous deux de spécifier leurs références SKU. Vous pouvez choisir de créer un ensemble de paramètres pour contrôler chaque référence SKU et les nombres d’instances des ressources :

Diagram of the parameters controlling an app service plan and a storage account.

Voici comment cela se présente dans le fichier Bicep :

param appServicePlanSkuName string
param appServicePlanSkuCapacity int
param storageAccountSkuName string

resource appServicePlan 'Microsoft.Web/serverfarms@2020-06-01' = {
  name: appServicePlanName
  location: location
  sku: {
    name: appServicePlanSkuName
    capacity: appServicePlanSkuCapacity
  }
}

resource storageAccount 'Microsoft.Storage/storageAccounts@2021-04-01' = {
  name: storageAccountSkuName
  location: location
  sku: {
    name: storageAccountSkuName
  }
}

C’est le format qui offre la plus grande flexibilité, car quiconque utilisant le modèle peut spécifier n’importe quelle combinaison de valeurs de paramètres. Cependant, plus vous ajoutez de ressources, plus vous avez besoin de paramètres. De ce fait, votre modèle gagne en complexité. De même, vous pouvez être amené à limiter certaines combinaisons de paramètres ou à veiller à ce que lorsqu’une ressource donnée est déployée avec une référence SKU, une autre ressource doit être déployée avec une autre référence SKU. Si vous fournissez un trop grand nombre de paramètres distincts, il est difficile d’appliquer ces règles.

Conseil

Mettez-vous à la place des personnes qui utiliseront votre modèle. En découvrant qu’il contient des dizaines de paramètres, vous risquez de les décourager de l’utiliser.

Vous pouvez peut-être réduire le nombre de paramètres en regroupant les paramètres apparentés sous la forme d’un objet de paramètre, comme ceci :

param appServicePlanSku object = {
  name: 'S1'
  capacity: 2
}

Cependant, cette approche peut limiter votre capacité à valider les valeurs des paramètres, et il n’est pas toujours évident pour les utilisateurs de votre modèle de comprendre comment définir l’objet.

Utiliser des jeux de configuration prédéfinis

L’autre possibilité est de fournir un jeu de configuration : un paramètre unique, dont la valeur est une liste limitée de valeurs autorisées, telle qu’une liste de types d’environnement. Au moment de déployer votre modèle, les utilisateurs doivent sélectionner une valeur pour ce seul paramètre. Quand ils sélectionnent une valeur pour le paramètre, le déploiement hérite automatiquement d’un ensemble de configuration :

Diagram of a configuration set controlling an app service plan and a storage account.

Voici comment se présente la définition du paramètre :

@allowed([
  'Production'
  'Test'
])
param environmentType string = 'Test'

Les ensembles de configuration offrent moins de flexibilité, car les personnes qui déploient votre modèle ne peuvent pas spécifier de tailles pour des ressources individuelles, mais vous pouvez valider chaque ensemble de configurations et vérifier qu’elles répondent à vos besoins. En optant pour des jeux de configuration, les utilisateurs de votre modèle ont moins besoin de comprendre les différentes options disponibles pour chaque ressource, et il devient plus facile d’en assurer le support, de le tester et de résoudre les problèmes associés.

Quand vous utilisez des jeux de configuration, vous créez une variable de mappage pour définir les propriétés spécifiques à définir sur les différentes ressources, en fonction de la valeur du paramètre :

var environmentConfigurationMap = {
  Production: {
    appServicePlan: {
      sku: {
        name: 'P2V3'
        capacity: 3
      }
    }
    storageAccount: {
      sku: {
        name: 'ZRS'
      }
    }
  }
  Test: {
    appServicePlan: {
      sku: {
        name: 'S2'
        capacity: 1
      }
    }
    storageAccount: {
      sku: {
        name: 'LRS'
      }
    }
  }
}

Vos définitions de ressources utilisent alors le mappage de configuration pour définir les propriétés des ressources :

resource appServicePlan 'Microsoft.Web/serverfarms@2020-06-01' = {
  name: appServicePlanName
  location: location
  sku: environmentConfigurationMap[environmentType].appServicePlan.sku
}

Les jeux de configuration peuvent vous aider à rendre les modèles complexes plus facilement accessibles. Ils peuvent aussi vous aider à appliquer vos propres règles et à encourager l’utilisation de valeurs de configuration prévalidées.

Notes

Cette approche est parfois appelée le t-shirt sizing. Quand vous achetez un t-shirt, vous n’avez pas beaucoup de choix pour la longueur, la largeur, les manches, etc. Ce choix se résume aux tailles S, M et L, et le fabricant de t-shirts a prédéfini les mesures en fonction de la taille.

Comment vos ressources sont-elles nommées ?

Dans un fichier Bicep, il est important de donner des noms explicites à vos ressources. Dans un fichier Bicep, les ressources ont deux noms :

Un nom symbolique, qui est utilisé uniquement dans le fichier Bicep et n’apparaît pas dans vos ressources Azure. D’une part, les noms symboliques aident les utilisateurs qui lisent ou modifient votre modèle à comprendre l’objet d’une définition de paramètre, de variable ou de ressource ; d’autre part, ils leur permettent d’évaluer le bien-fondé de modifier le modèle.
Un nom de ressource est le nom de la ressource qui créée dans Azure. Les noms de ressources s’accompagnent souvent de contraintes, qui imposent souvent l’unicité des noms.

Noms symboliques

Il est important de réfléchir aux noms symboliques que vous appliquez à vos ressources. Imaginez que certains de vos collègues aient besoin de modifier le modèle. Sauront-ils à quoi sert chaque ressource ?

Par exemple, supposons que vous souhaitez définir un compte de stockage pour y déposer des manuels de produits qui seront accessibles aux utilisateurs en téléchargement sur votre site web. Vous pouvez donner un nom symbolique à la ressource, par exemple storageAccount, mais s’il figure dans un fichier Bicep qui contient de nombreuses autres ressources et peut-être même d’autres comptes de stockage, ce nom ne sera pas suffisamment descriptif. Au lieu de cela, vous pouvez lui donner un nom symbolique qui renseigne sur sa finalité, par exemple productManualStorageAccount.

Dans un fichier Bicep, vous utilisez habituellement le style typographique camelCase pour les noms de paramètres, les variables et les noms symboliques des ressources. Cela signifie que le premier mot commence par une minuscule et que les autres mots commencent par une majuscule (comme dans l’exemple précédent, productManualStorageAccount). Vous n’est pas obligé d’utiliser le style camelCase. Si vous choisissez d’utiliser un style différent, il est important de se mettre d’accord au sein de l’équipe sur celui à utiliser et de l’employer systématiquement.

Noms de ressource

Chaque ressource Azure possède un nom. Les noms font partie de l’identificateur de la ressource. Dans de nombreux cas, ils sont également représentés comme les noms d’hôte que vous utilisez pour accéder à la ressource. Par exemple, si vous créez une application App Service sous le nom myapp, le nom d’hôte dont vous vous servirez pour accéder à l’application sera myapp.azurewebsites.net. Vous ne pouvez pas renommer les ressources une fois qu’elles ont été déployées.

Il est important de réfléchir à la façon dont vous nommez vos ressources Azure. De nombreuses organisations définissent leur propre convention de nommage des ressources. Cloud Adoption Framework pour Azure fournit des recommandations spécifiques qui peuvent vous aider à définir les vôtres. Le but d’une convention d’affectation de noms de ressources est d’aider quiconque au sein de votre organisation à comprendre à quoi sert chaque ressource.

Par ailleurs, chaque ressource Azure obéit à certaines règles et restrictions d’affectation de noms. Par exemple, il existe des restrictions concernant la longueur des noms, les caractères autorisés, et si les noms doivent être globaux uniques ou simplement uniques au sein d’un groupe de ressources.

Il peut être difficile de suivre toutes les conventions d’attribution de noms de votre organisation ainsi que les conditions d’affectation de noms pour Azure. Un modèle Bicep bien écrit doit dissimuler cette complexité à ses utilisateurs et déterminer automatiquement les noms des ressources. Voici un exemple d’approche à suivre :

Ajoutez un paramètre permettant de créer un suffixe d’unicité. Vous êtes ainsi assuré que le nom de vos ressources sera unique. Il est judicieux d’utiliser la fonction uniqueString() pour générer une valeur par défaut. Les personnes qui déploient votre modèle peuvent la remplacer par une valeur spécifique si elles souhaitent avoir un nom explicite. Veillez à utiliser l’élément décoratif @maxLength() pour limiter la longueur de ce suffixe afin que les noms de vos ressources ne dépassent pas leur longueur maximale.

Conseil

Il est préférable d’utiliser des suffixes d’unicité plutôt que des préfixes. Cette approche facilite le tri et l’analyse rapide de vos noms de ressources. De même, certaines ressources Azure imposent des restrictions sur le premier caractère du nom. Or, les noms générés de manière aléatoire peuvent parfois enfreindre ces restrictions.
Utilisez des variables pour construire des noms de ressources de manière dynamique. Votre code Bicep peut vérifier que les noms qu’il génère respectent la convention d’affectation de noms de votre organisation ainsi que les exigences Azure. Incluez le suffixe d’unicité dans le nom de la ressource.

Notes

Toutes les ressources n’exigent pas un nom global unique. Déterminez si vous incluez le suffixe d’unicité dans le nom de chaque ressource ou seulement dans ceux qui en ont besoin.

Continuer