Aanbevolen procedures voor Azure Resource Manager sjabloonAzure Resource Manager template best practices

Dit artikel bevat aanbevelingen voor het samen stellen van uw Resource Manager-sjabloon.This article gives recommendations about how to construct your Resource Manager template. Deze aanbevelingen helpen u veelvoorkomende problemen te voor komen wanneer u een sjabloon gebruikt om een oplossing te implementeren.These recommendations help you avoid common problems when using a template to deploy a solution.

Voor aanbevelingen over het beheren van uw Azure-abonnementen raadpleegt u Azure Enter prise-steigers: prescripted Subscription governance.For recommendations about how to govern your Azure subscriptions, see Azure enterprise scaffold: Prescriptive subscription governance.

Zie Azure Resource Manager sjablonen ontwikkelen voor Cloud consistentievoor aanbevelingen voor het maken van sjablonen die in alle Azure-Cloud omgevingen werken.For recommendations about how to build templates that work in all Azure cloud environments, see Develop Azure Resource Manager templates for cloud consistency.

Sjabloon limietenTemplate limits

Beperk de grootte van uw sjabloon tot 4 MB en elk parameter bestand tot 64 KB.Limit the size of your template to 4 MB, and each parameter file to 64 KB. De limiet van 4 MB is van toepassing op de uiteindelijke status van de sjabloon nadat deze is uitgebreid met iteratieve resource definities en waarden voor variabelen en para meters.The 4-MB limit applies to the final state of the template after it has been expanded with iterative resource definitions, and values for variables and parameters.

U bent ook beperkt tot:You're also limited to:

  • 256-para meters256 parameters
  • 256 variabelen256 variables
  • 800 bronnen (met inbegrip van het aantal kopieën)800 resources (including copy count)
  • 64 uitvoer waarden64 output values
  • 24.576 tekens in een sjabloon expressie24,576 characters in a template expression

U kunt enkele sjabloon limieten overschrijden met behulp van een geneste sjabloon.You can exceed some template limits by using a nested template. Zie voor meer informatie gekoppelde sjablonen gebruiken bij het implementeren van Azure-resources.For more information, see Using linked templates when deploying Azure resources. Als u het aantal para meters, variabelen of uitvoer wilt reduceren, kunt u verschillende waarden combi neren in een-object.To reduce the number of parameters, variables, or outputs, you can combine several values into an object. Zie objecten als para metersvoor meer informatie.For more information, see Objects as parameters.

ResourcegroepResource group

Wanneer u resources implementeert voor een resource groep, slaat de resource groep meta gegevens over de resources op.When you deploy resources to a resource group, the resource group stores metadata about the resources. De meta gegevens worden opgeslagen op de locatie van de resource groep.The metadata is stored in the location of the resource group.

Als de regio van de resource groep tijdelijk niet beschikbaar is, kunt u resources in de resource groep niet bijwerken omdat de meta gegevens niet beschikbaar zijn.If the resource group's region is temporarily unavailable, you can't update resources in the resource group because the metadata is unavailable. De resources in andere regio's zullen nog steeds werken zoals verwacht, maar u kunt ze niet bijwerken.The resources in other regions will still function as expected, but you can't update them. Als u het risico wilt minimaliseren, zoekt u de resource groep en de resources in dezelfde regio.To minimize risk, locate your resource group and resources in the same region.

ParametersParameters

De informatie in deze sectie kan nuttig zijn wanneer u met para meterswerkt.The information in this section can be helpful when you work with parameters.

