Udostępnij przez

Najlepsze rozwiązania dotyczące szablonów ARM

W tym artykule pokazano, jak używać zalecanych rozwiązań podczas konstruowania szablonu usługi Azure Resource Manager (szablonu usługi ARM). Te zalecenia pomagają uniknąć typowych problemów podczas korzystania z szablonu usługi ARM w celu wdrożenia rozwiązania.

Limity szablonów

Ogranicz rozmiar szablonu do 4 MB, a każda definicja zasobu to 1 MB. Limity mają zastosowanie do końcowego stanu szablonu po rozszerzeniu o iteracyjne definicje zasobów i wartości zmiennych i parametrów. Plik parametrów jest również ograniczony do 4 MB. Jeśli całkowity rozmiar żądania jest zbyt duży, może wystąpić błąd dotyczący szablonu lub pliku parametrów o rozmiarze mniejszym niż 4 MB. Aby uzyskać więcej informacji na temat sposobu upraszczania szablonu w celu uniknięcia dużego żądania, zobacz Rozwiązywanie błędów dotyczących przekroczenia rozmiaru zadania.

Istnieją również następujące ograniczenia:

  • 256 parametrów
  • 512 zmiennych
  • 800 zasobów (w tym liczba kopii)
  • 64 wartości wyjściowe
  • 10 unikalnych lokalizacji na subskrypcję/klienta/zakres grup zarządzania
  • 24 576 znaków w wyrażeniu szablonu

Niektóre limity szablonów można przekroczyć przy użyciu szablonu zagnieżdżonego. Aby uzyskać więcej informacji, zobacz Używanie połączonych i zagnieżdżonych szablonów podczas wdrażania zasobów platformy Azure. Aby zmniejszyć liczbę parametrów, zmiennych lub danych wyjściowych, można połączyć kilka wartości w obiekt. Aby uzyskać więcej informacji, zobacz Obiekty jako parametry.

Grupa zasobów

Podczas wdrażania zasobów w grupie zasobów grupa zasobów przechowuje metadane dotyczące zasobów. Metadane są przechowywane w lokalizacji grupy zasobów.

Jeśli region grupy zasobów jest tymczasowo niedostępny, nie można zaktualizować zasobów w grupie zasobów, ponieważ metadane są niedostępne. Zasoby w innych regionach będą nadal działać zgodnie z oczekiwaniami, ale nie można ich zaktualizować. Aby zminimalizować ryzyko, znajdź grupę zasobów i zasoby w tym samym regionie.

Parametry

Informacje przedstawione w tej sekcji mogą być przydatne podczas pracy z parametrami.

Ogólne zalecenia dotyczące parametrów

  • Zminimalizuj użycie parametrów. Zamiast tego należy użyć zmiennych lub wartości literałów dla właściwości, które nie muszą być określone podczas wdrażania.

  • Użyj zapisu camel case dla nazw parametrów.

  • Użyj parametrów dla ustawień, które różnią się w zależności od środowiska, takich jak jednostka SKU, rozmiar lub pojemność.

  • Użyj parametrów dla nazw zasobów, które chcesz określić w celu łatwej identyfikacji.

  • Podaj opis każdego parametru w metadanych.

    "parameters": {
  "storageAccountType": {
    "type": "string",
    "metadata": {
      "description": "The type of the new storage account created to store the VM disks."
    }
  }
}

  • Zdefiniuj wartości domyślne parametrów, które nie są poufne. Określając wartość domyślną, łatwiej jest wdrożyć szablon, a użytkownicy szablonu zobaczą przykład odpowiedniej wartości. Każda wartość domyślna parametru musi być prawidłowa dla wszystkich użytkowników w domyślnej konfiguracji wdrożenia.

    "parameters": {
  "storageAccountType": {
    "type": "string",
    "defaultValue": "Standard_GRS",
    "metadata": {
      "description": "The type of the new storage account created to store the VM disks."
    }
  }
}

  • Aby określić opcjonalny parametr, nie używaj pustego ciągu jako wartości domyślnej. Zamiast tego użyj wartości dosłownej lub wyrażenia językowego, aby utworzyć wartość.

    "storageAccountName": {
   "type": "string",
   "defaultValue": "[concat('storage', uniqueString(resourceGroup().id))]",
   "metadata": {
     "description": "Name of the storage account"
   }
}

  • Używaj allowedValues oszczędnie. Użyj go tylko wtedy, gdy musisz upewnić się, że niektóre wartości nie są uwzględnione w dozwolonych opcjach. Jeśli używasz allowedValues zbyt szeroko, możesz zablokować prawidłowe wdrożenia, nie aktualizując listy.

  • Gdy nazwa parametru w szablonie jest zgodna z parametrem w poleceniu wdrażania programu PowerShell, usługa Resource Manager rozwiązuje ten konflikt nazewnictwa, dodając postfiks FromTemplate do parametru szablonu. Jeśli na przykład dołączysz parametr o nazwie ResourceGroupName do szablonu, powoduje konflikt z parametrem ResourceGroupName w poleceniu cmdlet New-AzResourceGroupDeployment. Podczas wdrażania zostanie wyświetlony monit o podanie wartości ResourceGroupNameFromTemplate.

