Osvědčené postupy pro šablony ARM

  • Článek

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

Limity šablon

Omezte velikost šablony na 4 MB a každou definici prostředku na 1 MB. Omezení platí pro konečný stav šablony po rozšíření s iterativními definicemi prostředků a hodnotami 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ů
  • 512 proměnných
  • 800 prostředků (včetně počtu kopií)
  • 64 výstupních hodnot
  • 10 jedinečných umístění na předplatné, tenanta nebo rozsah 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ů

Při nasazování prostředků do skupiny prostředků ukládá skupina prostředků 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álu pro vlastnosti, které není nutné během nasazování zadávat.

  • 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.

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

  • 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 parametrů, které nejsou citlivé. Když zadáte výchozí hodnotu, je jednodušší šablonu nasadit a uživatelé šablony uvidí příklad odpovídající hodnoty. Všechny výchozí hodnoty 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 výraz jazyka.

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

  • Používejte allowedValues střídmě. Používejte 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 neudržíte v aktualizovaném stavu.

  • Když název parametru v šabloně odpovídá parametru v příkazu nasazení PowerShellu, Resource Manager tento konflikt pojmenování vyřeší přidáním přípony FromTemplate do parametru šablony. Pokud například do šablony zahrnete parametr s názvem ResourceGroupName , dojde ke 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žívejte securestring pro všechna hesla a tajné kódy. Pokud do objektu JSON předáte citlivá data, použijte tento secureObject typ. Parametry šablony se zabezpečeným řetězcem nebo zabezpečenými typy objektů se po nasazení prostředků nedají čí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 žádnou hodnotu, která vyžaduje secureString typ.

  • Nezadávejte výchozí hodnoty vlastností, které zvyšují prostor pro útok v aplikaci.

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

  • Pomocí parametru zadejte umístění pro prostředky a nastavte výchozí hodnotu na resourceGroup().location. Poskytnutí parametru umístění umožňuje uživatelům šablony zadat umístění, kde 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."
     }
   }
}

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

  • Použijte hodnotu parametru umístění pro prostředky, které budou pravděpodobně ve stejném umístění. Tento přístup minimalizuje počet, kolikrát se uživatelům zobrazí výzva k zadání informací o poloze.

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

Proměnné

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

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

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

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

  • Referenční funkci v variables oddílu šablony nelze použít. Funkce reference odvozuje jeho hodnotu ze stavu modulu runtime prostředku. Proměnné se ale přeloží během počáteční analýzy šablony. Vytvořte hodnoty, které potřebují reference funkci přímo v resources části outputs šablony.

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

  • Pomocí smyčky kopírování v proměnných vytvořte opakovaný vzor objektů JSON.

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

Verze rozhraní API

Nastavte vlastnost apiVersion na pevně zadanou verzi rozhraní API pro daný 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 nemůž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í se nezdaří.

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

Závislosti prostředků

Při rozhodování o tom, jaké závislosti se mají nastavit, použijte následující pokyny:

  • K nastavení implicitní závislosti mezi prostředky, které potřebují sdílet vlastnost, použijte funkci reference a předejte název prostředku. Nepřidávejte explicitní dependsOn prvek, pokud jste už definovali implicitní závislost. Tento přístup snižuje riziko zbytečné závislosti. Příklad nastavení implicitní závislosti najdete v referenčních a listových funkcích.

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

  • Prostředky s nastaveným prvkem false podmínky se automaticky odeberou z pořadí závislostí. Nastavte závislosti tak, jako by byl prostředek vždy nasazený.

  • Nechte závislosti kaskádovat bez explicitního nastavení. Váš virtuální počítač například 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 je virtuální počítač nasazený po všech třech prostředcích, ale explicitně nenastavujte virtuální počítač 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 potřebuje název jiného prostředku, možná nebudete potřebovat závislost. Tyto pokyny nefungují vždy, protože některé prostředky ověřují existenci druhého prostředku. Pokud se zobrazí chyba, přidejte závislost.

Zdroje informací

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

  • Pokud chcete pomoct ostatním přispěvatelům pochopit účel prostředku, zadejte comments pro každý prostředek v šabloně.

    "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 ve své šabloně používáte veřejný koncový bod (například veřejný koncový bod služby Azure Blob Storage), nezakódujte obor názvů pevně. reference Pomocí funkce můžete dynamicky načíst obor názvů. 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ě ve své š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ě se nesdílí 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řaďte virtuálnímu počítači veřejné IP adresy jenom v případech, kdy ji aplikace vyžaduje. Pokud se chcete připojit k virtuálnímu počítači pro účely správy, použijte příchozí pravidla NAT, bránu virtuální sítě nebo jumpbox.

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

  • domainNameLabel Vlastnost pro veřejné IP adresy musí být jedinečná. Hodnota domainNameLabel musí mít délku 3 až 63 znaků a dodržovat pravidla určená tímto regulárním výrazem: ^[a-z][a-z0-9-]{1,61}[a-z0-9]$. uniqueString Vzhledem k tomu, že funkce generuje řetězec, který je dlouhý 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ž do rozšíření vlastních skriptů přidáte heslo, použijte commandToExecute vlastnost v této 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 zašifrovaly při jejich předání jako parametry virtuálním počítačům a rozšířením, použijte protectedSettings vlastnost příslušných rozšíření.

  • Zadejte explicitní hodnoty vlastností, které mají výchozí hodnoty, které se můžou 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ž nasadíte cluster pomocí šablony ARM, nemusí toto výchozí chování vypadat tak, jak očekáváte. Opětovné nasazení šablony může způsobit neočekávaně upgrade 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ě comments vlastnosti jsou 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. Můžete se rozhodnout uložit soubory JSON, které obsahují // komentáře pomocí přípony .jsonc souboru, a označit tak, že soubor JSON obsahuje komentáře. Služba ARM také přijme komentáře v libovolném souboru JSON, včetně souborů parametrů.

Visual Studio Code ARM Tools

Práce s šablonami ARM je jednodušší pomocí nástrojů Azure Resource Manageru (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 Manageru. Další informace a instalace rozšíření najdete v tématu Nástroje Azure Resource Manageru (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 ve vaší šabloně.

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

Další kroky