Algemene aanbevelingen voor para metersGeneral recommendations for parameters

  • Minimaliseer het gebruik van para meters.Minimize your use of parameters. Gebruik in plaats daarvan variabelen of letterlijke waarden voor eigenschappen die tijdens de implementatie niet hoeven te worden opgegeven.Instead, use variables or literal values for properties that don't need to be specified during deployment.

  • Gebruik Camel-Case voor parameter namen.Use camel case for parameter names.

  • Gebruik para meters voor instellingen die variëren afhankelijk van de omgeving, zoals SKU, grootte of capaciteit.Use parameters for settings that vary according to the environment, like SKU, size, or capacity.

  • Gebruik para meters voor resource namen die u voor eenvoudige identificatie wilt opgeven.Use parameters for resource names that you want to specify for easy identification.

  • Geef een beschrijving op van elke para meter in de meta gegevens:Provide a description of every parameter in the metadata:

    "parameters": {
         "storageAccountType": {
             "type": "string",
             "metadata": {
                 "description": "The type of the new storage account created to store the VM disks."
             }
         }
    }
    
  • Standaard waarden definiëren voor para meters die niet gevoelig zijn.Define default values for parameters that aren't sensitive. Als u een standaard waarde opgeeft, is het eenvoudiger om de sjabloon te implementeren en zien gebruikers van uw sjabloon een voor beeld van een geschikte waarde.By specifying a default value, it's easier to deploy the template, and users of your template see an example of an appropriate value. Een standaard waarde voor een para meter moet geldig zijn voor alle gebruikers in de standaard implementatie configuratie.Any default value for a parameter must be valid for all users in the default deployment configuration.

    "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 para meter wilt opgeven, gebruikt u geen lege teken reeks als standaard waarde.To specify an optional parameter, don't use an empty string as a default value. Gebruik in plaats daarvan een letterlijke waarde of een taal expressie om een waarde te maken.Instead, use a literal value or a language expression to construct a value.

    "storageAccountName": {
       "type": "string",
       "defaultValue": "[concat('storage', uniqueString(resourceGroup().id))]",
       "metadata": {
         "description": "Name of the storage account"
       }
    },
    
  • Gebruik geen para meter voor de API-versie voor een resource type.Don't use a parameter for the API version for a resource type. De resource-eigenschappen en-waarden kunnen variëren per versie nummer.Resource properties and values can vary by version number. IntelliSense in een code-editor kan het juiste schema niet bepalen wanneer de API-versie is ingesteld op een para meter.IntelliSense in a code editor can't determine the correct schema when the API version is set to a parameter. In plaats daarvan wordt de API-versie in de sjabloon vastgelegd.Instead, hard-code the API version in the template.

  • Gebruik allowedValues spaarzaam.Use allowedValues sparingly. Gebruik deze alleen wanneer u moet controleren of sommige waarden niet zijn opgenomen in de toegestane opties.Use it only when you must make sure some values aren't included in the permitted options. Als u allowedValues te breed gebruikt, kunt u geldige implementaties blok keren door de lijst niet up-to-date te houden.If you use allowedValues too broadly, you might block valid deployments by not keeping your list up to date.

  • Wanneer een parameter naam in uw sjabloon overeenkomt met een para meter in de Power shell-implementatie opdracht, wordt deze naam conflicten opgelost door de achtervoegsel FromTemplate toe te voegen aan de sjabloon parameter.When a parameter name in your template matches a parameter in the PowerShell deployment command, Resource Manager resolves this naming conflict by adding the postfix FromTemplate to the template parameter. Als u bijvoorbeeld een para meter met de naam ResourceGroupName in uw sjabloon opneemt, wordt er een conflict veroorzaakt met de para meter ResourceGroupName in de cmdlet New-AzResourceGroupDeployment .For example, if you include a parameter named ResourceGroupName in your template, it conflicts with the ResourceGroupName parameter in the New-AzResourceGroupDeployment cmdlet. Tijdens de implementatie wordt u gevraagd om een waarde voor ResourceGroupNameFromTemplateop te geven.During deployment, you're prompted to provide a value for ResourceGroupNameFromTemplate.

