Metodtips för ARM-mallar

  • Artikel

Den här artikeln visar hur du använder rekommenderade metoder när du skapar en Azure Resource Manager-mall (ARM-mall). De här rekommendationerna hjälper dig att undvika vanliga problem när du använder en ARM-mall för att distribuera en lösning.

Mallgränser

Begränsa storleken på mallen till 4 MB och varje resursdefinition till 1 MB. Gränserna gäller för mallens slutliga tillstånd när den har utökats med iterativa resursdefinitioner och värden för variabler och parametrar. Parameterfilen är också begränsad till 4 MB. Du kan få ett fel om du har en mall eller parameterfil som är mindre än 4 MB men den totala storleken på begäran är för stor. Mer information om hur du kan förenkla mallen för att undvika stora begäranden finns i Lösa fel med överskriden jobbstorlek.

Du är också begränsad till:

  • 256 parametrar
  • 256 variabler
  • 800 resurser (inklusive antal kopior)
  • 64 utdatavärden
  • 10 unika platser per prenumeration/klientorganisation/hanteringsgruppsomfång
  • 24 576 tecken i ett malluttryck

Du kan överskrida vissa mallgränser med hjälp av en kapslad mall. Mer information finns i Använda länkade och kapslade mallar vid distribution av Azure-resurser. Om du vill minska antalet parametrar, variabler eller utdata kan du kombinera flera värden till ett objekt. Mer information finns i Objekt som parametrar.

Resursgrupp

När du distribuerar resurser till en resursgrupp lagrar resursgruppen metadata om resurserna. Metadata lagras på platsen för resursgruppen.

Om resursgruppens region inte är tillgänglig för tillfället kan du inte uppdatera resurser i resursgruppen eftersom metadata inte är tillgängliga. Resurserna i andra regioner fungerar fortfarande som förväntat, men du kan inte uppdatera dem. Du kan minimera risken genom att ha resursgruppen och resurserna i samma region.

Parametrar

Informationen i det här avsnittet kan vara användbar när du arbetar med parametrar.

Allmänna rekommendationer för parametrar

  • Minimera din användning av parametrar. Använd i stället variabler eller literalvärden för egenskaper som inte behöver anges under distributionen.

  • Använd kamelfall för parameternamn.

  • Använd parametrar för inställningar som varierar beroende på miljö, t. ex. SKU, storlek eller kapacitet.

  • Använd parametrar för resursnamn som du vill ange för enkel identifiering.

  • Ange en beskrivning av varje parameter i metadata.

    "parameters": {
  "storageAccountType": {
    "type": "string",
    "metadata": {
      "description": "The type of the new storage account created to store the VM disks."
    }
  }
}

  • Definiera standardvärden för parametrar som inte är känsliga. Genom att ange ett standardvärde är det enklare att distribuera mallen, och användarna av mallen ser ett exempel på ett lämpligt värde. Alla standardvärden för en parameter måste vara giltiga för alla användare i standardkonfigurationen för distribution.

    "parameters": {
  "storageAccountType": {
    "type": "string",
    "defaultValue": "Standard_GRS",
    "metadata": {
      "description": "The type of the new storage account created to store the VM disks."
    }
  }
}

  • Om du vill ange en valfri parameter ska du inte använda en tom sträng som standardvärde. Använd i stället ett literalvärde eller ett språkuttryck för att konstruera ett värde.

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

  • Använd allowedValues sparsamt. Använd den bara när du måste se till att vissa värden inte ingår i de tillåtna alternativen. Om du använder allowedValues för brett kan du blockera giltiga distributioner genom att inte hålla listan uppdaterad.

  • När ett parameternamn i mallen matchar en parameter i PowerShell-distributionskommandot löser Resource Manager namnkonflikten genom att lägga till postfixet FromTemplate i mallparametern. Om du till exempel inkluderar en parameter med namnet ResourceGroupName i mallen står den i konflikt med parametern ResourceGroupName i cmdleten New-AzResourceGroupDeployment . Under distributionen uppmanas du att ange ett värde för ResourceGroupNameFromTemplate.

Säkerhetsrekommendationer för parametrar

  • Använd alltid parametrar för användarnamn och lösenord (eller hemligheter).

  • Använd securestring för alla lösenord och hemligheter. Om du skickar känsliga data i ett JSON-objekt använder du secureObject typen . Mallparametrar med säker sträng eller säkra objekttyper kan inte läsas efter resursdistributionen.

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

  • Ange inte standardvärden för användarnamn, lösenord eller något värde som kräver en secureString typ.

  • Ange inte standardvärden för egenskaper som ökar programmets attackyta.

