Usuwanie błędów związanych z nieprawidłowym szablonem

  • Artykuł

W tym artykule opisano sposób rozwiązywania nieprawidłowych błędów szablonu dla plików Bicep i szablonów usługi Azure Resource Manager (szablony usługi ARM). Błąd występuje z kilku powodów, takich jak błąd składniowy, nieprawidłowa wartość parametru lub zależność cykliczna.

Objaw

Po wdrożeniu szablonu zostanie wyświetlony błąd wskazujący:

Code=InvalidTemplate
Message=<varies>

Komunikat o błędzie zależy od typu błędu.

Przyczyna

Ten błąd może wynikać z kilku różnych typów błędów. Zwykle obejmują one składnię lub błąd strukturalny w szablonie.

Rozwiązanie 1. Błąd składniowy

Jeśli zostanie wyświetlony komunikat o błędzie wskazujący niepowodzenie walidacji szablonu, może wystąpić problem ze składnią w szablonie.

Code=InvalidTemplate
Message=Deployment template validation failed

Błędy składni mogą wystąpić, ponieważ wyrażenia szablonu mają wiele elementów. Na przykład przypisanie nazwy dla konta magazynu obejmuje pary pojedynczych lub podwójnych cudzysłowów, nawiasy klamrowe, nawiasy kwadratowe i nawiasy. Wyrażenia zawierają również funkcje i znaki, takie jak znaki dolara, przecinki i kropki.

name: 'storage${uniqueString(resourceGroup().id)}'

Po wyświetleniu tego typu błędu przejrzyj składnię wyrażenia. Aby zidentyfikować błędy szablonu, możesz użyć Visual Studio Code z najnowszym rozszerzeniem Bicep lub rozszerzeniem Azure Resource Manager Tools.

Rozwiązanie 2. Niepoprawne długości segmentów

Inny nieprawidłowy błąd szablonu występuje, gdy nazwa zasobu nie jest w poprawnym formacie. Aby rozwiązać ten błąd, zobacz Rozwiązywanie błędów dotyczących niezgodności nazw i typów.

Rozwiązanie 3. Parametr nie jest prawidłowy

Dozwolone wartości parametru można określić w szablonie. Podczas wdrażania, jeśli podasz wartość, która nie jest dozwoloną wartością, zostanie wyświetlony komunikat podobny do następującego błędu:

Code=InvalidTemplate;
Message=Deployment template validation failed: 'The provided value {parameter value}
for the template parameter {parameter name} is not valid. The parameter value is not
part of the allowed values

Sprawdź szablon dozwolonych wartości parametru i użyj dozwolonej wartości podczas wdrażania. Aby uzyskać więcej informacji, zobacz dozwolone wartości szablonówBicep lub ARM.

Rozwiązanie 4. Zbyt wiele docelowych grup zasobów

Ten błąd może wystąpić we wcześniejszych wdrożeniach, ponieważ w jednym wdrożeniu ograniczono do pięciu docelowych grup zasobów. W maju 2020 r. limit ten został zwiększony do 800 grup zasobów. Aby uzyskać więcej informacji, zobacz sposób wdrażania w wielu grupach zasobów dla szablonówusługi Bicep lub ARM.

Rozwiązanie 5. Wykryto zależność cykliczną

Ten błąd występuje, gdy zasoby zależą od siebie w sposób uniemożliwiający rozpoczęcie wdrażania. Połączenie współzależności sprawia, że co najmniej dwa zasoby czekają na inne zasoby, które również czekają. Na przykład resource1 zależy od resource3elementu , resource2 zależy od resource1elementu i resource3 zależy od resource2elementu . Ten problem można zwykle rozwiązać, usuwając niepotrzebne zależności.

Bicep tworzy niejawną zależność, gdy jeden zasób używa symbolicznej nazwy innego zasobu. Jawna zależność używana dependsOn zwykle nie jest konieczna. Aby uzyskać więcej informacji, zobacz Zależności Bicep.

