Osvědčené postupy pro šablony ARM

  • Článek

V tomto článku se dozvíte, jak při vytváření šablony Azure Resource Manager (šablony ARM) použít doporučené postupy. Tato doporučení vám pomůžou vyhnout se běžným problémům při nasazování řešení pomocí šablony ARM.

Omezení šablon

Omezte velikost šablony na 4 MB a každou definici prostředku na 1 MB. Omezení platí pro konečný stav šablony po jejím rozšíření o definice iterativních prostředků a hodnoty proměnných a parametrů. Velikost souboru parametrů je také omezená na 4 MB. I když má šablona nebo soubor parametrů velikost menší než 4 MB, může dojít k chybě, pokud je příliš velká celková velikost požadavku. Další informace o tom, jak zjednodušit šablonu, abyste se vyhnuli velkým požadavkům, najdete v tématu Řešení chyb způsobených překročením velikosti úloh.

Platí také následující limity:

  • 256 parametrů
  • 256 proměnných
  • 800 prostředků (včetně počtu kopií)
  • 64 výstupních hodnot
  • 10 jedinečných umístění na rozsah předplatného, tenanta nebo skupiny pro správu
  • 24 576 znaků ve výrazu šablony

Některé limity šablon můžete překročit s použitím vnořené šablony. Další informace najdete v tématu Používání propojených a vnořených šablon při nasazování prostředků Azure. Pokud chcete snížit počet parametrů, proměnných nebo výstupů, můžete zkombinovat několik hodnot do objektu. Další informace najdete v tématu Objekty jako parametry.

Skupina prostředků

Když nasadíte prostředky do skupiny prostředků, skupina prostředků ukládá metadata o prostředcích. Metadata se uchovávají v umístění skupiny prostředků.

Pokud je oblast skupiny prostředků dočasně nedostupná, není možné aktualizovat prostředky ve skupině prostředků, protože metadata nejsou k dispozici. Prostředky v ostatních oblastech dál fungují podle očekávání, ale není možné je aktualizovat. Pokud chcete minimalizovat rizika, umístěte skupinu prostředků a prostředky do stejné oblasti.

Parametry

Informace v této části můžou být užitečné při práci s parametry.

Obecná doporučení pro parametry

  • Minimalizujte použití parametrů. Místo toho použijte proměnné nebo hodnoty literálů pro vlastnosti, které není potřeba zadávat během nasazení.

  • Pro názvy parametrů použijte velká a malá písmena.

  • Parametry můžete použít pro nastavení, která se liší podle prostředí, například podle skladové položky, velikosti nebo kapacity.

  • Pro názvy prostředků, které chcete zadat pro snadnou identifikaci, použijte parametry.

  • Zadejte popis každého parametru v metadatech.

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

  • Definujte výchozí hodnoty pro parametry, které nejsou citlivé. Zadáním výchozí hodnoty je nasazení šablony jednodušší a uživatelům šablony se zobrazí příklad vhodné hodnoty. Jakákoli výchozí hodnota parametru musí být platná pro všechny uživatele ve výchozí konfiguraci nasazení.

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

  • Pokud chcete zadat volitelný parametr, nepoužívejte prázdný řetězec jako výchozí hodnotu. Místo toho k vytvoření hodnoty použijte literálovou hodnotu nebo jazykový výraz.

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

  • Používejte allowedValues střídmě. Použijte ho jenom v případech, kdy se musíte ujistit, že některé hodnoty nejsou zahrnuté v povolených možnostech. Pokud používáte allowedValues příliš široce, můžete zablokovat platná nasazení tím, že seznam nebudete udržovat aktuální.

  • Pokud název parametru v šabloně odpovídá parametru v příkazu pro nasazení PowerShellu, Resource Manager tento konflikt názvů vyřeší přidáním přípony FromTemplate k parametru šablony. Pokud například do šablony zahrnete parametr s názvem ResourceGroupName , bude v konfliktu s parametrem ResourceGroupName v rutině New-AzResourceGroupDeployment . Během nasazování se zobrazí výzva k zadání hodnoty ResourceGroupNameFromTemplate.

Doporučení zabezpečení pro parametry

  • Vždy používejte parametry pro uživatelská jména a hesla (nebo tajné kódy).

  • Použijte securestring pro všechna hesla a tajné kódy. Pokud předáváte citlivá data v objektu JSON, použijte secureObject typ . Parametry šablony se zabezpečenými řetězci nebo zabezpečenými typy objektů nelze po nasazení prostředků číst.

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

  • Nezadávejte výchozí hodnoty pro uživatelská jména, hesla ani žádné hodnoty, které vyžadují secureString typ.

  • Nezadávejte výchozí hodnoty vlastností, které zvětšovat prostor pro útok aplikace.

