Osvědčené postupy pro šablonu ARM

V tomto článku se dozvíte, jak používat Doporučené postupy při vytváření šablony Azure Resource Manager (š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í.

Omezení šablon

Omezte velikost šablony na 4 MB. Limit velikosti 4 MB se vztahuje na konečný stav šablony po rozbalení pomocí iterativních definic prostředků a hodnot proměnných a parametrů. Soubor parametrů je také omezen na 4 MB. Pokud je celková velikost požadavku příliš velká, může se zobrazit chyba se šablonou nebo souborem parametrů menším než 4 MB. Další informace o tom, jak šablonu zjednodušit, abyste se vyhnuli velkému požadavku, najdete v tématu řešení chyb při překročení velikosti úlohy.

Máte také omezení:

  • parametry 256
  • proměnné 256
  • 800 prostředků (včetně počtu kopií)
  • 64 výstupní hodnoty
  • 24 576 znaků ve výrazu šablony

Můžete překročit několik omezení šablon pomocí vnořené šablony. Další informace najdete v tématu použití propojených a vnořených šablon při nasazování prostředků Azure. Chcete-li 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ů uloží metadata o prostředcích. Metadata se ukládají do umístění skupiny prostředků.

Pokud je oblast skupiny prostředků dočasně nedostupná, nemůžete aktualizovat prostředky ve skupině prostředků, protože metadata nejsou k dispozici. Prostředky v jiných oblastech budou pořád fungovat podle očekávání, ale nemůžete je aktualizovat. Pokud chcete minimalizovat riziko, vyhledejte skupinu prostředků a prostředky ve stejné oblasti.

Parametry

Informace v této části mohou 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í nutné zadávat během nasazování.

  • Pro názvy parametrů použijte ve stylu CamelCase Case.

  • 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 snadnější identifikaci.

  • Zadejte popis všech parametrů 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 snazší šablonu nasadit a uživatelé šablony uvidí příklad odpovídající hodnoty. Všechny výchozí hodnoty pro parametr 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."
        }
      }
    }
    
  • Chcete-li zadat volitelný parametr, nepoužívejte jako výchozí hodnotu prázdný řetězec. Místo toho použijte literálovou hodnotu nebo výraz jazyka pro vytvoření hodnoty.

    "storageAccountName": {
       "type": "string",
       "defaultValue": "[concat('storage', uniqueString(resourceGroup().id))]",
       "metadata": {
         "description": "Name of the storage account"
       }
    }
    
  • Používejte allowedValues zřídka. Použijte ji pouze v případě, že je nutné zajistit, aby některé hodnoty nebyly zahrnuty do povolených možností. Pokud používáte allowedValues moc široce, můžete zablokovat platná nasazení tím, že seznam nezůstane v aktuálním stavu.

  • Pokud název parametru ve vaší šabloně odpovídá parametru v příkazu PowerShell Deployment, Správce prostředků vyřeší tento konflikt názvů přidáním přípony FromTemplate do parametru Template. Například pokud zahrnete parametr s názvem ResourceGroupName v šabloně, je v konfliktu s parametrem ResourceGroupName v rutině New-AzResourceGroupDeployment . Během nasazování budete vyzváni k zadání hodnoty pro ResourceGroupNameFromTemplate.

Doporučení zabezpečení pro parametry

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

  • Používá securestring se pro všechna hesla a tajné klíče. Pokud předáte citlivé údaje v objektu JSON, použijte secureObject typ. Parametry šablony se zabezpečeným řetězcem nebo typy zabezpečených objektů nelze přečíst po nasazení prostředků.

    "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á hodnota, která vyžaduje secureString typ.

  • Neposkytněte výchozí hodnoty pro vlastnosti, které zvyšují prostor pro útoky v aplikaci.

