Automated Secure Infrastructure for Self Hosted Integration Runtime in Azure Data Factory Terraform
Published Mar 27 2023 08:26 AM 7,548 Views


This purpose of this project is to document how to securly automate a self hosted integration runtime (SHIR) for Azure Data Factory using terraform.


According to Microsoft Documentation , a self-hosted integration runtime can run copy activities between a cloud data store and a data store in a private network. It also can dispatch transform activities against compute resources in an on-premises network or an Azure virtual network. The installation of a self-hosted integration runtime needs an on-premises machine or a virtual machine inside a private network.


Automating this process requires an installtion script that will be used on a preferred virtual machine. Storing this script in a secure location and allowing your deployment to access this script becomes difficult in a completely private and secure Azure Data Factory environment. The technique used here is to upload the script to a secure storage account and allow the virtual machine private access to download the script from that same storage account


  • Azure subscription and contributor rights
  • You should already have a remote terraform backend set up. Follow this process  if you need help.
  • Azure DevOps Pipelines with a corresponding service connection set up to your Azure Subscription. Follow this  for help.
  • Self hosted Azure DevOps agent that is connected to your secure environment. NOTE: this is only required if you are using a fully private VNET and locked down enviornment/storage account.
    • These agents are used to run the terraform deployment to your secure enviornment. Because they can access your private network, they can safely run the deployment to your resources. Running an initial deployment on an Azure Public agent could work for the inital setup, but will not work for any subsequent runs as the Public agent will not have access to your secure enviornment. 


Workflow Diagram


Here you can see that an Azure DevOps Pipeline is run on a Self Hosted DevOps Agent that is connected to the secure VNET of the target enviornment. This pipeline runs a Terraform deployment to set up a secure VNET, Private Storage Account, Virtual Machine (for the SHIR), and an Azure Data Factory.

Walkthrough and Set Up Video


Infrastructure Instructions

Sample powershell installation script

This script will install the SHIR gateway from a virtual machine to a specific Azure Data Factory. The only prarmeter needed here is a authentication key for the gateway.



