New-PimHybridWorkerInfra
PIM for Active Directory: build the hybrid worker's Azure side (or check an Azure Arc server)
Part of the PIM Manager release - not a standalone download; it runs via the product's own install command or the updater.
Purpose
Builds the Azure side of the PIM for Active Directory hybrid worker -- its own resource group, network, deny-all firewall, NAT gateway egress and Windows VM -- or, for an Azure Arc-enabled on-premises server, checks the machine and builds nothing.
When to run it
Once per hybrid worker, first step. Azure VM worker: with -PeerVnetId and -DnsServers. On-premises worker: with -ArcMachineResourceId after the server is onboarded to Azure Arc. Deploy-PimHybridWorker.ps1 runs it for you.
Who may run it
| Kind | Role | Scope | Why |
|---|---|---|---|
| azureRbac | Contributor | the worker's subscription (Azure VM); Reader on the Arc machine (Arc) | creates the resource group, VNet, NSG, NAT gateway and VM; reads the Arc machine |
| azureRbac | Network Contributor | every VNet the worker peers with (-PeerVnetId) | the script creates both sides of each peering |
| azureRbac | SQL Server Contributor | the PIM SQL server (-SqlServerId) | the VNet rule for the worker subnet (Azure VM) or the firewall rules for -SqlAllowedPublicIp (Arc) |
What it changes
| Where | Action | What | Permission / role | Scope | Why | Undo |
|---|---|---|---|---|---|---|
| Azure (Azure VM worker) | create | resource group, VNet + subnet (Microsoft.Sql and Microsoft.Storage service endpoints, DNS = your DCs), NSG with deny-all inbound, NAT gateway + its public IP (Set-PimHybridWorkerEgress.ps1), peerings in both directions, the VM (Windows Server 2022 Azure Edition Core, Trusted Launch, system-assigned identity, NO public IP), a SQL VNet rule | the worker's own isolated network and machine; the local admin password is generated, used once and discarded | delete the resource group, the remote peerings and the SQL VNet rule 'pimhybridwrk' | ||
| privatelink.database.windows.net (-PrivateSqlDnsZoneId / -PrivateDnsZoneResourceGroup) | create | a virtual network link 'link-pimhybridwrk-<vnet>' (tagged pim-hybrid-worker) to the worker VNet and each -PrivateDnsLinkVnetId; the standard zone itself only with -CreatePrivateDnsZone when missing; a DNS zone group on the SQL private endpoint only when its A record is missing and the endpoint has none | a private-only PIM database must resolve to its private address; the DCs' conditional forwarder is printed, never written | Remove-PimHybridWorker.ps1 (the worker VNet's link); delete other links yourself | ||
| VNet peerings (-UseRemoteGateways / -AllowForwardedTraffic) | update | useRemoteGateways / allowForwardedTraffic on the worker-side peering; allowGatewayTransit on the hub side only when PIM created that peering (otherwise printed for the hub owner) | DCs reached through a hub VPN / ExpressRoute gateway | Set-PimHybridWorkerPeering.ps1 cannot turn them off; set them in the portal, or remove the worker | ||
| PIM SQL server (Arc, -SqlAllowedPublicIp) | create | one firewall rule per on-premises egress address (pimhybridwrk-arc-<server>-<n>) | an on-premises worker reaching a public SQL endpoint; not needed with a private endpoint | delete those firewall rules |
What it only reads
- the subscription's tenant
- what already exists (read-before-write): resource group, NSG, VNet, peerings, VM, SQL rules
- the Arc machine (status, OS, identity)
Parameters
| Parameter | Required | Default | What it does |
|---|---|---|---|
| -SubscriptionId | yes | The worker's subscription (Azure VM) or the Arc machine's. | |
| -TenantId | yes | The tenant; the script refuses a subscription in another one. | |
| -ArcMachineResourceId | no | On-premises worker: the Azure Arc machine's resource id. Builds nothing; checks it is connected, Windows and has an identity. | |
| -ArcApiVersion | no | 2024-07-10 | Microsoft.HybridCompute api-version. |
| -SqlAllowedPublicIp | no | Arc with a public SQL endpoint: the site's egress address(es). | |
| -ResourceGroup | no | rg-pimhybridwrk | Azure VM: the worker's resource group. |
| -Location | no | westeurope | Azure VM: the region (your choice). |
| -VmName | no | PIMHYBRIDWRK | Azure VM: VM and computer name, max 15 characters. |
| -VmSize | no | Standard_B2s | Azure VM: the size (4 GiB recommended). |
| -VnetName | no | vnet-pimhybridwrk | Azure VM: the worker VNet. |
| -AddressPrefix | no | 10.221.16.0/24 | Azure VM: VNet range (must not overlap the peered networks). |
| -SubnetPrefix | no | 10.221.16.0/27 | Azure VM: the worker subnet. |
| -PeerVnetId | no | Azure VM (required there): the VNet(s) with the domain controllers, optionally the PIM environment's. | |
| -DnsServers | no | Azure VM (required there): the domain controllers' addresses. | |
| -SqlServerId | no | The PIM SQL server's resource id (VNet rule / firewall rules). | |
| -Egress | no | NatGateway | Azure VM: NatGateway, or None when your network routes outbound. Never a public IP on the VM. |
| -Image | no | MicrosoftWindowsServer:WindowsServer:2022-datacenter-azure-edition-core-smalldisk:latest | Azure VM: the image (Publisher:Offer:Sku:Version). |
| -PrivateSqlDnsZoneId | no | Private-only PIM database: the EXISTING privatelink.database.windows.net zone (no other zone name is accepted). It is linked to the worker VNet (Azure VM) and to every -PrivateDnsLinkVnetId. | |
| -PrivateDnsLinkVnetId | no | More VNets to link the zone to: the DCs' VNet when the DCs are Azure VMs (Azure DNS answers from the zones linked to the ASKING DNS server's VNet), or the DNS Private Resolver's VNet (Arc / on-premises DCs). | |
| -CreatePrivateDnsZone | no | false | Create the standard zone privatelink.database.windows.net ONLY when it is missing (with -PrivateDnsZoneResourceGroup or -PrivateSqlDnsZoneId); attaches it to the SQL private endpoint when that endpoint has no DNS zone group yet. |
| -PrivateDnsZoneResourceGroup | no | Where the standard zone lives (in -SubscriptionId), instead of -PrivateSqlDnsZoneId. | |
| -PrivateSql | no | false | Print the conditional forwarder the DNS administrator adds (implied by the zone options). PIM never writes AD / on-premises DNS. |
| -DnsForwarderIp | no | 168.63.129.16 (Azure VM) / the Private Resolver inbound endpoint (Arc) | The address the printed forwarder points at: 168.63.129.16 for DCs that are Azure VMs, an Azure DNS Private Resolver inbound endpoint for DCs on-premises. |
| -UseRemoteGateways | no | false | Azure VM: DCs reached through the hub's VPN / ExpressRoute gateway -- the worker-side peering to -GatewayVnetId uses it (Set-PimHybridWorkerPeering.ps1; the hub must have a gateway and allow gateway transit). |
| -GatewayVnetId | no | Azure VM: the hub VNet with the gateway (one of -PeerVnetId). | |
| -AllowForwardedTraffic | no | false | Azure VM: the worker-side peering(s) accept traffic the hub forwards (an NVA / firewall in the hub). |
Preview with -WhatIf
Prints every resource it would create (or, for Arc, the checks and the firewall rules) and changes nothing.
Undo
Remove-PimHybridWorker.ps1 deletes everything this script created (it carries the tag pim-hybrid-worker). By hand: Azure VM: delete the worker's resource group, the remote peerings '<remote>-to-pimhybridwrk', the SQL VNet rule 'pimhybridwrk' and the zone link. Arc: delete the pimhybridwrk-arc-* SQL firewall rules.
Network
It connects to: management.azure.com (ARM REST) and login.microsoftonline.com -- browser sign-in or an Invardia support session; no Azure CLI, no PowerShell module
How it runs
Part of the PIM Manager release - not a standalone download; it runs via the product's own install command or the updater.
Release 3.0.70
Every script, identity and permission for your security review: PIM Manager