diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 129120b3a4..a4ca574867 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -20,7 +20,7 @@ Please delete options that are not relevant. - [ ] Bug fix (non-breaking change which fixes an issue) - [ ] New feature (non-breaking change which adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) -- [ ] This change requires a documentation update (Wiki) +- [ ] Update to documentation # Checklist diff --git a/arm/Microsoft.AAD/DomainServices/deploy.bicep b/arm/Microsoft.AAD/DomainServices/deploy.bicep index d47a8e6fcf..b8b482446d 100644 --- a/arm/Microsoft.AAD/DomainServices/deploy.bicep +++ b/arm/Microsoft.AAD/DomainServices/deploy.bicep @@ -128,6 +128,9 @@ param tags object = {} @maxValue(365) param diagnosticLogsRetentionInDays int = 365 +@description('Optional. Enable telemetry via the Customer Usage Attribution ID (GUID).') +param enableDefaultTelemetry bool = true + @allowed([ 'CanNotDelete' 'NotSpecified' @@ -172,6 +175,18 @@ var diagnosticsLogs = [for log in logsToEnable: { } }] +resource defaultTelemetry 'Microsoft.Resources/deployments@2021-04-01' = if (enableDefaultTelemetry) { + name: 'pid-47ed15a6-730a-4827-bcb4-0fd963ffbd82-${uniqueString(deployment().name)}' + properties: { + mode: 'Incremental' + template: { + '$schema': 'https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#' + contentVersion: '1.0.0.0' + resources: [] + } + } +} + resource domainService 'Microsoft.AAD/DomainServices@2021-05-01' = { name: name location: location diff --git a/arm/Microsoft.AAD/DomainServices/readme.md b/arm/Microsoft.AAD/DomainServices/readme.md index 0b5b5c892d..052da957d4 100644 --- a/arm/Microsoft.AAD/DomainServices/readme.md +++ b/arm/Microsoft.AAD/DomainServices/readme.md @@ -41,6 +41,7 @@ This template deploys Azure Active Directory Domain Services (AADDS). | `diagnosticStorageAccountId` | string | `''` | | Resource ID of the diagnostic storage account. | | `diagnosticWorkspaceId` | string | `''` | | Resource ID of the diagnostic log analytics workspace. | | `domainConfigurationType` | string | `'FullySynced'` | `[FullySynced, ResourceTrusting]` | The value is to provide domain configuration type. | +| `enableDefaultTelemetry` | bool | `True` | | Enable telemetry via the Customer Usage Attribution ID (GUID). | | `externalAccess` | string | `'Enabled'` | `[Enabled, Disabled]` | The value is to enable the Secure LDAP for external services of Azure ADDS Services. | | `filteredSync` | string | `'Enabled'` | | The value is to synchronise scoped users and groups. | | `kerberosArmoring` | string | `'Enabled'` | `[Enabled, Disabled]` | The value is to enable to provide a protected channel between the Kerberos client and the KDC. | diff --git a/arm/Microsoft.Compute/virtualMachines/deploy.bicep b/arm/Microsoft.Compute/virtualMachines/deploy.bicep index 2124046ea1..d2b9d03753 100644 --- a/arm/Microsoft.Compute/virtualMachines/deploy.bicep +++ b/arm/Microsoft.Compute/virtualMachines/deploy.bicep @@ -352,7 +352,7 @@ module virtualMachine_nic '.bicep/nested_networkInterface.bicep' = [for (nicConf enableIPForwarding: contains(nicConfiguration, 'enableIPForwarding') ? (!empty(nicConfiguration.enableIPForwarding) ? nicConfiguration.enableIPForwarding : false) : false enableAcceleratedNetworking: contains(nicConfiguration, 'enableAcceleratedNetworking') ? nicConfiguration.enableAcceleratedNetworking : true dnsServers: contains(nicConfiguration, 'dnsServers') ? (!empty(nicConfiguration.dnsServers) ? nicConfiguration.dnsServers : []) : [] - networkSecurityGroupId: contains(nicConfiguration, 'nsgId') ? (!empty(nicConfiguration.nsgId) ? nicConfiguration.nsgId : '') : '' + networkSecurityGroupId: contains(nicConfiguration, 'networkSecurityGroupId') ? (!empty(nicConfiguration.networkSecurityGroupId) ? nicConfiguration.networkSecurityGroupId : '') : '' ipConfigurationArray: nicConfiguration.ipConfigurations lock: lock diagnosticStorageAccountId: diagnosticStorageAccountId diff --git a/arm/Microsoft.Network/azureFirewalls/deploy.bicep b/arm/Microsoft.Network/azureFirewalls/deploy.bicep index f70cff6015..def11ea777 100644 --- a/arm/Microsoft.Network/azureFirewalls/deploy.bicep +++ b/arm/Microsoft.Network/azureFirewalls/deploy.bicep @@ -15,16 +15,16 @@ param azureSkuName string = 'AZFW_VNet' ]) param azureSkuTier string = 'Standard' -@description('Required. Shared services Virtual Network resource ID. The virtual network ID containing AzureFirewallSubnet. If a public ip is not provided, then the public ip that is created as part of this module will be applied with the subnet provided in this variable') +@description('Required. Shared services Virtual Network resource ID. The virtual network ID containing AzureFirewallSubnet. If a public ip is not provided, then the public ip that is created as part of this module will be applied with the subnet provided in this variable.') param vNetId string -@description('Optional. The public ip resource ID to associate to the AzureFirewallSubnet. If empty, then the public ip that is created as part of this module will be applied to the AzureFirewallSubnet') +@description('Optional. The public ip resource ID to associate to the AzureFirewallSubnet. If empty, then the public ip that is created as part of this module will be applied to the AzureFirewallSubnet.') param azureFirewallSubnetPublicIpId string = '' -@description('Optional. This is to add any additional public ip configurations on top of the public ip with subnet ip configuration') +@description('Optional. This is to add any additional public ip configurations on top of the public ip with subnet ip configuration.') param additionalPublicIpConfigurations array = [] -@description('Optional. Specifies if a public ip should be created by default if one is not provided') +@description('Optional. Specifies if a public ip should be created by default if one is not provided.') param isCreateDefaultPublicIP bool = true @description('Optional. Specifies the properties of the public IP to create and be used by Azure Firewall. If it\'s not provided and publicIPAddressId is empty, a \'-pip\' suffix will be appended to the Firewall\'s name.') @@ -85,7 +85,7 @@ param location string = resourceGroup().location @description('Optional. Specify the type of lock.') param lock string = 'NotSpecified' -@description('Optional. Array of role assignment objects that contain the \'roleDefinitionIdOrName\' and \'principalId\' to define RBAC role assignments on this resource. In the roleDefinitionIdOrName attribute, you can provide either the display name of the role definition, or its fully qualified ID in the following format: \'/providers/Microsoft.Authorization/roleDefinitions/c2f4ef07-c644-48eb-af81-4b1b4947fb11\'') +@description('Optional. Array of role assignment objects that contain the \'roleDefinitionIdOrName\' and \'principalId\' to define RBAC role assignments on this resource. In the roleDefinitionIdOrName attribute, you can provide either the display name of the role definition, or its fully qualified ID in the following format: \'/providers/Microsoft.Authorization/roleDefinitions/c2f4ef07-c644-48eb-af81-4b1b4947fb11\'.') param roleAssignments array = [] @description('Optional. Tags of the Azure Firewall resource.') @@ -142,11 +142,19 @@ var existingPip = { } } var newPip = { - publicIPAddress: { + publicIPAddress: (empty(azureFirewallSubnetPublicIpId) && isCreateDefaultPublicIP) ? { id: publicIPAddress.outputs.resourceId - } + } : null } +var ipConfigurations = concat([ + { + name: 'IpConfAzureFirewallSubnet' + //Use existing public ip, new public ip created in this module, or none if isCreateDefaultPublicIP is false + properties: union(subnet_var, !empty(azureFirewallSubnetPublicIpId) ? existingPip : {}, (isCreateDefaultPublicIP ? newPip : {})) + } +], additionalPublicIpConfigurations_var) + // ---------------------------------------------------------------------------- var diagnosticsLogs = [for category in diagnosticLogCategoriesToEnable: { @@ -226,14 +234,7 @@ resource azureFirewall 'Microsoft.Network/azureFirewalls@2021-05-01' = { firewallPolicy: empty(firewallPolicyId) ? null : { id: firewallPolicyId } - ipConfigurations: concat([ - { - name: 'IpConfAzureFirewallSubnet' - //Use existing public ip, new public ip created in this module, or none if isCreateDefaultPublicIP is false - properties: !empty(azureFirewallSubnetPublicIpId) ? union(subnet_var, existingPip) : (isCreateDefaultPublicIP ? union(subnet_var, newPip) : subnet_var) - } - ], additionalPublicIpConfigurations_var) - + ipConfigurations: ipConfigurations sku: { name: azureSkuName tier: azureSkuTier @@ -289,7 +290,7 @@ output resourceGroupName string = resourceGroup().name @description('The private IP of the Azure firewall.') output privateIp string = azureFirewall.properties.ipConfigurations[0].properties.privateIPAddress -@description('The public ipconfiguration object for the AzureFirewallSubnet') +@description('The public ipconfiguration object for the AzureFirewallSubnet.') output ipConfAzureFirewallSubnet object = azureFirewall.properties.ipConfigurations[0] @description('List of Application Rule Collections.') diff --git a/arm/Microsoft.Network/azureFirewalls/readme.md b/arm/Microsoft.Network/azureFirewalls/readme.md index c661be4c9c..784df6694d 100644 --- a/arm/Microsoft.Network/azureFirewalls/readme.md +++ b/arm/Microsoft.Network/azureFirewalls/readme.md @@ -8,6 +8,7 @@ This module deploys a firewall. - [Parameters](#Parameters) - [Outputs](#Outputs) - [Considerations](#Considerations) +- [Deployment examples](#Deployment-examples) ## Resource types @@ -26,14 +27,14 @@ This module deploys a firewall. | Parameter Name | Type | Description | | :-- | :-- | :-- | | `name` | string | Name of the Azure Firewall. | -| `vNetId` | string | Shared services Virtual Network resource ID. The virtual network ID containing AzureFirewallSubnet. If a public ip is not provided, then the public ip that is created as part of this module will be applied with the subnet provided in this variable | +| `vNetId` | string | Shared services Virtual Network resource ID. The virtual network ID containing AzureFirewallSubnet. If a public ip is not provided, then the public ip that is created as part of this module will be applied with the subnet provided in this variable. | **Optional parameters** | Parameter Name | Type | Default Value | Allowed Values | Description | | :-- | :-- | :-- | :-- | :-- | -| `additionalPublicIpConfigurations` | array | `[]` | | This is to add any additional public ip configurations on top of the public ip with subnet ip configuration | +| `additionalPublicIpConfigurations` | array | `[]` | | This is to add any additional public ip configurations on top of the public ip with subnet ip configuration. | | `applicationRuleCollections` | array | `[]` | | Collection of application rule collections used by Azure Firewall. | -| `azureFirewallSubnetPublicIpId` | string | `''` | | The public ip resource ID to associate to the AzureFirewallSubnet. If empty, then the public ip that is created as part of this module will be applied to the AzureFirewallSubnet | +| `azureFirewallSubnetPublicIpId` | string | `''` | | The public ip resource ID to associate to the AzureFirewallSubnet. If empty, then the public ip that is created as part of this module will be applied to the AzureFirewallSubnet. | | `azureSkuName` | string | `'AZFW_VNet'` | `[AZFW_VNet, AZFW_Hub]` | Name of an Azure Firewall SKU. | | `azureSkuTier` | string | `'Standard'` | `[Standard, Premium]` | Tier of an Azure Firewall. | | `diagnosticEventHubAuthorizationRuleId` | string | `''` | | Resource ID of the diagnostic event hub authorization rule for the Event Hubs namespace in which the event hub should be created or streamed to. | @@ -46,13 +47,13 @@ This module deploys a firewall. | `diagnosticWorkspaceId` | string | `''` | | Log Analytics workspace resource identifier. | | `enableDefaultTelemetry` | bool | `True` | | Enable telemetry via the Customer Usage Attribution ID (GUID). | | `firewallPolicyId` | string | `''` | | Resource ID of the Firewall Policy that should be attached. | -| `isCreateDefaultPublicIP` | bool | `True` | | Specifies if a public ip should be created by default if one is not provided | +| `isCreateDefaultPublicIP` | bool | `True` | | Specifies if a public ip should be created by default if one is not provided. | | `location` | string | `[resourceGroup().location]` | | Location for all resources. | | `lock` | string | `'NotSpecified'` | `[CanNotDelete, NotSpecified, ReadOnly]` | Specify the type of lock. | | `natRuleCollections` | array | `[]` | | Collection of NAT rule collections used by Azure Firewall. | | `networkRuleCollections` | array | `[]` | | Collection of network rule collections used by Azure Firewall. | | `publicIPAddressObject` | object | `{object}` | | Specifies the properties of the public IP to create and be used by Azure Firewall. If it's not provided and publicIPAddressId is empty, a '-pip' suffix will be appended to the Firewall's name. | -| `roleAssignments` | array | `[]` | | Array of role assignment objects that contain the 'roleDefinitionIdOrName' and 'principalId' to define RBAC role assignments on this resource. In the roleDefinitionIdOrName attribute, you can provide either the display name of the role definition, or its fully qualified ID in the following format: '/providers/Microsoft.Authorization/roleDefinitions/c2f4ef07-c644-48eb-af81-4b1b4947fb11' | +| `roleAssignments` | array | `[]` | | Array of role assignment objects that contain the 'roleDefinitionIdOrName' and 'principalId' to define RBAC role assignments on this resource. In the roleDefinitionIdOrName attribute, you can provide either the display name of the role definition, or its fully qualified ID in the following format: '/providers/Microsoft.Authorization/roleDefinitions/c2f4ef07-c644-48eb-af81-4b1b4947fb11'. | | `tags` | object | `{object}` | | Tags of the Azure Firewall resource. | | `threatIntelMode` | string | `'Deny'` | `[Alert, Deny, Off]` | The operation mode for Threat Intel. | | `zones` | array | `[1, 2, 3]` | | Zone numbers e.g. 1,2,3. | @@ -164,7 +165,7 @@ Tag names and tag values can be provided as needed. A tag can be left without a | Output Name | Type | Description | | :-- | :-- | :-- | | `applicationRuleCollections` | array | List of Application Rule Collections. | -| `ipConfAzureFirewallSubnet` | object | The public ipconfiguration object for the AzureFirewallSubnet | +| `ipConfAzureFirewallSubnet` | object | The public ipconfiguration object for the AzureFirewallSubnet. | | `location` | string | The location the resource was deployed into. | | `name` | string | The name of the Azure firewall. | | `natRuleCollections` | array | Collection of NAT rule collections used by Azure Firewall. | @@ -177,3 +178,305 @@ Tag names and tag values can be provided as needed. A tag can be left without a The `applicationRuleCollections` parameter accepts a JSON Array of AzureFirewallApplicationRule objects. The `networkRuleCollections` parameter accepts a JSON Array of AzureFirewallNetworkRuleCollection objects. + +## Deployment examples + +