Doporučení pro umístění pro parametry

  • Pomocí parametru určete umístění prostředků a nastavte výchozí hodnotu na resourceGroup().location. Poskytnutí parametru umístění umožňuje uživatelům šablony určit umístění, do kterého mají oprávnění k nasazení prostředků.

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

  • Jako parametr location nezadávejte allowedValues . Zadaná umístění nemusí být dostupná ve všech cloudech.

  • Hodnotu parametru location použijte pro prostředky, které jsou pravděpodobně ve stejném umístění. Tento přístup minimalizuje počet, kolikrát jsou uživatelé požádáni o zadání informací o poloze.

  • Pro prostředky, které nejsou dostupné ve všech umístěních, použijte samostatný parametr nebo zadejte hodnotu umístění literálu.

Proměnné

Následující informace můžou být užitečné při práci s proměnnými:

  • Pro názvy proměnných použijte velká a malá písmena.

  • Proměnné použijte pro hodnoty, které v šabloně potřebujete použít více než jednou. Pokud je hodnota použita pouze jednou, pevně zakódovaná hodnota usnadňuje čtení šablony.

  • Použijte proměnné pro hodnoty, které vytváříte ze složitého uspořádání funkcí šablony. Šablona se snadněji čte, když se složitý výraz zobrazuje jenom v proměnných.

  • V oddílu variables šablony nemůžete použít funkci reference. Funkce reference odvozuje svou hodnotu ze stavu modulu runtime prostředku. Proměnné jsou však vyřešeny během počáteční analýzy šablony. Sestavte hodnoty, které vyžadují reference funkci přímo v oddílu resources nebo outputs šablony.

  • Zahrňte proměnné pro názvy prostředků, které musí být jedinečné.

  • Použijte smyčku kopírování v proměnných k vytvoření opakovaného vzoru objektů JSON.

  • Odeberte nepoužívané proměnné.

Verze rozhraní API

apiVersion Nastavte vlastnost na pevně zakódovanou verzi rozhraní API pro typ prostředku. Při vytváření nové šablony doporučujeme pro typ prostředku použít nejnovější verzi rozhraní API. Informace o určení dostupných hodnot najdete v referenčních informacích k šabloně.

Pokud vaše šablona funguje podle očekávání, doporučujeme dál používat stejnou verzi rozhraní API. Při použití stejné verze rozhraní API se nemusíte starat o zásadní změny, které by mohly být zavedeny v novějších verzích.

Nepoužívejte parametr pro verzi rozhraní API. Vlastnosti a hodnoty prostředků se můžou lišit podle verze rozhraní API. IntelliSense v editoru kódu nedokáže určit správné schéma, pokud je verze rozhraní API nastavená na parametr. Pokud předáte verzi rozhraní API, která neodpovídá vlastnostem v šabloně, nasazení selže.

Nepoužívejte proměnné pro verzi rozhraní API.

Závislosti prostředků

Při rozhodování o tom, jaké závislosti nastavit, postupujte podle následujících pokynů:

  • reference Pomocí funkce a předáním názvu prostředku nastavte implicitní závislost mezi prostředky, které potřebují sdílet vlastnost. Nepřidávejte explicitní dependsOn prvek, pokud jste už definovali implicitní závislost. Tento přístup snižuje riziko zbytečných závislostí. Příklad nastavení implicitní závislosti najdete v tématu Funkce odkazů a seznamů.

  • Nastavte podřízený prostředek jako závislý na jeho nadřazeného prostředku.

  • Prostředky s elementem condition nastaveným na hodnotu se false automaticky odeberou z pořadí závislostí. Nastavte závislosti, jako kdyby byl prostředek nasazený vždy.

  • Nechte závislosti kaskádovitě, aniž byste je explicitně nastavili. Například virtuální počítač závisí na virtuálním síťovém rozhraní a rozhraní virtuální sítě závisí na virtuální síti a veřejných IP adresách. Proto se virtuální počítač nasadí po všech třech prostředcích, ale nenastavujte ho explicitně jako závislý na všech třech prostředcích. Tento přístup objasňuje pořadí závislostí a usnadňuje pozdější změnu šablony.

  • Pokud je možné určit hodnotu před nasazením, zkuste nasadit prostředek bez závislosti. Pokud například hodnota konfigurace vyžaduje název jiného prostředku, nemusíte potřebovat závislost. Tyto pokyny nemusí vždy fungovat, protože některé prostředky ověřují existenci druhého prostředku. Pokud se zobrazí chyba, přidejte závislost.

Zdroje a prostředky

