Udostępnij przez

Najlepsze rozwiązania dotyczące Bicep

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

Parametry

  • Użyj dobrego nazewnictwa dla deklaracji parametrów. Dobre nazwy ułatwiają odczytywanie i zrozumienie szablonów. Upewnij się, że używasz przejrzystych, 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 trwale zakodowane wartości 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 do wdrożenia przez każdego. Rozważ na przykład użycie warstw cenowych i jednostek SKU o niskich kosztach, aby ktoś wdrażający szablon w środowisku testowym niepotrzebnie nie ponosił dużych kosztów.

  • Używaj dekoratora @allowed oszczędnie. Jeśli nadmiernie używasz tego dekoratora, możesz zablokować prawidłowe wdrożenia. W miarę dodawania SKU i rozmiarów usług Azure, Twoja 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 wszelkie ważne informacje o tym, co szablon potrzebuje wartości parametrów.

    Możesz również użyć // komentarzy, aby dodać notatki 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, dzięki czemu kod Bicep jest ł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, zapoznaj się z Parametry w Bicep.

Zmienne

  • Podczas definiowania zmiennej typ danych nie jest wymagany. Zmienne wywnioskują typ z wyliczonej wartości.

  • Aby utworzyć zmienną, możesz użyć funkcji Bicep.

  • Po zdefiniowaniu zmiennej w pliku Bicep należy odwołać 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 notacji camelCase dla nazw, takich jak myVariableName lub myResource.

  • Funkcja uniqueString() jest przydatna do tworzenia unikatowych nazw zasobów. Po podaniu tych samych parametrów zwraca on 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 do tej samej grupy 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() nie mają znaczenia. Warto użyć wyrażenia szablonu, aby utworzyć nazwę zawierającą istotne informacje, takie jak krótki opis projektu lub nazwy środowiska, a także losowy składnik, aby zwiększyć unikalność nazwy.

    • 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.

    • Czasami uniqueString() funkcja tworzy ciągi rozpoczynające się od liczby. Niektóre zasoby platformy Azure, takie jak konta magazynu, nie zezwalają na rozpoczynanie ich 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żda osoba korzystająca z 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-11-15' = {

    Użyj:

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

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

Definicje zasobów

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

  • Spróbuj użyć właściwości zasobu jako danych wyjściowych, zamiast zakładać, jak będą zachowywać się zasoby. Na przykład, jeśli musisz wygenerować adres URL dla aplikacji w usłudze App Service, skorzystaj z właściwości defaultHostname aplikacji zamiast samodzielnie tworzyć 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, gdy zasób przekazuje własne właściwości.

  • Dobrym pomysłem jest użycie 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 przechowywania 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 zależności niejawnych w zależnościach jawnych. dependsOn Mimo że właściwość zasobu umożliwia zadeklarowanie jawnej zależności między zasobami, zazwyczaj można użyć właściwości innego zasobu przy użyciu jej symbolicznej nazwy. To podejście tworzy niejawną zależność między tymi dwoma zasobami i umożliwia Bicepowi 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żeń sprawia, że kod Bicep jest trudniejszy do odczytania i obsługi.

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

Wyniki

  • Oznaczanie poufnych danych w danych wyjściowych przy użyciu dekoratora @secure(), który uniemożliwia zarejestrowanie lub wyświetlenie poufnych danych wyjściowych. W przeciwnym razie można uzyskać dostęp do wartości wyjściowych przez wszystkich użytkowników, którzy mają dostęp do historii wdrożenia.

  • Zamiast przekazywać wartości właściwości za pośrednictwem danych wyjściowych, użyj istniejącego słowa kluczowego , aby wyszukać właściwości zasobów, które już istnieją. Najlepiej praktykować wyszukiwanie kluczy w innych zasobach w ten sposób, zamiast przekazywania ich za pomocą danych wyjściowych. Zawsze będziesz otrzymywać najbardziej up-to-date data.

Aby uzyskać więcej informacji na temat danych wyjściowych Bicep, zobacz Dane wyjściowe w 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.

Dalsze kroki

  • Last updated on