Example 1

+ +
+ +via JSON Parameter file + +```json +{ + "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#", + "contentVersion": "1.0.0.0", + "parameters": { + "name": { + "value": "<>-az-fw-min-001" + }, + "vNetId": { + "value": "/subscriptions/<>/resourceGroups/validation-rg/providers/Microsoft.Network/virtualNetworks/adp-<>-az-vnet-x-azfw" + } + } +} + +``` + +
+ +
+ +via Bicep module + +```bicep +module azureFirewalls './Microsoft.Network/azureFirewalls/deploy.bicep' = { + name: '${uniqueString(deployment().name)}-azureFirewalls' + params: { + name: '<>-az-fw-min-001' + vNetId: '/subscriptions/<>/resourceGroups/validation-rg/providers/Microsoft.Network/virtualNetworks/adp-<>-az-vnet-x-azfw' + } +``` + +
+

+ +

Example 2

+ +
+ +via JSON Parameter file + +```json +{ + "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#", + "contentVersion": "1.0.0.0", + "parameters": { + "name": { + "value": "<>-az-fw-x-001" + }, + "zones": { + "value": [ + "1", + "2", + "3" + ] + }, + "vNetId": { + "value": "/subscriptions/<>/resourceGroups/validation-rg/providers/Microsoft.Network/virtualNetworks/adp-<>-az-vnet-x-azfw" + }, + "azureFirewallSubnetPublicIpId": { + "value": "/subscriptions/<>/resourceGroups/validation-rg/providers/Microsoft.Network/publicIPAddresses/adp-<>-az-pip-x-fw" + }, + "applicationRuleCollections": { + "value": [ + { + "name": "allow-app-rules", + "properties": { + "priority": 100, + "action": { + "type": "allow" + }, + "rules": [ + { + "name": "allow-ase-tags", + "sourceAddresses": [ + "*" + ], + "protocols": [ + { + "protocolType": "HTTP", + "port": "80" + }, + { + "protocolType": "HTTPS", + "port": "443" + } + ], + "fqdnTags": [ + "AppServiceEnvironment", + "WindowsUpdate" + ] + }, + { + "name": "allow-ase-management", + "sourceAddresses": [ + "*" + ], + "protocols": [ + { + "protocolType": "HTTP", + "port": "80" + }, + { + "protocolType": "HTTPS", + "port": "443" + } + ], + "targetFqdns": [ + "management.azure.com" + ] + } + ] + } + } + ] + }, + "networkRuleCollections": { + "value": [ + { + "name": "allow-network-rules", + "properties": { + "priority": 100, + "action": { + "type": "allow" + }, + "rules": [ + { + "name": "allow-ntp", + "sourceAddresses": [ + "*" + ], + "destinationAddresses": [ + "*" + ], + "destinationPorts": [ + "123", + "12000" + ], + "protocols": [ + "Any" + ] + } + ] + } + } + ] + }, + "roleAssignments": { + "value": [ + { + "roleDefinitionIdOrName": "Reader", + "principalIds": [ + "<>" + ] + } + ] + }, + "diagnosticLogsRetentionInDays": { + "value": 7 + }, + "diagnosticStorageAccountId": { + "value": "/subscriptions/<>/resourceGroups/validation-rg/providers/Microsoft.Storage/storageAccounts/adp<>azsax001" + }, + "diagnosticWorkspaceId": { + "value": "/subscriptions/<>/resourcegroups/validation-rg/providers/microsoft.operationalinsights/workspaces/adp-<>-az-law-x-001" + }, + "diagnosticEventHubAuthorizationRuleId": { + "value": "/subscriptions/<>/resourceGroups/validation-rg/providers/Microsoft.EventHub/namespaces/adp-<>-az-evhns-x-001/AuthorizationRules/RootManageSharedAccessKey" + }, + "diagnosticEventHubName": { + "value": "adp-<>-az-evh-x-001" + } + } +} + +``` + +
+ +
+ +via Bicep module + +```bicep +module azureFirewalls './Microsoft.Network/azureFirewalls/deploy.bicep' = { + name: '${uniqueString(deployment().name)}-azureFirewalls' + params: { + name: '<>-az-fw-x-001' + zones: [ + '1' + '2' + '3' + ] + vNetId: '/subscriptions/<>/resourceGroups/validation-rg/providers/Microsoft.Network/virtualNetworks/adp-<>-az-vnet-x-azfw' + azureFirewallSubnetPublicIpId: '/subscriptions/<>/resourceGroups/validation-rg/providers/Microsoft.Network/publicIPAddresses/adp-<>-az-pip-x-fw' + applicationRuleCollections: [ + { + name: 'allow-app-rules' + properties: { + priority: 100 + action: { + type: 'allow' + } + rules: [ + { + name: 'allow-ase-tags' + sourceAddresses: [ + '*' + ] + protocols: [ + { + protocolType: 'HTTP' + port: '80' + } + { + protocolType: 'HTTPS' + port: '443' + } + ] + fqdnTags: [ + 'AppServiceEnvironment' + 'WindowsUpdate' + ] + } + { + name: 'allow-ase-management' + sourceAddresses: [ + '*' + ] + protocols: [ + { + protocolType: 'HTTP' + port: '80' + } + { + protocolType: 'HTTPS' + port: '443' + } + ] + targetFqdns: [ + 'management.azure.com' + ] + } + ] + } + } + ] + networkRuleCollections: [ + { + name: 'allow-network-rules' + properties: { + priority: 100 + action: { + type: 'allow' + } + rules: [ + { + name: 'allow-ntp' + sourceAddresses: [ + '*' + ] + destinationAddresses: [ + '*' + ] + destinationPorts: [ + '123' + '12000' + ] + protocols: [ + 'Any' + ] + } + ] + } + } + ] + roleAssignments: [ + { + roleDefinitionIdOrName: 'Reader' + principalIds: [ + '<>' + ] + } + ] + diagnosticLogsRetentionInDays: 7 + diagnosticStorageAccountId: '/subscriptions/<>/resourceGroups/validation-rg/providers/Microsoft.Storage/storageAccounts/adp<>azsax001' + diagnosticWorkspaceId: '/subscriptions/<>/resourcegroups/validation-rg/providers/microsoft.operationalinsights/workspaces/adp-<>-az-law-x-001' + diagnosticEventHubAuthorizationRuleId: '/subscriptions/<>/resourceGroups/validation-rg/providers/Microsoft.EventHub/namespaces/adp-<>-az-evhns-x-001/AuthorizationRules/RootManageSharedAccessKey' + diagnosticEventHubName: 'adp-<>-az-evh-x-001' + } +``` + +
+

