ARM sablon legjobb gyakorlatok

Ez a cikk bemutatja, hogyan használhatja az ajánlott eljárásokat az Azure Resource Manager-sablon (ARM-sablon) létrehozásakor. Ezek a javaslatok segítenek elkerülni a gyakori problémákat, amikor arm-sablont használnak egy megoldás üzembe helyezéséhez.

Sablonkorlátok

Korlátozza a sablon méretét 4 MB-ra, az egyes erőforrásdefiníciók pedig 1 MB-ra. A korlátok a sablon végleges állapotára vonatkoznak, miután iteratív erőforrásdefiníciókkal, valamint változók és paraméterek értékeivel bővült. A paraméterfájl mérete szintén 4 MB-ra van korlátozva. Ha a kérés teljes mérete túl nagy, 4 MB-nál kisebb méretű sablon- vagy paraméterfájllal kapcsolatos hibaüzenet jelenhet meg. A sablonok leegyszerűsítéséről a nagy méretű kérések elkerüléséhez további információért lásd a feladatméret túllépésével kapcsolatos hibák elhárítását ismertető részt.

Emellett a következő korlátozások is érvényesek:

• 256 paraméter
• 256 változó
• 800 erőforrás (beleértve a másolások számát)
• 64 kimeneti érték
• 10 egyedi hely előfizetésenként/bérlőnként/felügyeleti csoport hatóköreként
• 24 576 karakter egy sablonkifejezésben

Beágyazott sablon segítségével meghaladhat bizonyos sablonkorlátokat. További információ: Kapcsolt és beágyazott sablonok használata Azure-erőforrások üzembe helyezésekor. A paraméterek, változók vagy kimenetek számának csökkentéséhez egyesíthet több értéket egyetlen objektumba. További információt az objektumokkal, mint paraméterekkel foglalkozó részben talál.

Erőforráscsoport

Amikor erőforrásokat helyez üzembe egy erőforráscsoportban, az erőforráscsoport az erőforrások metaadatait tárolja. A metaadatok tárolása az erőforráscsoport helyén történik.

Ha az erőforráscsoport régiója ideiglenesen nem érhető el, akkor nem frissítheti az erőforráscsoportban található erőforrásokat, mivel a metaadatok nem érhetők el. A más régiókban található erőforrások a várt módon fognak működni, de nem lesznek frissíthetők. A kockázat minimalizálása érdekében az erőforráscsoportot és az erőforrásokat helyezze ugyanabba a régióba.

Paraméterek

Az ebben a szakaszban található információk hasznosak lehetnek a paraméterek használatakor.

Általános javaslatok paraméterekhez

• Minimalizálja a paraméterek használatát. Ehelyett olyan tulajdonságokhoz használjon változókat vagy literális értékeket, amelyeket nem kell megadni az üzembe helyezés során.

• A paraméternevekhez használjon tevees esetet.

• A paraméterek olyan beállításokhoz használhatók, amelyek a környezettől függően, például az SKU, a méret vagy a kapacitás szerint változnak.

• Az egyszerű azonosításhoz használjon paramétereket az olyan erőforrásnevekhez, amelyeket meg szeretne adni.

• Adjon leírást minden paraméterről a metaadatokban.

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

• Alapértelmezett értékek meghatározása a nem érzékeny paraméterekhez. Az alapértelmezett érték megadásával egyszerűbb üzembe helyezni a sablont, és a sablon felhasználói láthatnak egy példát egy megfelelő értékre. Egy paraméter alapértelmezett értékének érvényesnek kell lennie az alapértelmezett üzembe helyezési konfigurációban szereplő összes felhasználóra.

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

• Opcionális paraméter megadásához ne használjon üres sztringet alapértelmezett értékként. Ehelyett használjon literális értéket vagy nyelvi kifejezést egy érték létrehozásához.

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

• Használja a allowedValues weboldalt takarékosan. Csak akkor használja, ha meg kell győződnie arról, hogy bizonyos értékek nem szerepelnek az engedélyezett beállításokban. Ha túl széles körben használja allowedValues , letilthatja az érvényes üzemelő példányokat, ha nem tartja naprakészen a listát.

