Najlepsze rozwiązania dotyczące Bicep

  • Artykuł

W tym artykule zaleca się stosowanie praktyk podczas tworzenia plików Bicep. Te praktyki ułatwiają zrozumienie i użycie pliku Bicep.

Zasoby szkoleniowe

Jeśli wolisz dowiedzieć się więcej o najlepszych rozwiązaniach Bicep za pomocą wskazówek krok po kroku, zobacz Struktura kodu Bicep na potrzeby współpracy.

Parametry

  • Użyj dobrego nazewnictwa dla deklaracji parametrów. Dobre nazwy ułatwiają odczytywanie i zrozumienie szablonów. Upewnij się, że używasz wyraźnych, opisowych nazw i zachowaj spójność nazewnictwa.

  • Dokładnie zastanów się nad parametrami używanymi przez szablon. Spróbuj użyć parametrów dla ustawień, które zmieniają się między wdrożeniami. Zmienne i wartości zakodowane na kodzie mogą służyć do ustawień, które nie zmieniają się między wdrożeniami.

  • Należy pamiętać o używanych wartościach domyślnych. Upewnij się, że wartości domyślne są bezpieczne dla każdego, kto ma zostać wdrożony. Rozważ na przykład użycie warstw cenowych o niskich kosztach i jednostek SKU, aby ktoś wdrażający szablon w środowisku testowym nie ponosił zbyt dużych kosztów.

  • Używaj dekoratora @allowed oszczędnie. Jeśli używasz tego dekoratora zbyt szeroko, możesz zablokować prawidłowe wdrożenia. Ponieważ usługi platformy Azure dodają jednostki SKU i rozmiary, lista dozwolonych może nie być aktualna. Na przykład zezwolenie tylko na jednostki SKU Premium w wersji 3 może mieć sens w środowisku produkcyjnym, ale uniemożliwia korzystanie z tego samego szablonu w środowiskach nieprodukcyjnych.

  • Dobrym rozwiązaniem jest podanie opisów parametrów. Spróbuj ułatwić opisy i podaj ważne informacje o tym, co szablon potrzebuje wartości parametrów.

    Możesz również użyć // komentarzy do dodawania notatek w plikach Bicep.

  • Deklaracje parametrów można umieścić w dowolnym miejscu w pliku szablonu, chociaż zwykle dobrym pomysłem jest umieszczenie ich w górnej części pliku, aby kod Bicep był łatwy do odczytania.

  • Dobrym rozwiązaniem jest określenie minimalnej i maksymalnej długości znaków dla parametrów, które kontrolują nazewnictwo. Te ograniczenia pomagają uniknąć błędów później podczas wdrażania.

Aby uzyskać więcej informacji na temat parametrów Bicep, zobacz Parametry w pliku Bicep.

Zmienne

  • Podczas definiowania zmiennej typ danych nie jest potrzebny. Zmienne wywnioskuje typ z wartości rozpoznawania.

  • Do utworzenia zmiennej można użyć funkcji Bicep.

  • Po zdefiniowaniu zmiennej w pliku Bicep należy odwoływać się do wartości przy użyciu nazwy zmiennej.

Aby uzyskać więcej informacji na temat zmiennych Bicep, zobacz Zmienne w Bicep.

Nazwy

  • Użyj małych liter camel dla nazw, takich jak myVariableName lub myResource.

  • Funkcja uniqueString() jest przydatna do tworzenia unikatowych nazw zasobów. Po podaniu tych samych parametrów funkcja zwraca ten sam ciąg za każdym razem. Przekazanie identyfikatora grupy zasobów oznacza, że ciąg jest taki sam w każdym wdrożeniu w tej samej grupie zasobów, ale różni się w przypadku wdrażania w różnych grupach zasobów lub subskrypcjach.

  • Dobrym rozwiązaniem jest użycie wyrażeń szablonu do tworzenia nazw zasobów, takich jak w tym przykładzie:

    param shortAppName string = 'toy'
