Rebuild-PimEnvExternal
Rebuild a PIM Manager environment with the other exposure
Part of the PIM Manager release - not a standalone download; it runs via the product's own install command or the updater.
Purpose
Rebuilds the Container Apps part of a PIM Manager environment with the other exposure (private to public by default; Rebuild-PimEnvInternal.ps1 runs it from public to private): it captures the live PIM Manager and jobs, deletes and recreates the Container Apps environment on the same subnet and workspace, restores the apps from the capture and compares them, repairs what is keyed to the new identities, and attaches sign-in before the PIM Manager is reachable. Data is kept. It plans unless -Apply is given.
When to run it
Once, to move an environment that was built private (internal-only) to public, or (through Rebuild-PimEnvInternal.ps1) public to private. It is not a deploy step: an environment that already has the wanted exposure is left alone. Plan a maintenance window (the delete of a VNet-integrated environment takes 15-30 minutes). It runs on Windows (the capture protects secret values with Windows DPAPI). It is part of the PIM Manager release package: run it from the package folder that Install-Invardia or the guided install downloaded (signed), or, for Community, from the public repository at the release tag.
Who may run it
| Kind | Role | Scope | Why |
|---|---|---|---|
| azureRbac | Owner, or Contributor + User Access Administrator | the PIM resource group (role re-grants: their original scopes) | Deletes and recreates the Container Apps environment, the PIM Manager and the jobs, and grants the new system identities the Azure roles the old ones had. Signed in through the browser or the Invardia Support app session (no Azure CLI, no modules). |
| entraRole | Application Administrator (or owner of the PIM Manager's sign-in app) | the PIM Manager's sign-in app registration | Sign-in (Easy Auth) is attached to the new address; the reply address is added to the app registration. |
| other | Optional: an identity in the SQL admin group (grp-pim-sql-admins) with a certificate (-SqlAdminClientId + -SqlAdminCertThumbprint) | the environment's SQL database | Repairs the database users of the recreated apps (their SID is the new identity's application id). Without it the Azure roles are still repaired and the script says the database half is owed. |
| entraRole | Optional: Privileged Role Administrator (with -HostingAccessTenantId) | the tenant | Re-grants the new identities' Microsoft Graph application permissions (Initialize-PimHostingAccess.ps1). |
What it changes
| Where | Action | What | Permission / role | Scope | Why | Undo |
|---|---|---|---|---|---|---|
| Local file (temp folder) | create | the capture of the live environment, the PIM Manager and every job (configuration as JSON; secret values DPAPI-protected) in -CaptureDir | this computer, this Windows user | The rebuild restores from the capture and compares the result with it; a stopped run resumes from it (-ResumeFromCapture). Every file holding a secret value is shredded when the rebuild completes. | Delete the capture folder once the rebuild has completed. | |
| Azure (the PIM resource group) | remove | the Container Apps jobs, the PIM Manager app and the Container Apps environment (only with -Apply) | the resource group given | The internal/external setting of a Container Apps environment cannot be changed in place. | Re-run with -ResumeFromCapture -CaptureDir <the printed folder>; or run the rebuild in the other direction. | |
| Azure (the PIM resource group) | create | the Container Apps environment with the new exposure on the same subnet and workspace, the PIM Manager (ingress internal first) and every job, from the capture | the resource group given | The rebuild itself; the restore is compared field by field with the capture. | Run the rebuild in the other direction (Rebuild-PimEnvInternal.ps1 / Rebuild-PimEnvExternal.ps1). | |
| Azure (role assignments) | grant | each recreated app's and job's new system identity gets the Azure role assignments its old identity had | the same Azure roles the old identity held (recorded before the delete) | the scopes recorded before the delete | A recreated app gets a new identity; everything keyed to the old one stops matching. | Remove the role assignments of the new identities. |
| Environment SQL database | update | the contained database users of the recreated apps: dropped and created again from the new identity (SID = application id) with their recorded roles, for example db_owner, db_datareader (only with a SQL admin credential) | the environment's SQL database | The old database users no longer match the new identities; without the repair the PIM Manager cannot sign in to SQL. | None needed; the users match the live identities. | |
| Entra ID and the PIM Manager | update | sign-in (Easy Auth) on the new address and the reply address on the sign-in app registration; then the PIM Manager's ingress is switched on | the PIM Manager and its sign-in app | The PIM Manager is never reachable without sign-in. | Remove the reply address; switch the ingress off. | |
| Azure (private DNS) | create | to private: the private DNS zone for the new default domain (apex and wildcard to the static IP), linked to the PIM VNet and each -HubVnetId; to public: the stale zone of the old domain is removed (unless -KeepOldPrivateDnsZone) | the PIM resource group or -PrivateDnsResourceGroup | Clients must resolve the new address; a stale zone would shadow the public name. | Delete the zone (or re-create it). | |
| Azure (container registry) | update | public network access OFF (only with -LockRegistry; refused unless the registry is Premium with a private endpoint) | the registry in the resource group | A private environment pulls images and builds over the private endpoint. | Turn public network access back on for the registry. |
What it only reads
- the Container Apps environment, the PIM Manager app (with its secrets and sign-in configuration) and every job
- the data-bearing resources of the resource group (SQL, registry, Key Vault, VNet, Log Analytics, identities, storage) -- recorded before and checked after
- the system identities' Azure role assignments and application ids; with a SQL credential, the matching database users and their roles
Parameters
| Parameter | Required | Default | What it does |
|---|---|---|---|
| -Tag | yes | A short label for the capture files (any short name). | |
| -SubscriptionId | yes | The PIM subscription. | |
| -ResourceGroup | yes | The PIM resource group. | |
| -EnvName | no | cae-pim | The Container Apps environment. |
| -ManagerApp | no | ca-pim-manager | The PIM Manager app. |
| -CaptureDir | no | <temp>\pim-rebuild-<tag>-<time> | Where the capture is written (and read from with -ResumeFromCapture). |
| -EasyAuthTenantId | no | The tenant whose Entra ID signs users in to the PIM Manager. Required to go public unless the PIM Manager already has sign-in or -SkipEasyAuth is given. | |
| -AzureConfigDir | no | Accepted for older callers and ignored: the rebuild uses no Azure CLI. | |
| -SkipEasyAuth | no | false | Leave the PIM Manager on internal ingress and attach no sign-in (attach it yourself). |
| -KeepOldPrivateDnsZone | no | false | To public: keep the private DNS zone of the old domain. |
| -CustomDomain | no | To public: a custom name bound during the rebuild with a managed certificate (the script prints the DNS records and waits). | |
| -CustomDomainDnsReady | no | false | The custom name's DNS records already exist: do not wait for them. |
| -ResumeFromCapture | no | false | Continue a run that stopped after the delete, from the capture in -CaptureDir. |
| -DeleteTimeoutSeconds | no | 2700 | How long to wait for the environment delete. |
| -SqlServer | no | The SQL server (FQDN), for the database-user repair and the Graph re-grant. | |
| -SqlDatabase | no | PimPlatform | The database. |
| -SqlAdminClientId | no | An identity in the SQL admin group used for the database-user repair (with -SqlAdminCertThumbprint). | |
| -SqlAdminClientSecret | no | Legacy only: a client secret for -SqlAdminClientId. Prefer -SqlAdminCertThumbprint. | |
| -SqlAdminCertThumbprint | no | The thumbprint of -SqlAdminClientId's certificate in the local certificate store. | |
| -SkipIdentityRepair | no | false | Do not repair the database users or the role assignments of the new identities. |
| -EasyAuthAllowedPrincipals | no | [] | Who may sign in to the PIM Manager (users or groups). |
| -EasyAuthAllowAllTenantUsers | no | false | Every member account of the tenant may sign in (never guests). |
| -ToExposure | no | External | External (public) or Internal (private). Rebuild-PimEnvInternal.ps1 sets Internal. |
| -HubVnetId | no | [] | To private: the hub VNet(s) the new private DNS zone is also linked to. |
| -PrivateDnsResourceGroup | no | To private: where the new private DNS zone goes (same subscription; default the PIM resource group). | |
| -LockRegistry | no | false | Turn the registry's public network access off (refused unless Premium with a private endpoint). |
| -HostingAccessTenantId | no | Re-grant the new identities' Microsoft Graph permissions and the Run-now right in this tenant (Initialize-PimHostingAccess.ps1), in your own session. | |
| -HostingAccessClientId | no | Optional: a certificate identity for that re-grant instead of your session. | |
| -HostingAccessCertThumbprint | no | Its certificate thumbprint in the local certificate store. | |
| -Apply | no | false | Do it. Without it (and always with -WhatIf) the script prints the plan. |
Preview with -WhatIf
Reads the live environment and prints the plan: 'direction : <from> -> <to>', the captured PIM Manager and jobs, the keep-list, the identity-keyed state, then 'PLAN ONLY -- nothing was changed' with the would DELETE / CREATE / RESTORE / THEN lines and 'capture NOT written (-WhatIf)'. -WhatIf wins over -Apply. Nothing is deleted or created and no capture is written.
Undo
Run the rebuild in the other direction (Rebuild-PimEnvInternal.ps1 / Rebuild-PimEnvExternal.ps1). A run that stopped part-way resumes with -ResumeFromCapture -CaptureDir <the printed folder>. Data is never touched; point-in-time restore of the database remains available.
Network
It connects to: login.microsoftonline.com (sign-in), management.azure.com (Azure Resource Manager), graph.microsoft.com (identities, the sign-in app registration), <server>.database.windows.net:1433 (only for the database-user repair)
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