Konwertowanie i migrowanie zasobów do pliku Bicep

10 min

Po rozpoczęciu procesu migracji do aplikacji Bicep ważne jest, aby postępować zgodnie z procesem ustrukturyzowanym, aby upewnić się, że plik Bicep poprawnie opisuje zasoby platformy Azure. Należy upewnić się, że kod Bicep jest zgodny z najlepszymi rozwiązaniami i że jest w pełni przetestowany i bezpieczny do użycia w kolejnych wdrożeniach. W tej lekcji poznasz dwie pierwsze fazy migracji Bicep: fazę konwersji i fazę migracji.

Diagram that shows the convert and migrate phases of the recommended workflow for migrating Azure resources to Bicep.

Głównym celem tych dwóch faz jest przygotowanie nowego pliku Bicep przed później refaktoryzację i przetestowanie go.

Konwertowanie fazy

Celem fazy konwersji migrowania zasobów do Bicep jest przechwycenie początkowej 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 możliwych kroków, które należy wykonać w sekwencji:

Przechwyć reprezentację zasobów platformy Azure.
W razie potrzeby przekonwertuj reprezentację JSON na wartość Bicep przy użyciu decompile polecenia .

Diagram that shows a JSON template decompiled to JSON, and Azure resources that are exported to a JSON template, which is then decompiled.

Jeśli masz istniejący szablon JSON, który konwertujesz na Bicep, pierwszy krok jest łatwy, ponieważ masz już szablon źródłowy. W tej lekcji dowiesz się, jak ją dekompilować do Bicep.

Jeśli konwertujesz zasoby platformy Azure, które zostały wdrożone przy użyciu witryny Azure Portal lub innego narzędzia, musisz przechwycić definicje zasobów. Definicje zasobów można wyeksportować i przekonwertować na Bicep lub użyć polecenia Wstaw zasób w programie Visual Studio Code, aby wstawić reprezentację zasobu platformy Azure w formacie Bicep.

Jak platforma Azure reprezentuje zasoby

Azure Resource Manager to usługa używana do wdrażania zasobów i zarządzania nimi na platformie Azure. Wszystkie zasoby wdrożone na platformie Azure są śledzone przez usługę Resource Manager niezależnie od metody użytej do wdrożenia zasobu. Do interakcji z usługą Resource Manager można użyć witryny Azure Portal, interfejsu wiersza polecenia platformy Azure, programu Azure PowerShell, interfejsu API REST usługi Resource Manager i zestawów SDK platformy Azure.

Diagram that shows Resource Manager accepting requests from all Azure clients and libraries.

Istnieją dwa typy operacji na platformie Azure: operacje płaszczyzny sterowania i operacje płaszczyzny danych. Operacje płaszczyzny sterowania służą do zarządzania zasobami w ramach subskrypcji. Operacje płaszczyzny danych są używane do uzyskiwania dostępu do funkcji udostępnianych przez zasób. Na przykład używasz operacji płaszczyzny sterowania do utworzenia maszyny wirtualnej, ale używasz operacji płaszczyzny danych do łączenia się z maszyną wirtualną przy użyciu protokołu RDP (Remote Desktop Protocol).

Eksportowanie istniejących zasobów do szablonu JSON

Niezależnie od sposobu tworzenia zasobów platformy Azure usługa Resource Manager udostępnia informacje o każdym zasobie w formacie JSON. Gdy zostanie wyświetlony monit o kopię reprezentacji JSON zasobu, eksportujesz zasób. Plik JSON, który można wyeksportować, można dekompilować do pliku Bicep.

Usługa Resource Manager udostępnia wiele sposobów eksportowania zasobów platformy Azure do szablonu. Za pomocą witryny Azure Portal, interfejsu wiersza polecenia platformy Azure i poleceń cmdlet programu Azure PowerShell można eksportować pojedyncze zasoby, wiele zasobów i całe grupy zasobów.

Proces eksportowania jest operacją płaszczyzny sterowania, co oznacza, że eksportuje tylko konfigurację zasobów platformy Azure. Na przykład podczas eksportowania maszyny wirtualnej dane na dysku twardym maszyny wirtualnej nie są eksportowane. Podczas eksportowania konta magazynu obiekty blob i inne treści konta magazynu nie są uwzględniane w procesie eksportowania.

