Best practices voor ARM-sjablonen

In dit artikel wordt beschreven hoe u aanbevolen procedures gebruikt bij het maken van uw Azure Resource Manager (ARM-sjabloon). Met deze aanbevelingen kunt u veelvoorkomende problemen voorkomen wanneer u een ARM-sjabloon gebruikt om een oplossing te implementeren.

Limieten voor sjablonen

Beperk de grootte van uw sjabloon tot 4 MB. De limiet van 4 MB is van toepassing op de uiteindelijke status van de sjabloon nadat deze is uitgebreid met iteratieve resourcedefinities en waarden voor variabelen en parameters. Het parameterbestand is ook beperkt tot 4 MB. Er kan een foutbericht worden weergegeven met een sjabloon of parameterbestand van minder dan 4 MB, als de totale grootte van de aanvraag te groot is. Zie Resolve errors for job size exceeded(Fouten oplossen voor overschreden taakgrootte) voor meer informatie over het vereenvoudigen van uw sjabloon om een grote aanvraag te voorkomen.

U bent ook beperkt tot:

• 256 parameters
• 256 variabelen
• 800 resources (inclusief het aantal kopieën)
• 64 uitvoerwaarden
• 24.576 tekens in een sjabloonexpressie

U kunt enkele limieten voor sjablonen overschrijden met behulp van een geneste sjabloon. Zie Gekoppelde en geneste sjablonen gebruiken bij het implementeren van Azure-resources voor meer informatie. Als u het aantal parameters, variabelen of uitvoerwaarden wilt verkleinen, kunt u verschillende waarden combineren in een object. Raadpleeg Objects as parameters (Objecten als parameters) voor meer informatie.

Resourcegroep

Wanneer u resources implementeert in een resourcegroep, slaat de resourcegroep metagegevens over de resources op. De metagegevens worden opgeslagen op de locatie van de resourcegroep.

Als de regio van de resourcegroep tijdelijk niet beschikbaar is, kunt u resources in de resourcegroep niet bijwerken, omdat de metagegevens niet beschikbaar zijn. De resources in andere regio's werken nog steeds zoals verwacht, maar u kunt ze niet bijwerken. Om het risico te minimaliseren, zoekt u uw resourcegroep en resources in dezelfde regio.

Parameters

De informatie in deze sectie kan nuttig zijn wanneer u met parameters werkt.

Algemene aanbevelingen voor parameters

• Minimaliseer het gebruik van parameters. Gebruik in plaats daarvan variabelen of letterlijke waarden voor eigenschappen die niet hoeven te worden opgegeven tijdens de implementatie.

• Gebruik camel case voor parameternamen.

• Gebruik parameters voor instellingen die variëren afhankelijk van de omgeving, zoals SKU, grootte en capaciteit.

• Gebruik parameters voor resourcenamen die u wilt opgeven voor eenvoudige identificatie.

• Geef een beschrijving op van elke parameter in de metagegevens.

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

• Definieer standaardwaarden voor parameters die niet gevoelig zijn. Door een standaardwaarde op te geven, is het eenvoudiger om de sjabloon te implementeren en zien gebruikers van uw sjabloon een voorbeeld van een geschikte waarde. Een standaardwaarde voor een parameter moet geldig zijn voor alle gebruikers in de standaardimplementatieconfiguratie.

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

• Als u een optionele parameter wilt opgeven, gebruikt u geen lege tekenreeks als standaardwaarde. Gebruik in plaats daarvan een letterlijke waarde of een taalexpressie om een waarde te maken.

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

• Spaarzaam allowedValues gebruiken. Gebruik deze optie alleen wanneer u ervoor moet zorgen dat sommige waarden niet zijn opgenomen in de toegestane opties. Als u te allowedValues breed gebruikt, kunt u geldige implementaties blokkeren door uw lijst niet up-to-date te houden.

• Wanneer een parameternaam in uw sjabloon overeenkomt met een parameter in de PowerShell-implementatieopdracht, lost Resource Manager dit naamconflict op door het postfix FromTemplate toe te voegen aan de sjabloonparameter. Als u bijvoorbeeld een parameter met de naam ResourceGroupName opgeeft in uw sjabloon, conflicteert deze met de parameter ResourceGroupName in de cmdlet New-AzResourceGroupDeployment. Tijdens de implementatie wordt u gevraagd een waarde op te geven voor ResourceGroupNameFromTemplate.

Beveiligingsaanbevelingen voor parameters

• Gebruik altijd parameters voor gebruikersnamen en wachtwoorden (of geheimen).

• Gebruik securestring voor alle wachtwoorden en geheimen. Als u gevoelige gegevens door te geven in een JSON-object, gebruikt u het secureObject type . Sjabloonparameters met beveiligde tekenreeksen of beveiligde objecttypen kunnen niet worden gelezen na de implementatie van de resource.

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

• Geef geen standaardwaarden op voor gebruikersnamen, wachtwoorden of een waarde die een secureString type vereist.

