Add telemetry support (#8)

* add telemetry support

* fix broken link

* spelling

* Auto-update Bicep Module Docs for PR 8 [jtracey93/6d7a2534]

* add link to wiki

* Auto-update Bicep Module Docs for PR 8 [jtracey93/6d7a2534]

* Empty-Commit

Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>

README.md

@@ -33,7 +33,7 @@ TBC
 
 Parameters for the [`main.bicep`](main.bicep) module can be found [here: `main.bicep.parameters.md`](main.bicep.parameters.md).
 
-> These docs are automatically generated using [PSDocs.Azure](https://azure.github.io/PSDocs.Azure) from the Bicep module file itself and [this GitHub Action](.github/workflows/psdocs-azure.yml)
+> These docs are automatically generated using [PSDocs.Azure](https://azure.github.io/PSDocs.Azure) from the Bicep module file itself and [this GitHub Action](.github/workflows/update-bicep-module-docs.yml) as part of PRs that amend this bicep module.
 
 ## Contributing
 

docs/wiki/Telemetry.md

@@ -0,0 +1,41 @@
+<!-- markdownlint-disable -->
+## Telemetry Tracking Using Customer Usage Attribution (PID)
+<!-- markdownlint-restore -->
+
+Microsoft can identify the deployments of the Azure Resource Manager and Bicep templates with the deployed Azure resources. Microsoft can correlate these resources used to support the deployments. Microsoft collects this information to provide the best experiences with their products and to operate their business. The telemetry is collected through [customer usage attribution](https://docs.microsoft.com/azure/marketplace/azure-partner-customer-usage-attribution). The data is collected and governed by Microsoft's privacy policies, located at the [trust center](https://www.microsoft.com/trustcenter).
+
+To disable this tracking, we have included a parameter called `disableTelemetry` to every bicep module in this repo with a simple boolean flag. The default value `false` which **does not** disable the telemetry. If you would like to disable this tracking, then simply set this value to `true` and this module will not be included in deployments and **therefore disables** the telemetry tracking.
+
+If you are happy with leaving telemetry tracking enabled, no changes are required. Please do not edit the module name or value of the variable `cuaPid` in any module.
+
+For example, in the managementGroups.bicep file, you will see the following:
+
+```bicep
+@description('Set Parameter to True to Opt-out of deployment telemetry')
+param disableTelemetry bool = true
+```
+
+The default value is `false`, but by changing the parameter value `true` and saving this file, when you deploy this module either via PowerShell, Azure CLI, or as part of a pipeline the module deployment below will be ignored and therefore telemetry will not be tracked.
+
+```bicep
+resource moduleTelemetry 'Microsoft.Resources/deployments@2021-04-01' = if (!disableTelemetry) {
+  name: 'pid-${cuaPid}-${uniqueString(deployment().name, virtualNetworkLocation)}'
+  location: virtualNetworkLocation
+  properties: {
+    mode: 'Incremental'
+    template: {
+      '$schema': 'https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#'
+      contentVersion: '1.0.0.0'
+      resources: []
+    }
+  }
+}
+```
+
+## Module CUA PID Value Mapping
+
+The following are the unique CUA ID's (also known as PIDs) used in the modules:
+
+| Module Name  | CUA PID                                |
+| ------------ | -------------------------------------- |
+| `main.bicep` | `10d75183-0090-47b2-9c1b-48e3a4a36786` |

docs/wiki/_Sidebar.md

@@ -3,3 +3,4 @@
 - [About this module](https://github.com/azure/bicep-lz-vending/wiki/about)
 - [Permissions required](https://github.com/azure/bicep-lz-vending/wiki/permissions)
 - [Examples](https://github.com/azure/bicep-lz-vending/wiki/examples)
+- [Telemetry](https://github.com/azure/bicep-lz-vending/wiki/telemetry)

main.bicep

@@ -327,10 +327,21 @@ Each object must contain the following `keys`:
 ''')
 param roleAssignments array = []
 
+@metadata({
+  example: false
+})
+@sys.description('''Disable telemetry collection by this module.
+
+For more information on the telemtery collected by this module, that is controlled by this parameter, see this page in the wiki: [Telemetry Tracking Using Customer Usage Attribution (PID)](https://github.com/Azure/bicep-lz-vending/wiki/Telemetry)
+''')
+param disableTelemetry bool = false
+
 // VARIABLES
 
 var existingSubscriptionIDEmptyCheck = empty(existingSubscriptionId) ? 'No Subscription ID Provided' : existingSubscriptionId
 
+var cuaPid = '10d75183-0090-47b2-9c1b-48e3a4a36786'
+
 // Deployment name variables
 // LIMITS: Tenant = 64, Management Group = 64, Subscription = 64, Resource Group = 64
 var deploymentNames = {
@@ -339,6 +350,18 @@ var deploymentNames = {
 }
 
 // RESOURCES & MODULES
+resource moduleTelemetry 'Microsoft.Resources/deployments@2021-04-01' = if (!disableTelemetry) {
+  name: 'pid-${cuaPid}-${uniqueString(deployment().name, virtualNetworkLocation)}'
+  location: virtualNetworkLocation
+  properties: {
+    mode: 'Incremental'
+    template: {
+      '$schema': 'https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#'
+      contentVersion: '1.0.0.0'
+      resources: []
+    }
+  }
+}
 
 module createSubscription 'src/self/Microsoft.Subscription/aliases/deploy.bicep' = if (subscriptionAliasEnabled && empty(existingSubscriptionId)) {
   scope: tenant()

main.bicep.parameters.md

@@ -33,6 +33,7 @@ virtualNetworkVwanPropagatedRouteTablesResourceIds | No       | An array of of o
 virtualNetworkVwanPropagatedLabels | No       | An array of virtual hub route table labels to propagate routes to. If left blank/empty the default label will be propagated to only.  - Type: `[]` Array - Default value: `[]` *(empty array)* 
 roleAssignmentEnabled | No       | Whether to create role assignments or not. If true, supply the array of role assignment objects in the parameter called `roleAssignments`.  - Type: Boolean 
 roleAssignments | No       | Supply an array of objects containing the details of the role assignments to create.  Each object must contain the following `keys`: - `principalId` = The Object ID of the User, Group, SPN, Managed Identity to assign the RBAC role too. - `definition` = The Name of built-In RBAC Roles or a Resource ID of a Built-in or custom RBAC Role Definition. - `relativeScope` = 2 options can be provided for input value:     1. `''` *(empty string)* = Make RBAC Role Assignment to Subscription scope     2. `'/resourceGroups/<RESOURCE GROUP NAME>'` = Make RBAC Role Assignment to specified Resource Group  > See below [example in parameter file](#parameter-file) of various combinations  - Type: `[]` Array - Default value: `[]` *(empty array)* 
+disableTelemetry | No       | Disable telemetry collection by this module.  For more information on the telemtery collected by this module, that is controlled by this parameter, see this page in the wiki: [Telemetry Tracking Using Customer Usage Attribution (PID)](https://github.com/Azure/bicep-lz-vending/wiki/Telemetry) 
 
 ### subscriptionAliasEnabled
 
@@ -322,6 +323,17 @@ Each object must contain the following `keys`:
 - Default value: `[]` *(empty array)*
 
 
+### disableTelemetry
+
+![Parameter Setting](https://img.shields.io/badge/parameter-optional-green?style=flat-square)
+
+Disable telemetry collection by this module.
+
+For more information on the telemtery collected by this module, that is controlled by this parameter, see this page in the wiki: [Telemetry Tracking Using Customer Usage Attribution (PID)](https://github.com/Azure/bicep-lz-vending/wiki/Telemetry)
+
+
+- Default value: `False`
+
 ## Outputs
 
 Name | Type | Description
@@ -445,6 +457,9 @@ subscriptionResourceId | string | The Subscription Resource ID that has been cre
                     "relativeScope": "/resourceGroups/rsg-networking-001"
                 }
             ]
+        },
+        "disableTelemetry": {
+            "value": false
         }
     }
 }