Podczas eksportowania istniejących zasobów należy wziąć pod uwagę kilka kwestii:

Wyeksportowana definicja zasobu to migawka bieżącego stanu tego zasobu. Zawiera wszystkie zmiany wprowadzone w zasobie od czasu jego początkowego wdrożenia.
Wyeksportowany szablon może zawierać niektóre domyślne właściwości zasobu, które są zwykle pomijane z definicji Bicep. Na przykład proces eksportowania może dodawać właściwości tylko do odczytu, które platforma Azure ustawia automatycznie. Nie ma sensu uwzględniać tych właściwości, ponieważ są one tylko do odczytu. Rozważ usunięcie tych właściwości z definicji zasobów podczas migracji do aplikacji Bicep, aby pliki Bicep były wolne od niepotrzebnego kodu, co może spowodować zamieszanie.
Wyeksportowany szablon prawdopodobnie nie będzie zawierać wszystkich parametrów, które będą potrzebne do ponownego użycia szablonu. Podczas eksportowania szablonu wiele właściwości będzie zakodowanych w szablonie. W dalszej części tego modułu zobaczysz, jak dodać parametry.
Niektórych zasobów nie można wyeksportować przy użyciu tego podejścia i należy je zdefiniować ręcznie w pliku Bicep. W dalszej części tej lekcji dowiesz się, jak ponownie utworzyć te zasoby.

Zapisywanie wdrożeń w szablonie JSON

Jeśli zasób został wdrożony ręcznie w witrynie Azure Portal, możesz zauważyć opcję Pobierz szablon automatyzacji na karcie Przeglądanie i tworzenie . Ta opcja zapisuje szablon usługi ARM JSON oparty na nazwach i właściwościach ustawionych podczas tworzenia zasobu w portalu.

Usługa Resource Manager śledzi również wdrożenia zasobów. Operacje wdrażania obejmują zmiany przesłane przez środowisko tworzenia zasobów w witrynie Azure Portal i wszystkie wdrożenia szablonów usługi ARM. Zmiany istniejących zasobów wprowadzonych przy użyciu witryny Azure Portal, poleceń cmdlet programu Azure PowerShell, interfejsu wiersza polecenia platformy Azure lub innych narzędzi zwykle nie tworzą wdrożeń.

Jeśli wdrożenia zostały utworzone przy użyciu zgodnego narzędzia, możesz uzyskać dostęp do szablonu wdrożenia z historii wdrożenia grupy zasobów. Do zapisywania wdrożeń można użyć witryny Azure Portal, interfejsu wiersza polecenia platformy Azure lub programu Azure PowerShell.

Podczas zapisywania szablonów należy wziąć pod uwagę kilka rzeczy przy użyciu tej metody:

Zapisany szablon przedstawia stan zasobów w momencie wdrożenia. Nie zawiera żadnych zmian wprowadzonych po wdrożeniu.
Jeśli wdrożenie zawiera wiele zasobów, nie można wybrać określonych zasobów do uwzględnienia i wykluczenia. Ta operacja pobiera definicję wszystkich zasobów, które były częścią początkowego wdrożenia. Jednak po przejściu do fazy migracji procesu można ręcznie zignorować zasoby, których nie potrzebujesz.
Szablon zawiera tylko właściwości zasobów, które są wymagane do wdrożenia.
Szablon może zawierać parametry, których można użyć do ponownego wdrożenia szablonu w wielu środowiskach. Należy jednak potwierdzić, że te parametry odpowiadają Twoim potrzebom.
Szablon prawdopodobnie nie zawiera właściwości nadmiarowych, ale nadal należy sprawdzić, czy szablon zawiera wszystkie oczekiwane i usunięte niepotrzebne właściwości.

Uwaga

Jednak eksportujesz zasoby, eksportując istniejące zasoby lub zapisując wdrożenia, traktują wyeksportowany plik jako punkt początkowy i nie używaj ich bezpośrednio. Zamiast tego użyj go jako punktu wyjścia dla ostatecznego szablonu.

Wstawianie istniejących zasobów do Bicep

