Rebuild-PimEnvInternal
Convert a public PIM Manager environment to private
Part of the PIM Manager release - not a standalone download; it runs via the product's own install command or the updater.
Purpose
Converts a public (external) PIM Manager environment to private (internal-only): it captures the live PIM Manager and jobs, deletes and recreates the Container Apps environment internal-only on the same subnet and workspace, restores the apps from the capture and compares them, repairs what is keyed to the new identities, attaches sign-in and publishes the private DNS zone for the new address. Data is kept. It plans unless -Apply is given.
When to run it
Once, to convert a public environment to private (the 'rebuild' route of the conversion guide), after the registry has a private endpoint and the network is prepared. 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 and runs Rebuild-PimEnvExternal.ps1 next to it: 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 private 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. 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 (secret values DPAPI-protected) in -CaptureDir | this computer, this Windows user | The rebuild restores from it and resumes from it; files holding secret values are 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 public 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 rebuild public again with Rebuild-PimEnvExternal.ps1. | |
| Azure (the PIM resource group) | create | the internal-only Container Apps environment on the same subnet and workspace, the PIM Manager (ingress internal first) and every job, from the capture | the resource group given | The conversion itself; the restore is compared with the capture. | Rebuild-PimEnvExternal.ps1 -Apply (the same tool in the other direction). | |
| 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. | Remove the role assignments of the new identities. |
| Environment SQL database | update | the database users of the recreated apps, created again from the new identities with their recorded roles (only with a SQL admin credential) | the environment's SQL database | 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 private address and its reply address on the sign-in app registration; then ingress on for the VNet | the PIM Manager and its sign-in app | Without sign-in the PIM Manager stays on internal ingress. | Remove the reply address. | |
| Azure (private DNS) | create | the private DNS zone for the new default domain (apex and wildcard to the static IP), linked to the PIM VNet and each -HubVnetId | the PIM resource group or -PrivateDnsResourceGroup | Clients in the VNet and the peered networks must resolve the new private address. | Delete the zone. | |
| 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 -- recorded before and checked after
- the system identities' Azure role assignments and application ids; the registry and SQL server's private endpoints
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. Without it (and no sign-in configured) the PIM Manager stays on internal ingress. | |
| -AzureConfigDir | no | Accepted for older callers and ignored: the rebuild uses no Azure CLI. | |
| -SkipEasyAuth | no | false | Attach no sign-in (the PIM Manager stays on internal ingress). |
| -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). |
| -HubVnetId | no | [] | The hub VNet(s) the new private DNS zone is also linked to. Without it only the PIM VNet resolves the PIM Manager. |
| -PrivateDnsResourceGroup | no | 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. Needs -SqlServer. | |
| -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 : EXTERNAL -> INTERNAL-ONLY', the captured PIM Manager and jobs, the keep-list, then 'PLAN ONLY -- nothing was changed' with the would DELETE / CREATE ('--internal-only true') / RESTORE lines, the private DNS zone it would create, notes on the registry and SQL, and 'capture NOT written (-WhatIf)'. -WhatIf wins over -Apply. Nothing is deleted or created.
Undo
Rebuild-PimEnvExternal.ps1 -Tag <tag> -SubscriptionId <subscription> -ResourceGroup <rg> -EasyAuthTenantId <tenant> -Apply rebuilds the environment public again. A run that stopped part-way resumes with -ResumeFromCapture -CaptureDir <the printed folder>. Data is never touched.
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 and the Graph re-grant's one setting)
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