Migrowanie zasobów platformy Azure i szablonów ARM w formacie JSON, aby korzystać z Bicep.

Istnieje wiele korzyści związanych z definiowaniem zasobów platformy Azure w środowisku Bicep, w tym bardziej prostą składnią, modułyzacją, automatycznym zarządzaniem zależnościami, walidacją typu IntelliSense i ulepszonym środowiskiem tworzenia.

Podczas migrowania istniejących szablonów JSON Azure Resource Manager (ARM) do Bicep, zalecamy stosowanie pięciofazowego przepływu pracy:

Pierwszym krokiem procesu jest przechwycenie początkowej reprezentacji zasobów platformy Azure. W razie potrzeby możesz zdekompilować plik JSON do początkowego pliku Bicep, który następnie ulepszysz przez refaktoryzację. Gdy masz działający plik, testujesz i wdrażasz przy użyciu procesu, który minimalizuje ryzyko wystąpienia zmian zaburzających działanie w Twoim środowisku Azure.

W tym artykule podsumujemy ten zalecany przepływ pracy. Aby uzyskać więcej wskazówek, zobacz moduł Migrate Azure resources and JSON ARM templates to use Bicep Learn (Migrowanie zasobów platformy Azure i szablonów usługi ARM JSON do korzystania z usługi Bicep Learn).

Faza 1. Konwertowanie

W fazie konwersji migrowania zasobów za pomocą narzędzia Bicep celem jest uzyskanie wstępnej reprezentacji zasobów platformy Azure. Plik Bicep utworzony w tej fazie nie jest kompletny i nie jest gotowy do użycia. Jednak plik daje punkt wyjścia do migracji.

Faza konwersji składa się z dwóch kroków, które należy wykonać w sekwencji:

1. Przechwyć reprezentację zasobów platformy Azure. Jeśli masz istniejący szablon JSON, który konwertujesz na Bicep, pierwszy krok jest łatwy — masz już szablon źródłowy. Jeśli konwertujesz zasoby platformy Azure, które zostały wdrożone przy użyciu portalu lub innego narzędzia, musisz przechwycić definicje zasobów. Reprezentację zasobów w formacie JSON można przechwycić przy użyciu witryny Azure Portal, interfejsu wiersza polecenia platformy Azure lub poleceń cmdlet programu Azure PowerShell w celu wyeksportowania pojedynczych zasobów, wielu zasobów i całych grup zasobów. Możesz użyć polecenia Insert Resource w programie Visual Studio Code, aby zaimportować reprezentację zasobu platformy Azure w formacie Bicep.

2. W razie potrzeby przekonwertuj reprezentację JSON na Bicep przy użyciu polecenia dekompilacji.Narzędzie Bicep zawiera decompile polecenie do konwertowania szablonów. Możesz wywołać polecenie decompile z Visual Studio Code z rozszerzeniem Bicep, Azure CLI lub z Bicep CLI. Proces dekompilacji jest procesem opartym na najlepszych staraniach i nie gwarantuje pełnego mapowania z formatu JSON na Bicep. Może być konieczne skorygowanie wygenerowanego pliku Bicep, aby spełnić najlepsze praktyki dotyczące szablonu, zanim użyjesz pliku do wdrożenia zasobów.

Uwaga

Zasób można zaimportować, otwierając paletę poleceń programu Visual Studio Code. Naciśnij Ctrl+Shift+P w systemach Windows i Linux i ⌘+Shift+P w systemie macOS.

Program Visual Studio Code umożliwia wklejanie kodu JSON jako Bicep. Aby uzyskać więcej informacji, zobacz Wklej JSON jako polecenie Bicep.

Faza 2. Migrowanie

W fazie migracji zasobów do Bicep celem jest utworzenie pierwszej wersji roboczej wdrażalnego pliku Bicep i upewnienie się, że definiuje wszystkie zasoby platformy Azure, które są objęte migracją.

Faza migracji składa się z trzech kroków, które należy wykonać w sekwencji:

1. Utwórz nowy pusty plik Bicep. Dobrą praktyką jest utworzenie zupełnie nowego pliku Bicep. Plik, który utworzono w fazie konwersji, służy jako punkt odniesienia do zapoznania się, ale nie powinien być traktowany jako ostateczny ani wdrażany w niezmienionej formie.

2. Skopiuj każdy zasób z dekompilowanego szablonu. Skopiuj każdy zasób indywidualnie z przekonwertowanego pliku Bicep do nowego pliku Bicep. Ten proces pomaga rozwiązać wszelkie problemy dla poszczególnych zasobów i uniknąć nieporozumień w miarę wzrostu rozmiaru szablonu.