• Geef geen standaardwaarden op voor eigenschappen die het aantal aanvallen surface area van de toepassing verhogen.

Locatieaanbevelingen voor parameters

• Gebruik een parameter om de locatie voor resources op te geven en stel de standaardwaarde in op resourceGroup().location . Door een locatieparameter op te geven, kunnen gebruikers van de sjabloon een locatie opgeven waar ze machtigingen hebben om resources te implementeren.

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

• Geef niet op allowedValues voor de locatieparameter. De locaties die u opgeeft, zijn mogelijk niet in alle clouds beschikbaar.

• Gebruik de waarde van de locatieparameter voor resources die zich waarschijnlijk op dezelfde locatie bevinden. Met deze aanpak wordt het aantal keren dat gebruikers wordt gevraagd om locatiegegevens op te geven geminimaliseerd.

• Voor resources die niet in alle locaties beschikbaar zijn, gebruikt u een afzonderlijke parameter of geeft u een letterlijke locatiewaarde op.

Variabelen

De volgende informatie kan nuttig zijn wanneer u met variabelen werkt:

• Gebruik camel case voor namen van variabelen.

• Gebruik variabelen voor waarden die u meer dan één keer in een sjabloon moet gebruiken. Als een waarde slechts één keer wordt gebruikt, maakt een in code gecodeerde waarde uw sjabloon gemakkelijker te lezen.

• Gebruik variabelen voor waarden die u maakt op basis van een complexe rangschikking van sjabloonfuncties. Uw sjabloon is gemakkelijker te lezen wanneer de complexe expressie alleen wordt weergegeven in variabelen.

• U kunt de referentiefunctie niet gebruiken in de variables sectie van de sjabloon. De reference functie is afgeleid van de waarde van de runtime-status van de resource. Variabelen worden echter opgelost tijdens de eerste parsering van de sjabloon. Waarden maken die de functie reference rechtstreeks in de sectie of van de sjabloon nodig resources outputs hebben.

• Neem variabelen op voor resourcenamen die uniek moeten zijn.

• Gebruik een kopieerlus in variabelen om een herhaald patroon van JSON-objecten te maken.

• Verwijder ongebruikte variabelen.

API-versie

Stel de apiVersion eigenschap in op een in code gecodeerde API-versie voor het resourcetype. Wanneer u een nieuwe sjabloon maakt, wordt u aangeraden de nieuwste API-versie voor een resourcetype te gebruiken. Zie sjabloonverwijzing om de beschikbare waarden te bepalen.

Wanneer uw sjabloon werkt zoals verwacht, raden we u aan dezelfde API-versie te blijven gebruiken. Als u dezelfde API-versie gebruikt, hoeft u zich geen zorgen te maken over belangrijke wijzigingen die in latere versies kunnen worden geïntroduceerd.

Gebruik geen parameter voor de API-versie. Resource-eigenschappen en -waarden kunnen per API-versie verschillen. IntelliSense in een code-editor kan het juiste schema niet bepalen wanneer de API-versie is ingesteld op een parameter. Als u een API-versie door geeft die niet overeen komt met de eigenschappen in uw sjabloon, mislukt de implementatie.

Gebruik geen variabelen voor de API-versie.

Bronafhankelijkheden

Gebruik de volgende richtlijnen bij het bepalen van de afhankelijkheden die moeten worden ingesteld:

• Gebruik de reference functie en geef de resourcenaam door om een impliciete afhankelijkheid in te stellen tussen resources die een eigenschap moeten delen. Voeg geen expliciet element dependsOn toe wanneer u al een impliciete afhankelijkheid hebt gedefinieerd. Deze aanpak vermindert het risico op onnodige afhankelijkheden. Zie referentie- en lijstfuncties voor een voorbeeld van het instellen van een impliciete afhankelijkheid.

• Stel een onderliggende resource in als afhankelijk van de bovenliggende resource.

• Resources met het voorwaardeelement ingesteld op false worden automatisch verwijderd uit de afhankelijkheidsorder. Stel de afhankelijkheden in alsof de resource altijd wordt geïmplementeerd.

• Afhankelijkheden trapsgevat laten worden zonder ze expliciet in te stellen. Uw virtuele machine is bijvoorbeeld afhankelijk van een virtuele netwerkinterface en de virtuele netwerkinterface is afhankelijk van een virtueel netwerk en openbare IP-adressen. Daarom wordt de virtuele machine na alle drie de resources geïmplementeerd, maar stelt u de virtuele machine niet expliciet in als afhankelijk van alle drie de resources. Deze aanpak verduidelijkt de afhankelijkheidsorder en maakt het gemakkelijker om de sjabloon later te wijzigen.

• Als een waarde kan worden bepaald vóór de implementatie, implementeert u de resource zonder afhankelijkheid. Als een configuratiewaarde bijvoorbeeld de naam van een andere resource nodig heeft, hebt u mogelijk geen afhankelijkheid nodig. Deze richtlijnen werken niet altijd omdat sommige resources het bestaan van de andere resource controleren. Als er een foutmelding wordt weergegeven, voegt u een afhankelijkheid toe.