Rozszerzenie Bicep dla programu Visual Studio Code zawiera polecenie Wstaw zasób , które przechwytuje reprezentację Bicep zasobu platformy Azure. To polecenie odczytuje definicję JSON zasobu z platformy Azure, usuwa właściwości rozpoznawane jako tylko do odczytu i dekompiluje kod JSON do Bicep. Podobnie jak w przypadku funkcji export, wynikowy kod Bicep może być używany jako punkt wyjścia dla końcowego pliku Bicep.

Zasób można wstawić, otwierając paletę poleceń programu Visual Studio Code. Użyj kombinacji klawiszy Ctrl+Shift+P w systemach Windows i Linux oraz :+Shift+P w systemie macOS.

Dekompiluj źródłowy szablon usługi ARM JSON

Drugim krokiem migracji zasobów platformy Azure do aplikacji Bicep jest przekonwertowanie szablonów usługi ARM JSON i zasobów platformy Azure na szablony Bicep. Narzędzie Bicep zawiera polecenie służące do konwertowania decompile szablonów. Możesz wywołać polecenie za pomocą interfejsu decompile wiersza polecenia platformy Azure lub interfejsu wiersza polecenia Bicep.

Proces dekompilacji nie gwarantuje pełnego mapowania z formatu JSON na Bicep. Może być konieczne skorygowanie wygenerowanego pliku Bicep w celu spełnienia najlepszych rozwiązań dotyczących szablonu przed użyciem pliku do wdrożenia zasobów. Weź pod uwagę punkt początkowy migracji. W dalszej części tego modułu dowiesz się, jak rozwiązać wszelkie problemy występujące podczas procesu dekompilacji.

Po dekompilaniu szablonu ukończono fazę konwersji. Masz teraz prawidłowy plik Bicep, od którego chcesz zacząć.

Faza migracji

Celem fazy migracji migracji zasobów do Bicep jest utworzenie pierwszej wersji roboczej pliku Bicep możliwego do wdrożenia i upewnienia się, że definiuje wszystkie zasoby platformy Azure, które są w zakresie migracji.

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

Utwórz nowy pusty plik Bicep.
Skopiuj każdy zasób z dekompilowanego szablonu.
Zidentyfikuj i ponownie utwórz brakujące zasoby.

Diagram that shows the steps for migrating a template to Bicep.

Tworzenie nowego pliku Bicep

Dobrym rozwiązaniem jest utworzenie nowego pliku Bicep. Plik utworzony w fazie konwersji jest punktem odniesienia do przyjrzenia się, ale nie należy traktować go jako końcowego ani wdrażać w taki sposób, jak jest.

Kopiowanie zasobów do nowego pliku Bicep

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ąć pomyłek, ponieważ szablon staje się większy.

Ponowne tworzenie nieobsługiwanych zasobów

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 maszyn wirtualnych, takie jak DependencyAgentWindows i MMAExtension (Microsoft Monitoring Agent) to typy zasobów, których nie można wyeksportować.

Podczas próby wyeksportowania zasobu przy użyciu witryny Azure Portal, interfejsu wiersza polecenia platformy Azure lub programu Azure PowerShell i dołączono nieobsługiwany typ zasobu, zostanie wygenerowany szczegółowy komunikat o błędzie. Musisz ponownie utworzyć dowolny zasób, który nie został wyeksportowany, na przykład rozszerzenia maszyny wirtualnej, w nowym pliku Bicep. Możesz wybrać spośród kilku narzędzi i podejść do ponownego tworzenia zasobów, w tym eksploratora zasobów platformy Azure, dokumentacji szablonu usługi ARM i szablonów szybkiego startu platformy Azure.

Eksplorator zasobów Azure

Eksplorator zasobów platformy Azure to narzędzie osadzone w witrynie Azure Portal. W portalu nie są wyświetlane pewne typy zasobów, ale Eksplorator zasobów udostępnia reprezentację JSON zasobów. Aby uzyskać dostęp do Eksploratora zasobów, wyszukaj go w polu wyszukiwania:

Screenshot of the Azure portal that shows the search box with resource explorer entered.

W okienku wyników zostanie wyświetlona lista zarejestrowanych dostawców zasobów dla subskrypcji oraz szczegółowe informacje dotyczące wszystkich zasobów, grup zasobów i subskrypcji, do których masz uprawnienia do wyświetlania. Aby wyświetlić reprezentację zasobu w formacie JSON, wybierz hierarchię po lewej stronie okienka:

