Share via

Best practices voor ARM-sjablonen

  • Artikel

In dit artikel leest u hoe u aanbevolen procedures gebruikt bij het maken van uw Arm-sjabloon (Azure Resource Manager). 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 gelden voor 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 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."
    }
  }
}

  • 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. 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 samen te stellen.

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

  • Gebruik allowedValues spaarzaam. Gebruik deze alleen als u ervoor moet zorgen dat bepaalde 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 postfix FromTemplate toe te voegen aan de sjabloonparameter. Als u bijvoorbeeld een parameter met de naam ResourceGroupName in uw sjabloon opneemt, conflicteert deze met de parameter ResourceGroupName in de cmdlet New-AzResourceGroupDeployment. Tijdens de implementatie wordt u gevraagd om een waarde op te geven voor ResourceGroupNameFromTemplate.

Aanbevelingen voor beveiliging voor parameters

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

  • Gebruik 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 resources.

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

  • Geef geen standaardwaarden op voor gebruikersnamen, wachtwoorden of andere waarden waarvoor een secureString type is vereist.

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

Locatieaan aanbevelingen voor parameters

  • Gebruik een parameter om de locatie voor resources op te geven en stel de standaardwaarde resourceGroup().locationin op . 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 beschikbaar in alle clouds.

  • Gebruik de waarde van de locatieparameter voor resources die zich waarschijnlijk op dezelfde locatie bevinden. Deze aanpak minimaliseert het aantal keren dat gebruikers worden gevraagd om locatiegegevens op te geven.

  • Voor resources die niet beschikbaar zijn op alle locaties, 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 variabele namen.

  • 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 in variabelen wordt weergegeven.

  • U kunt de verwijzingsfunctie niet gebruiken in de variables sectie van de sjabloon. De reference functie leidt de waarde af van de runtimestatus van de resource. Variabelen worden echter opgelost tijdens de eerste parsering van de sjabloon. Maak waarden die de reference functie rechtstreeks in de resources of outputs sectie 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 eigenschap apiVersion in op een hard gecodeerde API-versie voor het resourcetype. Wanneer u een nieuwe sjabloon maakt, wordt u aangeraden de nieuwste API-versie voor een resourcetype te gebruiken. Als u de beschikbare waarden wilt bepalen, raadpleegt u de sjabloonreferentie.

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 mogelijk in latere versies 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 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 wanneer u bepaalt welke afhankelijkheden u wilt instellen:

  • Gebruik de functie reference 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 aanpak vermindert het risico dat er onnodige afhankelijkheden zijn. 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 waarop het voorwaardeelement is ingesteld false , worden automatisch verwijderd uit de afhankelijkheidsvolgorde. Stel de afhankelijkheden in alsof de resource altijd wordt geïmplementeerd.

  • Laat afhankelijkheden trapsgewijs worden uitgevoerd 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. De virtuele machine wordt daarom na alle drie de resources geïmplementeerd, maar stel de virtuele machine niet expliciet in als afhankelijk van alle drie de resources. Deze aanpak verduidelijkt de afhankelijkheidsvolgorde en maakt het later gemakkelijker om de sjabloon te wijzigen.

  • Als een waarde kan worden bepaald vóór de implementatie, probeert u de resource te implementeren zonder een 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 u een fout ontvangt, voegt u een afhankelijkheid toe.

Resources

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

  • Geef comments voor elke resource in de sjabloon op om andere inzenders inzicht te geven 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 voor Azure Blob Storage), moet u de naamruimte niet hardcodeeren . 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 wordt 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 naamruimte van de provider 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 beheerdoeleinden, gebruikt u inkomende NAT-regels, een virtuele netwerkgateway of een jumpbox.

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

  • De domainNameLabel eigenschap voor openbare IP-adressen moet uniek zijn. De domainNameLabel waarde moet tussen 3 en 63 tekens lang zijn en de regels volgen die zijn opgegeven 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 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 protectedSettings eigenschap van de relevante extensies om ervoor te zorgen dat geheimen worden versleuteld wanneer ze worden doorgegeven als parameters voor VM's en extensies.

  • Geef expliciete waarden op voor eigenschappen met standaardwaarden die na verloop van tijd kunnen worden gewijzigd. Als u bijvoorbeeld een AKS-cluster implementeert, kunt u de kubernetesVersion eigenschap opgeven of weglaten. Als u dit niet opgeeft, wordt het cluster standaard ingesteld op de secundaire N-1-versie en 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 implementeren van uw sjabloon kan ertoe leiden dat het cluster onverwacht wordt bijgewerkt naar een nieuwe Kubernetes-versie. U kunt in plaats daarvan een expliciet versienummer opgeven en dit vervolgens handmatig 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 op te slaan die opmerkingen bevatten // met behulp van de .jsonc bestandsextensie, om aan te geven dat het JSON-bestand opmerkingen bevat. De ARM-service accepteert ook opmerkingen in een JSON-bestand, inclusief parametersbestanden.

ARM-hulpprogramma's voor Visual Studio Code

Het 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 Azure Resource Manager-sjablonen te maken en te valideren. Zie Azure Resource Manager -hulpprogramma's (ARM) voor meer informatie en het installeren van de extensie.

Test-toolkit gebruiken

De TEST-toolkit voor ARM-sjablonen 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 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 Test-toolkit voor ARM-sjablonen gebruiken voor meer informatie.

Volgende stappen