Resourcedeclaratie in Bicep
In dit artikel wordt de syntaxis beschreven die u gebruikt om een resource toe te voegen aan uw Bicep-bestand.
Verklaring
Voeg een resourcedeclaratie toe met behulp van het resource trefwoord . U stelt een symbolische naam in voor de resource. De symbolische naam is niet hetzelfde als de resourcenaam. U gebruikt de symbolische naam om te verwijzen naar de resource in andere delen van uw Bicep-bestand.
resource <symbolic-name> '<full-type-name>@<api-version>' = {
<resource-properties>
}
Een declaratie voor een opslagaccount kan dus beginnen met:
resource stg 'Microsoft.Storage/storageAccounts@2021-04-01' = {
...
}
Symbolische namen zijn case-gevoelig. Ze kunnen letters, cijfers en onderstrepingstekens ( ) _ bevatten. Ze kunnen niet met een getal beginnen. Een resource kan niet dezelfde naam hebben als een parameter, variabele of module.
Zie Bicep resource reference (Bicep-resourceverwijzing)voor de beschikbare resourcetypen en -versie. Bicep biedt geen ondersteuning voor apiProfile , die beschikbaar is in Azure Resource Manager-sjablonen (ARM-sjablonen) JSON.
Als u een resource voorwaardelijk wilt implementeren, gebruikt u de if syntaxis. Zie Voorwaardelijke implementatie in Bicep voor meer informatie.
resource <symbolic-name> '<full-type-name>@<api-version>' = if (condition) {
<resource-properties>
}
Als u meer dan één exemplaar van een resource wilt implementeren, gebruikt u de for syntaxis. U kunt deator gebruiken om op te geven of de exemplaren batchSize serieel of parallel worden geïmplementeerd. Zie Iteratieve lussen in Bicep voor meer informatie.
@batchSize(int) // optional decorator for serial deployment
resource <symbolic-name> '<full-type-name>@<api-version>' = [for <item> in <collection>: {
<properties-to-repeat>
}]
U kunt ook de for syntaxis van de resource-eigenschappen gebruiken om een matrix te maken.
resource <symbolic-name> '<full-type-name>@<api-version>' = {
properties: {
<array-property>: [for <item> in <collection>: <value-to-repeat>]
}
}
Resourcenaam
Elke resource heeft een naam. Let bij het instellen van de resourcenaam op de regels en beperkingen voor resourcenamen.
resource stg 'Microsoft.Storage/storageAccounts@2019-06-01' = {
name: 'examplestorage'
...
}
Normaal gesproken stelt u de naam in op een parameter, zodat u tijdens de implementatie verschillende waarden kunt doorgeven.
@minLength(3)
@maxLength(24)
param storageAccountName string
resource stg 'Microsoft.Storage/storageAccounts@2019-06-01' = {
name: storageAccountName
...
}
Locatie
Voor veel resources is een locatie vereist. U kunt bepalen of de resource een locatie nodig heeft via intellisense of sjabloonverwijzing. In het volgende voorbeeld wordt een locatieparameter toegevoegd die wordt gebruikt voor het opslagaccount.
resource stg 'Microsoft.Storage/storageAccounts@2019-06-01' = {
name: 'examplestorage'
location: 'eastus'
...
}
Normaal gesproken stelt u de locatie in op een parameter, zodat u op verschillende locaties kunt implementeren.
param location string = resourceGroup().location
resource stg 'Microsoft.Storage/storageAccounts@2019-06-01' = {
name: 'examplestorage'
location: location
...
}
Verschillende resourcetypen worden ondersteund op verschillende locaties. Zie Beschikbare producten per regio om de ondersteunde locaties voor een Azure-service op te halen. Als u de ondersteunde locaties voor een resourcetype wilt op halen, gebruikt u Azure PowerShell of Azure CLI.
((Get-AzResourceProvider -ProviderNamespace Microsoft.Batch).ResourceTypes `
| Where-Object ResourceTypeName -eq batchAccounts).Locations
Tags
U kunt tags toepassen op een resource tijdens de implementatie. Tags helpen u bij het logisch organiseren van uw geïmplementeerde resources. Zie ARM-sjabloontags voor voorbeelden van de verschillende manieren waarop u de tags kunt opgeven.
Beheerde identiteiten voor Azure-resources
Sommige resources ondersteunen beheerde identiteiten voor Azure-resources. Deze resources hebben een identiteitsobject op het hoofdniveau van de resourcedeclaratie.
U kunt door het systeem toegewezen of door de gebruiker toegewezen identiteiten gebruiken.
In het volgende voorbeeld ziet u hoe u een door het systeem toegewezen identiteit configureert voor een Azure Kubernetes Service cluster.
resource aks 'Microsoft.ContainerService/managedClusters@2020-09-01' = {
name: clusterName
location: location
tags: tags
identity: {
type: 'SystemAssigned'
}
In het volgende voorbeeld ziet u hoe u een door de gebruiker toegewezen identiteit configureert voor een virtuele machine.
param userAssignedIdentity string
resource vm 'Microsoft.Compute/virtualMachines@2020-06-01' = {
name: vmName
location: location
identity: {
type: 'UserAssigned'
userAssignedIdentities: {
'${userAssignedIdentity}': {}
}
}
Resourcespecifieke eigenschappen
De voorgaande eigenschappen zijn algemeen voor de meeste resourcetypen. Nadat u deze waarden hebt ingesteld, moet u de eigenschappen instellen die specifiek zijn voor het resourcetype dat u implementeert.
Gebruik de resourceverwijzing IntelliSense of Bicep om te bepalen welke eigenschappen beschikbaar zijn en welke vereist zijn. In het volgende voorbeeld worden de resterende eigenschappen voor een opslagaccount instellen.
resource stg 'Microsoft.Storage/storageAccounts@2019-06-01' = {
name: 'examplestorage'
location: 'eastus'
sku: {
name: 'Standard_LRS'
tier: 'Standard'
}
kind: 'StorageV2'
properties: {
accessTier: 'Hot'
}
}
Afhankelijkheden
Bij het implementeren van resources moet u er mogelijk voor zorgen dat sommige resources bestaan vóór andere resources. U hebt bijvoorbeeld een logische SQL server nodig voordat u een database implementeert. U stelt deze relatie tot stand door één resource als afhankelijk van de andere resource te markeren. De volgorde van de resource-implementatie kan op twee manieren worden beïnvloed: impliciete afhankelijkheid en expliciete afhankelijkheid
Azure Resource Manager evalueert de afhankelijkheden tussen resources en implementeert deze in de afhankelijke volgorde. Als resources niet van elkaar afhankelijk zijn, worden deze door Resource Manager parallel geïmplementeerd. U hoeft alleen afhankelijkheden te definiëren voor resources die zijn geïmplementeerd in hetzelfde Bicep-bestand.
Impliciete afhankelijkheid
Er wordt een impliciete afhankelijkheid gemaakt wanneer de ene resourcedeclaratie verwijst naar een andere resource in dezelfde implementatie. In het volgende voorbeeld wordt bijvoorbeeld naar dnsZone verwezen door de tweede resourcedefinitie:
resource dnsZone 'Microsoft.Network/dnszones@2018-05-01' = {
name: 'myZone'
location: 'global'
}
resource otherResource 'Microsoft.Example/examples@2020-06-01' = {
name: 'exampleResource'
properties: {
// get read-only DNS zone property
nameServers: dnsZone.properties.nameServers
}
}
Een geneste resource heeft ook een impliciete afhankelijkheid van de resource die deze bevat.
resource myParent 'My.Rp/parentType@2020-01-01' = {
name: 'myParent'
location: 'West US'
// depends on 'myParent' implicitly
resource myChild 'childType' = {
name: 'myChild'
}
}
Wanneer er een impliciete afhankelijkheid bestaat, moet u geen expliciete afhankelijkheid toevoegen.
Zie Set name and type for child resources in Bicep (Naam en typeinstellen voor onderliggende resources in Bicep) voor meer informatie over geneste resources.
Expliciete afhankelijkheid
Een expliciete afhankelijkheid wordt gedeclareerd met de dependsOn eigenschap . De eigenschap accepteert een matrix met resource-id's, zodat u meer dan één afhankelijkheid kunt opgeven.
In het volgende voorbeeld ziet u een DNS-zone met otherZone de naam die afhankelijk is van een DNS-zone met de naam dnsZone :
resource dnsZone 'Microsoft.Network/dnszones@2018-05-01' = {
name: 'demoeZone1'
location: 'global'
}
resource otherZone 'Microsoft.Network/dnszones@2018-05-01' = {
name: 'demoZone2'
location: 'global'
dependsOn: [
dnsZone
]
}
Hoewel u misschien niet wilt gebruiken om relaties tussen uw resources toe te wijs, is het belangrijk om te begrijpen dependsOn waarom u dit doet. Als u bijvoorbeeld wilt documenteren hoe resources onderling zijn verbonden, dependsOn is niet de juiste benadering. U kunt na de implementatie geen query uitvoeren op de resources die in dependsOn het element zijn gedefinieerd. Het instellen van onnodige afhankelijkheden vertraagt de implementatietijd omdat Resource Manager resources niet parallel kunnen implementeren.
Hoewel expliciete afhankelijkheden soms vereist zijn, is de noodzaak ervan zeldzaam. In de meeste gevallen kunt u een symbolische naam gebruiken om de afhankelijkheid tussen resources te impliceren. Als u vindt dat u expliciete afhankelijkheden instelt, moet u overwegen of er een manier is om deze te verwijderen.
Afhankelijkheden visualiseren
Visual Studio Code biedt een hulpprogramma voor het visualiseren van de afhankelijkheden. Open een Bicep-bestand in Visual Studio Code en selecteer vervolgens de knop visualizer in de linkerbovenhoek. In de volgende schermopname ziet u de afhankelijkheden van een virtuele machine.
Bestaande resources
Als u wilt verwijzen naar een resource die zich buiten het huidige Bicep-bestand, gebruikt u het existing trefwoord in een resourcedeclaratie.
Wanneer u het existing trefwoord gebruikt, geeft u de name van de resource op. In het volgende voorbeeld wordt een bestaand opslagaccount in dezelfde resourcegroep als de huidige implementatie opgeslagen.
resource stg 'Microsoft.Storage/storageAccounts@2019-06-01' existing = {
name: 'examplestorage'
}
output blobEndpoint string = stg.properties.primaryEndpoints.blob
U kunt eventueel de eigenschap instellen scope voor toegang tot een resource in een ander bereik. In het volgende voorbeeld wordt verwezen naar een bestaand opslagaccount in een andere resourcegroep.
resource stg 'Microsoft.Storage/storageAccounts@2019-06-01' existing = {
name: 'examplestorage'
scope: resourceGroup(exampleRG)
}
output blobEndpoint string = stg.properties.primaryEndpoints.blob
Als u probeert te verwijzen naar een resource die niet bestaat, krijgt u de NotFound foutmelding en mislukt uw implementatie.
Zie Bereikfuncties voor Bicep voor meer informatie over het instellen van het bereik.
In de voorgaande voorbeelden wordt het opslagaccount niet geïmplementeerd. In plaats daarvan kunt u eigenschappen van de bestaande resource openen met behulp van de symbolische naam.
Volgende stappen
- Zie Voorwaardelijke implementatie in Bicep als u een resource voorwaardelijk wilt implementeren.