New-PimHubPrepareScript
Write the hub owner's preparation script (private install)
Purpose
Writes the script the hub network owner runs before (or during) a private PIM Manager installation: the hub side of the peering with exactly the name PIM setup looks for, optionally the rights for the deploy identity, and a check of both sides. It only writes a file; nothing in Azure is touched.
When to run it
Before a private (internal) installation when the hub VNet belongs to another team or another subscription, so the PIM installer cannot create the hub side of the peering. Run it, hand the written prepare-hub-<name>.ps1 to the hub owner, then continue the installation. The hub owner runs it with PowerShell 7 (or Windows PowerShell 5.1) on any machine, with a browser sign-in as the hub owner -- no Azure CLI, no PowerShell modules, nothing to install: first without -Apply (it prints its plan and changes nothing), then with -Apply. Setup writes the same file by itself when it cannot create the hub side.
Who may run it
No role needed.
What it changes
| Where | Action | What | Permission / role | Scope | Why | Undo |
|---|---|---|---|---|---|---|
| Local file | create | prepare-hub-<name>.ps1 in -OutDirectory (default: the current folder) | this computer | The script the hub owner runs. It is one self-contained file: an embedded browser sign-in to the hub's tenant (a sign-in to another tenant is refused), then Azure Resource Manager REST calls -- no Azure CLI, no modules. Without -Apply it only prints its plan. With -Apply it creates the hub-side peering on the hub VNet (virtualNetworkPeerings; waits for provisioningState Succeeded); with -DeployPrincipalObjectId it also makes an Azure role assignment for that identity: Network Contributor on the hub VNet, and with -DnsResourceGroup Private DNS Zone Contributor on that resource group (one fixed assignment name per scope + identity + role, so a second run adds nothing); with -PrivateDnsZoneName it links each existing zone to the hub VNet (virtualNetworkLinks 'link-<hub vnet>'). It never deletes anything and is safe to run twice. This script itself changes nothing in Azure. | Delete the file. (What the hub owner's run created is removed by them: the peering on the hub VNet, the role assignments and the DNS zone links it lists.) |
What it only reads
- nothing in Azure or the directory -- the peering names and resource ids are derived from the parameters
Parameters
| Parameter | Required | Default | What it does |
|---|---|---|---|
| -SpokeSubscriptionId | yes | The subscription of the PIM network (the spoke). | |
| -SpokeResourceGroup | yes | The resource group of the PIM network. | |
| -SpokeVnetName | yes | The PIM VNet name. The peering names are derived from it exactly as PIM setup derives them. | |
| -HubResourceGroup | yes | The hub VNet's resource group. | |
| -HubVnetName | yes | The hub VNet name. | |
| -HubSubscriptionId | no | The hub's subscription. Optional: empty = the hub is in the same subscription as the PIM network. | |
| -DeployPrincipalObjectId | no | The object id (GUID) of the PIM deploy identity. When given, the written script grants it Network Contributor on the hub VNet so setup can make its own side. Empty = the hub owner creates the hub side only. | |
| -DeployPrincipalType | no | ServicePrincipal | ServicePrincipal, User or Group: the type of -DeployPrincipalObjectId. |
| -DnsResourceGroup | no | The resource group of the private DNS zone when it is in the HUB subscription: the written script also grants the deploy identity Private DNS Zone Contributor there. | |
| -EnvironmentLabel | no | A label shown in the written script's header (default: the PIM VNet name). | |
| -TenantId | no | The tenant id (GUID) of the hub's tenant, baked into the written script for its browser sign-in. Empty = the written script finds the hub subscription's tenant itself when it runs. Either way a sign-in to another tenant is refused. | |
| -PrivateDnsZoneName | no | (none) | Existing private DNS zones in -DnsResourceGroup (hub subscription) that the written script links to the hub VNet as 'link-<hub vnet>'. Needs -DnsResourceGroup. A zone that does not exist yet is skipped with a message. |
| -OutDirectory | no | the current folder | Where the file is written. |
Preview with -WhatIf
Derives the peering names, prints 'What if: Performing the operation "write the hub owner's script: peering '<name>' on '<hub vnet>'" on target "<folder>\prepare-hub-<name>.ps1"' and 'preview only -- nothing was written'. No file is written.
Undo
Delete the written file. What the hub owner's run created (the hub-side peering, any role assignment and DNS zone link it lists) is removed by the hub owner.
Network
It connects to: none (this script makes no network call; the written script talks to login.microsoftonline.com (the hub owner's browser sign-in) and Azure Resource Manager (management.azure.com) when the hub owner runs it with -Apply)
Download and run
Run these lines in PowerShell: the first downloads the script into the current folder, the second runs it.
Invoke-WebRequest https://invardia.com/support/pim/New-PimHubPrepareScript.ps1 -OutFile New-PimHubPrepareScript.ps1
.\New-PimHubPrepareScript.ps1 -SpokeSubscriptionId <SpokeSubscriptionId> -SpokeResourceGroup <SpokeResourceGroup> -SpokeVnetName <SpokeVnetName> -HubResourceGroup <HubResourceGroup> -HubVnetName <HubVnetName>To check the download first, compare its SHA-256 with the published one:
SHA-256 fb69f87006f2059cb43884402d03415d7a422bc87d13f67a870dffb639fcf272
Checksums: SHA256SUMS.txt · Version 3.0.70
Before you run it, compare the file's SHA-256 with its line in SHA256SUMS.txt.
Every parameter: Get-Help .\New-PimHubPrepareScript.ps1 -Full · Source: New-PimHubPrepareScript.ps1
Every script, identity and permission for your security review: PIM Manager