Deployment Guide

Please follow the guide below to deploy the solution into your own tenant and subscription.

0. Prerequisites

Before getting started with the deployment, please review the prerequisites.

Supported regions

The solution supports the following Azure regions:

(Asia Pacific) Australia East
(Canada) Canada Central
(US) East US
(US) East US 2
(Europe) North Europe
(Europe) West Europe
(more to follow over the next weeks as Microsoft Purview expands the supported regions for managed Vnets)

Required for this solution

The following must be available to deploy the solution inside your Azure environment:

An Azure subscription. If you don't have an Azure subscription, create your Azure free account today.
User Access Administrator or Owner access to the subscription to be able to create a service principal and role assignments for it.
For the deployment, please choose one of the Supported Regions.
It is also expected that a few resources have been deployed upfront. This includes:
- A Vnet with two subnets, whereas one needs to have privateEndpointNetworkPolicies disabled and the other one needs to be delegated to Microsoft.Web/serverFarms.
- A Microsoft Purview account in one of the supported regions.
- Private DNS Zones for blob storage, file storage, and key vault.

(Optional) Deployment of required services

If the services mentioend previously have not been deployed upfront, you can also find a bicep template and parameter file here, which you can use to get your environment ready for the deployment of the Purview Automation solution. To deploy the setup, please execute the following steps:

Open /docs/reference/prerequisites/params.json and update at least the prefix value, which will be used as a prefix for all the resources that are getting deployed.
Now, open your terminal and navigate to the location of these templates.

Run either of the following commands to deploy the setup inside your subscription:

Azure CLI:

az deployment sub create \
    --location "northeurope" \
    --template-file "main.bicep" \
    --template-file "params.json"

Azure PowerShell:

New-AzSubscriptionDeployment `
    -Location "northeurope" `
    -TemplateFile "main.bicep" `
    -TemplateParameterFile "params.json"

Take note of the outputs of this deployment. The deployment provides output for all parameters that are required for subsequent steps.

Now, we can start with the deployment of the solution. There are tow options for the deployment:

GitHub Actions: For this deployment, please follow the steps below.
Deploy to Azure: For this option, please click on teh blue deployment button below:

1. Fork the repository

First, you must fork this repository. To do so, please follow the steps below:

Log in to GitHub using your GitHub account.
On GitHub, navigate to the main page of this repository.
In the top-right corner of the page, click Fork.
Select a repository name and description and click Create Fork.

2. Create Service Principal

A service principal with Contributor and User Access Administrator rights on the subscription level needs to be generated for authentication and authorization from GitHub to your Azure subscription. This is required to deploy resources to your environment. Follow the steps below to create a Service Principle:

Go to the Azure Portal to find the ID of your subscription.
Start the Cloud Shell or open your Terminal and login to Azure using the following Azure CLI command: az login.
Set the Azure context using az account set --subscription "<your-subscription-id>".

Execute the following command using Azure CLI to generate the required Service Principal credentials:

Azure CLI:

# Replace <your-service-principal-name> and <your-subscription-id> with your
# Azure subscription id and any name for your service principal.
az ad sp create-for-rbac \
    --name "<your-service-principal-name>" \
    --role "Contributor" \
    --scopes "/subscriptions/<your-subscription-id>" \
    --sdk-auth

This will generate the following JSON output:

{
    "clientId": "<GUID>",
    "clientSecret": "<GUID>",
    "subscriptionId": "<GUID>",
    "tenantId": "<GUID>",
    (...)
}

Note: Take note of the output. It will be required for the next steps.

Run the following command using Azure CLI or Azure PowerShell to assign the User Access Administrator role:

Azure CLI:

# Get Service Principal Object ID
az ad sp list \
    --display-name "<your-service-principal-name>" \
    --query "[].{objectId:objectId}" \
    --output tsv

# Assign the User Access Administrator role.
az role assignment create \
    --assignee "<your-service-principle-object-id>" \
    --role "User Access Administrator" \
    --scopes "/subscription/<your-subscription-id>"

Azure PowerShell:

# Get Service Principal Object ID
$spObjectId = (Get-AzADServicePrincipal -DisplayName "<your-service-principal-name>").id

# Assign the User Access Administrator role.
New-AzRoleAssignment `
    -ObjectId $spObjectId `
    -RoleDefinitionName "User Access Administrator" `
    -Scope "/subscription/<your-subscription-id>"

