Ressourcendeklaration in Bicep

  • Artikel

Dieser Artikel beschreibt die Syntax, mit der Sie eine Ressource zu Ihrer Bicep-Datei hinzufügen können. Die Anzahl der Ressourcen in einer Bicep-Datei ist auf 800 beschränkt. Weitere Informationen finden Sie unter Vorlagengrenzwerte.

Definieren von Ressourcen

Fügen Sie eine Ressourcendeklaration mit dem Schlüsselwort resource hinzu. Sie legen einen symbolischen Namen für die Ressource fest. Der symbolische Name ist nicht mit dem Ressourcennamen identisch. Sie verwenden den symbolischen Namen, um in anderen Teilen der Bicep-Datei auf die Ressource zu verweisen.

@<decorator>(<argument>)
resource <symbolic-name> '<full-type-name>@<api-version>' = {
  <resource-properties>
}

Eine Erklärung für ein Speicherkonto kann also mit:

resource stg 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  ...
}

Bei symbolischen Namen wird zwischen Groß- und Kleinschreibung unterschieden. Sie dürfen nur Buchstaben, Zahlen und Unterstriche (_) enthalten. Sie dürfen nicht mit einer Zahl beginnen. Eine Ressource darf nicht denselben Namen wie ein Parameter, eine Variable oder ein Modul haben.

Für die verfügbaren Ressourcentypen und Versionen, siehe Bicep-Ressourcenreferenz. Das apiProfile-Element wird von Bicep nicht unterstützt. Dieses Element ist in ARM-Vorlagen-JSON-Dateien (Azure Resource Manager) verfügbar. Sie können auch Ressourcen für Bicep-Erweiterbarkeitsanbieter definieren. Weitere Informationen finden Sie unter Bicep-Erweiterbarkeit des Kubernetes-Anbieters.

Um eine Ressource bedingt einzusetzen, verwenden Sie die Syntax if. Für weitere Informationen siehe Bedingter Einsatz in Bicep.

resource <symbolic-name> '<full-type-name>@<api-version>' = if (condition) {
  <resource-properties>
}

Um mehr als eine Instanz einer Ressource bereitzustellen, verwenden Sie die Syntax for. Sie können den Decorator batchSize verwenden, um anzugeben, ob die Instanzen nacheinander oder parallel bereitgestellt werden sollen. Für weitere Informationen siehe Iterative Schleifen in Bicep.

@batchSize(int) // optional decorator for serial deployment
resource <symbolic-name> '<full-type-name>@<api-version>' = [for <item> in <collection>: {
  <properties-to-repeat>
}]

Sie können auch die Syntax for für die Ressourceneigenschaften verwenden, um ein Array zu erstellen.

resource <symbolic-name> '<full-type-name>@<api-version>' = {
  properties: {
    <array-property>: [for <item> in <collection>: <value-to-repeat>]
  }
}

Verwenden von Decorator-Elementen

Decorator-Elemente werden im Format @expression geschrieben und oberhalb von Ressourcendeklarationen platziert. In der folgenden Tabelle werden die für Ressourcen verfügbaren Decorator-Elemente gezeigt.

Decorator Argument Beschreibung
batchSize none Richten Sie Instanzen so ein, dass sie sequenziell bereitgestellt werden.
Beschreibung string Geben Sie Beschreibungen für die Ressource an.

Decorators befinden sich im sys-Namespace. Wenn Sie diesen Decorator von einem anderen Element gleichen Namens unterscheiden müssen, stellen Sie dem Decorator sys voran. Zum Beispiel, wenn Ihre Bicep Datei einen Parameter mit dem Namen description enthält, müssen Sie den sys Namespace hinzufügen, wenn Sie den description Dekorator verwenden.

BatchSize

Sie können @batchSize() nur auf eine Ressourcen- oder Moduldefinition anwenden, die einen for-Ausdruck verwendet.

Standardmäßig werden Ressourcen parallel bereitgestellt. Wenn Sie den batchSize(int)Decorator hinzufügen, stellen Sie Instanzen seriell bereit.

@batchSize(3)
resource storageAccountResources 'Microsoft.Storage/storageAccounts@2023-04-01' = [for storageName in storageAccounts: {
  ...
}]

Weitere Informationen finden Sie unter Bereitstellung in Batches.

Beschreibung

