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