Najlepsze rozwiązania dotyczące szablonu usługi ARM

W tym artykule pokazano, jak używać zalecanych rozwiązań podczas tworzenia szablonu usługi Azure Resource Manager (szablon 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 rozwinięciu z iteracyjnymi definicjami zasobów oraz wartościami 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
• 256 zmiennych
• 800 zasobów (w tym liczba kopii)
• 64 wartości wyjściowe
• 10 unikatowych lokalizacji na subskrypcję/dzierżawę/zakres grupy 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 przypadku camel 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 dla 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 literału lub wyrażenia języka, 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żywaj 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, Resource Manager rozwiązuje ten konflikt nazewnictwa, dodając postfiks FromTemplate do parametru szablonu. Jeśli na przykład uwzględnisz parametr o nazwie ResourceGroupName w szablonie, 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ń dla parametrów

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

• Służy securestring do wszystkich haseł i wpisów tajnych. Jeśli przekazujesz poufne dane w obiekcie JSON, użyj secureObject typu . 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 wartości, które wymagają secureString typu.

• Nie udostępniaj wartości domyślnych dla 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 należy określać 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ę zapytań użytkowników o podanie informacji o lokalizacji.

• W przypadku zasobów, które nie są dostępne we wszystkich lokalizacjach, użyj oddzielnego parametru lub określ wartość lokalizacji literału.

Zmienne

Następujące informacje mogą być przydatne podczas pracy ze zmiennymi:

• Użyj przypadku camel dla nazw zmiennych.

• Użyj zmiennych dla wartości, których potrzebujesz użyć więcej niż raz w szablonie. Jeśli wartość jest używana tylko raz, trwale 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 referencyjnej w variables sekcji szablonu. Funkcja reference pobiera swoją wartość ze stanu środowiska uruchomieniowego zasobu. Zmienne są jednak rozwiązywane podczas początkowego analizowania szablonu. Konstruowanie wartości, które wymagają reference funkcji bezpośrednio w resources sekcji 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

apiVersion Ustaw właściwość na wersję zakodowanego 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 dokumentację 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 powodujące niezgodność, 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ć, użyj następujących wskazówek:

• reference Użyj funkcji i przekaż nazwę zasobu, aby ustawić niejawną zależność między zasobami, które muszą współużytkować właściwość. Nie należy dodawać jawnego dependsOn elementu, gdy zdefiniowano już niejawną zależność. Takie podejście zmniejsza ryzyko posiadania niepotrzebnych zależności. Przykład ustawiania niejawnej zależności można znaleźć w temacie Reference and list functions (Funkcje odwołania i listy).

• Ustaw zasób podrzędny jako zależny od zasobu nadrzędnego.

• Zasoby z ustawionym falseelementem warunku są automatycznie usuwane z kolejności zależności. Ustaw zależności tak, jakby zasób był zawsze wdrażany.

• Niech zależności są kaskadowe bez ich jawnego ustawienia. Na przykład maszyna wirtualna zależy od wirtualnego interfejsu sieciowego, a interfejs sieciowy wirtualny zależy od sieci wirtualnej i publicznych adresów IP. W związku z tym maszyna wirtualna jest wdrażana po wszystkich trzech zasobach, ale nie ustawiaj jawnie maszyny wirtualnej jako zależnej od wszystkich trzech zasobów. To podejście wyjaśnia kolejność zależności i ułatwia zmianę szablonu później.

• 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

Następujące informacje mogą być przydatne podczas pracy z zasobami:

• 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": "2019-06-01",
      "location": "[resourceGroup().location]",
      "comments": "This storage account is used to store the VM disks.",
        ...
    }
  ]
  

  Jeśli szablon usługi ARM jest przechowywany w .jsonc pliku, komentarze korzystające ze // składni są obsługiwane, jak pokazano tutaj.

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

  Aby uzyskać więcej informacji na temat komentarzy i metadanych, zobacz Omówienie struktury i składni szablonów usługi 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. reference Użyj funkcji , aby dynamicznie pobrać przestrzeń nazw. Za pomocą tego podejścia można wdrożyć szablon w różnych środowiskach publicznej przestrzeni nazw 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 szablonie.

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

  Jeśli konto magazynu jest wdrażane w tym samym szablonie, który tworzysz, a nazwa konta magazynu nie jest współużytkowana z innym zasobem w szablonie, nie musisz określać przestrzeni nazw dostawcy ani apiVersion podczas odwołowania się 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 magazynu, 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 jej 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:

  • Co to jest usługa Azure Bastion?
  • Jak nawiązać połączenie i zalogować się do maszyny wirtualnej platformy Azure z systemem Windows
  • Konfigurowanie dostępu usługi WinRM dla Virtual Machines w usłudze Azure Resource Manager
  • Nawiązywanie połączenia z maszyną wirtualną z systemem Linux

• Właściwość domainNameLabel 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 przez to wyrażenie regularne: ^[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))]"
  }
  

• Po dodaniu hasła do niestandardowego rozszerzenia skryptu użyj commandToExecute właściwości w protectedSettings właściwości .

  "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 wpisy tajne są szyfrowane po przekazaniu ich jako parametrów do maszyn wirtualnych i rozszerzeń, użyj protectedSettings właściwości 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. Jeśli na przykład wdrażasz klaster usługi AKS, możesz określić lub pominąć kubernetesVersion właściwość. Jeśli go nie określisz, klaster jest domyślnie włączony do wersji pomocniczej N-1 i najnowszej poprawki. Podczas wdrażania klastra przy użyciu szablonu usługi ARM to domyślne zachowanie może nie być oczekiwane. Ponowne wdrażanie szablonu może spowodować nieoczekiwane uaktualnienie klastra do nowej wersji platformy Kubernetes. Zamiast tego należy rozważyć określenie jawnego numeru wersji, a następnie ręcznie zmienić go, gdy wszystko będzie gotowe 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 Omówienie struktury i składni szablonów usługi 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.

Visual Studio Code narzędzia ARM

Praca z szablonami usługi ARM jest znacznie łatwiejsza dzięki narzędziom Azure Resource Manager (ARM) for Visual Studio Code. To rozszerzenie zapewnia obsługę języka, fragmenty kodu 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 szablonu usługi ARM to skrypt, który sprawdza, 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 Korzystanie z zestawu narzędzi do testowania szablonu usługi ARM.

Następne kroki

• Aby uzyskać informacje o strukturze pliku szablonu, zobacz Omówienie struktury i składni szablonów usługi ARM.
• Aby uzyskać zalecenia dotyczące tworzenia szablonów, które działają we wszystkich środowiskach chmury platformy Azure, zobacz Tworzenie szablonów usługi ARM na potrzeby spójności chmury.