Zalecenia dotyczące zabezpieczeń dotyczące parametrów

  • Zawsze używaj parametrów dla nazw użytkowników i haseł (lub wpisów tajnych).

  • Użyj securestring dla wszystkich haseł i wpisów tajnych. W przypadku przekazywania poufnych danych w obiekcie JSON użyj typu secureObject. Parametry szablonu z bezpiecznym ciągiem lub bezpiecznymi typami obiektów nie mogą być odczytywane po wdrożeniu zasobów.

    "parameters": {
  "secretValue": {
    "type": "securestring",
    "metadata": {
      "description": "The value of the secret to store in the vault."
    }
  }
}

  • Nie udostępniaj wartości domyślnych nazw użytkowników, haseł ani żadnej wartości wymagającej secureString typu.

  • Nie udostępniaj wartości domyślnych właściwości, które zwiększają obszar obszaru podatnego na ataki aplikacji.

Zalecenia dotyczące lokalizacji dla parametrów

  • Użyj parametru , aby określić lokalizację zasobów i ustawić wartość domyślną na resourceGroup().location. Podanie parametru lokalizacji umożliwia użytkownikom szablonu określenie lokalizacji, w której mają uprawnienia do wdrażania zasobów.

    "parameters": {
   "location": {
     "type": "string",
     "defaultValue": "[resourceGroup().location]",
     "metadata": {
       "description": "The location in which the resources should be deployed."
     }
   }
}

  • Nie określaj allowedValues parametru lokalizacji. Określone lokalizacje mogą nie być dostępne we wszystkich chmurach.

  • Użyj wartości parametru lokalizacji dla zasobów, które prawdopodobnie znajdują się w tej samej lokalizacji. Takie podejście minimalizuje liczbę monitów użytkowników o podanie informacji o lokalizacji.

  • Dla zasobów niedostępnych we wszystkich lokalizacjach użyj oddzielnego parametru lub określ dosłowną wartość lokalizacji.

Zmienne

Podczas pracy ze zmiennymi mogą być przydatne następujące informacje:

  • Użyj notacji camel case dla nazw zmiennych.

  • Użyj zmiennych dla wartości, które należy użyć więcej niż raz w szablonie. Jeśli wartość jest używana tylko raz, zakodowana wartość ułatwia odczytywanie szablonu.

  • Użyj zmiennych dla wartości tworzonych na podstawie złożonego układu funkcji szablonu. Szablon jest łatwiejszy do odczytania, gdy wyrażenie złożone pojawia się tylko w zmiennych.

  • Nie można użyć funkcji reference w variables sekcji szablonu. Funkcja reference uzyskuje wartość ze stanu środowiska uruchomieniowego zasobu. Zmienne są jednak rozpoznawane podczas początkowego analizowania szablonu. Skonstruuj wartości, które wymagają funkcji reference bezpośrednio w sekcji resources lub outputs szablonu.

  • Uwzględnij zmienne nazw zasobów, które muszą być unikatowe.

  • Użyj pętli kopiowania w zmiennych , aby utworzyć powtarzający się wzorzec obiektów JSON.

  • Usuń nieużywane zmienne.

Wersja interfejsu API

Ustaw właściwość apiVersion na ustaloną wersję interfejsu API dla typu zasobu. Podczas tworzenia nowego szablonu zalecamy użycie najnowszej wersji interfejsu API dla typu zasobu. Aby określić dostępne wartości, zobacz odniesienie do szablonu.

Jeśli szablon działa zgodnie z oczekiwaniami, zalecamy kontynuowanie korzystania z tej samej wersji interfejsu API. Korzystając z tej samej wersji interfejsu API, nie musisz martwić się o zmiany mogące powodować problemy z kompatybilnością, które mogą zostać wprowadzone w nowszych wersjach.

Nie używaj parametru dla wersji interfejsu API. Właściwości i wartości zasobów mogą się różnić w zależności od wersji interfejsu API. Funkcja IntelliSense w edytorze kodu nie może określić poprawnego schematu, gdy wersja interfejsu API jest ustawiona na parametr. Jeśli przekażesz wersję interfejsu API, która nie jest zgodna z właściwościami w szablonie, wdrożenie zakończy się niepowodzeniem.

Nie używaj zmiennych dla wersji interfejsu API.

Zależności zasobów