Platsrekommendationer för parametrar

  • Använd en parameter för att ange platsen för resurser och ange standardvärdet till resourceGroup().location. Om du anger en platsparameter kan användare av mallen ange en plats där de har behörighet att distribuera resurser.

    "parameters": {
   "location": {
     "type": "string",
     "defaultValue": "[resourceGroup().location]",
     "metadata": {
       "description": "The location in which the resources should be deployed."
     }
   }
}

  • Ange inte allowedValues för platsparametern. De platser som du anger kanske inte är tillgängliga i alla moln.

  • Använd värdet för platsparametern för resurser som sannolikt finns på samma plats. Den här metoden minimerar antalet gånger som användare uppmanas att ange platsinformation.

  • För resurser som inte är tillgängliga på alla platser använder du en separat parameter eller anger ett literalplatsvärde.

Variabler

Följande information kan vara användbar när du arbetar med variabler:

  • Använd kamel skiftläge för variabelnamn.

  • Använd variabler för värden som du behöver använda mer än en gång i en mall. Om ett värde bara används en gång gör ett hårdkodat värde mallen enklare att läsa.

  • Använd variabler för värden som du skapar från ett komplext arrangemang av mallfunktioner. Mallen är enklare att läsa när det komplexa uttrycket bara visas i variabler.

  • Du kan inte använda referensfunktionen i variables avsnittet i mallen. Funktionen reference härleder sitt värde från resursens körningstillstånd. Variabler löses dock under den inledande parsningen av mallen. Konstruera värden som behöver reference funktionen direkt i avsnittet eller outputs i resources mallen.

  • Inkludera variabler för resursnamn som måste vara unika.

  • Använd en kopieringsloop i variabler för att skapa ett upprepat mönster av JSON-objekt.

  • Ta bort oanvända variabler.

API-version

apiVersion Ange egenskapen till en hårdkodad API-version för resurstypen. När du skapar en ny mall rekommenderar vi att du använder den senaste API-versionen för en resurstyp. Information om hur du fastställer tillgängliga värden finns i mallreferensen.

När mallen fungerar som förväntat rekommenderar vi att du fortsätter att använda samma API-version. Genom att använda samma API-version behöver du inte bekymra dig om icke-bakåtkompatibla ändringar som kan introduceras i senare versioner.

Använd inte en parameter för API-versionen. Resursegenskaper och värden kan variera beroende på API-version. IntelliSense i en kodredigerare kan inte fastställa rätt schema när API-versionen är inställd på en parameter. Om du skickar in en API-version som inte matchar egenskaperna i mallen misslyckas distributionen.

Använd inte variabler för API-versionen.

Resursberoenden

När du bestämmer vilka beroenden som ska anges använder du följande riktlinjer:

  • reference Använd funktionen och skicka in resursnamnet för att ange ett implicit beroende mellan resurser som behöver dela en egenskap. Lägg inte till ett explicit dependsOn element när du redan har definierat ett implicit beroende. Den här metoden minskar risken för onödiga beroenden. Ett exempel på hur du anger ett implicit beroende finns i referens- och listfunktioner.

  • Ange en underordnad resurs som beroende av dess överordnade resurs.

  • Resurser med villkorselementet inställt på false tas automatiskt bort från beroendeordningen. Ange beroenden som om resursen alltid har distribuerats.

  • Låt beroenden överlappa utan att uttryckligen ange dem. Den virtuella datorn är till exempel beroende av ett virtuellt nätverksgränssnitt, och det virtuella nätverksgränssnittet är beroende av ett virtuellt nätverk och offentliga IP-adresser. Därför distribueras den virtuella datorn efter alla tre resurserna, men ange inte uttryckligen den virtuella datorn som beroende av alla tre resurserna. Den här metoden förtydligar beroendeordningen och gör det enklare att ändra mallen senare.

  • Om ett värde kan fastställas före distributionen kan du prova att distribuera resursen utan beroende. Om ett konfigurationsvärde till exempel behöver namnet på en annan resurs kanske du inte behöver något beroende. Den här vägledningen fungerar inte alltid eftersom vissa resurser verifierar att den andra resursen finns. Om du får ett fel lägger du till ett beroende.