• Ha a sablon egyik paraméterneve megegyezik a PowerShell üzembe helyezési parancsának egyik paraméterével, a Resource Manager feloldja ezt az elnevezési ütközést, ha hozzáadja a FromTemplate postfixet a sablonparaméterhez. Ha például egy ResourceGroupName nevű paramétert tartalmaz a sablonban, az ütközik a New-AzResourceGroupDeployment parancsmag ResourceGroupName paraméterével. Az üzembe helyezés során a rendszer kérni fogja, hogy adjon meg egy értéket a ResourceGroupNameFromTemplate számára.

Biztonsági javaslatok paraméterekhez

• Mindig használjon paramétereket a felhasználónevekhez és jelszavakhoz (vagy titkos kódokhoz).

• Használja a securestring címet minden jelszó és titok esetében. Ha bizalmas adatokat ad át egy JSON-objektumban, használja a típust secureObject . A biztonságos sztringgel vagy biztonságos objektumtípusokkal rendelkező sablonparaméterek nem olvashatók be az erőforrás üzembe helyezése után.

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

• Ne adjon meg alapértelmezett értékeket a felhasználónevekhez, jelszavakhoz vagy bármilyen típust secureString igénylő értékhez.

• Ne adjon meg alapértelmezett értékeket olyan tulajdonságokhoz, amelyek növelik az alkalmazás támadási felületét.

Helyjavaslatok paraméterekhez

• Paraméterrel adja meg az erőforrások helyét, és állítsa az alapértelmezett értéket a következőre resourceGroup().location: . Helyparaméter megadása lehetővé teszi a sablon felhasználói számára, hogy megadják azt a helyet, ahol engedéllyel rendelkeznek az erőforrások üzembe helyezésére.

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

• Ne adja meg allowedValues a helyparamétert. Előfordulhat, hogy a megadott helyek nem minden felhőben érhetők el.

• Használja a helyparaméter értékét olyan erőforrásokhoz, amelyek valószínűleg ugyanazon a helyen találhatók. Ez a módszer minimálisra csökkenti, hogy a felhasználók hányszor kérnek helyinformációt.

• Olyan erőforrások esetén, amelyek nem minden helyen érhetők el, használjon egy külön paramétert, vagy adjon meg egy literális helyértéket.

Változók

A változók használatakor az alábbi információk hasznosak lehetnek:

• Használjon teve esetet változónevekhez.

• Használjon változókat olyan értékekhez, amelyeket többször kell használnia egy sablonban. Ha egy értéket csak egyszer használ, a kemény kóddal kódolt érték megkönnyíti a sablon olvasását.

• A sablonfüggvények összetett elrendezéséből létrehozott értékekhez használjon változókat. A sablon könnyebben olvasható, ha az összetett kifejezés csak változókban jelenik meg.

• A referenciafüggvény nem használható a variables sablon szakaszában. A reference függvény az erőforrás futtatókörnyezeti állapotából nyeri az értékét. A változók azonban a sablon kezdeti elemzése során feloldódnak. Olyan értékeket hozhat létre, amelyek a reference függvényt közvetlenül a resources sablon vagy outputs a sablon szakaszában igénylik.

• Tartalmazzon változókat az erőforrásnevekhez, amelyeknek egyedinek kell lenniük.

• A változók másolási ciklusával JSON-objektumok ismétlődő mintáját hozhatja létre.

• Távolítsa el a nem használt változókat.

API-verzió

Állítsa be a apiVersion tulajdonságot az erőforrástípus keményen kódolt API-verziójára. Új sablon létrehozásakor javasoljuk, hogy egy erőforrástípushoz a legújabb API-verziót használja. A rendelkezésre álló értékek meghatározásához tekintse meg a sablonreferenciát.

Ha a sablon a várt módon működik, javasoljuk, hogy továbbra is ugyanazt az API-verziót használja. Ugyanannak az API-verziónak a használatával nem kell aggódnia a későbbi verziókban esetleg bevezetett kompatibilitástörő változások miatt.

