Best practices voor ARM-sjablonen

In dit artikel wordt beschreven 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. 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. 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 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, kunt u de sjabloon eenvoudiger 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 deze 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 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.

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 een waarde 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. Met deze benadering 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 variabelenamen.

  • 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 beter leesbaar 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 waarde van de reference functie wordt afgeleid van 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, raden we u aan de nieuwste API-versie voor een resourcetype te gebruiken. 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 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 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 trapsgewijs worden ingesteld 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 stel de virtuele machine niet expliciet in als afhankelijk van alle drie de resources. Deze benadering verduidelijkt de afhankelijkheidsvolgorde en maakt het gemakkelijker om de sjabloon later 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 foutmelding krijgt, voegt u een afhankelijkheid toe.

Resources

De volgende informatie kan handig 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), hoeft u de naamruimte niet hard te coden . 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 voor administratieve doeleinden verbinding wilt maken met een virtuele machine, gebruikt u binnenkomende 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 in 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 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 in de loop van de 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 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. Overweeg in plaats daarvan 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 Azure Resource Manager -hulpprogramma's (ARM) voor Visual Studio Code. Deze extensie biedt taalondersteuning, resourcefragmenten en automatisch aanvullen van resources, zodat u Azure Resource Manager-sjablonen kunt maken en valideren. Zie Azure Resource Manager (ARM) Tools (Azure Resource Manager) voor meer informatie en het installeren van de extensie.

Test-toolkit gebruiken

De TEST-toolkit voor ARM-sjablonen is een script dat controleert of uw sjabloon gebruikmaakt van aanbevolen procedures. Wanneer uw sjabloon niet voldoet aan de aanbevolen procedures, retourneert deze een lijst met waarschuwingen met voorgestelde wijzigingen. 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