Při práci s prostředky můžou být užitečné následující informace:

  • Aby ostatní přispěvatelé lépe pochopili účel prostředku, zadejte comments pro každý prostředek v šabloně hodnotu .

    "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.",
      ...
  }
]

    Pokud je vaše šablona ARM uložená .jsonc v souboru, podporují se komentáře používající syntaxi // , jak je znázorněno tady.

    "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]",
      ...
  }
]

    Další podrobnosti o komentářích a metadatech najdete v tématu Vysvětlení struktury a syntaxe šablon ARM.

  • Pokud v šabloně používáte veřejný koncový bod (například veřejný koncový bod úložiště objektů blob v Azure), nezakódujte obor názvů pevně. K dynamickému reference načtení oboru názvů použijte funkci . Tento přístup můžete použít k nasazení šablony do různých prostředí veřejného oboru názvů bez ruční změny koncového bodu v šabloně. Nastavte verzi rozhraní API na stejnou verzi, kterou používáte pro účet úložiště v šabloně.

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

    Pokud je účet úložiště nasazený ve stejné šabloně, kterou vytváříte, a název účtu úložiště není sdílený s jiným prostředkem v šabloně, nemusíte zadávat obor názvů poskytovatele ani apiVersion při odkazování na prostředek. Následující příklad ukazuje zjednodušenou syntaxi.

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

    Můžete také odkazovat na existující účet úložiště, který je v jiné skupině prostředků.

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

  • Přiřazovat veřejné IP adresy virtuálnímu počítači jenom v případech, kdy to vyžaduje aplikace. Pokud se chcete připojit k virtuálnímu počítači pro účely správy, použijte pravidla příchozího překladu adres (NAT), bránu virtuální sítě nebo jumpbox.

    Další informace o připojení k virtuálním počítačům najdete tady:

  • Vlastnost domainNameLabel veřejných IP adres musí být jedinečná. Hodnota domainNameLabel musí mít délku 3 až 63 znaků a musí se řídit pravidly určenými tímto regulárním výrazem: ^[a-z][a-z0-9-]{1,61}[a-z0-9]$. Vzhledem k uniqueString tomu, že funkce generuje řetězec o délce 13 znaků, dnsPrefixString je parametr omezen na 50 znaků.

    "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))]"
}

  • Když přidáte heslo k rozšíření vlastních skriptů, použijte commandToExecute vlastnost ve protectedSettings vlastnosti .

    "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'))]"
  }
}

    Poznámka

    Pokud chcete zajistit, aby se tajné kódy při předání virtuálním počítačům a rozšířením jako parametry zašifrovaly, použijte protectedSettings vlastnost příslušných rozšíření.

  • Zadejte explicitní hodnoty pro vlastnosti, které mají výchozí hodnoty, které se mohou v průběhu času měnit. Pokud například nasazujete cluster AKS, můžete vlastnost zadat nebo vynechat kubernetesVersion . Pokud ho nezadáte, cluster se ve výchozím nastavení nastaví na podverzi N-1 a nejnovější opravu. Když cluster nasadíte pomocí šablony ARM, nemusí být toto výchozí chování takové, jaké očekáváte. Opětovné nasazení šablony může vést k neočekávanému upgradu clusteru na novou verzi Kubernetes. Místo toho zvažte zadání explicitního čísla verze a jeho ruční změnu, až budete připraveni upgradovat cluster.

Komentáře

Kromě vlastnosti jsou comments podporovány komentáře používající syntaxi // . Další podrobnosti o komentářích a metadatech najdete v tématu Vysvětlení struktury a syntaxe šablon ARM. Soubory JSON, které obsahují // komentáře, můžete uložit pomocí přípony .jsonc souboru , abyste označili, že soubor JSON obsahuje komentáře. Služba ARM bude také přijímat komentáře v libovolném souboru JSON, včetně souborů parametrů.

Nástroje ARM pro Visual Studio Code

Práce se šablonami ARM je mnohem jednodušší díky nástrojům Azure Resource Manager (ARM) pro Visual Studio Code. Toto rozšíření poskytuje podporu jazyků, fragmenty prostředků a automatické dokončování prostředků, které vám pomůžou vytvářet a ověřovat šablony azure Resource Manager. Další informace a instalaci rozšíření najdete v tématu Nástroje Azure Resource Manager (ARM).

Použití testovací sady nástrojů

Testovací sada nástrojů pro šablony ARM je skript, který kontroluje, jestli vaše šablona používá doporučené postupy. Pokud vaše šablona nevyhovuje doporučeným postupům, vrátí seznam upozornění s navrhovanými změnami. Testovací sada nástrojů vám pomůže naučit se implementovat osvědčené postupy v šabloně.

Po dokončení šablony spusťte testovací sadu nástrojů a zjistěte, jestli existují způsoby, jak zlepšit její implementaci. Další informace najdete v tématu Použití testovací sady nástrojů pro šablony ARM.

Další kroky