Ne használjon paramétert az API-verzióhoz. Az erőforrás tulajdonságai és értékei API-verziónként eltérőek lehetnek. A kódszerkesztő intelliSense nem tudja meghatározni a megfelelő sémát, ha az API-verzió paraméterre van állítva. Ha olyan API-verziót ad át, amely nem felel meg a sablon tulajdonságainak, az üzembe helyezés sikertelen lesz.

Ne használjon változókat az API-verzióhoz.

Erőforrás-függőségek

Amikor eldönti, hogy milyen függőségeket szeretne beállítani, használja az alábbi irányelveket:

• A reference függvény használatával és az erőforrás nevének megadásával implicit függőséget állíthat be olyan erőforrások között, amelyeknek meg kell osztaniuk egy tulajdonságot. Ne adjon hozzá explicit dependsOn elemet, ha már definiált implicit függőséget. Ez a megközelítés csökkenti a szükségtelen függőségek kockázatát. Az implicit függőség beállítására példaként tekintse meg a referencia- és listafüggvényeket.

• Egy gyermek erőforrás beállítása a szülői erőforrástól függőnek.

• A feltételelemre beállított false erőforrások automatikusan törlődnek a függőségi sorrendből. Állítsa be a függőségeket úgy, mintha az erőforrás mindig üzembe lett volna helyezve.

• Hagyja, hogy a függőségek explicite beállítása nélkül kaszkádba kerüljenek. A virtuális gép például egy virtuális hálózati adaptertől függ, a virtuális hálózati adapter pedig a virtuális hálózattól és a nyilvános IP-címektől függ. Ezért a virtuális gép mindhárom erőforrás után üzembe lesz helyezve, de ne állítsa be explicit módon a virtuális gépet mind a három erőforrástól függőként. Ez a megközelítés tisztázza a függőségi sorrendet, és megkönnyíti a sablon későbbi módosítását.

• Ha az üzembe helyezés előtt meghatározható egy érték, próbálja meg függőség nélkül üzembe helyezni az erőforrást. Ha például egy konfigurációs értéknek szüksége van egy másik erőforrás nevére, lehet, hogy nincs szüksége függőségre. Ez az útmutató nem mindig működik, mert egyes erőforrások ellenőrzik a másik erőforrás meglétét. Ha hibaüzenetet kap, adjon hozzá egy függőséget.

Források

Az alábbi információk hasznosak lehetnek az erőforrások használatakor:

• Annak érdekében, hogy a többi hozzájáruló megértse az erőforrás célját, adja meg a sablonban a comments címet minden egyes erőforráshoz.

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

  Ha az ARM-sablon egy .jsonc fájlban van tárolva, a // szintaxist használó megjegyzések támogatottak az itt látható módon.

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

  A megjegyzésekről és a metaadatokról további információt az ARM-sablonok szerkezetének és szintaxisának ismertetése című témakörben talál.

• Ha nyilvános végpontot használ a sablonban (például nyilvános Azure Blob Storage-végpontot), ne kódozza le a névteret. A függvény használatával reference dinamikusan lekérheti a névteret. Ezzel a módszerrel üzembe helyezheti a sablont különböző nyilvános névtér-környezetekben anélkül, hogy manuálisan módosítaná a sablon végpontjait. Állítsa az API-verziót a sablon tárfiókjához használt verzióra.

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

  Ha a tárfiók ugyanabban a sablonban van üzembe helyezve, amelyet létrehoz, és a tárfiók neve nincs megosztva a sablon egy másik erőforrásával, akkor nem kell megadnia a szolgáltató névterét vagy az apiVersion erőforrásra való hivatkozáskor. Az alábbi példa az egyszerűsített szintaxist mutatja be.

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

  Hivatkozhat egy másik erőforráscsoportban található meglévő tárfiókra is.

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

• Nyilvános IP-címeket csak akkor rendelhet hozzá egy virtuális géphez, ha egy alkalmazásnak szüksége van rá. Ha rendszergazdai célból szeretne csatlakozni egy virtuális géphez, használjon bejövő NAT-szabályokat, virtuális hálózati átjárót vagy jumpboxot.

  További információ a virtuális gépekhez való csatlakozásról:

  • Mi az az Azure Bastion?
  • Csatlakozás és bejelentkezés Windows rendszerű Azure-beli virtuális gépre
  • WinRM-hozzáférés beállítása virtuális gépekhez az Azure Resource Managerben
  • Csatlakozás Linux rendszerű virtuális géphez