Podczas podejmowania decyzji o tym, jakie zależności należy ustawić, skorzystaj z następujących wytycznych:

  • Użyj funkcji reference i przekaż nazwę zasobu, aby ustawić niejawną zależność między zasobami, które muszą współużytkować właściwość. Nie dodawaj jawnego dependsOn elementu, gdy już zdefiniowano niejawną zależność. Takie podejście zmniejsza ryzyko wystąpienia niepotrzebnych zależności. Aby zapoznać się z przykładem ustawiania niejawnej zależności, zobacz funkcje odwołań i list.

  • Ustaw, aby zasób podrzędny był zależny od zasobu nadrzędnego.

  • Zasoby z elementem warunku ustawionym na false są automatycznie usuwane z kolejności zależności. Ustaw zależności tak, jakby zasób był zawsze wdrożony.

  • Pozwalaj na kaskadowe zależności bez ich jawnego ustawiania. Na przykład maszyna wirtualna zależy od interfejsu sieci wirtualnej, a interfejs sieciowy wirtualny zależy od sieci wirtualnej i publicznych adresów IP. W związku z tym maszyna wirtualna jest implementowana po wykorzystaniu wszystkich trzech zasobów, ale nie należy jawnie konfigurować jej jako zależnej od wszystkich trzech zasobów. Takie podejście wyjaśnia kolejność zależności i ułatwia późniejsze zmianę szablonu.

  • Jeśli wartość można określić przed wdrożeniem, spróbuj wdrożyć zasób bez zależności. Jeśli na przykład wartość konfiguracji wymaga nazwy innego zasobu, może nie być potrzebna zależność. Te wskazówki nie zawsze działają, ponieważ niektóre zasoby weryfikują istnienie innego zasobu. Jeśli wystąpi błąd, dodaj zależność.

Zasoby

Podczas pracy z zasobami mogą być przydatne następujące informacje:

  • Aby ułatwić innym współautorom zrozumienie przeznaczenia zasobu, określ comments dla każdego zasobu w szablonie.

    "resources": [
  {
    "name": "[variables('storageAccountName')]",
    "type": "Microsoft.Storage/storageAccounts",
    "apiVersion": "2025-06-01",
    "location": "[resourceGroup().location]",
    "comments": "This storage account is used to store the VM disks.",
      ...
  }
]

    Jeśli szablon ARM jest przechowywany w .jsonc pliku, obsługiwane są komentarze używające składni //, jak to pokazano.

    "resources": [
  {
    // This storage account is used to store the VM disks.
    "name": "[variables('storageAccountName')]",
    "type": "Microsoft.Storage/storageAccounts",
    "apiVersion": "2025-06-01",
    "location": "[resourceGroup().location]",
      ...
  }
]

    Aby uzyskać więcej informacji na temat komentarzy i metadanych, zobacz Zrozumienie struktury i składni szablonów ARM.

  • Jeśli używasz publicznego punktu końcowego w szablonie (na przykład publicznego punktu końcowego usługi Azure Blob Storage), nie koduj przestrzeni nazw. Użyj funkcji reference, aby dynamicznie pobierać przestrzeń nazw. Tej metody można użyć do wdrożenia szablonu w różnych środowiskach przestrzeni nazw publicznych bez ręcznej zmiany punktu końcowego w szablonie. Ustaw wersję interfejsu API na tę samą wersję, której używasz dla konta magazynu w ramach szablonu.

    "diagnosticsProfile": {
  "bootDiagnostics": {
    "enabled": "true",
    "storageUri": "[reference(resourceId('Microsoft.Storage/storageAccounts', variables('storageAccountName')), '2019-06-01').primaryEndpoints.blob]"
  }
}

    Jeśli konto magazynowe jest wdrażane w tym samym szablonie, który tworzysz, a jego nazwa nie jest współdzielona z innym zasobem w szablonie, nie musisz określać przestrzeni nazw dostawcy ani elementu apiVersion przy odwołaniu do zasobu. W poniższym przykładzie przedstawiono uproszczoną składnię.

    "diagnosticsProfile": {
  "bootDiagnostics": {
    "enabled": "true",
    "storageUri": "[reference(variables('storageAccountName')).primaryEndpoints.blob]"
  }
}

    Możesz również odwołać się do istniejącego konta przechowywania, które znajduje się w innej grupie zasobów.

    "diagnosticsProfile": {
  "bootDiagnostics": {
    "enabled": "true",
    "storageUri": "[reference(resourceId(parameters('existingResourceGroup'), 'Microsoft.Storage/storageAccounts', parameters('existingStorageAccountName')), '2019-06-01').primaryEndpoints.blob]"
  }
}

  • Przypisz publiczne adresy IP do maszyny wirtualnej tylko wtedy, gdy aplikacja tego wymaga. Aby nawiązać połączenie z maszyną wirtualną do celów administracyjnych, użyj reguł NAT dla ruchu przychodzącego, bramy sieci wirtualnej lub serwera przesiadkowego.

    Aby uzyskać więcej informacji na temat nawiązywania połączenia z maszynami wirtualnymi, zobacz:

  • Właściwość domainNameLabel dla publicznych adresów IP musi być unikatowa. Wartość domainNameLabel musi mieć długość od 3 do 63 znaków i postępować zgodnie z regułami określonymi w tym wyrażeniu regularnym: ^[a-z][a-z0-9-]{1,61}[a-z0-9]$. uniqueString Ponieważ funkcja generuje ciąg o długości 13 znaków, dnsPrefixString parametr jest ograniczony do 50 znaków.

    "parameters": {
  "dnsPrefixString": {
    "type": "string",
    "maxLength": 50,
    "metadata": {
      "description": "The DNS label for the public IP address. It must be lowercase. It should match the following regular expression, or it will raise an error: ^[a-z][a-z0-9-]{1,61}[a-z0-9]$"
    }
  }
},
"variables": {
  "dnsPrefix": "[concat(parameters('dnsPrefixString'),uniquestring(resourceGroup().id))]"
}

  • Podczas dodawania hasła do niestandardowego rozszerzenia skryptu, użyj właściwości commandToExecute w nodze protectedSettings.

    "properties": {
  "publisher": "Microsoft.Azure.Extensions",
  "type": "CustomScript",
  "typeHandlerVersion": "2.0",
  "autoUpgradeMinorVersion": true,
  "settings": {
    "fileUris": [
      "[concat(variables('template').assets, '/lamp-app/install_lamp.sh')]"
    ]
  },
  "protectedSettings": {
    "commandToExecute": "[concat('sh install_lamp.sh ', parameters('mySqlPassword'))]"
  }
}

    Uwaga

    Aby upewnić się, że tajemnice są szyfrowane przy ich przekazywaniu jako parametry do maszyn wirtualnych i rozszerzeń, użyj właściwości protectedSettings odpowiednich rozszerzeń.

  • Określ jawne wartości właściwości, które mają wartości domyślne, które mogą ulec zmianie w czasie. Na przykład, jeśli wdrażasz klaster AKS, możesz określić lub pominąć właściwość kubernetesVersion. Jeśli go nie określisz, klaster jest domyślnie ustawiony na wersję pomocniczą N-1 i najnowszą poprawkę. Podczas wdrażania klastra przy użyciu szablonu ARM to domyślne zachowanie może nie odpowiadać Twoim oczekiwaniom. Ponowne wdrożenie szablonu może spowodować nieoczekiwane uaktualnienie klastra do nowej wersji platformy Kubernetes. Zamiast tego rozważ określenie jawnego numeru wersji, a następnie ręcznie zmieniać go, gdy będziesz gotowy do uaktualnienia klastra.