Aby rozwiązać zależność cykliczną:

  1. W szablonie znajdź zasób zidentyfikowany w zależności cyklicznej.
  2. W przypadku tego zasobu sprawdź dependsOn właściwość i wszelkie zastosowania reference funkcji lub resourceId , aby zobaczyć, od których zasobów zależy.
  3. Sprawdź te zasoby, aby sprawdzić, od których zasobów zależą. Postępuj zgodnie z zależnościami, dopóki nie zauważysz zasobu, który zależy od oryginalnego zasobu.
  4. W przypadku zasobów zaangażowanych w zależność cykliczną należy dokładnie zbadać wszystkie zastosowania dependsOn właściwości, aby zidentyfikować wszelkie zależności, które nie są potrzebne. Aby rozwiązać problemy z wdrożeniem, usuń zależności cykliczne. Zamiast usuwać kod, można użyć komentarzy, aby kod nie był uruchamiany podczas następnego wdrożenia. W szablonach usługi ARM lub plikachBicep można używać komentarzy jednowierszowych (//) lub komentarzy wielowierszowych (/* ... */).
  5. Ponownie wdróż szablon.

Usunięcie wartości z dependsOn właściwości może powodować błędy podczas wdrażania szablonu. Jeśli wystąpi błąd, dodaj zależność z powrotem do szablonu. Jeśli do obejścia kodu w szablonie użyto komentarzy, możesz usunąć komentarze, aby przywrócić kod.

Jeśli takie podejście nie rozwiąże zależności cyklicznej, rozważ przeniesienie części logiki wdrażania do zasobów podrzędnych (takich jak rozszerzenia lub ustawienia konfiguracji). Skonfiguruj te zasoby podrzędne do wdrożenia po zasobach zaangażowanych w zależność cykliczną. Załóżmy na przykład, że wdrażasz dwie maszyny wirtualne, ale musisz ustawić właściwości na każdym z nich, które odwołują się do drugiego. Można je wdrożyć w następującej kolejności:

  1. vm1
  2. vm2
  3. Rozszerzenie na maszynie vm1 zależy od maszyny wirtualnej vm1 i vm2. Rozszerzenie ustawia wartości na maszynie wirtualnej vm1, które pobiera z maszyny vm2.
  4. Rozszerzenie na maszynie wirtualnej vm2 zależy od maszyny wirtualnej vm1 i vm2. Rozszerzenie ustawia wartości na maszynie wirtualnej vm2, które pobiera z maszyny vm1.

Takie samo podejście działa w przypadku aplikacji App Service. Rozważ przeniesienie wartości konfiguracji do podrzędnego zasobu aplikacji. Dwie aplikacje internetowe można wdrożyć w następującej kolejności:

  1. webapp1
  2. webapp2
  3. Konfiguracja aplikacji webapp1 zależy od aplikacji internetowej1 i aplikacji internetowej2. Zawiera ona ustawienia aplikacji z wartościami z aplikacji internetowejApp2.
  4. Konfiguracja aplikacji webapp2 zależy od aplikacji internetowej1 i aplikacji internetowej2. Zawiera ona ustawienia aplikacji z wartościami z aplikacji webapp1.

Rozwiązanie 6. Weryfikowanie składni wyeksportowanych szablonów

Po wdrożeniu zasobów na platformie Azure można wyeksportować kod JSON szablonu usługi ARM i zmodyfikować go na potrzeby innych wdrożeń. Przed wdrożeniem zasobów należy zweryfikować wyeksportowany szablon pod kątem poprawnej składni.

Szablon można wyeksportować z poziomu portalu, interfejsu wiersza polecenia platformy Azure lub Azure PowerShell. Istnieją zalecenia dotyczące eksportowania szablonu z zasobu lub grupy zasobów lub historii wdrażania.

Po wyeksportowaniu szablonu usługi ARM można dekompilować szablon JSON do elementu Bicep. Następnie użyj najlepszych rozwiązań i linter, aby zweryfikować kod.

Aby uzyskać więcej informacji, przejdź do następujących artykułów: