New-PimHostingPrerequisites
Create the Azure prerequisites of a PIM Manager environment
Part of the PIM Manager release - not a standalone download; it runs via the product's own install command or the updater.
Purpose
Creates, or finds and reuses, what a PIM Manager environment needs in the subscription before the containers are deployed: the resource providers, the resource group, the VNet with its delegated Container Apps subnet, Log Analytics, the container registry (optionally Premium with a private endpoint and a build pool), the image-pull identity, and the SQL server and database with Entra-only sign-in and the SQL admin group. Every step is find-or-create and read back at the end.
When to run it
Normally never by hand: Invoke-PimDeployAll.ps1 runs it as its 'prereq' step. Run it yourself to change an existing environment's prerequisites with the same names, for example to make the registry private (Premium, private endpoint, build pool) or to add the SQL private endpoint before or after a conversion to private. It is part of the PIM Manager release package (it loads the engine's REST libraries 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 subscription | Registers resource providers, creates the resource group and everything in it, and grants the image-pull identity AcrPull on the registry. Signed in through the browser or the Invardia Support app session (-UseSignedInAccount; no Azure CLI, no modules). |
| entraRole | Privileged Role Administrator | the tenant | Creates the role-assignable SQL admin group (grp-pim-sql-admins) and adds its members. |
What it changes
| Where | Action | What | Permission / role | Scope | Why | Undo |
|---|---|---|---|---|---|---|
| Azure (subscription) | update | resource provider registrations: Microsoft.App, Microsoft.ContainerRegistry, Microsoft.OperationalInsights, Microsoft.Network, Microsoft.Sql, Microsoft.Storage, Microsoft.KeyVault, Microsoft.ManagedIdentity, Microsoft.Insights | the subscription | A fresh subscription refuses the creates without them. | Not needed (a registration costs nothing); unregister in the portal if required. | |
| Azure (the PIM resource group) | create | the resource group, the VNet and the Container Apps subnet (delegated to Microsoft.App/environments), the Log Analytics workspace and the container registry (find-or-create; an existing registry is upgraded to the requested SKU, never downgraded) | the resource group (-ResourceGroupName) | Everything the container deploy assumes exists. | Delete the resources (or the resource group) -- only when the environment is removed. | |
| Azure (private networking) | create | with -AcrPublicAccess false / -SqlPrivateEndpoint: the private-endpoint subnet, the registry's and SQL server's private endpoints, the privatelink.azurecr.io / privatelink.database.windows.net zones linked to the VNet, and the registry build pool (-AcrAgentPoolName) | the resource group or -PrivateDnsResourceGroup (same subscription) | A private registry and database are reachable only through private endpoints; the build pool builds images inside the VNet. | Delete the private endpoints, zones and build pool. | |
| Azure (network) | create | with -InternalRanges and -FirewallIp, in a network the installation made: route table rt-pim (one route per range, next hop VirtualAppliance -> the firewall, BGP route propagation off) attached to the apps subnet (its other settings kept), and the two answers as tags on the resource group (pim-return-ranges, pim-return-firewall) so the nightly updater can report a missing route | the resource group and the apps subnet | Behind a hub firewall the replies to your network must go back through the firewall, or they time out. | Detach the route table from the subnet, delete rt-pim and remove the two tags. | |
| Azure (identities) | grant | the image-pull identity id-pim-<token> (created) gets AcrPull on the registry; with private SQL the SQL identity id-pim-sql-<token> is created | AcrPull | the container registry | The Container Apps pull images with this identity; no registry password is kept. | Remove the role assignment and the identity. |
| Azure SQL | create | the SQL server (Entra-only authentication, TLS 1.2) and the database PimPlatform (S0 minimum), the connection policy (-SqlConnectionPolicy), the AllowAzureServices rule only when no subnet path exists, and the temporary AllowSetupHost rule for this host | the resource group | The PIM store. The setup-host rule is the setup window; Invoke-PimDeployAll removes it at the end of its run. | Delete the AllowSetupHost rule when done (standalone run); the server and database hold the data and are never removed by PIM. | |
| Entra ID | grant | the SQL server's Entra admin converges on the role-assignable group grp-pim-sql-admins; members: the environment identities, the SQL identity, the person or identity running the deploy and the Invardia Support app (-SupportAppId) | SQL Entra admin (through the group membership) | the SQL server | One admin model for public and private SQL; nobody loses access when the admin moves. | Remove members from the group, or set another Entra admin on the SQL server. |
What it only reads
- the subscription (it must be visible to the sign-in and belong to -TenantId)
- every resource before it is created (find-or-create), and all of them again at the end (=== VERIFY ===)
Parameters
| Parameter | Required | Default | What it does |
|---|---|---|---|
| -TenantId | yes | The tenant. | |
| -SubscriptionId | yes | The PIM subscription (must belong to -TenantId). | |
| -Token | yes | Short name every default resource name is derived from (rg-automateit-<token>, vnet-pim-<token>, ...); override any name with the parameters below. | |
| -Index | no | -1 | Address-plan index for the <AddressBase>.<Index*8>.0/21 scheme. Give this OR -VnetAddressPrefix + -SubnetAddressPrefix. |
| -AdminAppId | no | Automation: the deploy identity's client id (with -AdminCertPem). Customers use -UseSignedInAccount. | |
| -UseSignedInAccount | no | false | Create everything as the person signed in (browser) or the Invardia Support app session. The recommended way. |
| -AdminSecret | no | Legacy automation only: a client secret for -AdminAppId. Not for customer use. | |
| -AdminCertPem | no | Automation: PEM file (key + certificate) of -AdminAppId. | |
| -Location | no | swedencentral | The Azure region. |
| -SqlServiceObjective | no | the product tier (S3) | The database tier. Leave it out for the product tier (S3, 250 GB maximum size). A Standard tier below it (S0, S1, S2) is created as named and pinned, so updates keep it; Basic is never created. |
| -SqlConnectionPolicy | no | Default | Default, Proxy or Redirect. Proxy when your firewall allows only port 1433 to SQL. |
| -AcrSku | no | Basic | Basic, Standard or Premium. Only Premium has network controls (private endpoint, public access off). |
| -AcrPublicAccess | no | Default | Default, true or false. false needs Premium, a private-endpoint subnet and a build pool. On an existing registry the private endpoint is added and public access is turned off later (the conversion's -LockRegistry). |
| -PrivateEndpointSubnetName | no | pim-endpoints | The private-endpoint subnet (it cannot be the Container Apps subnet). |
| -PrivateEndpointSubnetAddressPrefix | no | Its address range (a /26 is enough). | |
| -PrivateDnsResourceGroup | no | Where the privatelink zones go (same subscription; default the PIM resource group). | |
| -VnetResourceGroup | no | the PIM resource group | The VNet's own resource group (same subscription): the VNet, its subnets and the private endpoints' subnet are read and created there. |
| -SqlPublicAccessDisabled | no | false | With -SqlPrivateEndpoint: the SQL server is created with public network access disabled (an existing one is switched off once its private endpoint exists) and no firewall rule is written. |
| -PrivateDnsZoneLinkVnetIds | no | Also link the installation's own privatelink zones to these VNets (the hub). Never used for central zones. | |
| -InternalRanges | no | [] | With -FirewallIp (both or neither): your internal ranges. Route table rt-pim in the resource group gets one route per range (next hop VirtualAppliance -> -FirewallIp, BGP route propagation off) and is attached to the apps subnet, read back. A refusal is a warning and a network hand-off line, never a stop. |
| -FirewallIp | no | With -InternalRanges: the hub firewall's private IP, the return route's next hop. | |
| -ReturnRouteHandOffOnly | no | false | The VNet is your own: nothing is written to it; the return route is printed as a network hand-off line. |
| -PrivateDnsZonesResourceGroupId | no | Your central privatelink zones (a resource group id, any subscription): used, never created or written -- a missing zone stops the step, and no link is made there. | |
| -SqlPrivateEndpoint | no | false | Create the SQL server's private endpoint and the privatelink.database.windows.net zone. |
| -AcrAgentPoolName | no | The registry build pool (Premium), placed in the private-endpoint subnet. | |
| -AcrAgentPoolCount | no | 0 | Build agents between builds (0: each build scales the pool to 2 and back to 0). |
| -AcrAgentPoolTier | no | S2 | S1, S2 or S3 (S2 by default). |
| -AddressBase | no | 10.220 | The /16 the -Index scheme carves from. |
| -ResourceGroupName | no | rg-automateit-<token> | Your own resource group name. |
| -VnetName | no | vnet-pim-<token> | Your own VNet name. |
| -SubnetName | no | snet-pim-aca | Your own Container Apps subnet name. |
| -VnetAddressPrefix | no | Your VNet range (with -SubnetAddressPrefix). | |
| -SubnetAddressPrefix | no | Your Container Apps subnet range (/27 or larger; /24 or /23 recommended). | |
| -AcrName | no | acrpim<token> | Your own registry name (letters and digits). |
| -LogAnalyticsName | no | law-pim-<token> | Your own Log Analytics workspace name. |
| -SqlServerName | no | sql-ait-<token> | Your own SQL server name (without .database.windows.net). |
| -SkipSql | no | false | Create no SQL server (a central store is used). |
| -SqlAdminGroupName | no | grp-pim-sql-admins | The SQL admin group. |
| -UpdateJobName | no | ca-pim-update | The name of the update job whose identity the SQL admin group setup looks up. Change it only when your installation uses its own resource names (the names are recorded per installation, so renames keep working). |
| -SupportAppId | no | The Invardia Support app's application id, added to the SQL admin group (alias -TroubleshootingAppId). | |
| -SkipSqlAdminGroup | no | false | Keep a single-principal SQL admin instead of the group. |
| -SetupHostIp | no | This host's public IP for the temporary AllowSetupHost rule; without it the IP is read from api.ipify.org (said on screen). |
Preview with -WhatIf
Checks the names, the address plan and the options from the parameters, prints the summary (subscription, location, VNet / subnet, registry / workspace) and one 'What if: would ...' line per step (providers, resource group, VNet, Log Analytics, registry, private endpoints, pull identity with AcrPull, SQL server and database, SQL admin group), then 'RESULT: WHAT-IF'. Nothing is signed in to and nothing is created.
Undo
The resources are find-or-create and hold the environment; remove them only together with the environment (delete the resource group, the SQL admin group and the sign-in app registration). After a standalone run, delete the temporary AllowSetupHost SQL firewall rule once the deploy's SQL steps are done.
Network
It connects to: login.microsoftonline.com (sign-in), management.azure.com (Azure Resource Manager), graph.microsoft.com (the SQL admin group), api.ipify.org (only without -SetupHostIp and only when SQL is created with a public endpoint)
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