AJÁNLOTT ELJÁRÁSOK AZ ARM-sablonhoz

  • Cikk

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ás-definí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
  • Előfizetés/bérlő/felügyeleti csoport hatóköreként 10 egyedi hely
  • 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.

Paraméterekre vonatkozó általános javaslatok

  • 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 erőforrásnevekhez.

  • Adja meg a metaadatok összes paraméterének leírását.

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

  • A nem bizalmas paraméterek alapértelmezett értékeinek meghatározása. Az alapértelmezett érték megadásával könnyebb üzembe helyezni a sablont, és a sablon felhasználói láthatnak egy példát a megfelelő értékre. A paraméterek alapértelmezett értékének érvényesnek kell lennie az alapértelmezett üzembehelyezési konfigurációban lévő ö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."
    }
  }
}

  • Ha nem kötelező paramétert szeretne megadni, ne használjon üres sztringet alapértelmezett értékként. Ehelyett használjon literálértéket vagy nyelvkifejezé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áljon allowedValues 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, Resource Manager feloldja ezt az elnevezési ütközést a FromTemplate postfix sablonparaméterhez való hozzáadásával. 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).

  • Minden jelszóhoz és titkos kódhoz használható securestring . 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 értékre resourceGroup().location. A 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éhez.

    "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 megközelítés minimálisra csökkenti azt a számot, amikor a felhasználókat a helyadatok megadására kérik fel.

  • Olyan erőforrások esetében, amelyek nem érhetők el minden helyen, 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:

  • Változónevekhez használjon tevees esetet.

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

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

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

  • Adja meg az egyedi erőforrásnevek változóit.

  • 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ípushoz tartozó, kódolt API-verzióra. Új sablon létrehozásakor javasoljuk, hogy egy erőforrástípushoz a legújabb API-verziót használja. Az elérhető é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. Ha ugyanazt az API-verziót használja, nem kell aggódnia a későbbi verziókban esetlegesen 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 az API-verziótól függően változhatnak. A kódszerkesztőben lévő 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:

  • Használja a függvényt reference , és adja meg az erőforrás nevét a tulajdonság megosztásához szükséges erőforrások közötti implicit függőség beállításához. 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. Implicit függőség beállítására példa: referencia- és listafüggvények.

  • Állítson be egy gyermekerőforrást a szülőerőforrástól függőként.

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

  • Hagyja, hogy a függőségek kaszkádoltak legyenek anélkül, hogy explicit módon beállítanák őket. 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 egy 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 explicit módon úgy, hogy a virtuális gép mind a három erőforrástól függ. 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, előfordulhat, hogy nincs szükség 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:

  • Ha más közreműködőknek szeretné megérteni az erőforrás célját, adja meg comments a sablonban szereplő egyes erőforrásokat.

    "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 egy nyilvános Azure Blob Storage-végpontot), ne kódolt 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érkörnyezetekben anélkül, hogy manuálisan módosítaná a sablon végpontját. Állítsa az API-verziót arra a verzióra, amelyet a sablon tárfiókjához használ.

    "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 ön hoz létre, és a tárfiók neve nincs megosztva a sablon egy másik erőforrásával, nem kell megadnia a szolgáltatói névteret vagy a apiVersion nevet, amikor az erőforrásra hivatkozik. 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]"
  }
}

  • Csak akkor rendeljen nyilvános IP-címeket 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:

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

    Megjegyzés

    Annak érdekében, hogy a titkos kulcsok titkosítva legyenek, amikor 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óra és a legújabb javításra lesz bekapcsolva. Ha ARM-sablonnal helyezi üzembe a fürtöt, előfordulhat, hogy ez az alapértelmezett viselkedés nem a várt módon működik. Ha újra üzembe helyezi a sablont, a fürt váratlanul új Kubernetes-verzióra frissülhet. 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, jelezve, hogy a JSON-fájl megjegyzéseket tartalmaz. Az ARM-szolgáltatás megjegyzéseket is elfogad minden JSON-fájlban, beleértve a paraméterfájlokat is.

Visual Studio Code ARM-eszközök

Az ARM-sablonok használata sokkal egyszerűbb a Visual Studio Code-hoz készült Azure Resource Manager (ARM) 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 ismertető cikket.

Tesztelési eszkö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.

A sablon befejezése után futtassa a tesztelési eszközkészletet, és ellenőrizze, hogy vannak-e olyan módszerek, amelyekkel javíthatja a megvalósítást. További információ: Arm-sablontesztelési eszközkészlet használata.

Következő lépések