feat: module avm/res/network/virtual-network-gateway (#3324)

## Description
Applied the same approach we did for several other modules that may or
must use a public IP, allowing the use of an existing Public IP
(resourceID)

Closes #3061

## Pipeline Reference


[![avm.res.network.virtual-network-gateway](https://github.com/fabmas/bicep-registry-modules/actions/workflows/avm.res.network.virtual-network-gateway.yml/badge.svg?branch=vnetgw-pip)](https://github.com/fabmas/bicep-registry-modules/actions/workflows/avm.res.network.virtual-network-gateway.yml)

| Pipeline |
| -------- |
|          |

## Type of Change

<!-- Use the checkboxes [x] on the options that are relevant. -->

- [ ] Update to CI Environment or utilities (Non-module affecting
changes)
- [x] Azure Verified Module updates:
- [ ] Bugfix containing backwards-compatible bug fixes, and I have NOT
bumped the MAJOR or MINOR version in `version.json`:
- [x] Someone has opened a bug report issue, and I have included "Closes
#{bug_report_issue_number}" in the PR description.
- [ ] The bug was found by the module author, and no one has opened an
issue to report it yet.
- [x] Feature update backwards compatible feature updates, and I have
bumped the MINOR version in `version.json`.
- [ ] Breaking changes and I have bumped the MAJOR version in
`version.json`.
  - [x] Update to documentation

## Checklist

- [x] I'm sure there are no other open Pull Requests for the same
update/change
- [x] I have run `Set-AVMModule` locally to generate the supporting
module files.
- [x] My corresponding pipelines / checks run clean and green without
any errors or warnings

<!-- Please keep up to date with the contribution guide at
https://aka.ms/avm/contribute/bicep -->

avm/res/network/virtual-network-gateway/main.bicep

@@ -8,8 +8,11 @@ param name string
 @description('Optional. Location for all resources.')
 param location string = resourceGroup().location
 
-@description('Optional. Specifies the name of the Public IP used by the Virtual Network Gateway. If it\'s not provided, a \'-pip\' suffix will be appended to the gateway\'s name.')
-param gatewayPipName string = '${name}-pip1'
+@description('Optional. The Public IP resource ID to associate to the Virtual Network Gateway. If empty, then a new Public IP will be created and applied to the Virtual Network Gateway.')
+param existingFirstPipResourceId string = ''
+
+@description('Optional. Specifies the name of the Public IP to be created for the Virtual Network Gateway. This will only take effect if no existing Public IP is provided. If neither an existing Public IP nor this parameter is specified, a new Public IP will be created with a default name, using the gateway\'s name with the \'-pip1\' suffix.')
+param firstPipName string = '${name}-pip1'
 
 @description('Optional. Resource ID of the Public IP Prefix object. This is only needed if you want your Public IPs created in a PIP Prefix.')
 param publicIPPrefixResourceId string = ''
@@ -21,7 +24,7 @@ param publicIpZones array = [
   3
 ]
 
-@description('Optional. DNS name(s) of the Public IP resource(s). If you enabled active-active configuration, you need to provide 2 DNS names, if you want to use this feature. A region specific suffix will be appended to it, e.g.: your-DNS-name.westeurope.cloudapp.azure.com.')
+@description('Optional. DNS name(s) of the Public IP resource(s). If you enabled Active-Active mode, you need to provide 2 DNS names, if you want to use this feature. A region specific suffix will be appended to it, e.g.: your-DNS-name.westeurope.cloudapp.azure.com.')
 param domainNameLabel array = []
 
 @description('Required. Specifies the gateway type. E.g. VPN, ExpressRoute.')
@@ -39,7 +42,7 @@ param gatewayType string
 ])
 param vpnGatewayGeneration string = 'None'
 
-@description('Optional. The SKU of the Gateway.')
+@description('Required. The SKU of the Gateway.')
 @allowed([
   'Basic'
   'VpnGw1'
@@ -143,18 +146,26 @@ var isBgp = (clusterSettings.clusterMode == 'activeActiveBgp' || clusterSettings
 
 var isActiveActive = (clusterSettings.clusterMode == 'activeActiveNoBgp' || clusterSettings.clusterMode == 'activeActiveBgp') && !isExpressRoute
 
-var activeGatewayPipNameVar = isActiveActive ? (clusterSettings.?activeGatewayPipName ?? '${name}-pip2') : null
+var existingSecondPipResourceIdVar = isActiveActive ? clusterSettings.?existingSecondPipResourceId : null
 
-var virtualGatewayPipNameVar = isActiveActive
-  ? [
-      gatewayPipName
-      activeGatewayPipNameVar
-    ]
-  : [
-      gatewayPipName
-    ]
+var secondPipNameVar = isActiveActive ? (clusterSettings.?secondPipName ?? '${name}-pip2') : null
+
+var arrayPipNameVar = isActiveActive
+  ? concat(
+      !empty(existingFirstPipResourceId)
+        ? []
+        : [firstPipName],
+      !empty(existingSecondPipResourceIdVar)
+        ? []
+        : [secondPipNameVar]
+    )
+  : concat(
+      !empty(existingFirstPipResourceId)
+        ? []
+        : [firstPipName]
+    )
 
-// Potential BGP configurations (active-active vs active-passive)
+// Potential BGP configurations (Active-Active vs Active-Passive)
 var bgpSettingsVar = isActiveActive
   ? {
       asn: clusterSettings.?asn ?? 65515
@@ -179,7 +190,7 @@ var bgpSettingsVar = isActiveActive
       ]
     }
 
-// Potential IP configurations (active-active vs active-passive)
+// Potential IP configurations (Active-Active vs Active-Passive)
 var ipConfiguration = isActiveActive
   ? [
       {
@@ -188,8 +199,11 @@ var ipConfiguration = isActiveActive
           subnet: {
             id: '${vNetResourceId}/subnets/GatewaySubnet'
           }
+          // Use existing Public IP, new Public IP created in this module
           publicIPAddress: {
-            id: az.resourceId('Microsoft.Network/publicIPAddresses', gatewayPipName)
+            id: !empty(existingFirstPipResourceId)
+              ? existingFirstPipResourceId
+              : az.resourceId('Microsoft.Network/publicIPAddresses', firstPipName)
           }
         }
         name: 'vNetGatewayConfig1'
@@ -202,8 +216,12 @@ var ipConfiguration = isActiveActive
           }
           publicIPAddress: {
             id: isActiveActive
-              ? az.resourceId('Microsoft.Network/publicIPAddresses', activeGatewayPipNameVar)
-              : az.resourceId('Microsoft.Network/publicIPAddresses', gatewayPipName)
+            ? !empty(existingSecondPipResourceIdVar)
+            ? existingSecondPipResourceIdVar
+            : az.resourceId('Microsoft.Network/publicIPAddresses', secondPipNameVar)
+          : !empty(existingFirstPipResourceId)
+            ? existingFirstPipResourceId
+            : az.resourceId('Microsoft.Network/publicIPAddresses', firstPipName)
           }
         }
         name: 'vNetGatewayConfig2'
@@ -217,7 +235,9 @@ var ipConfiguration = isActiveActive
             id: '${vNetResourceId}/subnets/GatewaySubnet'
           }
           publicIPAddress: {
-            id: az.resourceId('Microsoft.Network/publicIPAddresses', gatewayPipName)
+            id: !empty(existingFirstPipResourceId)
+              ? existingFirstPipResourceId
+              : az.resourceId('Microsoft.Network/publicIPAddresses', firstPipName)
           }
         }
         name: 'vNetGatewayConfig1'
