Gekoppelde en geneste sjablonen gebruiken bij het implementeren van Azure-resources

Artikel
09/14/2021
19 minuten om te lezen

Als u complexe oplossingen wilt implementeren, kunt u uw Azure Resource Manager sjabloon (ARM-sjabloon) in veel gerelateerde sjablonen oprollen en deze vervolgens samen implementeren via een hoofdsjabloon. De gerelateerde sjablonen kunnen afzonderlijke bestanden of sjabloonsyntaxis zijn die zijn ingesloten in de hoofdsjabloon. In dit artikel wordt de term gekoppelde sjabloon gebruikt om te verwijzen naar een afzonderlijk sjabloonbestand waarnaar wordt verwezen via een koppeling vanuit de hoofdsjabloon. De term geneste sjabloon wordt gebruikt om te verwijzen naar de syntaxis van ingesloten sjablonen in de hoofdsjabloon.

Voor kleine tot middelgrote oplossingen is één sjabloon eenvoudiger te begrijpen en te onderhouden. U kunt alle resources en waarden in één bestand bekijken. Voor geavanceerde scenario's kunt u met gekoppelde sjablonen de oplossing opsplitsen in de beoogde onderdelen. U kunt deze sjablonen eenvoudig opnieuw gebruiken voor andere scenario's.

Zie Zelfstudie: Een gekoppelde sjabloon implementeren voor een zelfstudie.

Notitie

Voor gekoppelde of geneste sjablonen kunt u de implementatiemodus alleen instellen op Incrementele. De hoofdsjabloon kan echter worden geïmplementeerd in de volledige modus. Als u de hoofdsjabloon in de volledige modus implementeert en de gekoppelde of geneste sjabloon is gericht op dezelfde resourcegroep, worden de resources die zijn geïmplementeerd in de gekoppelde of geneste sjabloon opgenomen in de evaluatiefase voor de implementatie van de volledige modus. De gecombineerde verzameling resources die is geïmplementeerd in de hoofdsjabloon en gekoppelde of geneste sjablonen wordt vergeleken met de bestaande resources in de resourcegroep. Alle resources die niet zijn opgenomen in deze gecombineerde verzameling, worden verwijderd.

Als de gekoppelde of geneste sjabloon is gericht op een andere resourcegroep, gebruikt die implementatie de incrementele modus.

Geneste sjabloon

Als u een sjabloon wilt nesten, voegt u een implementatieresource toe aan uw hoofdsjabloon. Geef in template de eigenschap de sjabloonsyntaxis op.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {},
  "variables": {},
  "resources": [
    {
      "type": "Microsoft.Resources/deployments",
      "apiVersion": "2021-04-01",
      "name": "nestedTemplate1",
      "properties": {
        "mode": "Incremental",
        "template": {
          <nested-template-syntax>
        }
      }
    }
  ],
  "outputs": {
  }
}

In het volgende voorbeeld wordt een opslagaccount geïmplementeerd via een geneste sjabloon.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storageAccountName": {
      "type": "string"
    }
  },
  "resources": [
    {
      "type": "Microsoft.Resources/deployments",
      "apiVersion": "2021-04-01",
      "name": "nestedTemplate1",
      "properties": {
        "mode": "Incremental",
        "template": {
          "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
          "contentVersion": "1.0.0.0",
          "resources": [
            {
              "type": "Microsoft.Storage/storageAccounts",
              "apiVersion": "2021-04-01",
              "name": "[parameters('storageAccountName')]",
              "location": "West US",
              "sku": {
                "name": "Standard_LRS"
              },
              "kind": "StorageV2"
            }
          ]
        }
      }
    }
  ],
  "outputs": {
  }
}

Evaluatiebereik van expressies in geneste sjablonen

Wanneer u een geneste sjabloon gebruikt, kunt u opgeven of sjabloonexpressies worden geëvalueerd binnen het bereik van de bovenliggende sjabloon of de geneste sjabloon. Het bereik bepaalt hoe parameters, variabelen en functies zoals resourceGroup en abonnement worden opgelost.

U stelt het bereik in via de expressionEvaluationOptions eigenschap . De eigenschap is standaard ingesteld op , wat betekent dat het bereik van de expressionEvaluationOptions outer bovenliggende sjabloon wordt gebruikt. Stel de waarde in op inner om ervoor te zorgen dat expressies worden geëvalueerd binnen het bereik van de geneste sjabloon.

{
  "type": "Microsoft.Resources/deployments",
  "apiVersion": "2021-04-01",
  "name": "nestedTemplate1",
  "properties": {
    "expressionEvaluationOptions": {
      "scope": "inner"
    },
  ...

Notitie

Wanneer bereik is ingesteld op , kunt u de functie niet gebruiken in de sectie uitvoer van een geneste sjabloon voor een resource die u hebt geïmplementeerd outer reference in de geneste sjabloon. Als u de waarden voor een geïmplementeerde resource in een geneste sjabloon wilt retourneren, gebruikt u bereik of converteert u uw inner geneste sjabloon naar een gekoppelde sjabloon.

De volgende sjabloon laat zien hoe sjabloonexpressie wordt opgelost op basis van het bereik. Deze bevat een variabele met de exampleVar naam die is gedefinieerd in zowel de bovenliggende sjabloon als de geneste sjabloon. Deze retourneert de waarde van de variabele .

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
  },
  "variables": {
    "exampleVar": "from parent template"
  },
  "resources": [
    {
      "type": "Microsoft.Resources/deployments",
      "apiVersion": "2021-04-01",
      "name": "nestedTemplate1",
      "properties": {
        "expressionEvaluationOptions": {
          "scope": "inner"
        },
        "mode": "Incremental",
        "template": {
          "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
          "contentVersion": "1.0.0.0",
          "variables": {
            "exampleVar": "from nested template"
          },
          "resources": [
          ],
          "outputs": {
            "testVar": {
              "type": "string",
              "value": "[variables('exampleVar')]"
            }
          }
        }
      }
    }
  ],
  "outputs": {
    "messageFromLinkedTemplate": {
      "type": "string",
      "value": "[reference('nestedTemplate1').outputs.testVar.value]"
    }
  }
}

De waarde van exampleVar verandert afhankelijk van de waarde van de eigenschap in scope expressionEvaluationOptions . In de volgende tabel ziet u de resultaten voor beide bereiken.

Evaluatiebereik	Uitvoer
Innerlijke	van geneste sjabloon
outer (of standaard)	van bovenliggende sjabloon

In het volgende voorbeeld wordt een SQL server geïmplementeerd en wordt een sleutelkluisgeheim opgehaald dat moet worden gebruikt voor het wachtwoord. Het bereik is ingesteld op omdat de sleutelkluis-id dynamisch wordt gemaakt (zie in de buitenste sjablonen) en deze als parameter doorgeeft aan inner adminPassword.reference.keyVault de parameters geneste sjabloon.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]",
      "metadata": {
        "description": "The location where the resources will be deployed."
      }
    },
    "vaultName": {
      "type": "string",
      "metadata": {
        "description": "The name of the keyvault that contains the secret."
      }
    },
    "secretName": {
      "type": "string",
      "metadata": {
        "description": "The name of the secret."
      }
    },
    "vaultResourceGroupName": {
      "type": "string",
      "metadata": {
        "description": "The name of the resource group that contains the keyvault."
      }
    },
    "vaultSubscription": {
      "type": "string",
      "defaultValue": "[subscription().subscriptionId]",
      "metadata": {
        "description": "The name of the subscription that contains the keyvault."
      }
    }
  },
  "resources": [
    {
      "type": "Microsoft.Resources/deployments",
      "apiVersion": "2021-04-01",
      "name": "dynamicSecret",
      "properties": {
        "mode": "Incremental",
        "expressionEvaluationOptions": {
          "scope": "inner"
        },
        "parameters": {
          "location": {
            "value": "[parameters('location')]"
          },
          "adminLogin": {
            "value": "ghuser"
          },
          "adminPassword": {
            "reference": {
              "keyVault": {
                "id": "[resourceId(parameters('vaultSubscription'), parameters('vaultResourceGroupName'), 'Microsoft.KeyVault/vaults', parameters('vaultName'))]"
              },
              "secretName": "[parameters('secretName')]"
            }
          }
        },
        "template": {
          "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
          "contentVersion": "1.0.0.0",
          "parameters": {
            "adminLogin": {
              "type": "string"
            },
            "adminPassword": {
              "type": "securestring"
            },
            "location": {
              "type": "string"
            }
          },
          "variables": {
            "sqlServerName": "[concat('sql-', uniqueString(resourceGroup().id, 'sql'))]"
          },
          "resources": [
            {
              "type": "Microsoft.Sql/servers",
              "apiVersion": "2021-02-01-preview",
              "name": "[variables('sqlServerName')]",
              "location": "[parameters('location')]",
              "properties": {
                "administratorLogin": "[parameters('adminLogin')]",
                "administratorLoginPassword": "[parameters('adminPassword')]"
              }
            }
          ],
          "outputs": {
            "sqlFQDN": {
              "type": "string",
              "value": "[reference(variables('sqlServerName')).fullyQualifiedDomainName]"
            }
          }
        }
      }
    }
  ],
  "outputs": {
  }
}

Wees voorzichtig bij het gebruik van veilige parameterwaarden in een geneste sjabloon. Als u het bereik naar buiten in stelt, worden de beveiligde waarden opgeslagen als tekst zonder tekst in de implementatiegeschiedenis. Een gebruiker die de sjabloon in de implementatiegeschiedenis bekijkt, kan de beveiligde waarden zien. Gebruik in plaats daarvan het binnenste bereik of voeg aan de bovenliggende sjabloon de resources toe die veilige waarden nodig hebben.

In het volgende fragment ziet u welke waarden veilig zijn en welke niet.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "adminUsername": {
      "type": "string",
      "metadata": {
        "description": "Username for the Virtual Machine."
      }
    },
    "adminPasswordOrKey": {
      "type": "securestring",
      "metadata": {
        "description": "SSH Key or password for the Virtual Machine. SSH key is recommended."
      }
    }
  },
  ...
  "resources": [
    {
      "type": "Microsoft.Compute/virtualMachines",
      "apiVersion": "2021-04-01",
      "name": "mainTemplate",
      "properties": {
        ...
        "osProfile": {
          "computerName": "mainTemplate",
          "adminUsername": "[parameters('adminUsername')]",
          "adminPassword": "[parameters('adminPasswordOrKey')]" // Yes, secure because resource is in parent template
        }
      }
    },
    {
      "name": "outer",
      "type": "Microsoft.Resources/deployments",
      "apiVersion": "2021-04-01",
      "properties": {
        "expressionEvaluationOptions": {
          "scope": "outer"
        },
        "mode": "Incremental",
        "template": {
          "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
          "contentVersion": "1.0.0.0",
          "resources": [
            {
              "type": "Microsoft.Compute/virtualMachines",
              "apiVersion": "2021-04-01",
              "name": "outer",
              "properties": {
                ...
                "osProfile": {
                  "computerName": "outer",
                  "adminUsername": "[parameters('adminUsername')]",
                  "adminPassword": "[parameters('adminPasswordOrKey')]" // No, not secure because resource is in nested template with outer scope
                }
              }
            }
          ]
        }
      }
    },
    {
      "name": "inner",
      "type": "Microsoft.Resources/deployments",
      "apiVersion": "2021-04-01",
      "properties": {
        "expressionEvaluationOptions": {
          "scope": "inner"
        },
        "mode": "Incremental",
        "parameters": {
          "adminPasswordOrKey": {
              "value": "[parameters('adminPasswordOrKey')]"
          },
          "adminUsername": {
              "value": "[parameters('adminUsername')]"
          }
        },
        "template": {
          "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
          "contentVersion": "1.0.0.0",
          "parameters": {
            "adminUsername": {
              "type": "string",
              "metadata": {
                "description": "Username for the Virtual Machine."
              }
            },
            "adminPasswordOrKey": {
              "type": "securestring",
              "metadata": {
                "description": "SSH Key or password for the Virtual Machine. SSH key is recommended."
              }
            }
          },
          "resources": [
            {
              "type": "Microsoft.Compute/virtualMachines",
              "apiVersion": "2021-04-01",
              "name": "inner",
              "properties": {
                ...
                "osProfile": {
                  "computerName": "inner",
                  "adminUsername": "[parameters('adminUsername')]",
                  "adminPassword": "[parameters('adminPasswordOrKey')]" // Yes, secure because resource is in nested template and scope is inner
                }
              }
            }
          ]
        }
      }
    }
  ]
}

Een gekoppelde sjabloon

Als u een sjabloon wilt koppelen, voegt u een implementatieresource toe aan uw hoofdsjabloon. Geef in templateLink de eigenschap de URI op van de sjabloon die u wilt opnemen. In het volgende voorbeeld wordt een koppeling gemaakt naar een sjabloon in een opslagaccount.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {},
  "variables": {},
  "resources": [
    {
      "type": "Microsoft.Resources/deployments",
      "apiVersion": "2021-04-01",
      "name": "linkedTemplate",
      "properties": {
        "mode": "Incremental",
        "templateLink": {
          "uri":"https://mystorageaccount.blob.core.windows.net/AzureTemplates/newStorageAccount.json",
          "contentVersion":"1.0.0.0"
        }
      }
    }
  ],
  "outputs": {
  }
}

Wanneer u naar een gekoppelde sjabloon verwijst, kan de waarde van geen lokaal bestand of een bestand zijn dat uri alleen beschikbaar is op uw lokale netwerk. Azure Resource Manager moeten toegang hebben tot de sjabloon. Geef een URI-waarde op die kan worden gedownload als HTTP of HTTPS.

U kunt verwijzen naar sjablonen met parameters die HTTP of HTTPS bevatten. Een veelvoorkomende patroon is bijvoorbeeld het gebruik van de _artifactsLocation parameter . U kunt de gekoppelde sjabloon instellen met een expressie zoals:

"uri": "[concat(parameters('_artifactsLocation'), '/shared/os-disk-parts-md.json', parameters('_artifactsLocationSasToken'))]"

Als u een koppeling maakt naar een sjabloon in GitHub, gebruikt u de onbewerkte URL. De koppeling heeft de volgende indeling: https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/get-started-with-templates/quickstart-template/azuredeploy.json . Selecteer Onbewerkte om de onbewerkte koppeling op te halen.

Onbewerkte URL selecteren

Notitie

Voor het implementeren van een sjabloon of een verwijzing naar een gekoppelde sjabloon die is opgeslagen in een persoonlijke GitHub-opslag plaats, raadpleegt u een aangepaste oplossing die wordt beschreven in een MVP-blog. U kunt een Azure- functie instellen als een proxy om de URL te maken die nodig is voor toegang tot een sjabloon bestand in een persoonlijke github-opslag plaats.

Parameters voor gekoppelde sjabloon

U kunt de parameters voor uw gekoppelde sjabloon opgeven in een extern bestand of inline. Wanneer u een extern parameterbestand opgeeft, gebruikt u de parametersLink eigenschap :

"resources": [
  {
    "type": "Microsoft.Resources/deployments",
    "apiVersion": "2021-04-01",
    "name": "linkedTemplate",
    "properties": {
      "mode": "Incremental",
      "templateLink": {
        "uri": "https://mystorageaccount.blob.core.windows.net/AzureTemplates/newStorageAccount.json",
        "contentVersion": "1.0.0.0"
      },
      "parametersLink": {
        "uri": "https://mystorageaccount.blob.core.windows.net/AzureTemplates/newStorageAccount.parameters.json",
        "contentVersion": "1.0.0.0"
      }
    }
  }
]

Als u parameterwaarden inline wilt doorgeven, gebruikt u de parameters eigenschap .

"resources": [
  {
    "type": "Microsoft.Resources/deployments",
    "apiVersion": "2021-04-01",
    "name": "linkedTemplate",
    "properties": {
      "mode": "Incremental",
      "templateLink": {
        "uri": "https://mystorageaccount.blob.core.windows.net/AzureTemplates/newStorageAccount.json",
        "contentVersion": "1.0.0.0"
      },
      "parameters": {
        "storageAccountName": {
          "value": "[parameters('storageAccountName')]"
        }
      }
    }
  }
]

U kunt niet zowel inlineparameters als een koppeling naar een parameterbestand gebruiken. De implementatie mislukt met een fout wanneer zowel parametersLink als parameters worden opgegeven.

Relatief pad gebruiken voor gekoppelde sjablonen

De relativePath eigenschap van maakt het eenvoudiger om Microsoft.Resources/deployments gekoppelde sjablonen te maken. Deze eigenschap kan worden gebruikt voor het implementeren van een externe gekoppelde sjabloon op een locatie ten opzichte van het bovenliggende sjabloon. Voor deze functie moeten alle sjabloonbestanden worden gefaseerd en beschikbaar zijn op een externe URI, zoals GitHub of Azure-opslagaccount. Wanneer de hoofdsjabloon wordt aangeroepen met behulp van een URI van Azure PowerShell of Azure CLI, is de onderliggende implementatie-URI een combinatie van het bovenliggende en relativePath.

Notitie

Bij het maken van een templateSpec worden alle sjablonen waarnaar wordt verwezen door de eigenschap verpakt in de relativePath templateSpec-resource door Azure PowerShell of Azure CLI. Het is niet vereist dat de bestanden worden gefaseerd. Zie Een sjabloonspecificatie maken met gekoppelde sjablonen voor meer informatie.

Stel dat u een mapstructuur als deze ziet:

relatief pad naar gekoppelde resource manager-sjabloon

In de volgende sjabloon ziet u hoe mainTemplate.json nestedChild.json implementeert, zoals geïllustreerd in de voorgaande afbeelding.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {},
  "functions": [],
  "variables": {},
  "resources": [
    {
      "type": "Microsoft.Resources/deployments",
      "apiVersion": "2021-04-01",
      "name": "childLinked",
      "properties": {
        "mode": "Incremental",
        "templateLink": {
          "relativePath": "children/nestedChild.json"
        }
      }
    }
  ],
  "outputs": {}
}

In de volgende implementatie is de URI van de gekoppelde sjabloon in de voorgaande sjabloon https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/linked-template-relpath/children/nestedChild.json .

PowerShell
Azure-CLI