3. Add secret to GitHub repository

In the previous step, you have created Service Principal credentials which will now be saved as repository secret to deploy the solution to your subsciption:

On GitHub, navigate to the main page of the repository.
Under your repository name, click on the Settings tab.
In the left sidebar, click Secrets.
Click New repository secret.
Type the name AZURE_CREDENTIALS for your secret in the Name input box.

Enter the JSON output from above as value for your secret.

{
    "clientId": "<GUID>",
    "clientSecret": "<GUID>",
    "subscriptionId": "<GUID>",
    "tenantId": "<GUID>",
    (...)
}

Click Add secret.

4. Update parameters

In order to deploy the Infrastructure as Code (IaC) templates to the desired Azure subscription, you will need to modify some parameters in the forked repository. Therefore, this step should not be skipped. There are two files that require updates:

.github/workflows/deploy.yml and
infra/params.json.

Update these files in a separate branch and then merge via Pull Request to trigger the initial deployment. Follow the steps below to successfully update the parameters:

Open .github/workflows/deploy.yml.

Update AZURE_SUBSCRIPTION_ID and AZURE_LOCATION in the environment variables section:

env:
    DOTNET_VERSION: "6.0.x"
    WORKING_DIRECTORY: "code/"
    AZURE_SUBSCRIPTION_ID: "4060c03e-0d2e-44b7-82a3-da9376fe50b2"  # Update to '<your-subscription_id>'
    AZURE_LOCATION: "northeurope"                                  # Update to '<your-azure-region>'