Resurser

Följande information kan vara användbar när du arbetar med resurser:

  • Om du vill hjälpa andra deltagare att förstå syftet med resursen anger du comments för varje resurs i mallen.

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

    Om ARM-mallen lagras i en .jsonc fil stöds kommentarer som använder syntaxen // , som du ser här.

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

    Mer information om kommentarer och metadata finns i Förstå strukturen och syntaxen för ARM-mallar.

  • Om du använder en offentlig slutpunkt i mallen (till exempel en offentlig Slutpunkt för Azure Blob Storage) ska du inte hårdkoda namnområdet. reference Använd funktionen för att dynamiskt hämta namnområdet. Du kan använda den här metoden för att distribuera mallen till olika offentliga namnområdesmiljöer utan att manuellt ändra slutpunkten i mallen. Ange API-versionen till samma version som du använder för lagringskontot i mallen.

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

    Om lagringskontot distribueras i samma mall som du skapar och namnet på lagringskontot inte delas med en annan resurs i mallen behöver du inte ange providernamnområdet eller apiVersion när du refererar till resursen. I följande exempel visas den förenklade syntaxen.

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

    Du kan också referera till ett befintligt lagringskonto som finns i en annan resursgrupp.

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

  • Tilldela offentliga IP-adresser till en virtuell dator endast när ett program kräver det. Om du vill ansluta till en virtuell dator för administrativa ändamål använder du inkommande NAT-regler, en virtuell nätverksgateway eller en jumpbox.

    Mer information om hur du ansluter till virtuella datorer finns i:

  • Egenskapen domainNameLabel för offentliga IP-adresser måste vara unik. Värdet domainNameLabel måste vara mellan 3 och 63 tecken långt och följa de regler som anges i det här reguljära uttrycket: ^[a-z][a-z0-9-]{1,61}[a-z0-9]$. uniqueString Eftersom funktionen genererar en sträng som är 13 tecken lång är parametern dnsPrefixString begränsad till 50 tecken.

    "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))]"
}

  • När du lägger till ett lösenord i ett anpassat skripttillägg använder du commandToExecute egenskapen i protectedSettings egenskapen .

    "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'))]"
  }
}

    Anteckning

    För att säkerställa att hemligheter krypteras när de skickas som parametrar till virtuella datorer och tillägg använder du protectedSettings egenskapen för relevanta tillägg.

  • Ange explicita värden för egenskaper som har standardvärden som kan ändras över tid. Om du till exempel distribuerar ett AKS-kluster kan du antingen ange eller utelämna kubernetesVersion egenskapen. Om du inte anger det är klustret standardvärdet för N-1-delversionen och den senaste korrigeringen. När du distribuerar klustret med hjälp av en ARM-mall är det här standardbeteendet kanske inte det du förväntar dig. Om du distribuerar om mallen kan det resultera i att klustret oväntat uppgraderas till en ny Kubernetes-version. Överväg i stället att ange ett explicit versionsnummer och sedan ändra det manuellt när du är redo att uppgradera klustret.

Kommentarer

Förutom egenskapen comments stöds kommentarer som använder syntaxen // . Mer information om kommentarer och metadata finns i Förstå strukturen och syntaxen för ARM-mallar. Du kan välja att spara JSON-filer som innehåller // kommentarer med filnamnstillägget .jsonc för att ange att JSON-filen innehåller kommentarer. ARM-tjänsten accepterar också kommentarer i alla JSON-filer, inklusive parameterfiler.

ARM-verktyg i Visual Studio Code

Det är mycket enklare att arbeta med ARM-mallar med Azure Resource Manager-verktyg (ARM) för Visual Studio Code. Det här tillägget tillhandahåller språkstöd, resursfragment och automatisk slutförande av resurser som hjälper dig att skapa och validera Azure Resource Manager-mallar. Mer information och installera tillägget finns i Verktyg för Azure Resource Manager (ARM).

Använda testverktyg

Testverktyget för ARM-mallar är ett skript som kontrollerar om mallen använder rekommenderade metoder. När mallen inte är kompatibel med rekommenderade metoder returneras en lista med varningar med föreslagna ändringar. Testverktyget kan hjälpa dig att lära dig hur du implementerar metodtips i mallen.

När du har slutfört mallen kör du testverktyget för att se om det finns sätt att förbättra dess implementering. Mer information finns i Använda testverktyget för ARM-mallar.

Nästa steg