Remove-PimHybridWorker
PIM for Active Directory: remove the hybrid worker (Azure VM or 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
Removes the PIM for Active Directory hybrid worker and everything PIM's worker scripts created for it, and prints the Active Directory clean-up for the AD administrator.
When to run it
When you retire a hybrid worker. Run it without -Apply first: it lists what it would delete and what it keeps. -Target Azure for the worker VM New-PimHybridWorkerInfra.ps1 built; -Target Arc for an on-premises Azure Arc server (the server itself is never removed). -StatePath reads the values Deploy-PimHybridWorker.ps1 remembered.
Who may run it
| Kind | Role | Scope | Why |
|---|---|---|---|
| azureRbac | Contributor | the worker's resource group (Azure VM) | deletes the VM, its NIC and disk, the VNet, NAT gateway, public IP, NSG and the empty resource group |
| azureRbac | Network Contributor | every VNet the worker was peered with; the private DNS zone (with -PrivateSqlDnsZoneId) | deletes the remote-side peerings PIM created and the zone's link to the worker VNet |
| azureRbac | SQL Server Contributor | the PIM SQL server | deletes the VNet rule 'pimhybridwrk' (Azure VM) or the firewall rules 'pimhybridwrk-arc-<server>-<n>' (Arc) |
| azureRbac | User Access Administrator | the source container (-SourceContainerId) | deletes the worker identity's Storage Blob Data Reader assignment |
| entraRole | Privileged Role Administrator | the tenant | deletes the worker identity's Microsoft Graph application permission grants (appRoleAssignments) |
| other | member of the PIM SQL admin group | the PIM database | DROP USER of the worker's contained database user |
| azureRbac | Azure Connected Machine Resource Administrator | the Arc machine (-Target Arc) | runs Install-PimHybridWorker.ps1 -Phase Remove on the server through run-command |
What it changes
| Where | Action | What | Permission / role | Scope | Why | Undo |
|---|---|---|---|---|---|---|
| Microsoft Graph (the worker identity) | remove | the application permission grants Grant-PimHybridWorkerAccess.ps1 gives: Group.Read.All, User.Read.All, PrivilegedAssignmentSchedule.Read.AzureADGroup, Mail.Send (when granted) | the worker no longer reads the directory | Grant-PimHybridWorkerAccess.ps1 | ||
| the source container | remove | Storage Blob Data Reader of the worker identity | the worker no longer fetches PIM code | Grant-PimHybridWorkerAccess.ps1 | ||
| the PIM database | remove | the contained user -SqlUserName (database user), only when it carries the worker identity's SID | no database access is left behind | Grant-PimHybridWorkerAccess.ps1 | ||
| the PIM SQL server | remove | VNet rule 'pimhybridwrk' (only when it names the worker subnet) / firewall rules 'pimhybridwrk-arc-<server>-<n>' | created for the worker | New-PimHybridWorkerInfra.ps1 | ||
| privatelink.database.windows.net (with -PrivateSqlDnsZoneId) | remove | the zone's link to the worker VNet; links to other VNets and the zone itself are kept and listed | created for the worker | New-PimHybridWorkerInfra.ps1 -PrivateSqlDnsZoneId | ||
| the worker's Azure resources (Azure VM) | remove | the remote-side peerings '<remote>-to-pimhybridwrk' and the worker-side peerings, the VM with its NIC and OS disk, the VNet, the NAT gateway and its public IP, the NSG, and the resource group when PIM created it and it is empty -- only resources tagged pim-hybrid-worker=<worker> (or, with -IncludeUntagged, carrying exactly the scripts' name) | the worker is retired; nothing PIM did not create is touched | Deploy-PimHybridWorker.ps1 (a new worker; the VM's identity is new, so the grants are re-run) | ||
| the Arc server (-Target Arc) | remove | the worker's six scheduled tasks, its gMSAs' membership of 'Hybrid agent extension applications' and 'log on as a batch job', C:\PIM\app and C:\PIM\bin (logs kept) -- the machine, its agent and identity stay | the worker is retired | Install-PimHybridWorker.ps1 -Phase Configure |
What it only reads
- the subscription's tenant
- the worker VM / Arc machine and its identity
- the identity's Graph grants and role assignments
- the SQL server's rules
- the peerings on both sides
- the NAT gateway, public IP, NSG and resource group with their tags
- the private DNS zone's links
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. | |
| -Target | yes | Azure (the worker VM) or Arc (an on-premises Azure Arc server). Read from -StatePath when given there. | |
| -ResourceGroup | no | rg-pimhybridwrk | Azure: the worker's resource group. |
| -VmName | no | PIMHYBRIDWRK | Azure: the worker VM (the tag value pim-hybrid-worker). |
| -VnetName | no | vnet-pimhybridwrk | Azure: the worker VNet. |
| -NatGatewayName | no | natgw-<vmname> | Azure: the NAT gateway Set-PimHybridWorkerEgress.ps1 created. |
| -PublicIpName | no | pip-<vmname> | Azure: the NAT gateway's public IP. |
| -PrivateSqlDnsZoneId | no | The privatelink.database.windows.net zone the build linked; its link to the worker VNet is deleted. | |
| -IncludeUntagged | no | false | A worker built before the tags: also accept untagged resources carrying exactly the scripts' names in -ResourceGroup. Check the plan first. |
| -NoGuestCheck | no | false | Azure: do not read the products registered on the VM (C:\ProgramData\HybridWorkerHost\guests) before removing it. Only when the VM cannot run commands and you know no other product's worker is on it; without it, a VM whose registry cannot be read is kept. |
| -ArcMachineResourceId | no | Arc: the machine's resource id (required for -Target Arc). The machine is never removed. | |
| -ArcApiVersion | no | 2024-07-10 | Microsoft.HybridCompute api-version. |
| -PrintOnly | no | false | Arc: write the self-contained removal script for the server's administrator instead of using run-command. |
| -SqlServerId | no | The PIM SQL server: its worker rules and the contained user are removed. | |
| -SqlDatabase | no | PimPlatform | The PIM database. |
| -SqlUserName | no | PIMHYBRIDWRK | The worker's contained user. |
| -KeepSqlUser | no | false | Leave the database user in place. |
| -SourceContainerId | no | The source container whose Storage Blob Data Reader assignment is removed. | |
| -AdDomain | no | AD (printed only): the NetBIOS domain name. | |
| -GmsaName | no | gMSA-PIM-L1-T0 | AD (printed only): the worker gMSA. |
| -GmsaOu | no | AD (printed only): the OU holding the gMSAs and their groups. | |
| -ServerGmsaName | no | AD (printed only): the server-onboarding gMSA, when used. | |
| -ServerOu | no | AD (printed only): the OUs the servers GPO is linked to. | |
| -ServerAdminGpoName | no | PIM for AD: <ServerGmsaName>-PermissionGroup is local administrator (servers) | AD (printed only): the servers GPO's name. |
| -ComputerOu | no | AD (printed only): the OU of the worker VM's computer account. | |
| -GroupsOu | no | AD (printed only): the OU where the PermissionGroup holds rights. | |
| -AdminAccountsOu | no | AD (printed only): the admin-account OUs where the PermissionGroup holds rights. | |
| -GrantProtectedGroupMembership | no | false | AD (printed only): the worker was given the AdminSDHolder right. |
| -StatePath | no | A Deploy-PimHybridWorker.ps1 state file: every value not given is read from it. | |
| -Apply | no | false | Delete. Without it the script only prints the plan. |
| -PollSeconds | no | 10 | How often a delete is checked until the resource is gone. |
Preview with -WhatIf
Without -Apply (or with -WhatIf) it prints every object it would delete, every object it keeps and why, and the Active Directory clean-up; changes nothing.
Undo
Nothing deleted can be restored by this script: build the worker again with Deploy-PimHybridWorker.ps1 (a new VM identity, so the grants are given again). Active Directory is never changed by it.
Network
It connects to: management.azure.com (ARM REST), graph.microsoft.com, the PIM SQL server on 1433 (DROP USER), 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