Parameter	Description	Sample value
AZURE_SUBSCRIPTION_ID	Specifies the subscription ID where all the resources will be deployed	`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
AZURE_LOCATION	Specifies the region where you want the resources to be deployed. Please check Supported Regions	`northeurope`

Commit the changes.
Open infra/params.json.

Update the variable values in this file. More details for each parameter can be found below:

Parameter	Description	Sample value
`location`	Specifies the location for all resources.	`northeurope`
`environment`	Specifies the environment of the deployment.	`dev`, `tst` or `prd`
`prefix`	Specifies the prefix for all resources created in this deployment.	`prefi`
`tags`	Specifies the tags that you want to apply to all resources.	{`key`: `value`}
`purviewId`	Specifies the Resource ID of the central Purview instance.	`/subscriptions/<your-subscription-id>/resourceGroups/<your-rg-name>/providers/Microsoft.Purview/accounts/<your-purview-name>`
`purviewRootCollectionName`	Specifies the name of the root collection of the Purview account. By default, the name is equal to your Purview account.	`dmz-dev-purview001`
`purviewManagedStorageId`	Specifies the Resource ID of the managed storage of the central purview instance.	`/subscriptions/<your-subscription-id>/resourceGroups/<your-rg-name>/providers/Microsoft.Storage/storageAccounts/<your-storage-account-name>`
`purviewManagedEventHubId`	Specifies the Resource ID of the managed event hub of the central purview instance.	`/subscriptions/<your-subscription-id>/resourceGroups/<your-rg-name>/providers/Microsoft.EventHub/namespaces/<your-eventhub-namespace-name>`
`eventGridTopicSourceSubscriptions`	Specifies the subscriptions that should be monitored for data service deployments. The parameter accepts a list of objects. Each object specifies a subscription ID and a location in which the event grid topic will be deployed.	`[{"subscriptionId": "<your-subscription-id>", "location": "<your-azure-location>"}]`
`createEventSubscription`	Specifies whether the Azure function should be registered as consumer to the event grid topic. Leave teh default value. The GitHub Action pipeline will overwrite this parameter in the various deployment stages to make sure that the deployment runs successfully.	`false`
`subnetId`	Specifies the Resource ID of the subnet to which all private endpoints will connect.	`/subscriptions/<your-subscription-id>/resourceGroups/<your-rg-name>/providers/Microsoft.Network/virtualNetworks/<your-vnet-name>/subnets/<your-subnet-name>`
`functionSubnetId`	Specifies the Resource ID of the subnet to which the function will be injected.	`/subscriptions/<your-subscription-id>/resourceGroups/<your-rg-name>/providers/Microsoft.Network/virtualNetworks/<your-vnet-name>/subnets/<your-subnet-name>`
`privateDnsZoneIdBlob`	Specifies the Resource ID of the private DNS zone for Blob Storage.	`/subscriptions/<your-subscription-id>/resourceGroups/<your-rg-name>/providers/Microsoft.Network/privateDnsZones/privatelink.blob.core.windows.net`
`privateDnsZoneIdFile`	Specifies the Resource ID of the private DNS zone for File Storage.	`/subscriptions/<your-subscription-id>/resourceGroups/<your-rg-name>/providers/Microsoft.Network/privateDnsZones/privatelink.file.core.windows.net`
`privateDnsZoneIdKeyVault`	Specifies the Resource ID of the private DNS zone for KeyVault.	`/subscriptions/<your-subscription-id>/resourceGroups/<your-rg-name>/providers/Microsoft.Network/privateDnsZones/privatelink.vaultcore.azure.net`
`purviewRootCollectionMetadataPolicyId`	Specifies the root collection metadata policy ID of the Purview account. To get this ID, please execute the CLI commands or PowerShell commands specified below.	`e647bedc-2322-4380-bfc3-cacf504e3b2f`

Purview Root Collection Metadata Policy ID

Azure PowerShell

# Specify the purview account name and subscription ID
$subscriptionId = "<your-subscription-id>"
$purviewAccountName = "<your-purview-account-name>"
$purviewRootCollectioName = $purviewAccountName

Set-AzContext -Subscription $subscriptionId
$azureAccessToken = (Get-AzAccessToken -ResourceUrl "https://purview.azure.net").Token
$purviewRootCollectionMetadataPolicyId = (Invoke-RestMethod -Method Get -Uri "https://${purviewAccountName}.purview.azure.com/policystore/metadataPolicies?collectionName=${purviewRootCollectioName}&api-version=2021-07-01-preview" -Headers @{ "Authorization"="Bearer ${azureAccessToken}" }).values[0].id
Write-Host "Your Purview Root Collection Metadata Policy ID is the following (without single quotes): '${purviewRootCollectionMetadataPolicyId}'"

Azure CLI

# Specify the purview account name and subscription ID
SUBSCRIPTION_ID="<your-subscription-id>"
PURVIEW_ACCOUNT_NAME="<your-purview-account-name>"
PURVIEW_ROOT_COLLECTION_NAME=$PURVIEW_ACCOUNT_NAME

# 0. Set Azure Context
az account set -s $SUBSCRIPTION_ID

# 1. Get AAD Access Token
ACCESS_TOKEN=$(az account get-access-token --scope "https://purview.azure.net/.default" --query "accessToken" -o tsv)
echo "Your Access Token is the following (without single quotes): '$ACCESS_TOKEN'"

# 2 Make REST API call and replace <your-purview-account-name>, <your-purview-root-collection-name> and <your-access-token>
PURVIEW_ROOT_COLLECTION_METADATA_POLICY_ID=$(az rest --method get --url "https://$PURVIEW_ACCOUNT_NAME.purview.azure.com/policyStore/metadataPolicies?collectionName=$PURVIEW_ROOT_COLLECTION_NAME&api-version=2021-07-01-preview" --skip-authorization-header --headers Authorization="Bearer $ACCESS_TOKEN" --query "values[0].id")
echo "Your Purview Root Collection Metadata Policy ID is the following (without single quotes): '$PURVIEW_ROOT_COLLECTION_METADATA_POLICY_ID'"

Commit the changes.
Merge the changes into the main branch of your repository.
Follow the workflow deployment.

5. Post-deployment steps

After deploying the solution successfully through GitHub Actions, you have to grant the the managed identity of the Azure function Data Source Admin rights to the root collection of Purview:

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Deployment.md

Deployment.md

Deployment Guide

0. Prerequisites

Supported regions

Required for this solution

(Optional) Deployment of required services

1. Fork the repository

2. Create Service Principal

3. Add secret to GitHub repository

4. Update parameters

Purview Root Collection Metadata Policy ID

5. Post-deployment steps

Files

Deployment.md

Latest commit

History

Deployment.md

File metadata and controls

Deployment Guide

0. Prerequisites

Supported regions

Required for this solution

(Optional) Deployment of required services

1. Fork the repository

2. Create Service Principal

3. Add secret to GitHub repository

4. Update parameters

Purview Root Collection Metadata Policy ID

5. Post-deployment steps