[Modules] Added telemetry to AAD module & description to docs

.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
 

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

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

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-<GUID>-${uniqueString(deployment().name)}'`, resulting in deployments such as `'pid-<GUID>-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-<GUID>'` (without the suffix)._

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
 }