• A domainNameLabel nyilvános IP-címek tulajdonságának egyedinek kell lennie. Az domainNameLabel értéknek 3 és 63 karakter közötti hosszúságúnak kell lennie, és kövesse az ebben a reguláris kifejezésben megadott szabályokat: ^[a-z][a-z0-9-]{1,61}[a-z0-9]$. Mivel a uniqueString függvény egy 13 karakter hosszú sztringet hoz létre, a dnsPrefixString paraméter legfeljebb 50 karakter hosszúságú lehet.

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

• Amikor jelszót ad hozzá egy egyéni szkriptbővítményhez, használja a commandToExecute tulajdonság tulajdonságát 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'))]"
    }
  }
  

  Feljegyzés

  Annak érdekében, hogy a titkos kulcsok titkosítva legyenek, amikor azok paraméterekként vannak átadva a virtuális gépeknek és bővítményeknek, használja a protectedSettings megfelelő bővítmények tulajdonságát.

• Adjon meg explicit értékeket azokhoz a tulajdonságokhoz, amelyek alapértelmezett értékei idővel változhatnak. Ha például egy AKS-fürtöt helyez üzembe, megadhatja vagy kihagyhatja a tulajdonságot kubernetesVersion . Ha nem adja meg, akkor a fürt alapértelmezés szerint az N-1 alverzió és a legújabb javítás lesz. Ha ARM-sablonnal telepíti a fürtöt, előfordulhat, hogy ez az alapértelmezett viselkedés nem az elvárt. A sablon ismételt üzembe helyezése azt eredményezheti, hogy a fürt váratlanul frissítve lesz egy új Kubernetes-verzióra. Ehelyett fontolja meg egy explicit verziószám megadását, majd manuálisan módosítsa, amikor készen áll a fürt frissítésére.

Megjegyzések

A tulajdonság mellett a comments// szintaxist használó megjegyzések is támogatottak. A megjegyzésekről és a metaadatokról további információt az ARM-sablonok szerkezetének és szintaxisának ismertetése című témakörben talál. A fájlkiterjesztés használatával mentheti a .jsonc megjegyzéseket tartalmazó // JSON-fájlokat, hogy jelezze, hogy a JSON-fájl megjegyzéseket tartalmaz. Az ARM-szolgáltatás bármely JSON-fájlban, beleértve a paraméterfájlokat is, megjegyzéseket is elfogad.

Visual Studio Code ARM-eszközök

Az ARM-sablonok használata sokkal egyszerűbb az Azure Resource Manager (ARM) Visual Studio Code-eszközökkel. Ez a bővítmény nyelvi támogatást, erőforrás-kódrészleteket és automatikus erőforrás-kiegészítést biztosít az Azure Resource Manager-sablonok létrehozásához és érvényesítéséhez. További információkért és a bővítmény telepítéséhez tekintse meg az Azure Resource Manager (ARM) eszközeit.

Teszteszközkészlet használata

Az ARM-sablontesztelési eszközkészlet egy olyan szkript, amely ellenőrzi, hogy a sablon az ajánlott eljárásokat használja-e. Ha a sablon nem felel meg az ajánlott eljárásoknak, a javasolt módosításokat tartalmazó figyelmeztetések listáját adja vissza. A tesztelési eszközkészlet segítségével megtudhatja, hogyan valósíthat meg ajánlott eljárásokat a sablonban.

Miután befejezte a sablont, futtassa a teszteszközkészletet, és ellenőrizze, hogy van-e mód a megvalósítás javítására. További információ: ARM-sablontesztelési eszközkészlet használata.

Következő lépések

• A sablonfájl szerkezetéről további információt az ARM-sablonok szerkezetének és szintaxisának ismertetése című témakörben talál.
• Az összes Azure-felhőkörnyezetben működő sablonok készítésére vonatkozó javaslatokért tekintse meg az ARM-sablonok felhőkonzisztenciához való fejlesztését ismertető témakört.