# init log setting
$logLoc = "$env:SystemDrive\WindowsAzure\Logs\Plugins\Microsoft.Compute.CustomScriptExtension\"
if (! (Test-Path($logLoc))) {
	New-Item -path $logLoc -type directory -Force
$logPath = "$logLoc\tracelog.log"
"Start to excute gatewayInstall.ps1. `n" | Out-File $logPath

function Now-Value() {
	return (Get-Date -Format "yyyy-MM-dd HH:mm:ss")

function Throw-Error([string] $msg) {
	try {
		throw $msg
	catch {
		$stack = $_.ScriptStackTrace
		Trace-Log "DMDTTP is failed: $msg`nStack:`n$stack"

	throw $msg

function Trace-Log([string] $msg) {
	$now = Now-Value
	try {
		"${now} $msg`n" | Out-File $logPath -Append
	catch {
		#ignore any exception during trace


function Run-Process([string] $process, [string] $arguments) {
	Write-Verbose "Run-Process: $process $arguments"
	$errorFile = "$env:tmp\tmp$pid.err"
	$outFile = "$env:tmp\tmp$pid.out"
	"" | Out-File $outFile
	"" | Out-File $errorFile	

	$errVariable = ""

	if ([string]::IsNullOrEmpty($arguments)) {
		$proc = Start-Process -FilePath $process -Wait -Passthru -NoNewWindow `
			-RedirectStandardError $errorFile -RedirectStandardOutput $outFile -ErrorVariable errVariable
	else {
		$proc = Start-Process -FilePath $process -ArgumentList $arguments -Wait -Passthru -NoNewWindow `
			-RedirectStandardError $errorFile -RedirectStandardOutput $outFile -ErrorVariable errVariable
	$errContent = [string] (Get-Content -Path $errorFile -Delimiter "!!!DoesNotExist!!!")
	$outContent = [string] (Get-Content -Path $outFile -Delimiter "!!!DoesNotExist!!!")

	Remove-Item $errorFile
	Remove-Item $outFile

	if ($proc.ExitCode -ne 0 -or $errVariable -ne "") {		
		Throw-Error "Failed to run process: exitCode=$($proc.ExitCode), errVariable=$errVariable, errContent=$errContent, outContent=$outContent."

	Trace-Log "Run-Process: ExitCode=$($proc.ExitCode), output=$outContent"

	if ([string]::IsNullOrEmpty($outContent)) {
		return $outContent

	return $outContent.Trim()

function Download-Gateway([string] $url, [string] $gwPath) {
	try {
		$ErrorActionPreference = "Stop";
		$client = New-Object System.Net.WebClient
		$client.DownloadFile($url, $gwPath)
		Trace-Log "Download gateway successfully. Gateway loc: $gwPath"
	catch {
		Trace-Log "Fail to download gateway msi"
		Trace-Log $_.Exception.ToString()

function Install-Gateway([string] $gwPath) {
	if ([string]::IsNullOrEmpty($gwPath)) {
		Throw-Error "Gateway path is not specified"

	if (!(Test-Path -Path $gwPath)) {
		Throw-Error "Invalid gateway path: $gwPath"
	Trace-Log "Start Gateway installation"
	Run-Process "msiexec.exe" "/i gateway.msi INSTALLTYPE=AzureTemplate /quiet /norestart"		
	Start-Sleep -Seconds 30	

	Trace-Log "Installation of gateway is successful"

function Get-RegistryProperty([string] $keyPath, [string] $property) {
	Trace-Log "Get-RegistryProperty: Get $property from $keyPath"
	if (! (Test-Path $keyPath)) {
		Trace-Log "Get-RegistryProperty: $keyPath does not exist"

	$keyReg = Get-Item $keyPath
	if (! ($keyReg.Property -contains $property)) {
		Trace-Log "Get-RegistryProperty: $property does not exist"
		return ""

	return $keyReg.GetValue($property)

function Get-InstalledFilePath() {
	$filePath = Get-RegistryProperty "hklm:\Software\Microsoft\DataTransfer\DataManagementGateway\ConfigurationManager" "DiacmdPath"
	if ([string]::IsNullOrEmpty($filePath)) {
		Throw-Error "Get-InstalledFilePath: Cannot find installed File Path"
	Trace-Log "Gateway installation file: $filePath"

	return $filePath

function Register-Gateway([string] $instanceKey) {
	Trace-Log "Register Agent"
	$filePath = Get-InstalledFilePath
	Run-Process $filePath "-era 8060"
	Run-Process $filePath "-k $instanceKey"
	Trace-Log "Agent registration is successful!"

if ((Get-Process "diahost" -ea SilentlyContinue) -eq $Null) {
	Trace-Log "Integration Runtime is not running. Initiating Download - Install - Register sequence.";
	Trace-Log "Log file: $logLoc"
	$uri = ""
	Trace-Log "Gateway download fw link: $uri"
	$gwPath = "$PWD\gateway.msi"
	Trace-Log "Gateway download location: $gwPath"
	Download-Gateway $uri $gwPath
	Install-Gateway $gwPath
	Register-Gateway $gatewayKey

else {
	Trace-Log "Integration Runtime is already running. Skipping installation & configuration.";


Walthrough of Terraform Code

Set up Azure Data Factory and Self Hosted Integration Runtime
resource "azurerm_data_factory" "adf" {
  name                = "adf-poc-${random_string.random.result}"
  location            = "East US"
  resource_group_name =

resource "azurerm_data_factory_integration_runtime_self_hosted" "shir" {
  name                = "adf-poc-shir"
  resource_group_name =
  data_factory_id     =

The second resource here is needed to create the self hosted integration runtime within Azure data factory and is also used because this resource exposes the authentication key  to create a gateway and connect a virtual machine to this runtime. This is the gateway key that we will pass into our powershell script.


Set up secure storage account to store script
  • The following code shows setting up the storage account. Then setting up a private container within the storage account. And lastly uploading the installtion script as a blob object to the container.
#Storage account
resource "azurerm_storage_account" "storageaccount" {
  name                     = "shirst${random_string.random.result}"
  resource_group_name      =
  location                 = var.location
  account_tier             = "Standard"
  account_replication_type = "LRS"
  account_kind             = "StorageV2"
  min_tls_version          = "TLS1_2"

  blob_properties {
    cors_rule {
      allowed_headers    = ["*"]
      allowed_methods    = ["DELETE", "GET", "HEAD", "MERGE", "POST", "OPTIONS", "PUT", "PATCH"]
      allowed_origins    = ["*"]
      exposed_headers    = ["*"]
      max_age_in_seconds = 200

#Storage container and blob
resource "azurerm_storage_container" "newcontainer" {
  name                  = "shir-script"
  storage_account_name  =
  container_access_type = "private"
resource "azurerm_storage_blob" "newblob" {
  name                   = "adf-shir.ps1"
  storage_account_name   =
  storage_container_name =
  type                   = "Block"
  access_tier            = "Cool"
  source                 = "../gatewayinstall.ps1"
Securely Lock down storage account network to make it private
  • This only allows resources within the same private network of your environment to access this storage account
#Storage network rules
resource "azurerm_storage_account_network_rules" "storageaccountnetworkrules" {
  resource_group_name  =
  storage_account_name =

  default_action             = "Deny"
  ip_rules                   = []
  virtual_network_subnet_ids = []
  bypass                     = ["Metrics", "Logging", "AzureServices"]
  depends_on = [


Allow network access to storage account via private endpoints
  • This allows a secure private ip address for communication to and from this storage account
#--------Storage Account Private Endpoints and DNS A Records--------#
resource "azurerm_private_endpoint" "pe_000" {
  name                = "${}-dfs"
  location            = var.location
  resource_group_name =
  subnet_id           =

  private_service_connection {
    name                           = "${}-connection"
    private_connection_resource_id =
    is_manual_connection           = false
    subresource_names              = ["dfs"]

  private_dns_zone_group {
    name                 =
    private_dns_zone_ids = []

resource "azurerm_private_dns_a_record" "privatednsarecord-000" {
  name                =
  zone_name           =
  resource_group_name =
  ttl                 = "300"
  records             = [azurerm_private_endpoint.pe_000.private_service_connection.0.private_ip_address]
  depends_on          = [azurerm_private_endpoint.pe_000]

resource "azurerm_private_endpoint" "pe_001" {
  name                = "${}-blob"
  location            = var.location
  resource_group_name =
  subnet_id           =

  private_service_connection {
    name                           = "${}-connection"
    private_connection_resource_id =
    is_manual_connection           = false
    subresource_names              = ["blob"]

  private_dns_zone_group {
    name                 =
    private_dns_zone_ids = []

resource "azurerm_private_dns_a_record" "privatednsarecord-001" {
  name                =
  zone_name           =
  resource_group_name =
  ttl                 = "300"
  records             = [azurerm_private_endpoint.pe_001.private_service_connection.0.private_ip_address]
  depends_on          = [azurerm_private_endpoint.pe_001]


Create virtual machine for self hosted integration runtime
  • This windows machine uses Microsoft's default 2019 image.
    NOTE: The admin password is exposed below for testing and deployment purposes. For a secure production ready deployment, this password should only be referenced via an Azure Key Vault injection.
#Windows VM
resource "azurerm_windows_virtual_machine" "main" {
  name                  = "shir-vm-${random_string.random.result}"
  location              = var.location
  resource_group_name   =
  network_interface_ids = []
  size               = "Standard_B1s"
  admin_username = "testadmin"
  admin_password = "Password1234!"
  source_image_reference {
    publisher = "MicrosoftWindowsServer"
    offer     = "WindowsServer"
    sku       = "2019-Datacenter"
    version   = "latest"
  os_disk {
    name              = "myosdisk1"
    caching           = "ReadWrite"
    storage_account_type = "Standard_LRS"

  identity {
    type = "SystemAssigned"
Create Virtual Machine extenstion to install Self Hosted Integration runtime Gateway Script
  • Here the VM extension will reference the script stored in our secure storage account to install on the machine.
  • This connection is secure because the VM is communicating to the storage account via our private endpoints in the same secure enviornment as our other resources.
#VM Custom Script Extension
resource "azurerm_virtual_machine_extension" "vmextension-0000" {
  name                       = "ADF-SHIR"
  virtual_machine_id         =
  publisher                  = "Microsoft.Compute"
  type                       = "CustomScriptExtension"
  type_handler_version       = "1.10"
  auto_upgrade_minor_version = true

  protected_settings = <<PROTECTED_SETTINGS
          "fileUris": ["${format("",,,}"],
          "commandToExecute": "${join(" ", ["powershell.exe -ExecutionPolicy Unrestricted -File",,"-gatewayKey ${azurerm_data_factory_integration_runtime_self_hosted.shir.auth_key_1}"])}",
          "storageAccountName": "${}",
          "storageAccountKey": "${azurerm_storage_account.storageaccount.primary_access_key}"


Version history
Last update:
‎Sep 23 2022 04:09 PM
Updated by: