Best practices voor ARM-sjablonen

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

Limieten voor sjablonen

Beperk de grootte van uw sjabloon tot 4 MB en elke resourcedefinitie tot 1 MB. De limieten zijn 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. Mogelijk krijgt u een fout met een sjabloon of parameterbestand van minder dan 4 MB als de totale grootte van de aanvraag te groot is. Zie Fouten oplossen voor taakgrootte overschreden 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
• 10 unieke locaties per abonnement/tenant/beheergroepbereik
• 24.576 tekens in een sjabloonexpressie

U kunt enkele limieten voor sjablonen overschrijden met behulp van een geneste sjabloon. Voor meer informatie raadpleegt u Gekoppelde en geneste sjablonen gebruiken bij het implementeren van Azure-resources. 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. Als u het risico wilt minimaliseren, zoekt u uw resourcegroep en resources in dezelfde regio.

Parameters

De informatie in deze sectie kan handig 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."
      }
    }
  }
  

• Standaardwaarden definiëren 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. Elke 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"
     }
  }
  

• Gebruik allowedValues spaarzaam. Gebruik dit alleen als u ervoor moet zorgen dat sommige waarden niet zijn opgenomen in de toegestane opties. Als u te breed gebruikt allowedValues , 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 navoegsel FromTemplate toe te voegen aan de sjabloonparameter. Als u bijvoorbeeld een parameter met de naam ResourceGroupName opneemt 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.

Beveiligingsaanbeveling voor parameters

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

• Gebruiken securestring voor alle wachtwoorden en geheimen. Als u gevoelige gegevens in een JSON-object doorgeeft, gebruikt u het secureObject type. Sjabloonparameters met beveiligde tekenreeks- 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 waarden waarvoor een secureString type is vereist.

• Geef geen standaardwaarden op voor eigenschappen die de kwetsbaarheid voor aanvallen van de toepassing vergroten.

Locatieaanbeveling voor parameters

• Gebruik een parameter om de locatie voor resources op te geven en stel de standaardwaarde in op resourceGroup().location. Als u een locatieparameter opgeeft, kunnen gebruikers van de sjabloon een locatie opgeven waar ze gemachtigd zijn 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. Op deze manier wordt het aantal keren dat gebruikers wordt gevraagd om locatiegegevens op te geven geminimaliseerd.

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

Variabelen

De volgende informatie kan handig 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 eenmaal wordt gebruikt, is de sjabloon gemakkelijker te lezen met een in code vastgelegde waarde.

• 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 verwijzingsfunctie niet gebruiken in de variables sectie van de sjabloon. De reference functie ontleent de waarde aan de runtimestatus van de resource. Variabelen worden echter opgelost tijdens het initiële parseren van de sjabloon. Maak waarden die de reference functie rechtstreeks in de resources sectie of outputs van de sjabloon nodig 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 vastgelegde API-versie voor het resourcetype. Wanneer u een nieuwe sjabloon maakt, wordt u aangeraden de nieuwste API-versie te gebruiken voor een resourcetype. Zie sjabloonreferentie 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 wijzigingen die fouten veroorzaken die mogelijk in latere versies worden geïntroduceerd.

Gebruik geen parameter voor de API-versie. Resource-eigenschappen en -waarden kunnen variëren per API-versie. IntelliSense in een code-editor kan niet het juiste schema bepalen wanneer de API-versie is ingesteld op een parameter. Als u een API-versie doorgeeft die niet overeenkomt 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 u wilt instellen:

• 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 dependsOn element toe wanneer u al een impliciete afhankelijkheid hebt gedefinieerd. Deze benadering 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 waarvoor het voorwaardeelement is ingesteld op false , worden automatisch verwijderd uit de afhankelijkheidsvolgorde. Stel de afhankelijkheden in alsof de resource altijd wordt geïmplementeerd.

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

• Als een waarde kan worden bepaald vóór de implementatie, probeert u de resource zonder een afhankelijkheid te implementeren. 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 verifiëren. Als u een foutmelding krijgt, 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 comments in het doel 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 uw ARM-sjabloon is opgeslagen in een .jsonc bestand, worden opmerkingen met behulp van de // syntaxis ondersteund, zoals hier wordt weergegeven.

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

  Zie Inzicht in de structuur en syntaxis van ARM-sjablonen voor meer informatie over opmerkingen en metagegevens.

• Als u een openbaar eindpunt in uw sjabloon gebruikt (zoals een openbaar eindpunt van Azure Blob Storage), moet u de naamruimte niet in code schrijven . 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 apiVersion niet op te geven wanneer u naar de 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 dat zich in een andere resourcegroep bevindt.

  "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 voor administratieve doeleinden, gebruikt u binnenkomende NAT-regels, een virtuele netwerkgateway of een jumpbox.

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

  • Wat is Azure Bastion?
  • Verbinding maken met en aanmelden bij een virtuele Azure-machine met Windows
  • WinRM-toegang instellen voor Virtual Machines in Azure Resource Manager
  • Verbinding maken met een Linux-VM

• De domainNameLabel eigenschap voor openbare IP-adressen moet uniek zijn. De domainNameLabel waarde moet tussen 3 en 63 tekens lang zijn en moet voldoen aan de regels die zijn opgegeven door deze reguliere expressie: ^[a-z][a-z0-9-]{1,61}[a-z0-9]$. Omdat de uniqueString functie een tekenreeks van 13 tekens genereert, is de dnsPrefixString parameter beperkt tot 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 de commandToExecute eigenschap in de protectedSettings eigenschap.

  "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 protectedSettings relevante extensies om ervoor te zorgen dat geheimen worden versleuteld wanneer ze als parameters worden doorgegeven aan VM's en extensies.

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

Opmerkingen

Naast de comments eigenschap worden opmerkingen met behulp van de // syntaxis ondersteund. Zie Inzicht in de structuur en syntaxis van ARM-sjablonen voor meer informatie over opmerkingen en metagegevens. U kunt ervoor kiezen om JSON-bestanden met opmerkingen op te slaan met behulp van de .jsonc bestandsextensie, om aan te geven dat // het JSON-bestand opmerkingen bevat. De ARM-service accepteert ook opmerkingen in elk JSON-bestand, inclusief parametersbestanden.

ARM-hulpprogramma's voor Visual Studio Code

Werken met ARM-sjablonen is veel eenvoudiger met de Arm-hulpprogramma's (Azure Resource Manager) voor Visual Studio Code. Deze extensie biedt taalondersteuning, resourcefragmenten en automatisch aanvullen van resources om u te helpen Bij het maken en valideren van Azure Resource Manager-sjablonen. Zie Hulpprogramma's voor Azure Resource Manager (ARM) voor meer informatie en het installeren van de extensie.

Test-toolkit gebruiken

De testtoolkit voor ARM-sjablonen is een script waarmee wordt gecontroleerd of uw sjabloon gebruikmaakt van aanbevolen procedures. Wanneer uw sjabloon niet compatibel is met aanbevolen procedures, wordt een lijst met waarschuwingen met voorgestelde wijzigingen geretourneerd. De test-toolkit kan u helpen bij het implementeren van best practices in uw sjabloon.

Nadat u de sjabloon hebt voltooid, voert u de test-toolkit uit om te zien of er manieren zijn waarop u de implementatie ervan kunt verbeteren. Zie Use ARM template test toolkit (Test-toolkit voor ARM-sjablonen 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.