Invoke-PimHybridWorkerRunCommand
PIM for Active Directory: run the hybrid worker installer through Azure run-command
Part of the PIM Manager release - not a standalone download; it runs via the product's own install command or the updater.
Purpose
Runs the hybrid worker installer on the worker machine (an Azure VM or an Azure Arc-enabled server) through Azure run-command, so nothing inbound is needed, or writes it as a self-contained script for the server's administrator.
When to run it
For each install phase: -Phase Join (Azure VM only, with the offline-join blob), then -Phase Configure after the grants; -Phase Update to move the worker to its ring's version at once. Deploy-PimHybridWorker.ps1 runs it for you.
Who may run it
| Kind | Role | Scope | Why |
|---|---|---|---|
| azureRbac | Virtual Machine Contributor | the worker VM (Azure VM) | creates and deletes the run-command resource; it runs as SYSTEM on the worker |
| other | Azure Connected Machine Resource Administrator (Azure RBAC) | the Arc machine (Arc) | creates and deletes the run-command resource on the Arc machine; it runs as SYSTEM on the server |
What it changes
| Where | Action | What | Permission / role | Scope | Why | Undo |
|---|---|---|---|---|---|---|
| the worker machine's Azure resource | create | a managed run-command pim-hybrid-worker-<phase> carrying Install-PimHybridWorker.ps1 and its arguments (the offline-join blob only as a protected parameter); DELETED after the run | delivers the install without anything inbound | nothing is left; the install phase itself is undone as Install-PimHybridWorker.ps1 describes | ||
| this computer | create | only when run-command cannot be used or with -PrintOnly: the self-contained install script (-OutScript), without the secret | the server's administrator runs it locally | delete the file |
What it only reads
- the machine (location; for Arc its status and OS)
- the run-command result: state, exit code, output, error
Parameters
| Parameter | Required | Default | What it does |
|---|---|---|---|
| -SubscriptionId | yes | The machine's subscription; another one is refused. | |
| -TenantId | yes | The tenant. | |
| -MachineResourceId | yes | The worker: .../Microsoft.Compute/virtualMachines/<vm> or .../Microsoft.HybridCompute/machines/<server>. | |
| -Phase | yes | Join (Azure VM only), Configure, Update, Layout, Remove (the worker's tasks and rights on the machine; used by Remove-PimHybridWorker.ps1) Guests (read only: the other products registered on the machine; used by Remove-PimHybridWorker.ps1) or MetadataAccess (Azure VM: re-applies only the rule that limits who may reach the instance metadata service). | |
| -InstallParameters | no | @{} | Install-PimHybridWorker.ps1's parameters (GmsaName, SqlServer, TenantId, SourceContainerUrl, Ring, ...); HostType Arc is added for an Arc machine. |
| -ProtectedParameterNames | no | OdjBlob | Arguments sent only as protected (write-only) parameters, never in the script text. |
| -PrintOnly | no | false | Do not use run-command: write the self-contained script. |
| -OutScript | no | pim-hybrid-worker-<phase>-<machine>.ps1 in the current folder | Where the self-contained script is written. |
| -TimeoutMinutes | no | 45 | Run-command timeout. |
| -PollSeconds | no | 15 | How often the result is read. |
| -ComputeApiVersion | no | 2024-03-01 | Microsoft.Compute api-version (Azure VM). |
| -ArcApiVersion | no | 2024-07-31-preview | Microsoft.HybridCompute api-version (Arc run-command). |
Preview with -WhatIf
Reads the machine and prints the run-command it would create; creates nothing and runs nothing.
Undo
The run-command resource is deleted after every run; undo the install phase as Install-PimHybridWorker.ps1 describes.
Network
It connects to: management.azure.com (ARM REST) and login.microsoftonline.com -- browser sign-in or an Invardia support session; nothing to the machine directly; 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