Verbessern von Parametern und Namen
Die Interaktion Ihrer Kollegen mit Ihrer Vorlage erfolgt am häufigsten über Parameter. Wenn Sie Ihre Vorlage bereitstellen, müssen Sie Werte für die Parameter angeben. Nach der Erstellung einer Ressource vermittelt ihr Name allen Personen, die sich Ihre Azure-Umgebung ansehen, wichtige Informationen zu ihrem Zweck.
In dieser Lerneinheit werden wichtige Überlegungen bei der Planung der Parameter für Bicep-Dateien und der Benennung Ihrer Ressourcen erläutert.
Wie verständlich sind die Parameter?
Parameter tragen dazu bei, Bicep-Dateien wiederverwendbar und flexibel zu machen. Es ist wichtig, dass der Zweck jedes Parameters für jede Person ersichtlich ist, die ihn verwendet. Wenn Ihre Kollegen mit Ihrer Vorlage arbeiten, verwenden sie Parameter, um das Verhalten ihrer Bereitstellung anzupassen.
Angenommen, Sie müssen mithilfe einer Bicep-Datei ein Speicherkonto bereitstellen. Eine der erforderlichen Eigenschaften des Speicherkontos ist die Stock Keeping Unit (SKU), die den Grad der Datenredundanz definiert. Die SKU verfügt über mehrere Eigenschaften, die wichtigste lautet name. Wenn Sie einen Parameter erstellen, um den Wert für die SKU des Speicherkontos festzulegen, verwenden Sie einen klar definierten Namen, z. B. storageAccountSkuName. Die Verwendung dieses Namens anstelle eines generischen Namens, z. B. sku oder skuName, hilft anderen zu erkennen, welchem Zweck der Parameter dient und welche Auswirkungen das Festlegen seines Werts hat.
Standardwerte sind eine wichtige Möglichkeit, Ihre Vorlage für andere Benutzer verwendbar zu machen. Standardwerte sollten verwendet werden, wo immer sie sinnvoll sind. Sie unterstützen die Benutzer Ihrer Vorlage auf zwei Arten:
- Standardwerte vereinfachen die Bereitstellung Ihrer Vorlage. Wenn Ihre Parameter Standardwerte aufweisen, die für die meisten Benutzer Ihrer Vorlage geeignet sind, können die Benutzer die Parameterwerte weglassen, anstatt sie bei jeder Bereitstellung der Vorlage anzugeben.
- Standardwerte bieten ein Beispiel für den von Ihnen erwarteten Parameterwert. Wenn Vorlagenbenutzer einen anderen Wert auswählen müssen, kann der Standardwert nützliche Hinweise dazu liefern, wie der Wert lauten sollte.
Bicep kann auch mit Parameter-Decorators dabei helfen, die Eingaben der Benutzer zu überprüfen. Sie können mithilfe dieser Decorators eine Parameterbeschreibung bereitstellen oder angeben, welche Arten von Werten zulässig sind. Bicep stellt verschiedene Typen von Parameter-Decorators bereit:
Beschreibungen bieten lesbare Informationen über den Zweck des Parameters und die Auswirkungen, die das Festlegen seines Werts hat.
Werteinschränkungen erzwingen Beschränkungen der Werte, die für den Parameter eingegeben werden dürfen. Mit dem Decorator
@allowed()können Sie eine Liste mit bestimmten zulässigen Werten angeben. Sie können die Decorator-Elemente@minValue()und@maxValue()verwenden, um die Mindest- und Höchstwerte für numerische Parameter zu erzwingen, und Sie können die Decorator-Elemente@minLength()und@maxLength()verwenden, um die Länge von Zeichenfolgen- und Arrayparametern zu erzwingen.Tipp
Seien Sie vorsichtig, wenn Sie mit dem Parameter-Decorator
@allowed()SKUs angeben. Azure-Dienste fügen häufig neue SKUs hinzu, und Ihre Vorlage sollte deren Verwendung nicht unnötigerweise verhindern. Sie können mit Azure Policy die Verwendung bestimmter SKUs erzwingen. Verwenden Sie den Decorator@allowed()nur für SKUs, wenn aus bestimmten Gründen die Benutzer Ihrer Vorlage eine spezielle SKU nicht auswählen sollten. Beispielsweise sind eventuell die für Ihre Vorlage erforderlichen Features in der betreffenden SKU nicht verfügbar. Erläutern Sie dies mithilfe des Decorators@description()oder eines Kommentars, der die Gründe für jeden zukünftigen Benutzer erläutert.Metadaten werden zwar nicht häufig verwendet, können jedoch angewendet werden, um zusätzliche benutzerdefinierte Metadaten des Parameters bereitzustellen.
Wie flexibel sollte eine Bicep-Datei sein?
Durch das Definieren von Infrastructure-as-Code sollen Ihre Vorlagen wiederverwendbar und flexibel werden. Es empfiehlt sich nicht, Vorlagen für einen einzelnen Zweck mit einer hartcodierten Konfiguration zu erstellen. Andererseits ist es nicht sinnvoll, alle Ressourceneigenschaften als Parameter verfügbar zu machen. Erstellen Sie Vorlagen für Ihr spezielles Geschäftsproblem oder Ihre spezielle Lösung und keine generischen Vorlagen, die für jede Situation verwendbar sein müssen. Außerdem sollten nicht so viele Parameter vorhanden sein, dass die Eingabe der Werte sehr lange dauert, bevor Sie die Vorlage bereitstellen können. Dies ist besonders wichtig, wenn Sie die SKUs und die Anzahl der Instanzen von Ressourcen konfigurieren.
Überlegen Sie beim Planen einer Vorlage, wie Sie einen sinnvollen Kompromiss zwischen Flexibilität und Einfachheit erzielen. Es gibt zwei gängige Möglichkeiten zum Bereitstellen von Parametern in Vorlagen:
- Bereitstellen von Freiformkonfigurationsoptionen
- Verwenden vordefinierter Konfigurationssätze
Betrachten wir beide Ansätze anhand einer Bicep-Beispieldatei, die ein Speicherkonto und einen Azure App Service-Plan bereitstellt.
Bereitstellen von Freiformkonfigurationsoptionen
Sowohl der App Service-Plan als auch das Speicherkonto erfordern, dass Sie deren SKUs angeben. Sie können eine Reihe von Parametern erstellen, um die einzelnen SKUs und die jeweilige Instanzenanzahl für die Ressourcen zu steuern:
In Bicep sieht dies wie folgt aus:
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
}
}
Dieses Format bietet die größte Flexibilität, da jeder Benutzer der Vorlage eine beliebige Kombination von Parameterwerten angeben kann. Wenn Sie jedoch weitere Ressourcen hinzufügen, benötigen Sie weitere Parameter. Dadurch erhöht sich die Komplexität der Vorlage. Außerdem müssen Sie möglicherweise bestimmte Kombinationen von Parametern beschränken oder sicherstellen, dass beim Bereitstellen einer bestimmten Ressource mit einer SKU eine weitere Ressource mit einer anderen SKU bereitgestellt werden muss. Wenn Sie zu viele verschiedene Parameter angeben, lassen sich diese Regeln schwierig erzwingen.
Tipp
Berücksichtigen Sie die zukünftigen Benutzer Ihrer Vorlage. Die Anzeige Dutzender von Parametern kann sie verwirren und dazu führen, dass sie auf Ihre Vorlage verzichten.
Möglicherweise können Sie die Anzahl der Parameter reduzieren, indem Sie wie im folgenden Beispiel verwandte Parameter in Form eines Parameterobjekts gruppieren:
param appServicePlanSku object = {
name: 'S1'
capacity: 2
}
Dieser Ansatz kann jedoch das Überprüfen der Parameterwerte beeinträchtigen, und für die Benutzer Ihrer Vorlage lässt sich das Definieren des Objekts nicht immer einfach begreifen.
Verwenden vordefinierter Konfigurationssätze
Alternativ können Sie einen Konfigurationssatz angeben: einen einzelnen Parameter, für den nur eine eingeschränkte Liste von Werten zulässig ist, z. B. eine Liste von Umgebungstypen. Wenn Benutzer Ihre Vorlage bereitstellen, müssen sie einen Wert für nur diesen einen Parameter auswählen. Wenn sie einen Wert für den Parameter auswählen, erbt die Bereitstellung automatisch einen Konfigurationssatz:
Die Parameterdefinition sieht wie folgt aus:
@allowed([
'Production'
'Test'
])
param environmentType string = 'Test'
Konfigurationssätze bieten eine geringere Flexibilität, da Personen, die Ihre Vorlage bereitstellen, keine Größen für einzelne Ressourcen angeben können. Sie können jedoch alle Konfigurationssätze überprüfen und sicherstellen, dass sie Ihren Anforderungen entsprechen. Durch die Verwendung von Konfigurationssätzen brauchen die Benutzer Ihrer Vorlage nicht alle unterschiedlichen Optionen zu begreifen, die für die einzelnen Ressourcen verfügbar sind. Konfigurationssätze erleichtern außerdem das Unterstützen und Testen der Vorlagen und die Problembehandlung für Vorlagen.
Wenn Sie mit Konfigurationssätzen arbeiten, erstellen Sie eine Zuordnungsvariable, um die speziellen Eigenschaften zu definieren, die für verschiedene Ressourcen basierend auf dem Parameterwert festgelegt werden:
var environmentConfigurationMap = {
Production: {
appServicePlan: {
sku: {
name: 'P2V3'
capacity: 3
}
}
storageAccount: {
sku: {
name: 'ZRS'
}
}
}
Test: {
appServicePlan: {
sku: {
name: 'S2'
capacity: 1
}
}
storageAccount: {
sku: {
name: 'LRS'
}
}
}
}
In den Ressourcendefinitionen wird dann die Konfigurationszuordnung verwendet, um die Ressourceneigenschaften zu definieren:
resource appServicePlan 'Microsoft.Web/serverfarms@2023-12-01' = {
name: appServicePlanName
location: location
sku: environmentConfigurationMap[environmentType].appServicePlan.sku
}
Mithilfe von Konfigurationssätzen können Sie den Zugriff auf komplexe Vorlagen vereinfachen. Sie können Ihnen auch helfen, eigene Regeln zu erzwingen und die Verwendung vorab überprüfter Konfigurationswerte zu fördern.
Hinweis
Dieser Ansatz wird manchmal als Aufwandsschätzung mit T-Shirt-Größen (T-shirt sizing) bezeichnet. Wenn Sie ein T-Shirt kaufen, stehen Ihnen nicht viele Optionen für Länge, Breite, Ärmellänge usw. zur Verfügung. Sie wählen einfach zwischen Klein, Mittel und Groß, und der T-Shirt-Designer hat die Maße auf Grundlage der jeweiligen Größe vordefiniert.
Wie werden Ihre Ressourcen benannt?
In Bicep ist es wichtig, den Ressourcen aussagekräftige Namen zu geben. In Bicep werden für Ressourcen zwei Arten von Namen verwendet:
Symbolische Namen werden nur innerhalb der Bicep-Datei verwendet und nicht in Azure-Ressourcen angezeigt. Symbolische Namen helfen Benutzern, die Ihre Vorlage lesen oder ändern, den Zweck einer Parameter-, Variablen- oder Ressourcendefinition zu verstehen und fundierte Entscheidungen darüber zu treffen, ob die Vorlage geändert werden sollte.
Ressourcennamen sind die Namen der Ressourcen, die in Azure erstellt werden. Für viele Ressourcen gelten Einschränkungen bezüglich ihrer Namen, und viele erfordern eindeutige Namen.
Symbolische Namen
Es ist wichtig, sich die symbolischen Namen gut zu überlegen, die Sie auf Ihre Ressourcen anwenden. Angenommen, Kollegen müssen die Vorlage ändern. Werden sie den Zweck jeder Ressource begreifen?
Angenommen, Sie möchten ein Speicherkonto definieren, das Produkthandbücher enthält, die Benutzer von Ihrer Website herunterladen können. Sie könnten der Ressource einen symbolischen Namen geben, z. B. storageAccount. Dieser Name ist jedoch nicht aussagekräftig genug, wenn sich die Ressource in einer Bicep-Datei befindet, die viele weitere Ressourcen und vielleicht sogar weitere Speicherkonten enthält. Sie könnten ihr stattdessen einen symbolischen Namen geben, der Informationen über ihren Zweck enthält, z. B. productManualStorageAccount.
In Bicep verwenden Sie normalerweise die camelCase-Schreibweise für die symbolischen Namen von Parametern, Variablen und Ressourcen. Dies bedeutet, dass das erste Wort mit einem Kleinbuchstaben beginnt und alle folgenden Wörter mit einem Großbuchstaben beginnen (wie bei productManualStorageAccount im vorherigen Beispiel). Die Verwendung der camelCase-Schreibweise ist nicht zwingend vorgeschrieben. Wenn Sie sich für ein anderes Format entscheiden, ist es wichtig, sich in Ihrem Team auf einen Standard zu einigen und diesen konsistent zu verwenden.
Ressourcennamen
Jede Azure-Ressource weist einen Namen auf. Namen sind Teil des Bezeichners der Ressource. Häufig werden sie auch als die Hostnamen dargestellt, die Sie für den Zugriff auf die Ressource verwenden. Wenn Sie z. B. eine App Service-App mit dem Namen myapp erstellen, lautet der Hostname, den Sie für den Zugriff auf die App verwenden, myapp.azurewebsites.net. Sie können Ressourcen nach der Bereitstellung nicht umbenennen.
Überlegen Sie sich gut, wie Sie Ihre Azure-Ressourcen benennen. Viele Organisationen definieren eine eigene Namenskonvention für Ressourcen. Das Cloud Adoption Framework für Azure bietet spezielle Anleitungen, die Sie beim Definieren Ihrer Namenskonvention unterstützen. Eine Namenskonvention für Ressourcen soll allen Benutzern in Ihrem Unternehmen das Verständnis des Zwecks der einzelnen Ressourcen erleichtern.
Darüber hinaus gelten für jede Azure-Ressource bestimmte Benennungsregeln und -einschränkungen. Beispielsweise gibt es Einschränkungen hinsichtlich der Länge von Namen, der Zeichen, die sie enthalten dürfen, und der Anforderung, ob Namen global eindeutig oder nur innerhalb einer Ressourcengruppe eindeutig sein müssen.
Es kann kompliziert sein, alle Namenskonventionen für Ihre Organisation sowie die Benennungsanforderungen für Azure zu erfüllen. Eine gut geschriebene Bicep-Vorlage sollte diese Komplexität vor den Benutzern verbergen und die Namen für Ressourcen automatisch bestimmen. Dies ist ein Beispiel für einen sinnvollen Ansatz:
Fügen Sie einen Parameter hinzu, der zum Erstellen eines Eindeutigkeitssuffixes verwendet wird. Dadurch wird sichergestellt, dass Ihre Ressourcen eindeutige Namen haben. Es empfiehlt sich, mit der
uniqueString()-Funktion einen Standardwert zu generieren. Personen, die Ihre Vorlage bereitstellen, können diesen mit einem speziellen Wert überschreiben, wenn sie einen aussagekräftigen Namen verwenden möchten. Beschränken Sie mit dem Decorator@maxLength()die Länge des Suffixes, damit die Ressourcennamen nicht ihre maximale Länge überschreiten.Tipp
Die Verwendung von Eindeutigkeitssuffixen ist der Verwendung von Präfixen vorzuziehen. Dieser Ansatz erleichtert das Sortieren und schnelle Überprüfen Ihrer Ressourcennamen. Darüber hinaus gelten für einige Azure-Ressourcen Einschränkungen hinsichtlich des ersten Zeichens des Namens, und zufällig generierte Namen können manchmal gegen diese Einschränkungen verstoßen.
Verwenden Sie Variablen, um Ressourcennamen dynamisch zu erstellen. Im Bicep-Code können Sie sicherstellen, dass die von ihm generierten Namen der Namenskonvention Ihrer Organisation sowie den Azure-Anforderungen entsprechen. Schließen Sie das Eindeutigkeitssuffix als Teil des Ressourcennamens ein.
Hinweis
Nicht jede Ressource erfordert einen global eindeutigen Namen. Überlegen Sie, ob Sie das Eindeutigkeitssuffix in den Namen jeder Ressource oder nur in solche einschließen, die es erfordern.