Resources

De volgende informatie kan nuttig zijn wanneer u met resources werkt:

• Geef voor elke resource in de sjabloon op om andere inzenders inzicht te geven in het doel comments van de resource.

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

• Als u een openbaar eindpunt in uw sjabloon gebruikt (zoals een openbaar eindpunt voor Azure Blob Storage), moet u de naamruimte niet in code code opslaan. Gebruik de reference functie om de naamruimte dynamisch op te halen. U kunt deze methode gebruiken om de sjabloon te implementeren in verschillende openbare naamruimteomgevingen zonder het eindpunt in de sjabloon handmatig te wijzigen. Stel de API-versie in op dezelfde versie die u gebruikt voor het opslagaccount in uw sjabloon.

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

  Als het opslagaccount is geïmplementeerd in dezelfde sjabloon die u maakt en de naam van het opslagaccount niet wordt gedeeld met een andere resource in de sjabloon, hoeft u de providernaamruimte of de niet op te geven wanneer u naar de apiVersion resource verwijst. In het volgende voorbeeld ziet u de vereenvoudigde syntaxis.

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

  U kunt ook verwijzen naar een bestaand opslagaccount in een andere resourcegroep.

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

• Wijs openbare IP-adressen alleen toe aan een virtuele machine wanneer een toepassing dit vereist. Als u verbinding wilt maken met een virtuele machine (VM) voor debuggen, of voor beheer- of beheerdoeleinden, gebruikt u inkomende NAT-regels, een virtuele netwerkgateway of een jumpbox.

  Zie voor meer informatie over het maken van verbinding met virtuele machines:

  • VM's uitvoeren voor een architectuur met meerdere lagen in Azure
  • WinRM-toegang instellen voor VM's in Azure Resource Manager
  • Externe toegang tot uw VM toestaan met behulp van de Azure Portal
  • Externe toegang tot uw VM toestaan met behulp van PowerShell
  • Externe toegang tot uw Linux-VM toestaan met behulp van Azure CLI

• De domainNameLabel eigenschap voor openbare IP-adressen moet uniek zijn. De waarde moet tussen de 3 en 63 tekens lang zijn en de regels volgen die zijn opgegeven domainNameLabel door deze reguliere expressie: ^[a-z][a-z0-9-]{1,61}[a-z0-9]$ . Omdat de uniqueString functie een tekenreeks genereert die 13 tekens lang is, is de parameter beperkt tot dnsPrefixString 50 tekens.

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

• Wanneer u een wachtwoord toevoegt aan een aangepaste scriptextensie, gebruikt u commandToExecute de eigenschap in de eigenschap 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'))]"
    }
  }
  

  Notitie

  Gebruik de eigenschap van de relevante extensies om ervoor te zorgen dat geheimen worden versleuteld wanneer ze als parameters worden doorgegeven aan VM's protectedSettings en extensies.

• Geef expliciete waarden op voor eigenschappen met standaardwaarden die na een periode kunnen worden gewijzigd. Als u bijvoorbeeld een AKS-cluster implementeert, kunt u de eigenschap opgeven of kubernetesVersion weglaten. Als u dit niet opgeeft, wordt het cluster standaard ingesteld op de secundaire versie van N-1en de meest recente patch . Wanneer u het cluster implementeert met behulp van een ARM-sjabloon, is dit standaardgedrag mogelijk niet wat u verwacht. Het opnieuw toepassen van uw sjabloon kan ertoe leiden dat het cluster onverwacht wordt bijgewerkt naar een nieuwe Kubernetes-versie. In plaats daarvan kunt u overwegen een expliciet versienummer op te geven en dit vervolgens handmatig te wijzigen wanneer u klaar bent om uw cluster bij te werken.

Test toolkit gebruiken

De arm-sjabloontesttoolkit is een script waarmee wordt gecontroleerd of uw sjabloon gebruikmaakt van aanbevolen procedures. Wanneer uw sjabloon niet voldoet aan aanbevolen procedures, wordt er een lijst met waarschuwingen met voorgestelde wijzigingen weergegeven. De testtoolkit kan u helpen bij het implementeren van best practices in uw sjabloon.

Nadat u de sjabloon hebt voltooid, kunt u de testtoolkit uitvoeren om te zien of er manieren zijn waarop u de implementatie ervan kunt verbeteren. Zie Use ARM template test toolkit (Arm-sjabloontesttoolkit gebruiken) voor meer informatie.

Volgende stappen

• Zie Inzicht in de structuur en syntaxis van ARM-sjablonen voor meer informatie over de structuur van het sjabloonbestand.
• Zie ARM-sjablonen ontwikkelen voor cloudconsistentie voor aanbevelingen over het bouwen van sjablonen die in alle Azure-cloudomgevingen werken.