diff --git a/docs/wiki/The library - Module design.md b/docs/wiki/The library - Module design.md index caf9b2a67a..f461480904 100644 --- a/docs/wiki/The library - Module design.md +++ b/docs/wiki/The library - Module design.md @@ -16,6 +16,7 @@ This section details the design principles followed by the CARML Bicep modules. - [Outputs](#outputs) - [ReadMe](#readme) - [Parameter files](#parameter-files) +- [Telemetry](#telemetry) --- @@ -535,3 +536,19 @@ Parameter files in CARML leverage the common `deploymentParameters.json` schema - Likewise, the `name` parameter we have in most modules should give some indication of the file it was deployed with. For example, a `min.parameters.json` parameter file for the virtual network module may have a `name` property with the value `sxx-az-vnet-min-001` where `min` relates to the prefix of the parameter file itself. - A module should have as many parameter files as it needs to evaluate all parts of the module's functionality. - Sensitive data should not be stored inside the parameter file but rather be injected by the use of tokens, as described in the [Token replacement](./The%20CI%20environment%20-%20Token%20replacement) section, or via a [key vault reference](https://docs.microsoft.com/en-us/azure/azure-resource-manager/templates/key-vault-parameter?tabs=azure-cli#reference-secrets-with-static-id). + +# Telemetry + +Each module in CARML contains a `defaultTelemetry` deployment `'pid--${uniqueString(deployment().name)}'`, resulting in deployments such as `'pid--nx2c3rnlt2wru'`. + +This resource enables the team responsible for CARML to query the number of deployments of a given template from Azure - and as such get insights into its adoption. + +When using CARML's CI environment you can enable/disable this deployment by switching the `enableDefaultTelemetry` setting in the `settings.json` file in the repository's root. This value is automatically injected into each individual deployment that is executed as part of the environment's pipeline. + +When consuming the modules outside of CARML's pipelines you can either +- Set the parameter to a default value of `'false'` +- Set the parameter to false when deploying a module + +> **Note:** _The deployment and its GUID can NOT be used to track [Azure Consumed Revenue (ACR)](https://docs.microsoft.com/en-us/azure/marketplace/azure-partner-customer-usage-attribution)._ +> +> _If you want to track it, we recommend to implement it on the consuming template's level (i.e. the workload/solution) and apply the required naming format `'pid-'` (without the suffix)._ diff --git a/settings.json b/settings.json index a25371a5d3..9198a0f7d0 100644 --- a/settings.json +++ b/settings.json @@ -12,5 +12,8 @@ } ] }, + // Enable or disable CARMLs CI telemetry tracking. + // Note: This tracks the number of deployments only + // For more information see: https://github.com/Azure/ResourceModules/wiki/The%20library%20-%20Module%20design#telemetry "enableDefaultTelemetry": true }