3. Zidentyfikuj i utwórz ponownie brakujące zasoby. Nie wszystkie typy zasobów platformy Azure można eksportować za pośrednictwem witryny Azure Portal, interfejsu wiersza polecenia platformy Azure lub programu Azure PowerShell. Na przykład rozszerzenia maszyny wirtualnej, takie jak DependencyAgentWindows i MMAExtension (Microsoft Monitoring Agent) nie są obsługiwanymi typami zasobów do eksportu. W przypadku wszystkich zasobów, które nie zostały wyeksportowane, takich jak rozszerzenia maszyny wirtualnej, należy ponownie utworzyć te zasoby w nowym pliku Bicep. Zasoby można odtworzyć przy użyciu różnych narzędzi i podejść, w tym Azure Resource Explorer, dokumentacji referencyjnej Bicep i ARM template, oraz witryny Azure Quickstart Templates.

Faza 3. Refaktoryzacja

W fazie refaktoryzacji migrowania zasobu do aplikacji Bicep celem jest zwiększenie jakości kodu Bicep. Te ulepszenia mogą obejmować zmiany, takie jak dodawanie komentarzy do kodu, które dostosowują szablon do standardów szablonu.

Faza wdrażania składa się z ośmiu kroków, które należy wykonać w dowolnej kolejności:

1. Przejrzyj wersje interfejsu API zasobów. Podczas eksportowania zasobów platformy Azure wyeksportowany szablon może nie zawierać najnowszej wersji interfejsu API dla typu zasobu. Jeśli istnieją określone właściwości potrzebne do przyszłych wdrożeń, zaktualizuj interfejs API do odpowiedniej wersji. Dobrym rozwiązaniem jest przejrzenie wersji interfejsu API dla każdego wyeksportowanego zasobu.

2. Przejrzyj sugestie linter w nowym pliku Bicep. Gdy używasz rozszerzenia Bicep dla programu Visual Studio Code do tworzenia plików Bicep, Bicep linter uruchamia się automatycznie i wyróżnia sugestie oraz błędy w kodzie. Wiele sugestii i błędów obejmuje opcję zastosowania szybkiego rozwiązania problemu. Przejrzyj te zalecenia i dostosuj plik Bicep.

3. Popraw parametry, zmienne i nazwy symboliczne. Możliwe, że nazwy parametrów, zmiennych i nazw symbolicznych generowanych przez dekompiler nie są zgodne ze standardową konwencją nazewnictwa. Przejrzyj wygenerowane nazwy i w razie potrzeby wprowadź korekty.

4. Upraszczanie wyrażeń. Proces dekompilowania może nie zawsze korzystać z niektórych funkcji Bicep. Przejrzyj wszystkie wyrażenia wygenerowane w konwersji i uprość je. Na przykład, dekompilowany szablon może zawierać funkcję concat() lub format(), które można uprościć, używając interpolacji ciągów znaków. Przejrzyj wszelkie sugestie z narzędzia „linter” i w razie potrzeby wprowadź korekty.

5. Przejrzyj zasoby podrzędne i rozszerzenia. Istnieje kilka sposobów deklarowania zasobów podrzędnych i zasobów rozszerzeń w aplikacji Bicep, w tym łączenie nazw twoich zasobów, używanie słowa kluczowego parent, i użycie zagnieżdżonych zasobów. Rozważ przejrzenie tych zasobów po dekompilacji i upewnienie się, że struktura spełnia Twoje standardy. Na przykład, upewnij się, że nie używasz łączenia ciągów do tworzenia nazw zasobów podrzędnych — należy użyć parent jako właściwości lub zasobu zagnieżdżonego. Podobnie podsieci mogą być przywołyane jako właściwości sieci wirtualnej lub jako oddzielny zasób.

6. Modularyzowanie. Jeśli konwertujesz szablon zawierający wiele zasobów, rozważ podzielenie poszczególnych typów zasobów na moduły dla uproszczenia. Moduły Bicep pomagają zmniejszyć złożoność wdrożeń i zwiększyć możliwość ponownego zastosowania kodu Bicep.

   Uwaga

   Możliwe jest użycie szablonów JSON jako modułów we wdrożeniach Bicep. Bicep ma możliwość rozpoznawania modułów JSON i odwoływać się do nich podobnie do sposobu używania modułów Bicep.

7. Dodaj komentarze i opisy. Dobry kod Bicep jest samoopisujący się. Bicep umożliwia dodawanie komentarzy i @description() atrybutów do kodu, które ułatwiają dokumentowanie infrastruktury. Bicep obsługuje zarówno komentarze jednowierszowe przy użyciu sekwencji znaków //, jak i komentarze wielowierszowe, które zaczynają się od /* i kończą się */. Komentarze można dodawać do określonych wierszy w kodzie i w sekcjach kodu.