param shortEnvironmentName string = 'prod'
param appServiceAppName string = '${shortAppName}-${shortEnvironmentName}-${uniqueString(resourceGroup().id)}'

    Używanie wyrażeń szablonu do tworzenia nazw zasobów daje kilka korzyści:

    • Ciągi generowane przez uniqueString() program nie mają znaczenia. Warto użyć wyrażenia szablonu, aby utworzyć nazwę zawierającą istotne informacje, takie jak krótki deskryptor nazwy projektu lub środowiska, a także losowy składnik, aby nazwa była bardziej unikatowa.

    • Funkcja uniqueString() nie gwarantuje globalnie unikatowych nazw. Dodając dodatkowy tekst do nazw zasobów, można zmniejszyć prawdopodobieństwo ponownego użycia istniejącej nazwy zasobu.

    • uniqueString() Czasami funkcja tworzy ciągi rozpoczynające się od liczby. Niektóre zasoby platformy Azure, takie jak konta magazynu, nie zezwalają na rozpoczynanie nazw od liczb. To wymaganie oznacza, że dobrym pomysłem jest użycie interpolacji ciągów do tworzenia nazw zasobów. Możesz dodać prefiks do unikatowego ciągu.

    • Wiele typów zasobów platformy Azure ma reguły dotyczące dozwolonych znaków i długości ich nazw. Osadzanie tworzenia nazw zasobów w szablonie oznacza, że każdy, kto używa szablonu, nie musi pamiętać, aby samodzielnie przestrzegać tych reguł.

  • Unikaj używania name w nazwie symbolicznej. Nazwa symboliczna reprezentuje zasób, a nie nazwę zasobu. Na przykład zamiast następującej składni:

    resource cosmosDBAccountName 'Microsoft.DocumentDB/databaseAccounts@2023-04-15' = {

    Używać:

    resource cosmosDBAccount 'Microsoft.DocumentDB/databaseAccounts@2023-04-15' = {

  • Unikaj rozróżniania zmiennych i parametrów przy użyciu sufiksów.

Definicje zasobów

  • Zamiast osadzać wyrażenia złożone bezpośrednio we właściwościach zasobu, użyj zmiennych do przechowywania wyrażeń. Takie podejście ułatwia odczytywanie i zrozumienie pliku Bicep. Zapobiega to zaśmiecaniu definicji zasobów logiką.

  • Spróbuj użyć właściwości zasobu jako danych wyjściowych, a nie założeń dotyczących zachowania zasobów. Jeśli na przykład musisz użyć adresu URL do aplikacji App Service, użyj właściwości defaultHostname aplikacji zamiast samodzielnie utworzyć ciąg dla adresu URL. Czasami te założenia nie są poprawne w różnych środowiskach lub zasoby zmieniają sposób ich działania. Bezpieczniej jest mieć zasób informujący o własnych właściwościach.

  • Warto użyć najnowszej wersji interfejsu API dla każdego zasobu. Nowe funkcje w usługach platformy Azure są czasami dostępne tylko w nowszych wersjach interfejsu API.

  • Jeśli to możliwe, unikaj używania funkcji reference i resourceId w pliku Bicep. Dostęp do dowolnego zasobu w aplikacji Bicep można uzyskać przy użyciu nazwy symbolicznej. Jeśli na przykład zdefiniujesz konto magazynu o nazwie symbolicznej toyDesignDocumentsStorageAccount, możesz uzyskać dostęp do jego identyfikatora zasobu przy użyciu wyrażenia toyDesignDocumentsStorageAccount.id. Używając nazwy symbolicznej, należy utworzyć niejawną zależność między zasobami.

  • Preferuj używanie niejawnych zależności w zależnościach jawnych. dependsOn Chociaż właściwość zasobu umożliwia deklarowanie jawnej zależności między zasobami, zwykle można użyć właściwości innego zasobu przy użyciu jego symbolicznej nazwy. Takie podejście tworzy niejawną zależność między tymi dwoma zasobami i umożliwia Bicep zarządzanie samą relacją.

  • Jeśli zasób nie został wdrożony w pliku Bicep, nadal możesz uzyskać symboliczne odwołanie do zasobu przy użyciu słowa kluczowego existing .

Zasoby podrzędne

  • Unikaj zagnieżdżania zbyt wielu warstw głęboko. Zbyt wiele zagnieżdżania sprawia, że kod Bicep jest trudniej odczytać i pracować z nim.

  • Unikaj konstruowania nazw zasobów dla zasobów podrzędnych. Utracisz korzyści, które zapewnia Bicep, gdy rozumie relacje między zasobami. parent Zamiast tego użyj właściwości lub zagnieżdżania.

Dane wyjściowe

  • Upewnij się, że dane wyjściowe nie są tworzone dla poufnych danych. Dostęp do wartości wyjściowych można uzyskać od każdej osoby, która ma dostęp do historii wdrożenia. Nie są one odpowiednie do obsługi wpisów tajnych.

  • Zamiast przekazywać wartości właściwości wokół danych wyjściowych, użyj istniejącego słowa kluczowego , aby wyszukać właściwości zasobów, które już istnieją. Najlepszym rozwiązaniem jest wyszukiwanie kluczy z innych zasobów w ten sposób zamiast przekazywania ich przez dane wyjściowe. Zawsze będziesz otrzymywać najbardziej aktualne dane.

Aby uzyskać więcej informacji na temat danych wyjściowych Bicep, zobacz Outputs in Bicep (Dane wyjściowe w aplikacji Bicep).

Zakresy dzierżawy

Nie można tworzyć zasad ani przypisań ról w zakresie dzierżawy. Jeśli jednak musisz udzielić dostępu lub zastosować zasady w całej organizacji, możesz wdrożyć te zasoby w głównej grupie zarządzania.

Następne kroki