Um eine Erklärung hinzuzufügen, fügen Sie Ressourcendeklarationen eine Beschreibung hinzu. Zum Beispiel:

@description('Create a number of storage accounts')
resource storageAccountResources 'Microsoft.Storage/storageAccounts@2023-04-01' = [for storageName in storageAccounts: {
  ...
}]

Mit Markdown formatierter Text kann für den Beschreibungstext verwendet werden.

Ressourcenname

Jede Ressource besitzt einen Namen. Achten Sie beim Festlegen des Ressourcennamens auf die Regeln und Einschränkungen für Ressourcennamen.

resource stg 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name: 'examplestorage'
  ...
}

In der Regel legen Sie den Namen auf einen Parameter fest, damit Sie während der Bereitstellung unterschiedliche Werte übergeben können.

@minLength(3)
@maxLength(24)
param storageAccountName string

resource stg 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name: storageAccountName
  ...
}

Ressourcenspeicherort

Viele Ressourcen erfordern einen Speicherort. Sie können mittels IntelliSense oder über eine Vorlagenreferenz ermitteln, ob die Ressource einen Speicherort benötigt. Im folgenden Beispiel wird ein Speicherortparameter hinzugefügt, der für das Speicherkonto verwendet wird.

resource stg 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name: 'examplestorage'
  location: 'eastus'
  ...
}

In der Regel legen Sie den Standort auf einen Parameter fest, damit die Bereitstellung an verschiedenen Standorten erfolgen kann.

param location string = resourceGroup().location

resource stg 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name: 'examplestorage'
  location: location
  ...
}

An verschiedenen Speicherorten werden unterschiedliche Ressourcentypen unterstützt. Informationen zum Abrufen der unterstützten Standorte für einen Azure-Dienst finden Sie unter Verfügbare Produkte nach Region. Verwenden Sie Azure PowerShell oder die Azure-Befehlszeilenschnittstelle, um die unterstützten Speicherorte für einen Ressourcentyp abzurufen.

((Get-AzResourceProvider -ProviderNamespace Microsoft.Batch).ResourceTypes `
  | Where-Object ResourceTypeName -eq batchAccounts).Locations

Ressourcentags

Sie können während der Bereitstellung Tags auf eine Ressource anwenden. Tags helfen Ihnen dabei, Ihre bereitgestellten Ressourcen logisch zu organisieren. Beispiele für die verschiedenen Methoden zum Angeben der Tags finden Sie unter ARM-Vorlagen-Tags.

Verwaltete Identitäten für Ressourcen

Einige Ressourcen unterstützen verwaltete Identitäten für Azure-Ressourcen. Diese Ressourcen verfügen über ein Identitätsobjekt auf der Stammebene der Ressourcendeklaration.

Sie können entweder systemseitig oder benutzerseitig zugewiesene Identitäten verwenden.

Das folgende Beispiel zeigt, wie sie eine systemseitig zugewiesene Identität für einen Azure Kubernetes Service-Cluster konfigurieren.

resource aks 'Microsoft.ContainerService/managedClusters@2024-02-01' = {
  name: clusterName
  location: location
  tags: tags
  identity: {
    type: 'SystemAssigned'
  }

Im nächsten Beispiel wird gezeigt, wie Sie eine benutzerseitig zugewiesene Identität für einen virtuellen Computer konfigurieren.

param userAssignedIdentity string

resource vm 'Microsoft.Compute/virtualMachines@2024-03-01' = {
  name: vmName
  location: location
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '${userAssignedIdentity}': {}
    }
  }

Ressourcenspezifische Eigenschaften

Die vorstehenden Eigenschaften sind für die meisten Ressourcentypen generisch. Nachdem Sie diese Werte festgelegt haben, müssen Sie die Eigenschaften festlegen, die für den Ressourcentyp, den Sie bereitstellen, spezifisch sind.

Verwenden Sie Intellisense oder die Bicep-Ressourcenreferenz, um festzustellen, welche Eigenschaften verfügbar sind und welche erforderlich sind. Im folgenden Beispiel werden die restlichen Eigenschaften für ein Speicherkonto festgelegt.

resource stg 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name: 'examplestorage'
  location: 'eastus'
  sku: {
    name: 'Standard_LRS'
    tier: 'Standard'
  }
  kind: 'StorageV2'
  properties: {
    accessTier: 'Hot'
  }
}

Nächste Schritte