feat: Introduce Zone-Redundancy interface for Bicep (#1870)

Author: AlexanderSehr

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 >}}

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

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

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< '>providerNamespace</>resourceType<@>apiVersion<' = {
+  name: '>exampleResource<'
+  properties: {
+    ... // other properties
+    zones: !empty(availabilityZone) ? array(string(availabilityZone)) : null
+  }
+}

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< '>providerNamespace</>resourceType<@>apiVersion<' = {
+  name: '>exampleResource<'
+  properties: {
+    ... // other properties
+    zones: map(availabilityZones ?? [], zone => '${zone}')
+  }
+}