Screenshot of the Azure portal that shows Azure Resource Explorer.

Wybierając zasób, możesz wyświetlić reprezentację JSON w następujący sposób:

{
    "name": "DependencyAgentWindows",
    "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/rg-app-prod-truckline/providers/Microsoft.Compute/virtualMachines/vm-prod-001/extensions/DependencyAgentWindows",
    "type": "Microsoft.Compute/virtualMachines/extensions",
    "location": "eastus",
    "properties": {
        "autoUpgradeMinorVersion": true,
        "provisioningState": "Succeeded",
        "publisher": "Microsoft.Azure.Monitoring.DependencyAgent",
        "type": "DependencyAgentWindows",
        "typeHandlerVersion": "9.10"
    }
}

Możesz użyć reprezentacji JSON, aby zdefiniować zasób Bicep:

resource dependencyAgentWindows 'Microsoft.Compute/virtualMachines/extensions@2022-08-01' = {
  parent: virtualMachine
  name: 'DependencyAgentWindows'
  location: 'eastus'
  properties: {
    autoUpgradeMinorVersion: true
    publisher: 'Microsoft.Azure.Monitoring.DependencyAgent'
    type: 'DependencyAgentWindows'
    typeHandlerVersion: '9.10'
  }
}

Uwaga

Reprezentacja JSON zawiera właściwość o nazwie provisioningState. Właściwość provisioningState jest tylko do odczytu i jest automatycznie ustawiana przez platformę Azure, więc nie jest uwzględniana w definicji zasobu Bicep.

Napiwek

Rozszerzenie Bicep dla programu Visual Studio Code ułatwia definiowanie zasobów platformy Azure w środowisku Bicep. Na przykład reprezentacja zasobu Bicep obejmuje wersję interfejsu API, ale wyeksportowana wersja JSON nie. W programie Visual Studio Code po rozpoczęciu wprowadzania typu zasobu sugerowana jest automatycznie wersja interfejsu API.

Dokumentacja szablonu usługi Resource Manager

Dokumentacja szablonu usługi ARM to źródło informacji o strukturze szablonu usługi ARM, typach zasobów, wersjach interfejsu API i definicjach właściwości dla zasobów platformy Azure. Dokumentacja zawiera przykłady w formatach Bicep i JSON.

Możesz wybrać określonych dostawców zasobów i typów zasobów, takich jak Microsoft.Web/serverfarms, i ich wersje interfejsu API. Możesz sprawdzić, które właściwości zasobu są wymagane i które są opcjonalne. Możesz również wyświetlić opisy właściwości, które pomagają zrozumieć, co robią właściwości.

Szablony szybkiego startu platformy Azure

Repozytorium szablonów szybkiego startu platformy Azure to kolekcja szablonów współautorów społeczności. To repozytorium szablonów z możliwością wyszukiwania zawiera przykłady wielu zasobów i rozwiązań platformy Azure. W niektórych przewodnikach Szybki start dostępny jest zarówno szablon usługi ARM w formacie JSON, jak i szablon usługi ARM Bicep. Możesz użyć tych szablonów jako punktu odniesienia, aby ułatwić tworzenie i weryfikowanie szablonów do wdrożenia.

Załóżmy, że chcesz znaleźć szablon, który tworzy plan usługi aplikacja systemu Azure i aplikację. Każdy szablon szybkiego startu umożliwia wdrożenie szablonu bezpośrednio na platformie Azure lub wyświetlenie szablonu w usłudze GitHub.

Screenshot that shows an Azure Quickstart Template that deploys a basic Linux web app.

Pamiętaj, że szablony szybkiego startu platformy Azure to współtworzenie społeczności. Niektóre przykłady mogą być nieaktualne, ponieważ funkcje są regularnie dodawane do usług platformy Azure. Przykłady mogą również obejmować zasoby i właściwości, których nie potrzebujesz do użycia szablonu. Jednak repozytorium szablonów szybkiego startu jest przydatnym zasobem, który ułatwia zrozumienie sposobu wdrażania zasobów przy użyciu szablonów usługi ARM.