Komentarze

Oprócz comments właściwości obsługiwane są komentarze korzystające ze // składni. Aby uzyskać więcej informacji na temat komentarzy i metadanych, zobacz Zrozumienie struktury i składni szablonów ARM. Możesz zapisać pliki JSON zawierające // komentarze przy użyciu .jsonc rozszerzenia pliku, aby wskazać, że plik JSON zawiera komentarze. Usługa ARM będzie również akceptować komentarze w dowolnym pliku JSON, w tym pliki parametrów.

Narzędzia ARM programu Visual Studio Code

Praca z szablonami usługi ARM jest łatwiejsza w przypadku narzędzi usługi Azure Resource Manager (ARM) dla programu Visual Studio Code. To rozszerzenie zapewnia obsługę języka, fragmenty zasobów i automatyczne uzupełnianie zasobów, aby ułatwić tworzenie i weryfikowanie szablonów usługi Azure Resource Manager. Aby dowiedzieć się więcej i zainstalować rozszerzenie, zobacz Narzędzia usługi Azure Resource Manager (ARM).

Korzystanie z zestawu narzędzi do testowania

Zestaw narzędzi do testowania szablonów ARM to skrypt sprawdzający, czy szablon korzysta z zalecanych rozwiązań. Jeśli szablon nie jest zgodny z zalecanymi rozwiązaniami, zwraca listę ostrzeżeń z sugerowanymi zmianami. Zestaw narzędzi do testowania może pomóc Ci dowiedzieć się, jak zaimplementować najlepsze rozwiązania w szablonie.

Po ukończeniu szablonu uruchom zestaw narzędzi do testowania, aby sprawdzić, czy istnieją sposoby ulepszania jego implementacji. Aby uzyskać więcej informacji, zobacz Używanie zestawu narzędzi do testowania szablonu ARM.

Następne kroki

  • Last updated on