Doporučení pro umístění parametrů

  • Pomocí parametru zadejte umístění pro prostředky a nastavte výchozí hodnotu na resourceGroup().location . Zadání parametru Location umožňuje uživatelům šablony určit 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 pro parametr Location. Zadaná umístění nemusí být k dispozici ve všech cloudech.

  • Pro prostředky, které jsou pravděpodobně ve stejném umístění, použijte hodnotu parametru Location. Tento přístup minimalizuje počet vyzvání uživatelů k zadání informací o poloze.

  • U prostředků, které nejsou k dispozici 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 ve stylu CamelCase Case.

  • Použijte proměnné pro hodnoty, které je třeba 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é vytváříte ze složitých uspořádání funkcí šablon. Pokud se složitý výraz zobrazuje pouze v proměnných, šablona je snazší číst.

  • Odkazovou funkci nelze použít v variables části šablony. referenceFunkce odvodí svoji hodnotu z běhového stavu prostředku. Proměnné jsou však při počáteční analýze šablony vyřešeny. Sestavte hodnoty, které tuto reference funkci potřebují přímo v resources části nebo v outputs šabloně.

  • Přidejte 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žité proměnné.

Verze rozhraní API

Nastavte apiVersion vlastnost na pevně kódovanou 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. Chcete-li zjistit dostupné hodnoty, přečtěte si téma Reference k šabloně.

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

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

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

Závislosti prostředků

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

  • Použijte reference funkci a předejte název prostředku k nastavení implicitní závislosti mezi prostředky, které potřebují sdílet vlastnost. Nepřidejte explicitní dependsOn element, pokud jste již definovali implicitní závislost. Tento přístup snižuje riziko zbytečných závislostí. Příklad nastavení implicitní závislosti naleznete v tématu reference and list Functions.

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

  • Prostředky s prvkem podmínky nastavenou na hodnotu false jsou automaticky odebrány z pořadí závislostí. Nastavte závislosti, jako by byl prostředek vždy nasazen.

  • Závislosti se dají uspořádat bez explicitního nastavování. Například váš 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 virtuální počítač se explicitně nenastaví jako závislý na všech třech prostředcích. Tento přístup vysvětluje pořadí závislostí a usnadňuje pozdější změnu šablony.

  • Pokud je možné hodnotu určit 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á závislost nepotřebujete. Tyto pokyny ne vždy fungují, 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 vám mohou pomoct následující informace:

  • Pokud chcete ostatním přispěvatelům pomoct 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 v šabloně (například veřejný koncový bod služby Azure Blob Storage) používáte veřejný koncový bod, nezadáte obor názvů na pevný kód. K reference dynamickému 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ých oborů 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 vaší š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ředekem v šabloně, nemusíte při odkazování na prostředek zazadat obor názvů poskytovatele ani . apiVersion 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řípadě, že to aplikace vyžaduje. Pokud se chcete připojit k virtuálnímu počítači za účelem ladění nebo pro účely správy nebo 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 v těchto tématu:

  • Vlastnost domainNameLabel veřejných IP adres musí být jedinečná. Hodnota musí mít 3 až 63 znaků a musí se řídit pravidly určenými tímto domainNameLabel regulárním výrazem: ^[a-z][a-z0-9-]{1,61}[a-z0-9]$ . Vzhledem k tomu, že funkce generuje řetězec o 13 znacích, je parametr omezen uniqueString na dnsPrefixString 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 do 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 jejich předaní jako parametry virtuálnímkům a rozšířením zašifrované, použijte vlastnost protectedSettings příslušných rozšíření.

  • Zadejte explicitní hodnoty vlastností, které mají výchozí hodnoty, které se mohou v průběhu času měnit. Pokud například nasazujete cluster AKS, můžete buď zadat, nebo vynechat kubernetesVersion vlastnost . Pokud ho nezadáte, bude cluster ve výchozím nastavení podverdou N-1a nejnovější opravou . Pokud cluster nasazujete pomocí šablony ARM, toto výchozí chování nemusí být to, co 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.

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 nedodržuje doporučené postupy, 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 podívejte se, 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