Beveiligings aanbevelingen voor para metersSecurity recommendations for parameters

  • Gebruik altijd para meters voor gebruikers namen en wacht woorden (of geheimen).Always use parameters for user names and passwords (or secrets).

  • Gebruik securestring voor alle wacht woorden en geheimen.Use securestring for all passwords and secrets. Als u gevoelige gegevens doorgeeft in een JSON-object, gebruikt u het secureObject type.If you pass sensitive data in a JSON object, use the secureObject type. Sjabloon parameters met een beveiligde teken reeks of beveiligde object typen kunnen niet worden gelezen na het implementeren van de resource.Template parameters with secure string or secure object types can't be read after resource deployment.

    "parameters": {
         "secretValue": {
             "type": "securestring",
             "metadata": {
                 "description": "The value of the secret to store in the vault."
             }
         }
    }
    
  • Geef geen standaard waarden op voor gebruikers namen, wacht woorden of voor waarden waarvoor een secureString type vereist is.Don't provide default values for user names, passwords, or any value that requires a secureString type.

  • Geef geen standaard waarden op voor eigenschappen waarmee de aanval surface area van de toepassing wordt verhoogd.Don't provide default values for properties that increase the attack surface area of the application.

Aanbevelingen voor de locatie van para metersLocation recommendations for parameters

  • Gebruik een para meter om de locatie voor resources op te geven en stel de standaard waarde in op resourceGroup().location.Use a parameter to specify the location for resources, and set the default value to resourceGroup().location. Als u een locatie parameter opgeeft, kunnen gebruikers van de sjabloon een locatie opgeven waarvoor ze gemachtigd zijn om te implementeren.Providing a location parameter enables users of the template to specify a location that they have permission to deploy to.

    "parameters": {
       "location": {
         "type": "string",
         "defaultValue": "[resourceGroup().location]",
         "metadata": {
           "description": "The location in which the resources should be deployed."
         }
       }
    },
    
  • Geef geen allowedValues op voor de locatie parameter.Don't specify allowedValues for the location parameter. De locaties die u opgeeft, zijn mogelijk niet beschikbaar in alle Clouds.The locations you specify might not be available in all clouds.

  • Gebruik de locatie parameter waarde voor bronnen die zich waarschijnlijk op dezelfde locatie bevinden.Use the location parameter value for resources that are likely to be in the same location. Deze aanpak minimaliseert het aantal keren dat gebruikers worden gevraagd om locatie gegevens op te geven.This approach minimizes the number of times users are asked to provide location information.

  • Voor bronnen die niet op alle locaties beschikbaar zijn, gebruikt u een afzonderlijke para meter of geeft u een letterlijke locatie waarde op.For resources that aren't available in all locations, use a separate parameter or specify a literal location value.

VariabelenVariables

De volgende informatie kan nuttig zijn wanneer u met variabelenwerkt:The following information can be helpful when you work with variables:

  • Gebruik Camel Case voor namen van variabelen.Use camel case for variable names.

  • Gebruik variabelen voor waarden die u meer dan één keer wilt gebruiken in een sjabloon.Use variables for values that you need to use more than once in a template. Als een waarde slechts één keer wordt gebruikt, wordt uw sjabloon in een in code vastgelegde waarde gemakkelijker te lezen.If a value is used only once, a hard-coded value makes your template easier to read.

  • Gebruik variabelen voor waarden die u maakt op basis van een complexe schikking van sjabloon functies.Use variables for values that you construct from a complex arrangement of template functions. De sjabloon is gemakkelijker te lezen wanneer de complexe expressie alleen in variabelen wordt weer gegeven.Your template is easier to read when the complex expression only appears in variables.

  • Gebruik geen variabelen voor het apiVersion van een resource.Don't use variables for apiVersion on a resource. De API-versie bepaalt het schema van de resource.The API version determines the schema of the resource. Vaak kunt u de versie niet wijzigen zonder de eigenschappen van de resource te wijzigen.Often, you can't change the version without changing the properties for the resource.

  • U kunt de functie Reference niet gebruiken in de sectie Varia bles van de sjabloon.You can't use the reference function in the variables section of the template. De verwijzings functie heeft zijn waarde afgeleid van de runtime status van de resource.The reference function derives its value from the resource's runtime state. Variabelen worden echter opgelost tijdens het eerst parseren van de sjabloon.However, variables are resolved during the initial parsing of the template. Bouw waarden die de verwijzings functie rechtstreeks nodig hebben in het gedeelte resources of uitvoer van de sjabloon.Construct values that need the reference function directly in the resources or outputs section of the template.

  • Variabelen voor resource namen bevatten die uniek moeten zijn.Include variables for resource names that must be unique.

  • Gebruik een copy-lus in variabelen om een herhaald patroon van JSON-objecten te maken.Use a copy loop in variables to create a repeated pattern of JSON objects.

  • Ongebruikte variabelen verwijderen.Remove unused variables.