@@ -323,7 +343,7 @@ resource avmTelemetry 'Microsoft.Resources/deployments@2024-03-01' = if (enableT
 // Public IPs
 @batchSize(1)
 module publicIPAddress 'br/public:avm/res/network/public-ip-address:0.5.1' = [
-  for (virtualGatewayPublicIpName, index) in virtualGatewayPipNameVar: {
+  for (virtualGatewayPublicIpName, index) in arrayPipNameVar: {
     name: virtualGatewayPublicIpName
     params: {
       name: virtualGatewayPublicIpName
@@ -336,7 +356,7 @@ module publicIPAddress 'br/public:avm/res/network/public-ip-address:0.5.1' = [
       skuName: skuName == 'Basic' ? 'Basic' : 'Standard'
       zones: skuName != 'Basic' ? publicIpZones : []
       dnsSettings: {
-        domainNameLabel: length(virtualGatewayPipNameVar) == length(domainNameLabel)
+        domainNameLabel: length(arrayPipNameVar) == length(domainNameLabel)
           ? domainNameLabel[index]
           : virtualGatewayPublicIpName
         domainNameLabelScope: ''
@@ -468,7 +488,7 @@ output name string = virtualNetworkGateway.name
 @description('The resource ID of the virtual network gateway.')
 output resourceId string = virtualNetworkGateway.id
 
-@description('Shows if the virtual network gateway is configured in active-active mode.')
+@description('Shows if the virtual network gateway is configured in Active-Active mode.')
 output activeActive bool = virtualNetworkGateway.properties.activeActive
 
 @description('The location the resource was deployed into.')
@@ -557,17 +577,25 @@ type diagnosticSettingType = {
 }[]?
 
 type activePassiveNoBgpType = {
+
   clusterMode: 'activePassiveNoBgp'
+
 }
 
 type activeActiveNoBgpType = {
+
   clusterMode: 'activeActiveNoBgp'
 
-  @description('Optional. Specifies the name of the Public IP used by the Virtual Network Gateway when active-active configuration is required. If it\'s not provided, a \'-pip2\' suffix will be appended to the gateway\'s name.')
-  activeGatewayPipName: string?
+  @description('Optional. The secondary Public IP resource ID to associate to the Virtual Network Gateway in the Active-Active mode. If empty, then a new secondary Public IP will be created as part of this module and applied to the Virtual Network Gateway.')
+  existingSecondPipResourceId: string?
+
+  @description('Optional. Specifies the name of the secondary Public IP to be created for the Virtual Network Gateway in the Active-Active mode. This will only take effect if no existing secondary Public IP is provided. If neither an existing secondary Public IP nor this parameter is specified, a new secondary Public IP will be created with a default name, using the gateway\'s name with the \'-pip2\' suffix.')
+  secondPipName: string?
+
 }
 
 type activePassiveBgpType = {
+
   clusterMode: 'activePassiveBgp'
 
   @description('Optional. The Autonomous System Number value. If it\'s not provided, a default \'65515\' value will be assigned to the ASN.')
@@ -580,19 +608,22 @@ type activePassiveBgpType = {
 }
 
 type activeActiveBgpType = {
+
   clusterMode: 'activeActiveBgp'
 
-  @description('Optional. Specifies the name of the Public IP used by the Virtual Network Gateway when active-active configuration is required. If it\'s not provided, a \'-pip2\' suffix will be appended to the gateway\'s name.')
-  activeGatewayPipName: string?
-
+  @description('Optional. The secondary Public IP resource ID to associate to the Virtual Network Gateway in the Active-Active mode. If empty, then a new secondary Public IP will be created as part of this module and applied to the Virtual Network Gateway.')
+  existingSecondPipResourceId: string?
+
+  @description('Optional. Specifies the name of the secondary Public IP to be created for the Virtual Network Gateway in the Active-Active mode. This will only take effect if no existing secondary Public IP is provided. If neither an existing secondary Public IP nor this parameter is specified, a new secondary Public IP will be created with a default name, using the gateway\'s name with the \'-pip2\' suffix.')
+  secondPipName: string?
+
   @description('Optional. The Autonomous System Number value. If it\'s not provided, a default \'65515\' value will be assigned to the ASN.')
   @minValue(0)
   @maxValue(4294967295)
   asn: int?
 
   @description('Optional. The list of custom BGP IP Address (APIPA) peering addresses which belong to IP configuration.')
   customBgpIpAddresses: string[]?
-
   @description('Optional. The list of the second custom BGP IP Address (APIPA) peering addresses which belong to IP configuration.')
   secondCustomBgpIpAddresses: string[]?
 }