8. Postępuj zgodnie z najlepszymi praktykami dotyczącymi Bicep. Upewnij się, że plik Bicep przestrzega standardowych zaleceń. Zapoznaj się z dokumentem referencyjnym Bicep best practices (Najlepsze rozwiązania dotyczące Bicep), aby poznać wszystkie elementy, które mogły zostać pominięte.

Faza 4. Testowanie

W fazie testowania migrowania zasobów do aplikacji Bicep celem jest zweryfikowanie integralności zmigrowanych szablonów i przeprowadzenie wdrożenia testowego.

Faza testowania składa się z dwóch kroków, które należy wykonać w sekwencji:

1. Uruchom operację warunkową wdrożenia szablonu usługi ARM. Aby ułatwić zweryfikowanie przekonwertowanych szablonów przed wdrożeniem, możesz użyć operacji analizy warunkowej wdrożenia szablonu usługi Azure Resource Manager. Porównuje bieżący stan środowiska z żądanym stanem zdefiniowanym w szablonie. Narzędzie generuje listę zmian, które zostaną wprowadzone bez stosowania zmian w środowisku. Możesz użyć analizy co-jeżeli zarówno w przypadku wdrożeń z trybem przyrostowym, jak i trybem pełnym. Nawet jeśli planujesz wdrożenie szablonu przy użyciu trybu przyrostowego, dobrym pomysłem jest uruchomienie operacji analizy co-jeżeli w trybie pełnym.

2. Przeprowadź wdrożenie testowe. Przed wprowadzeniem przekonwertowanego pliku Bicep do środowiska produkcyjnego rozważ uruchomienie wielu wdrożeń testowych. Jeśli masz wiele środowisk (na przykład programowanie, testowanie i środowisko produkcyjne), możesz najpierw spróbować wdrożyć szablon w jednym ze środowisk nieprodukcyjnych. Po wdrożeniu porównaj oryginalne zasoby z nowymi wdrożeniami zasobów pod kątem spójności.

Faza 5. Wdrażanie

W fazie wdrażania migracji zasobów do aplikacji Bicep celem jest wdrożenie końcowego pliku Bicep w środowisku produkcyjnym.

Faza wdrażania składa się z czterech kroków, które należy wykonać w sekwencji:

1. Przygotuj plan wycofania. Zdolność do odzyskiwania po nieudanym wdrożeniu jest kluczowa. Utwórz strategię cofania zmian, jeśli jakiekolwiek zmiany krytyczne zostaną wprowadzone w środowiskach. Utwórz spis typów wdrożonych zasobów, takich jak maszyny wirtualne, aplikacje internetowe i bazy danych. Należy również rozważyć płaszczyznę danych każdego zasobu. Czy masz sposób na odzyskanie maszyny wirtualnej i jej danych? Czy masz sposób na odzyskanie bazy danych po usunięciu? Dobrze opracowany plan wycofania pomaga zachować czas przestoju na możliwie najniższym poziomie w przypadku jakichkolwiek problemów z wdrożeniem.

2. Uruchom operację analizy warunkowej względem środowiska produkcyjnego. Przed wdrożeniem końcowego pliku Bicep w środowisku produkcyjnym uruchom operację analizy co-jeżeli w środowisku produkcyjnym, upewnij się, że używasz wartości parametrów produkcyjnych i rozważ udokumentowanie wyników.

3. Wdróż ręcznie. Jeśli zamierzasz użyć przekonwertowanego szablonu w potoku, takiego jak Azure DevOps lub GitHub Actions, najpierw rozważ uruchomienie wdrożenia z komputera lokalnego. Wskazane jest przetestowanie funkcjonalności szablonu przed jego dołączeniem do potoku produkcyjnego. Dzięki temu możesz szybko reagować, jeśli wystąpi problem.

4. Uruchom testy dymne. Po zakończeniu wdrażania należy uruchomić serię testów dymnych, aby upewnić się, że aplikacja lub obciążenie działa prawidłowo. Na przykład przetestuj, czy aplikacja internetowa jest dostępna za pośrednictwem normalnych kanałów dostępu, takich jak publiczny Internet lub za pośrednictwem firmowej sieci VPN. W przypadku baz danych spróbuj nawiązać połączenie z bazą danych i wykonać serię zapytań. W przypadku maszyn wirtualnych zaloguj się do maszyny wirtualnej i upewnij się, że wszystkie usługi są uruchomione.

Następne kroki

Aby dowiedzieć się więcej na temat dekompilera Bicep, zobacz Dekompilowanie szablonu ARM JSON do Bicep.