BronafhankelijkhedenResource dependencies

Wanneer u wilt bepalen welke afhankelijkheden er moeten worden ingesteld, gebruikt u de volgende richt lijnen:When deciding what dependencies to set, use the following guidelines:

  • Gebruik de functie Reference en geef de naam van de resource door om een impliciete afhankelijkheid in te stellen tussen resources die een eigenschap moeten delen.Use the reference function and pass in the resource name to set an implicit dependency between resources that need to share a property. Voeg geen expliciet dependsOn element toe wanneer u al een impliciete afhankelijkheid hebt gedefinieerd.Don't add an explicit dependsOn element when you've already defined an implicit dependency. Deze aanpak vermindert het risico van overbodige afhankelijkheden.This approach reduces the risk of having unnecessary dependencies.

  • Stel een onderliggende bron in die afhankelijk is van de bovenliggende resource.Set a child resource as dependent on its parent resource.

  • Resources waarvoor het element voor waarde is ingesteld op ONWAAR, worden automatisch verwijderd uit de afhankelijkheids volgorde.Resources with the condition element set to false are automatically removed from the dependency order. Stel de afhankelijkheden zo in dat de resource altijd wordt geïmplementeerd.Set the dependencies as if the resource is always deployed.

  • Zorg ervoor dat afhankelijkheden trapsgewijs worden ingesteld zonder ze expliciet in te stellen.Let dependencies cascade without setting them explicitly. Uw virtuele machine is bijvoorbeeld afhankelijk van een virtuele netwerk interface en de virtuele netwerk interface is afhankelijk van een virtueel netwerk en open bare IP-adressen.For example, your virtual machine depends on a virtual network interface, and the virtual network interface depends on a virtual network and public IP addresses. De virtuele machine wordt daarom geïmplementeerd na alle drie de resources, maar u hoeft de virtuele machine niet expliciet in te stellen als afhankelijk van alle drie de resources.Therefore, the virtual machine is deployed after all three resources, but don't explicitly set the virtual machine as dependent on all three resources. Deze benadering verduidelijkt de afhankelijkheids volgorde en maakt het eenvoudiger om de sjabloon later te wijzigen.This approach clarifies the dependency order and makes it easier to change the template later.

  • Als een waarde kan worden bepaald vóór de implementatie, probeert u de resource te implementeren zonder een afhankelijkheid.If a value can be determined before deployment, try deploying the resource without a dependency. Als voor een configuratie waarde bijvoorbeeld de naam van een andere resource nodig is, hebt u mogelijk geen afhankelijkheid nodig.For example, if a configuration value needs the name of another resource, you might not need a dependency. Deze richt lijnen werken niet altijd omdat sommige resources de aanwezigheid van de andere bron verifiëren.This guidance doesn't always work because some resources verify the existence of the other resource. Als er een fout bericht wordt weer gegeven, voegt u een afhankelijkheid toe.If you receive an error, add a dependency.

BronnenResources

