Ulepszanie parametrów i nazw
Parametry są najbardziej typowym sposobem interakcji współpracowników z szablonem. Podczas wdrażania szablonu należy określić wartości parametrów. Po jego utworzeniu nazwa zasobu zawiera ważne informacje o jego celach dla każdego, kto patrzy na środowisko platformy Azure.
W tej lekcji dowiesz się więcej na temat niektórych kluczowych zagadnień podczas planowania parametrów dla plików Bicep i nazw nadanych zasobom.
Jak zrozumiałe są parametry?
Parametry ułatwiają wielokrotne i elastyczne użycie plików Bicep. Ważne jest, aby cel każdego parametru był jasny dla każdego, kto go używa. Gdy współpracownicy pracują z szablonem, używają parametrów w celu dostosowania zachowania ich wdrożenia.
Załóżmy na przykład, że musisz wdrożyć konto magazynu przy użyciu pliku Bicep. Jedną z wymaganych właściwości konta magazynu jest jednostka magazynowa (SKU), która definiuje poziom nadmiarowości danych. Jednostka SKU ma kilka właściwości, a najważniejszą wartością jest name. Podczas tworzenia parametru w celu ustawienia wartości jednostki SKU konta magazynu użyj jasno zdefiniowanej nazwy, takiej jak storageAccountSkuName. Użycie tej wartości zamiast nazwy ogólnej, takiej jak sku lub skuName , pomoże innym zrozumieć przeznaczenie parametru i efekty ustawiania jego wartości.
Wartości domyślne to ważny sposób, aby szablon był używany przez inne osoby. Ważne jest, aby używać wartości domyślnych, w których mają sens. Ułatwiają one użytkownikom szablonu na dwa sposoby:
- Wartości domyślne upraszczają proces wdrażania szablonu. Jeśli parametry mają dobre wartości domyślne, które działają dla większości użytkowników szablonu, użytkownicy mogą pominąć wartości parametrów zamiast określać je za każdym razem, gdy wdrażają szablon.
- Wartości domyślne stanowią przykład sposobu, w jaki oczekiwano, aby wartość parametru wyglądała. Jeśli użytkownicy szablonu muszą wybrać inną wartość, wartość domyślna może dostarczyć przydatnych wskazówek dotyczących tego, jak powinna wyglądać ich wartość.
Bicep może również pomóc w zweryfikowaniu danych wejściowych, które użytkownicy udostępniają za pośrednictwem dekoratorów parametrów. Można użyć tych dekoratorów, aby podać opis parametru lub określić, jakie rodzaje wartości są dozwolone. Bicep udostępnia kilka typów dekoratorów parametrów:
Opisy zawierają czytelne dla człowieka informacje o celu parametru i wpływ ustawiania jego wartości.
Ograniczenia wartości wymuszają limity dotyczące tego, co użytkownicy mogą wprowadzać dla wartości parametru. Listę określonych, dozwolonych wartości można określić przy użyciu dekoratora
@allowed(). Można użyć@minValue()dekoratorów i@maxValue(), aby wymusić minimalne i maksymalne wartości parametrów liczbowych, a także użyć@minLength()dekoratorów i@maxLength()wymusić długość parametrów ciągu i tablicy.Napiwek
Należy zachować ostrożność podczas używania dekoratora parametrów do określania
@allowed()jednostek SKU. Usługi platformy Azure często dodają nowe jednostki SKU i nie chcesz, aby szablon niepotrzebnie uniemożliwiał ich użycie. Rozważ użycie usługi Azure Policy, aby wymusić użycie określonych jednostek SKU i użyć@allowed()dekoratora z jednostkami SKU tylko wtedy, gdy istnieją powody funkcjonalne, dla których użytkownicy szablonu nie powinni wybierać określonej jednostki SKU. Na przykład funkcje, których potrzebuje szablon, mogą nie być dostępne w tej jednostce SKU. Wyjaśnij to za pomocą dekoratora@description()lub komentarza, który sprawia, że powody są jasne dla każdego w przyszłości.Metadane, chociaż nie są często używane, można zastosować w celu zapewnienia dodatkowych niestandardowych metadanych dotyczących parametru.
Jak elastyczny powinien być plik Bicep?
Jednym z celów definiowania infrastruktury jako kodu jest uczynienie szablonów elastycznymi i wielokrotnego użytku. Nie chcesz tworzyć szablonów jednofunkcyjnych, które mają ustaloną konfigurację. Z drugiej strony nie ma sensu uwidaczniać wszystkich właściwości zasobów jako parametrów. Utwórz szablony, które działają dla konkretnego problemu biznesowego lub rozwiązania, a nie ogólne szablony, które muszą działać w każdej sytuacji. Nie chcesz również mieć tak wielu parametrów, że wprowadzanie wartości przed wdrożeniem szablonu zajmuje dużo czasu. Jest to szczególnie ważne podczas konfigurowania jednostek SKU i liczby wystąpień zasobów.
Podczas planowania szablonu zastanów się, jak zrównoważysz elastyczność z prostotą. Istnieją dwa typowe sposoby udostępniania parametrów w szablonach:
- Udostępnianie opcji konfiguracji w formie bezpłatnej
- Korzystanie ze wstępnie zdefiniowanych zestawów konfiguracji
Rozważmy oba podejścia, korzystając z przykładowego pliku Bicep, który wdraża konto magazynu i plan usługi aplikacja systemu Azure.
Udostępnianie opcji konfiguracji w formie bezpłatnej
Zarówno plan usługi App Service, jak i konto magazynu wymagają określenia ich jednostek SKU. Możesz rozważyć utworzenie zestawu parametrów do kontrolowania poszczególnych jednostek SKU i liczby wystąpień dla zasobów:
Oto jak wygląda to w 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
}
}
Ten format zapewnia największą elastyczność, ponieważ każdy, kto używa szablonu, może określić dowolną kombinację wartości parametrów. Jednak w miarę dodawania większej liczby zasobów potrzebne są więcej parametrów. W rezultacie szablon staje się bardziej skomplikowany. Ponadto może być konieczne ograniczenie niektórych kombinacji parametrów lub upewnienie się, że po wdrożeniu określonego zasobu przy użyciu jednej jednostki SKU należy wdrożyć inny zasób przy użyciu innej jednostki SKU. Jeśli podasz zbyt wiele oddzielnych parametrów, trudno jest wymusić te reguły.
Napiwek
Pomyśl o osobach, które będą pracować z szablonem. Wyświetlanie kilkudziesięciu parametrów może ich przytłoczyć i spowodować ich porzucenie przy użyciu szablonu.
Możesz zmniejszyć liczbę parametrów, grupując powiązane parametry w postaci obiektu parametrów, w następujący sposób:
param appServicePlanSku object = {
name: 'S1'
capacity: 2
}
Jednak takie podejście może zmniejszyć możliwość weryfikowania wartości parametrów i nie zawsze jest łatwe dla użytkowników szablonu, aby zrozumieć, jak zdefiniować obiekt.
Korzystanie ze wstępnie zdefiniowanych zestawów konfiguracji
Alternatywnie można podać zestaw konfiguracji: pojedynczy parametr, którego wartość jest ograniczoną listą dozwolonych wartości, takich jak lista typów środowiska. Gdy użytkownicy wdrażają szablon, muszą wybrać wartość tylko dla tego jednego parametru. Po wybraniu wartości parametru wdrożenie automatycznie dziedziczy zestaw konfiguracji:
Definicja parametru wygląda następująco:
@allowed([
'Production'
'Test'
])
param environmentType string = 'Test'
Zestawy konfiguracji zapewniają niższą elastyczność, ponieważ osoby wdrażające szablon nie mogą określać rozmiarów poszczególnych zasobów, ale można zweryfikować każdy zestaw konfiguracji i upewnić się, że pasują do Twoich wymagań. Korzystanie z zestawów konfiguracji zmniejsza potrzebę zrozumienia przez użytkowników szablonu wszystkich dostępnych opcji dla każdego zasobu i ułatwia obsługę, testowanie i rozwiązywanie problemów z szablonami.
Podczas pracy z zestawami konfiguracji należy utworzyć zmienną mapy w celu zdefiniowania określonych właściwości do ustawiania na różnych zasobach na podstawie wartości parametru:
var environmentConfigurationMap = {
Production: {
appServicePlan: {
sku: {
name: 'P2V3'
capacity: 3
}
}
storageAccount: {
sku: {
name: 'ZRS'
}
}
}
Test: {
appServicePlan: {
sku: {
name: 'S2'
capacity: 1
}
}
storageAccount: {
sku: {
name: 'LRS'
}
}
}
}
Definicje zasobów służą następnie do definiowania właściwości zasobu za pomocą mapy konfiguracji:
resource appServicePlan 'Microsoft.Web/serverfarms@2020-06-01' = {
name: appServicePlanName
location: location
sku: environmentConfigurationMap[environmentType].appServicePlan.sku
}
Zestawy konfiguracji mogą ułatwić dostęp do złożonych szablonów. Mogą one również pomóc w wymuszaniu własnych reguł i zachęcaniu do używania wstępnie zweryfikowanych wartości konfiguracji.
Uwaga
Takie podejście jest czasami nazywane ustalaniem rozmiaru koszulki. Kiedy kupujesz t-shirt, nie masz wielu opcji długości, szerokości, rękawów i tak dalej. Wystarczy wybrać jedną z małych, średnich i dużych rozmiarów, a projektant t-shirtu wstępnie zdefiniował te pomiary na podstawie tego rozmiaru.
Jak nazwane są twoje zasoby?
W aplikacji Bicep ważne jest nadanie zasobom znaczących nazw. Zasoby w Bicep mają dwie nazwy:
Nazwy symboliczne są używane tylko w pliku Bicep i nie są wyświetlane w zasobach platformy Azure. Nazwy symboliczne ułatwiają użytkownikom odczytywanie lub modyfikowanie szablonu w celu zrozumienia celu parametru, zmiennej lub definicji zasobu, a także ułatwiają użytkownikom podejmowanie świadomych decyzji dotyczących tego, czy zmienić szablon.
Nazwy zasobów to nazwy zasobów tworzonych na platformie Azure. Wiele zasobów ma ograniczenia dotyczące ich nazw, a wiele z tych zasobów wymaga, aby ich nazwy stały się unikatowe.
Nazwy symboliczne
Ważne jest, aby myśleć o nazwach symbolicznych, które mają zastosowanie do zasobów. Załóżmy, że masz współpracowników, którzy muszą zmodyfikować szablon. Czy zrozumieją, na czym polega każdy zasób?
Załóżmy na przykład, że chcesz zdefiniować konto magazynu, które będzie zawierać podręczniki produktów dla użytkowników do pobrania z witryny internetowej. Zasób można nadać symboliczną nazwę (na przykład), storageAccountale jeśli znajduje się w pliku Bicep zawierającym wiele innych zasobów, a może nawet innych kont magazynu, ta nazwa nie jest wystarczająco opisowa. Zamiast tego można nadać jej symboliczną nazwę zawierającą pewne informacje o jego celu, takie jak productManualStorageAccount.
W Bicep zwykle używasz stylu wielkości liter camelCase dla nazw parametrów, zmiennych i nazw symbolicznych zasobów. Oznacza to, że używasz małej litery dla pierwszego wyrazu, a następnie wielką literą pierwszego słowa (jak w poprzednim przykładzie ). productManualStorageAccount Nie musisz używać camelCase. Jeśli zdecydujesz się używać innego stylu, ważne jest, aby uzgodnić jeden standard w zespole i konsekwentnie go używać.
Nazwy zasobów
Każdy zasób platformy Azure ma nazwę. Nazwy składają się na część identyfikatora zasobu. W wielu przypadkach są one również reprezentowane jako nazwy hostów używane do uzyskiwania dostępu do zasobu. Na przykład podczas tworzenia aplikacji usługi App Service o nazwie myappnazwa hosta używana do uzyskiwania dostępu do aplikacji będzie następująca myapp.azurewebsites.net: . Nie można zmienić nazwy zasobów po ich wdrożeniu.
Ważne jest, aby wziąć pod uwagę sposób nazywania zasobów platformy Azure. Wiele organizacji definiuje własną konwencję nazewnictwa zasobów. Przewodnik Cloud Adoption Framework dla platformy Azure zawiera konkretne wskazówki , które mogą pomóc w zdefiniowaniu Twoich. Celem konwencji nazewnictwa zasobów jest pomoc wszystkim w organizacji w zrozumieniu, do czego służy każdy zasób.
Ponadto każdy zasób platformy Azure ma pewne reguły i ograniczenia nazewnictwa. Istnieją na przykład ograniczenia dotyczące długości nazw, znaków, które mogą zawierać, oraz tego, czy nazwy muszą być globalnie unikatowe, czy tylko unikatowe w obrębie grupy zasobów.
Może być złożone, aby przestrzegać wszystkich konwencji nazewnictwa dla organizacji, a także wymagań dotyczących nazewnictwa dla platformy Azure. Dobrze napisany szablon Bicep powinien ukrywać tę złożoność przed użytkownikami i automatycznie określać nazwy zasobów. Oto jeden z przykładów podejścia do zastosowania:
Dodaj parametr używany do tworzenia sufiksu unikatowości. Pomaga to zapewnić, że zasoby mają unikatowe nazwy. Dobrym pomysłem jest użycie
uniqueString()funkcji do wygenerowania wartości domyślnej. Osoby, którzy wdrażają szablon, mogą zastąpić go określoną wartością, jeśli chcą mieć znaczącą nazwę. Pamiętaj, aby użyć dekoratora@maxLength(), aby ograniczyć długość tego sufiksu, aby nazwy zasobów nie przekraczały maksymalnej długości.Napiwek
Lepiej używać sufiksów unikatowości, a nie prefiksów. Takie podejście ułatwia sortowanie i szybkie skanowanie nazw zasobów. Ponadto niektóre zasoby platformy Azure mają ograniczenia dotyczące pierwszego znaku nazwy, a nazwy generowane losowo mogą czasami naruszać te ograniczenia.
Używanie zmiennych do dynamicznego konstruowania nazw zasobów. Twój kod Bicep może zapewnić, że nazwy, które generuje, są zgodne z konwencją nazewnictwa organizacji, a także wymaganiami platformy Azure. Dołącz sufiks unikatowości jako część nazwy zasobu.
Uwaga
Nie każdy zasób wymaga globalnie unikatowej nazwy. Zastanów się, czy należy uwzględnić sufiks unikatowości w nazwach każdego zasobu, czy tylko te, które go potrzebują.