Aanbevolen procedures voor ARM-sjablonen

In dit artikel wordt beschreven hoe u aanbevolen procedures gebruikt bij het maken van uw Azure Resource Manager-sjabloon (ARM-sjabloon). Met deze aanbevelingen kunt u veelvoorkomende problemen 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. 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. 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 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 een waarde op te geven voor ResourceGroupNameFromTemplate.

Beveiligingsaanveling voor parameters

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

  • Gebruiken securestring voor alle wachtwoorden en geheimen. Als u gevoelige gegevens doorgeeft in een JSON-object, 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 de kwetsbaarheid voor aanvallen van de toepassing vergroten.

Locatieaanaanveling 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 beschikbaar in alle clouds.

  • Gebruik de waarde van de locatieparameter voor resources die zich waarschijnlijk op dezelfde locatie bevinden. Deze benadering minimaliseert het aantal keren dat gebruikers wordt 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 nuttig 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, maakt een in code vastgelegde 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 in variabelen wordt weergegeven.

  • U kunt de verwijzingsfunctie niet gebruiken in de variables sectie van de sjabloon. De reference functie is afgeleid 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.

  • Ongebruikte variabelen verwijderen.

API-versie

Stel de apiVersion eigenschap in op een in code vastgelegde API-versie voor het resourcetype. Bij het maken van een nieuwe sjabloon raden we u aan de nieuwste API-versie voor een resourcetype te gebruiken. Zie de 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 in latere versies kunnen 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 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 bij het bepalen van welke afhankelijkheden 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 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 trapsgewijs worden ingesteld zonder deze 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 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 eenvoudiger om de sjabloon te wijzigen.

  • Als vóór de implementatie een waarde kan worden bepaald, kunt u proberen de resource zonder 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 controleren. Als er een fout optreedt, 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 van de resource comments .

    "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 De structuur en syntaxis van ARM-sjablonen begrijpen voor meer informatie over opmerkingen en metagegevens.

  • Als u een openbaar eindpunt in uw sjabloon gebruikt (zoals een openbaar eindpunt voor Azure Blob Storage), hoeft u de naamruimte niet hardcode te gebruiken . 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 handmatig in de sjabloon 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 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 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:

  • De domainNameLabel eigenschap voor openbare IP-adressen moet uniek zijn. De domainNameLabel waarde moet tussen 3 en 63 tekens lang zijn en 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 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 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 het cluster standaard ingesteld op de secundaire versie N-1 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. In plaats daarvan kunt u een expliciet versienummer opgeven en het 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 De structuur en syntaxis van ARM-sjablonen begrijpen voor meer informatie over opmerkingen en metagegevens. U kunt ervoor kiezen om JSON-bestanden die opmerkingen bevatten // 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

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 u te helpen bij het maken en valideren van Azure Resource Manager-sjablonen. 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 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 om de implementatie ervan te verbeteren. Zie Test-toolkit voor ARM-sjablonen gebruiken voor meer informatie.

Volgende stappen