De volgende informatie kan nuttig zijn wanneer u met resourceswerkt:The following information can be helpful when you work with resources:

  • Om andere inzenders inzicht te geven in het doel van de resource, geeft u opmerkingen op voor elke resource in de sjabloon:To help other contributors understand the purpose of the resource, specify comments for each resource in the template:

    "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 eind punt in uw sjabloon gebruikt (zoals een openbaar eind punt voor Azure Blob-opslag), hoeft u de naam ruimte niet vast te coderen .If you use a public endpoint in your template (such as an Azure Blob storage public endpoint), don't hard-code the namespace. Gebruik de functie Reference om de naam ruimte dynamisch op te halen.Use the reference function to dynamically retrieve the namespace. U kunt deze methode gebruiken om de sjabloon te implementeren in verschillende open bare naam ruimte omgevingen zonder het eind punt in de sjabloon hand matig te wijzigen.You can use this approach to deploy the template to different public namespace environments without manually changing the endpoint in the template. Stel de API-versie in op de versie die u gebruikt voor het opslag account in uw sjabloon:Set the API version to the same version that you're using for the storage account in your template:

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

    Als het opslag account is geïmplementeerd in dezelfde sjabloon die u maakt en de naam van het opslag account niet wordt gedeeld met een andere resource in de sjabloon, hoeft u de naam ruimte van de provider of de apiVersion niet op te geven als u verwijst naar de bron.If the storage account is deployed in the same template that you're creating and the name of the storage account isn't shared with another resource in the template, you don't need to specify the provider namespace or the apiVersion when you reference the resource. In het volgende voor beeld ziet u de vereenvoudigde syntaxis:The following example shows the simplified syntax:

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

    U kunt ook verwijzen naar een bestaand opslag account dat zich in een andere resource groep bevindt:You also can reference an existing storage account that is in a different resource group:

    "diagnosticsProfile": {
         "bootDiagnostics": {
             "enabled": "true",
             "storageUri": "[reference(resourceId(parameters('existingResourceGroup'), 'Microsoft.Storage/storageAccounts', parameters('existingStorageAccountName')), '2019-06-01').primaryEndpoints.blob]"
         }
    }
    
  • Wijs alleen open bare IP-adressen toe aan een virtuele machine wanneer deze vereist zijn voor een toepassing.Assign public IP addresses to a virtual machine only when an application requires it. Als u verbinding wilt maken met een virtuele machine (VM) voor fout opsporing of voor beheer-of beheer doeleinden, gebruikt u binnenkomende NAT-regels, een virtuele netwerk gateway of een JumpBox.To connect to a virtual machine (VM) for debugging, or for management or administrative purposes, use inbound NAT rules, a virtual network gateway, or a jumpbox.

    Zie voor meer informatie over het maken van verbinding met virtuele machines:For more information about connecting to virtual machines, see:

  • De eigenschap domeinnaam label voor open bare IP-adressen moet uniek zijn.The domainNameLabel property for public IP addresses must be unique. De domeinnaam label -waarde moet tussen de 3 en 63 tekens lang zijn en de regels volgen die zijn opgegeven met deze reguliere expressie: ^[a-z][a-z0-9-]{1,61}[a-z0-9]$.The domainNameLabel value must be between 3 and 63 characters long, and follow the rules specified by this regular expression: ^[a-z][a-z0-9-]{1,61}[a-z0-9]$. Omdat de functie Unique string een teken reeks genereert die 13 tekens lang is, is de para meter dnsPrefixString beperkt tot 50 tekens:Because the uniqueString function generates a string that is 13 characters long, the dnsPrefixString parameter is limited to 50 characters:

    "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 wacht woord aan een aangepaste script extensie toevoegt, gebruikt u de eigenschap commandToExecute in de eigenschap protectedSettings :When you add a password to a custom script extension, use the commandToExecute property in the protectedSettings property:

    "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 protectedSettings van de relevante extensies om ervoor te zorgen dat geheimen worden versleuteld wanneer ze worden door gegeven als para meters voor vm's en uitbrei dingen.To ensure that secrets are encrypted when they are passed as parameters to VMs and extensions, use the protectedSettings property of the relevant extensions.

Volgende stappenNext steps