Metodtips för ARM-mallar

  • Artikel
  • 9 minuter för att läsa

Den här artikeln visar hur du använder rekommenderade metoder när du skapar 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.

Mallbegränsningar

Begränsa storleken på mallen till 4 MB. Gränsen på 4 MB gäller 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 med en mall- eller parameterfil på mindre än 4 MB om den totala storleken på begäran är för stor. Mer information om hur du förenklar mallen för att undvika en stor begäran finns i Lösa fel när jobbstorleken har överskridits.

Du är också begränsad till:

  • 256 parametrar
  • 256 variabler
  • 800 resurser (inklusive antal kopior)
  • 64 utdatavärden
  • 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 när du distribuerar 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å resursgruppens plats.

Om resursgruppens region är tillfälligt otillgänglig 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 leta upp din resursgrupp och dina resurser 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 användningen av parametrar. Använd i stället variabler eller literalvärden för egenskaper som inte behöver anges under distributionen.

  • Använd kamelfallet 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ändare 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 standarddistributionskonfigurationen.

    "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 resursdistribution.

    "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 värden 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 . Genom att ange 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 för allowedValues platsparametern. De platser som du anger kanske inte är tillgängliga i alla moln.

  • Använd platsparametervärdet 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 literalt platsvärde.

Variabler

Följande information kan vara till hjälp när du arbetar med variabler:

  • Använd kamelfallet 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 lättare att läsa.

  • Använd variabler för värden som du skapar från en komplex ordning med mallfunktioner. Mallen är lättare 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 dess värde från resursens körningstillstånd. Variabler matchas dock under den inledande parsningen av mallen. Skapa värden som behöver reference funktionen direkt i avsnittet eller i resources outputs 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 för JSON-objekt.

  • Ta bort oanvända variabler.

API-version

Ange egenskapen apiVersion 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 större ä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 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 ska du använda följande riktlinjer:

  • Använd funktionen reference 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 är distribuerad.

  • Låt beroenden överlappa utan att ange dem explicit. 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 anger inte uttryckligen den virtuella datorn som beroende av alla tre resurserna. Den här metoden klargör beroendeordningen och gör det enklare att ändra mallen senare.

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

Resurser

Följande information kan vara till hjälp när du arbetar med resurser:

  • För att 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 du använder en offentlig slutpunkt i mallen (till exempel en offentlig slutpunkt för Azure Blob Storage) hårdkodar du inte namnområdet. Använd funktionen reference 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 providernamnrymden eller när du refererar till apiVersion 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 (VM) för felsökning, eller för hanterings- eller administrationssyfte, 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 måste vara mellan 3 och 63 tecken långt och följa reglerna som domainNameLabel anges i det här reguljära uttrycket: ^[a-z][a-z0-9-]{1,61}[a-z0-9]$ . Eftersom funktionen uniqueString genererar en sträng som är 13 tecken lång är dnsPrefixString parametern 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 tillägg för anpassat skript använder commandToExecute du egenskapen i egenskapen protectedSettings .

    "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 med tiden. Om du till exempel distribuerar ett AKS-kluster kan du antingen ange eller utelämna kubernetesVersion egenskapen. Om du inte anger det får klustret som standard delversionen N-1och den senaste korrigeringen . När du distribuerar klustret med hjälp av en ARM-mall kanske det här standardbeteendet inte är det du förväntar dig. Omdistribution av mallen kan resultera i att klustret uppgraderas till en ny Kubernetes-version oväntat. Överväg i stället att ange ett explicit versionsnummer och ändra det manuellt när du är redo att uppgradera klustret.

Använda testverktyg

Testverktygssatsen 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 över varningar med föreslagna ändringar. Testverktygen kan hjälpa dig att lära dig hur du implementerar metodtips i mallen.

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

Nästa steg