New-AzResourceGroupDeployment `
  -Name linkedTemplateWithRelativePath `
  -ResourceGroupName "myResourceGroup" `
  -TemplateUri "https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/linked-template-relpath/mainTemplate.json"

az deployment group create \
  --name linkedTemplateWithRelativePath \
  --resource-group myResourceGroup \
  --template-uri "https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/linked-template-relpath/mainTemplate.json"

Als u gekoppelde sjablonen wilt implementeren met een relatief pad dat is opgeslagen in een Azure-opslagaccount, gebruikt u de parameter om het SAS-token op te geven dat moet worden gebruikt met QueryString / query-string de parameter TemplateUri. Deze parameter wordt alleen ondersteund door Azure CLI versie 2.18 of hoger en Azure PowerShell versie 5.4 of hoger.

PowerShell
Azure-CLI

New-AzResourceGroupDeployment `
  -Name linkedTemplateWithRelativePath `
  -ResourceGroupName "myResourceGroup" `
  -TemplateUri "https://stage20210126.blob.core.windows.net/template-staging/mainTemplate.json" `
  -QueryString $sasToken

az deployment group create \
  --name linkedTemplateWithRelativePath \
  --resource-group myResourceGroup \
  --template-uri "https://stage20210126.blob.core.windows.net/template-staging/mainTemplate.json" \
  --query-string $sasToken

Zorg ervoor dat er geen vooraanstaand '?' in QueryString staat. De implementatie voegt er een toe bij het samenstellen van de URI voor de implementaties.

Sjabloonspecificaties

In plaats van uw gekoppelde sjablonen op een toegankelijk eindpunt te onderhouden, kunt u een sjabloonspecificatie maken die de hoofdsjabloon en de gekoppelde sjablonen verpakt in één entiteit die u kunt implementeren. De sjabloonspecificatie is een resource in uw Azure-abonnement. Zo kunt u de sjabloon eenvoudig veilig delen met gebruikers in uw organisatie. U gebruikt op rollen gebaseerd toegangsbeheer van Azure (Azure RBAC) om toegang te verlenen tot de sjabloonspecificatie. Deze functie is momenteel beschikbaar als preview-versie.

Zie voor meer informatie:

Afhankelijkheden

Net als bij andere resourcetypen kunt u afhankelijkheden instellen tussen de gekoppelde sjablonen. Als de resources in één gekoppelde sjabloon moeten worden geïmplementeerd vóór resources in een tweede gekoppelde sjabloon, stelt u de tweede sjabloon in die afhankelijk is van de eerste.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {},
  "variables": {},
  "resources": [
    {
      "type": "Microsoft.Resources/deployments",
      "apiVersion": "2021-04-01",
      "name": "linkedTemplate1",
      "properties": {
        "mode": "Incremental",
        "templateLink": {
          "uri": "[uri(deployment().properties.templateLink.uri, 'firstresources.json')]",
          "contentVersion": "1.0.0.0"
        }
      }
    },
    {
      "type": "Microsoft.Resources/deployments",
      "apiVersion": "2021-04-01",
      "name": "linkedTemplate2",
      "dependsOn": [
        "[resourceId('Microsoft.Resources/deployments', 'linkedTemplate1')]"
      ],
      "properties": {
        "mode": "Incremental",
        "templateLink": {
          "uri": "[uri(deployment().properties.templateLink.uri, 'secondresources.json')]",
          "contentVersion": "1.0.0.0"
        }
      }
    }
  ]
}

contentVersion

U hoeft de eigenschap voor de eigenschap of niet contentVersion templateLink op te parametersLink geven. Als u geen op geeft, wordt de huidige versie van de contentVersion sjabloon geïmplementeerd. Als u een waarde op geeft voor de inhoudsversie, moet deze overeenkomen met de versie in de gekoppelde sjabloon; anders mislukt de implementatie met een fout.

Variabelen gebruiken om sjablonen te koppelen

In de vorige voorbeelden zijn in code gecodeerde URL-waarden voor de sjabloonkoppelingen weergegeven. Deze aanpak werkt mogelijk voor een eenvoudige sjabloon, maar werkt niet goed voor een grote set modulaire sjablonen. In plaats daarvan kunt u een statische variabele maken waarin een basis-URL voor de hoofdsjabloon wordt opgeslagen en vervolgens dynamisch URL's voor de gekoppelde sjablonen worden gemaakt op basis van die basis-URL. Het voordeel van deze benadering is dat u de sjabloon eenvoudig kunt verplaatsen of vervorken, omdat u alleen de statische variabele in de hoofdsjabloon hoeft te wijzigen. De hoofdsjabloon geeft de juiste URI's door in de gedecomprimeerde sjabloon.

In het volgende voorbeeld ziet u hoe u een basis-URL gebruikt om twee URL's te maken voor gekoppelde sjablonen ( sharedTemplateUrl en vmTemplateUrl ).

"variables": {
  "templateBaseUrl": "https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/application-workloads/postgre/postgresql-on-ubuntu/",
  "sharedTemplateUrl": "[uri(variables('templateBaseUrl'), 'shared-resources.json')]",
  "vmTemplateUrl": "[uri(variables('templateBaseUrl'), 'database-2disk-resources.json')]"
}

U kunt deployment() ook gebruiken om de basis-URL voor de huidige sjabloon op te halen en deze gebruiken om de URL voor andere sjablonen op dezelfde locatie op te halen. Deze aanpak is handig als de locatie van uw sjabloon wordt gewijzigd of als u URL's voor hardcodering in het sjabloonbestand wilt vermijden. De templateLink eigenschap wordt alleen geretourneerd wanneer u een koppeling maakt naar een externe sjabloon met een URL. Als u een lokale sjabloon gebruikt, is die eigenschap niet beschikbaar.

"variables": {
  "sharedTemplateUrl": "[uri(deployment().properties.templateLink.uri, 'shared-resources.json')]"
}

Uiteindelijk gebruikt u de variabele in de uri eigenschap van een templateLink eigenschap.

"templateLink": {
 "uri": "[variables('sharedTemplateUrl')]",
 "contentVersion":"1.0.0.0"
}

Kopiëren gebruiken

Als u meerdere exemplaren van een resource wilt maken met een geneste sjabloon, voegt u het element toe copy op het niveau van de Microsoft.Resources/deployments resource. Als het bereik is, kunt inner u de kopie ook toevoegen in de geneste sjabloon.

De volgende voorbeeldsjabloon laat zien hoe u copy kunt gebruiken met een geneste sjabloon.

"resources": [
  {
    "type": "Microsoft.Resources/deployments",
    "apiVersion": "2021-04-01",
    "name": "[concat('nestedTemplate', copyIndex())]",
    // yes, copy works here
    "copy": {
      "name": "storagecopy",
      "count": 2
    },
    "properties": {
      "mode": "Incremental",
      "expressionEvaluationOptions": {
        "scope": "inner"
      },
      "template": {
        "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
        "contentVersion": "1.0.0.0",
        "resources": [
          {
            "type": "Microsoft.Storage/storageAccounts",
            "apiVersion": "2021-04-01",
            "name": "[concat(variables('storageName'), copyIndex())]",
            "location": "West US",
            "sku": {
              "name": "Standard_LRS"
            },
            "kind": "StorageV2"
            // Copy works here when scope is inner
            // But, when scope is default or outer, you get an error
            // "copy": {
            //   "name": "storagecopy",
            //   "count": 2
            // }
          }
        ]
      }
    }
  }
]

Waarden ophalen uit de gekoppelde sjabloon

Als u een uitvoerwaarde van een gekoppelde sjabloon wilt ophalen, haalt u de eigenschapswaarde op met een syntaxis zoals: "[reference('deploymentName').outputs.propertyName.value]" .

Bij het verkrijgen van een uitvoer-eigenschap van een gekoppelde sjabloon mag de naam van de eigenschap geen streepje bevatten.

In de volgende voorbeelden wordt gedemonstreerd hoe u naar een gekoppelde sjabloon verwijst en een uitvoerwaarde op haalt. De gekoppelde sjabloon retourneert een eenvoudig bericht. Eerst de gekoppelde sjabloon:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {},
  "variables": {},
  "resources": [],
  "outputs": {
    "greetingMessage": {
      "value": "Hello World",
      "type": "string"
    }
  }
}

De hoofdsjabloon implementeert de gekoppelde sjabloon en haalt de geretourneerde waarde op. U ziet dat deze op naam verwijst naar de implementatieresource en dat deze de naam gebruikt van de eigenschap die wordt geretourneerd door de gekoppelde sjabloon.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {},
  "variables": {},
  "resources": [
    {
      "type": "Microsoft.Resources/deployments",
      "apiVersion": "2021-04-01",
      "name": "linkedTemplate",
      "properties": {
        "mode": "incremental",
        "templateLink": {
          "uri": "[uri(deployment().properties.templateLink.uri, 'helloworld.json')]",
          "contentVersion": "1.0.0.0"
        }
      }
    }
  ],
  "outputs": {
    "messageFromLinkedTemplate": {
      "type": "string",
      "value": "[reference('linkedTemplate').outputs.greetingMessage.value]"
    }
  }
}

In het volgende voorbeeld ziet u een sjabloon die een openbaar IP-adres implementeert en de resource-id van de Azure-resource voor dat openbare IP-adres retourneert:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "publicIPAddresses_name": {
      "type": "string"
    }
  },
  "variables": {},
  "resources": [
    {
      "type": "Microsoft.Network/publicIPAddresses",
      "apiVersion": "2021-02-01",
      "name": "[parameters('publicIPAddresses_name')]",
      "location": "eastus",
      "properties": {
        "publicIPAddressVersion": "IPv4",
        "publicIPAllocationMethod": "Dynamic",
        "idleTimeoutInMinutes": 4
      },
      "dependsOn": []
    }
  ],
  "outputs": {
    "resourceID": {
      "type": "string",
      "value": "[resourceId('Microsoft.Network/publicIPAddresses', parameters('publicIPAddresses_name'))]"
    }
  }
}

Als u het openbare IP-adres uit de voorgaande sjabloon wilt gebruiken bij het implementeren van een load balancer, koppelt u aan de sjabloon en declareer u een afhankelijkheid van de Microsoft.Resources/deployments resource. Het openbare IP-adres op de load balancer is ingesteld op de uitvoerwaarde van de gekoppelde sjabloon.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "loadBalancers_name": {
      "defaultValue": "mylb",
      "type": "string"
    },
    "publicIPAddresses_name": {
      "defaultValue": "myip",
      "type": "string"
    }
  },
  "variables": {},
  "resources": [
    {
      "type": "Microsoft.Network/loadBalancers",
      "apiVersion": "2021-02-01",
      "name": "[parameters('loadBalancers_name')]",
      "location": "eastus",
      "properties": {
        "frontendIPConfigurations": [
          {
            "name": "LoadBalancerFrontEnd",
            "properties": {
              "privateIPAllocationMethod": "Dynamic",
              "publicIPAddress": {
                "id": "[reference('linkedTemplate').outputs.resourceID.value]"
              }
            }
          }
        ],
        "backendAddressPools": [],
        "loadBalancingRules": [],
        "probes": [],
        "inboundNatRules": [],
        "outboundNatRules": [],
        "inboundNatPools": []
      },
      "dependsOn": [
        "[resourceId('Microsoft.Resources/deployments', 'linkedTemplate')]"
      ]
    },
    {
      "type": "Microsoft.Resources/deployments",
      "apiVersion": "2021-04-01",
      "name": "linkedTemplate",
      "properties": {
        "mode": "Incremental",
        "templateLink": {
          "uri": "[uri(deployment().properties.templateLink.uri, 'public-ip.json')]",
          "contentVersion": "1.0.0.0"
        },
        "parameters": {
          "publicIPAddresses_name": { "value": "[parameters('publicIPAddresses_name')]" }
        }
      }
    }
  ]
}

Implementatiegeschiedenis

Resource Manager verwerkt elke sjabloon als een afzonderlijke implementatie in de implementatiegeschiedenis. Een hoofdsjabloon met drie gekoppelde of geneste sjablonen wordt in de implementatiegeschiedenis weergegeven als:

Implementatiegeschiedenis

U kunt deze afzonderlijke vermeldingen in de geschiedenis gebruiken om uitvoerwaarden op te halen na de implementatie. Met de volgende sjabloon maakt u een openbaar IP-adres en wordt het IP-adres uitgevoerd:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "publicIPAddresses_name": {
      "type": "string"
    }
  },
  "variables": {},
  "resources": [
    {
      "type": "Microsoft.Network/publicIPAddresses",
      "apiVersion": "2021-02-01",
      "name": "[parameters('publicIPAddresses_name')]",
      "location": "southcentralus",
      "properties": {
        "publicIPAddressVersion": "IPv4",
        "publicIPAllocationMethod": "Static",
        "idleTimeoutInMinutes": 4,
        "dnsSettings": {
          "domainNameLabel": "[concat(parameters('publicIPAddresses_name'), uniqueString(resourceGroup().id))]"
        }
      },
      "dependsOn": []
    }
  ],
  "outputs": {
    "returnedIPAddress": {
      "type": "string",
      "value": "[reference(parameters('publicIPAddresses_name')).ipAddress]"
    }
  }
}

De volgende sjabloon is een koppeling naar de voorgaande sjabloon. Er worden drie openbare IP-adressen gemaakt.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
  },
  "variables": {},
  "resources": [
    {
      "type": "Microsoft.Resources/deployments",
      "apiVersion": "2021-04-01",
      "name": "[concat('linkedTemplate', copyIndex())]",
      "copy": {
        "count": 3,
        "name": "ip-loop"
      },
      "properties": {
        "mode": "Incremental",
        "templateLink": {
        "uri": "[uri(deployment().properties.templateLink.uri, 'static-public-ip.json')]",
        "contentVersion": "1.0.0.0"
        },
        "parameters":{
          "publicIPAddresses_name":{"value": "[concat('myip-', copyIndex())]"}
        }
      }
    }
  ]
}

Na de implementatie kunt u de uitvoerwaarden ophalen met het volgende PowerShell-script:

$loopCount = 3
for ($i = 0; $i -lt $loopCount; $i++)
{
  $name = 'linkedTemplate' + $i;
  $deployment = Get-AzResourceGroupDeployment -ResourceGroupName examplegroup -Name $name
  Write-Output "deployment $($deployment.DeploymentName) returned $($deployment.Outputs.returnedIPAddress.value)"
}

Of Azure CLI-script in een Bash-shell:

#!/bin/bash

for i in 0 1 2;
do
  name="linkedTemplate$i";
  deployment=$(az deployment group show -g examplegroup -n $name);
  ip=$(echo $deployment | jq .properties.outputs.returnedIPAddress.value);
  echo "deployment $name returned $ip";
done

Een externe sjabloon beveiligen

Hoewel de gekoppelde sjabloon extern beschikbaar moet zijn, hoeft deze niet algemeen beschikbaar te zijn voor het publiek. U kunt uw sjabloon toevoegen aan een privéopslagaccount dat alleen toegankelijk is voor de eigenaar van het opslagaccount. Vervolgens maakt u een SAS-token (Shared Access Signature) om toegang in te stellen tijdens de implementatie. U voegt dat SAS-token toe aan de URI voor de gekoppelde sjabloon. Hoewel het token wordt doorgegeven als een beveiligde tekenreeks, wordt de URI van de gekoppelde sjabloon, inclusief het SAS-token, vastgelegd in de implementatiebewerkingen. Als u de blootstelling wilt beperken, stelt u een verloopdatum voor het token in.

Het parameterbestand kan ook worden beperkt tot toegang via een SAS-token.

Op dit moment kunt u geen koppeling maken naar een sjabloon in een opslagaccount dat zich achter een firewall Azure Storage bevinden.

Belangrijk

In plaats van uw gekoppelde sjabloon te beveiligen met een SAS-token, kunt u een sjabloonspecificatie maken. De sjabloonspecificatie slaat de hoofdsjabloon en de gekoppelde sjablonen veilig op als een resource in uw Azure-abonnement. U gebruikt Azure RBAC om toegang te verlenen aan gebruikers die de sjabloon moeten implementeren.

In het volgende voorbeeld ziet u hoe u een SAS-token door geeft bij het koppelen aan een sjabloon:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "containerSasToken": { "type": "securestring" }
  },
  "resources": [
    {
      "type": "Microsoft.Resources/deployments",
      "apiVersion": "2021-04-01",
      "name": "linkedTemplate",
      "properties": {
        "mode": "Incremental",
        "templateLink": {
          "uri": "[concat(uri(deployment().properties.templateLink.uri, 'helloworld.json'), parameters('containerSasToken'))]",
          "contentVersion": "1.0.0.0"
        }
      }
    }
  ],
  "outputs": {
  }
}

In PowerShell krijgt u een token voor de container en implementeert u de sjablonen met de volgende opdrachten. U ziet dat containerSasToken de parameter is gedefinieerd in de sjabloon. Het is geen parameter in de New-AzResourceGroupDeployment opdracht .

Set-AzCurrentStorageAccount -ResourceGroupName ManageGroup -Name storagecontosotemplates
$token = New-AzStorageContainerSASToken -Name templates -Permission r -ExpiryTime (Get-Date).AddMinutes(30.0)
$url = (Get-AzStorageBlob -Container templates -Blob parent.json).ICloudBlob.uri.AbsoluteUri
New-AzResourceGroupDeployment -ResourceGroupName ExampleGroup -TemplateUri ($url + $token) -containerSasToken $token

Voor Azure CLI in een Bash-shell krijgt u een token voor de container en implementeert u de sjablonen met de volgende code:

#!/bin/bash

expiretime=$(date -u -d '30 minutes' +%Y-%m-%dT%H:%MZ)
connection=$(az storage account show-connection-string \
  --resource-group ManageGroup \
  --name storagecontosotemplates \
  --query connectionString)
token=$(az storage container generate-sas \
  --name templates \
  --expiry $expiretime \
  --permissions r \
  --output tsv \
  --connection-string $connection)
url=$(az storage blob url \
  --container-name templates \
  --name parent.json \
  --output tsv \
  --connection-string $connection)
parameter='{"containerSasToken":{"value":"?'$token'"}}'
az deployment group create --resource-group ExampleGroup --template-uri $url?$token --parameters $parameter

Voorbeeldsjablonen

In de volgende voorbeelden worden veelgebruikte gekoppelde sjablonen gebruikt.

Hoofdsjabloon	Een gekoppelde sjabloon	Description
Hallo wereld	gekoppelde sjabloon	Retourneert een tekenreeks uit een gekoppelde sjabloon.
Load Balancer met openbaar IP-adres	gekoppelde sjabloon	Hiermee wordt het openbare IP-adres van de gekoppelde sjabloon en wordt die waarde in de load balancer.
Meerdere IP-adressen	gekoppelde sjabloon	Hiermee maakt u verschillende openbare IP-adressen in de gekoppelde sjabloon.

Volgende stappen

Zie Zelfstudie: Een gekoppelde sjabloon implementeren voor een zelfstudie.
Zie Define the order for deploying resources in ARM templates (De volgorde voor het implementeren van resources definiëren in ARM-sjablonen)voor meer informatie over het definiëren van de implementatieorder voor uw resources.
Zie Resource-iteratie in ARM-sjablonenvoor meer informatie over het definiëren van één resource, maar het maken van veel exemplaren ervan.
Zie Resources implementeren met ARM-sjablonen en Azure PowerShell of Resources implementeren met ARM-sjablonen en Azure CLIvoor stappen voor het instellen van een sjabloon in een opslagaccount en het genereren van een SAS-token.

Gekoppelde en geneste sjablonen gebruiken bij het implementeren van Azure-resources

Beoordeel uw ervaring

Geneste sjabloon

Evaluatiebereik van expressies in geneste sjablonen

Een gekoppelde sjabloon

Parameters voor gekoppelde sjabloon

Relatief pad gebruiken voor gekoppelde sjablonen

Sjabloonspecificaties

Afhankelijkheden

contentVersion

Variabelen gebruiken om sjablonen te koppelen

Kopiëren gebruiken

Waarden ophalen uit de gekoppelde sjabloon

Implementatiegeschiedenis

Een externe sjabloon beveiligen

Voorbeeldsjablonen

Volgende stappen