diff --git a/docs/content/specs-defs/specs/bicep/interfaces.md b/docs/content/specs-defs/specs/bicep/interfaces.md index 1dc5f6220..2c357c32e 100644 --- a/docs/content/specs-defs/specs/bicep/interfaces.md +++ b/docs/content/specs-defs/specs/bicep/interfaces.md @@ -275,3 +275,32 @@ Which returns a JSON-formatted output like: This interface is a **SHOULD** instead of a **MUST** and therefore the AVM core team have not mandated a interface schema to use. {{% /notice %}} + +## Zonal & zone-redundant resources + +Many Azure resources can be deployed into specific availability zones. Depending on whether a resource is 'zonal' (i.e., deploys a single instance into a single zone) or 'zone-redundant' (i.e., spreads multiple of its instances across the configured zones), implementing a different interface is required. Simply put, the zone of a zonal resource must be a required parameter (but give the user the option to 'opt-out'), while zone-redundant resources must span all available zones by default, but still give the user the option to 'opt-out'. Please note that the support for Availability Zones may differ from region to region. + +{{< tabs title="" >}} +{{% tab title="Variant 1: Zone-redundant resource (e.g., VirtualMachineScaleSet)" %}} + + {{< highlight lineNos="false" type="bicep" wrap="true" title="Parameter & Resource Example" >}} + {{% include file="/static/includes/interfaces/bicep/int.zone.schema1.bicep" %}} + {{< /highlight >}} + + {{< highlight lineNos="false" type="bicep" wrap="true" title="Input Example with Values" >}} + {{% include file="/static/includes/interfaces/bicep/int.zone.input1.bicep" %}} + {{< /highlight >}} + +{{% /tab %}} +{{% tab title="Variant 2: Zonal resource (e.g., Compute Disk)" %}} + + {{< highlight lineNos="false" type="bicep" wrap="true" title="Parameter & Resource Example" >}} + {{% include file="/static/includes/interfaces/bicep/int.zone.schema2.bicep" %}} + {{< /highlight >}} + + {{< highlight lineNos="false" type="bicep" wrap="true" title="Input Example with Values" >}} + {{% include file="/static/includes/interfaces/bicep/int.zone.input2.bicep" %}} + {{< /highlight >}} + +{{% /tab %}} +{{< /tabs >}} diff --git a/docs/static/includes/interfaces/bicep/int.zone.input1.bicep b/docs/static/includes/interfaces/bicep/int.zone.input1.bicep new file mode 100644 index 000000000..13bd82846 --- /dev/null +++ b/docs/static/includes/interfaces/bicep/int.zone.input1.bicep @@ -0,0 +1,2 @@ +availabilityZone: -1 // Deploy into no zone +availabilityZone: 1 // Deploy into zone 1 diff --git a/docs/static/includes/interfaces/bicep/int.zone.input2.bicep b/docs/static/includes/interfaces/bicep/int.zone.input2.bicep new file mode 100644 index 000000000..5c68ed524 --- /dev/null +++ b/docs/static/includes/interfaces/bicep/int.zone.input2.bicep @@ -0,0 +1,2 @@ +availabilityZones: [] // Deploy into no zone +availabilityZones: [1, 2] // Deploy into zone 1 & 2 diff --git a/docs/static/includes/interfaces/bicep/int.zone.schema1.bicep b/docs/static/includes/interfaces/bicep/int.zone.schema1.bicep new file mode 100644 index 000000000..559a40e82 --- /dev/null +++ b/docs/static/includes/interfaces/bicep/int.zone.schema1.bicep @@ -0,0 +1,24 @@ +// ============== // +// Parameters // +// ============== // + +@description('Required. If set to 1, 2 or 3, the availability zone is hardcoded to that value. If set to -1, no zone is defined. Note that the availability zone numbers here are the logical availability zone in your Azure subscription. Different subscriptions might have a different mapping of the physical zone and logical zone. To understand more, please refer to [Physical and logical availability zones](https://learn.microsoft.com/en-us/azure/reliability/availability-zones-overview?tabs=azure-cli#physical-and-logical-availability-zones) and [Distribute VMs and disks across availability zones](https://learn.microsoft.com/en-us/azure/virtual-machines/disks-high-availability#distribute-vms-and-disks-across-availability-zones).') +@allowed([ + -1 + 1 + 2 + 3 +]) +param availabilityZone int + +// ============= // +// Resources // +// ============= // + +resource >singularMainResourceType< '>providerNamespaceresourceType<@>apiVersion<' = { + name: '>exampleResource<' + properties: { + ... // other properties + zones: !empty(availabilityZone) ? array(string(availabilityZone)) : null + } +} diff --git a/docs/static/includes/interfaces/bicep/int.zone.schema2.bicep b/docs/static/includes/interfaces/bicep/int.zone.schema2.bicep new file mode 100644 index 000000000..23c6648df --- /dev/null +++ b/docs/static/includes/interfaces/bicep/int.zone.schema2.bicep @@ -0,0 +1,23 @@ +// ============== // +// Parameters // +// ============== // + +@description('Optional. The list of Availability zones to use for the zone-redundant resources.') +@allowed([ + 1 + 2 + 3 +]) +param availabilityZones int[] = [1, 2, 3] + +// ============= // +// Resources // +// ============= // + +resource >singularMainResourceType< '>providerNamespaceresourceType<@>apiVersion<' = { + name: '>exampleResource<' + properties: { + ... // other properties + zones: map(availabilityZones ?? [], zone => '${zone}') + } +}