Troubleshooting IPAM Pool Reference In Azure Bicep

Introduction

In this article, we will explore and address a common issue encountered when deploying Azure Virtual Networks (VNets) using Bicep, specifically related to referencing IP Address Management (IPAM) Pools across different subscriptions. This issue manifests as a NotFound error, indicating that the IPAM Pool cannot be found despite providing the correct ID. We'll delve into the problem, provide a step-by-step explanation, and offer solutions to ensure successful deployments. If you're working with Azure Network Manager, IPAM pools, and Bicep, this guide is for you. Understanding the intricacies of cross-subscription deployments and resource referencing is crucial for maintaining infrastructure as code in complex Azure environments.

The Problem: IPAM Pool Not Found Error

When deploying a VNet in a subscription different from the one hosting the Azure Network Manager and its associated IPAM Pools, you might encounter the following error:

Ipam API call failed with status NotFound with error message Pool with ARM ID <IPAMPoolID> not found., please check the parameters and retry.

This error typically arises even when the IPAM Pool ID is correctly provided in the Bicep template. The core challenge lies in the cross-subscription referencing of resources, which requires careful configuration and understanding of Azure's resource management model. This error can be frustrating, especially when the deployment works seamlessly through the Azure portal. Let's dissect the potential causes and how to address them effectively.

Understanding the Error Context

To fully grasp the issue, it's essential to understand the context in which it occurs. The scenario involves:

1. Azure Network Manager (ANM): A centralized network management service that allows you to manage and govern network resources across multiple subscriptions.
2. IPAM Pools: Used within ANM to allocate and manage IP address prefixes. These pools define the range of IP addresses that can be assigned to VNets and subnets.
3. Cross-Subscription Deployment: Deploying a VNet in Subscription B while referencing an IPAM Pool in Subscription A, where the Azure Network Manager resides.
4. Bicep: An Infrastructure as Code (IaC) language used to define and deploy Azure resources declaratively.

The error message indicates that the Azure Resource Manager (ARM) cannot locate the specified IPAM Pool. This can be due to various reasons, including incorrect resource IDs, insufficient permissions, or issues with the Bicep template's structure.

Reproducing the Issue

To illustrate the problem, consider the following scenario:

1. Set up an Azure Network Manager and IPAM pools in Subscription A. Note the region where these resources are deployed.
2. Add Subscription B to the scope of the Azure Network Manager. This allows the ANM to manage resources in Subscription B.
3. Attempt to deploy a VNet to Subscription B in the same region as the ANM and IPAM pools.

The Bicep code snippet below demonstrates a common approach to defining the VNet with IPAM Pool references:

resource anmRg 'Microsoft.Resources/resourceGroups@2025-04-01' existing = {
  scope: subscription('7b4e5b72-e47b-4fd3-8d90-2d9567799c99') // Subscription A
  name: 'azureNetworkManager-RG'
}

resource ANM 'Microsoft.Network/networkManagers@2024-10-01' existing = {
  scope: anmRg
  name: 'azureNetworkManager'
}

resource ipamPool 'Microsoft.Network/networkManagers/ipamPools@2024-07-01' existing = {
  parent: ANM
  name: 'IP-ApplicationPool'
}

resource ANMnetwork 'Microsoft.Network/virtualNetworks@2024-10-01' = {
  name: vnetName
  location: location
  properties: {
    addressSpace: {
      ipamPoolPrefixAllocations: [
        {
          numberOfIpAddresses: '64'
          pool: {id: ipamPool.id}
        }
      ]
    }
    subnets: [
      for subnet in subnets: {
        name: subnetname
        properties: {
          ipamPoolPrefixAllocations: [
            {
              pool: {id: ipamPool.id}
              numberOfIpAddresses: '32'
            }
          ]
        }
      }
    ]
  }
}

In this code:

• We reference the Azure Network Manager and IPAM Pool in Subscription A using the existing keyword.
• We attempt to deploy a VNet in Subscription B, referencing the IPAM Pool from Subscription A.
• The ipamPoolPrefixAllocations property is used to specify the IPAM Pool for both the VNet's address space and its subnets.

When this Bicep template is deployed to Subscription B, it is likely to result in the NotFound error, despite the IPAM Pool ID being correctly specified. This discrepancy between portal deployments and Bicep deployments highlights the need for a deeper understanding of how Bicep handles cross-subscription references.

Root Causes and Solutions

Several factors can contribute to the NotFound error when referencing IPAM Pools across subscriptions. Let's explore the most common causes and their corresponding solutions.

1. Incorrect Resource ID

Cause: The most straightforward reason for a NotFound error is an incorrect Resource ID for the IPAM Pool. Even a minor typo can lead to this issue.

Solution:

• Verify the Resource ID: Double-check the Resource ID of the IPAM Pool in Subscription A. Ensure that the ID matches exactly in your Bicep template.
• Use the Azure Portal: Navigate to the IPAM Pool in the Azure Portal and copy the Resource ID directly from the properties blade. This eliminates the possibility of manual errors.
• Dynamic Resource ID Generation: Use Bicep's string interpolation features to construct the Resource ID dynamically. This ensures that the ID is always correct, even if the resource names change.

2. Permissions Issues

Cause: The service principal or user account deploying the Bicep template in Subscription B might lack the necessary permissions to access the IPAM Pool in Subscription A.

Solution:

• Role Assignments: Ensure that the service principal or user account has the Network Contributor role (or a custom role with equivalent permissions) on the resource group in Subscription A where the Azure Network Manager and IPAM Pools are located.
• Cross-Subscription Access: Verify that the identity used for the deployment has the appropriate permissions to access resources across subscriptions. This might involve setting up managed identities and granting them access through Azure RBAC (Role-Based Access Control).

3. Scope Definition in Bicep

Cause: Incorrect scope definition in the Bicep template can lead to resources being deployed in the wrong context, causing referencing issues.

Solution:

• Explicit Scope: Use the scope property in your Bicep resources to explicitly define the target scope for each resource. This ensures that resources are deployed in the intended subscription and resource group.
• Subscription-Level Deployments: For cross-subscription deployments, consider using subscription-level deployments to manage resources across multiple subscriptions from a single template.

4. Bicep Version and API Versions

Cause: Incompatibilities between the Bicep CLI version, Azure API versions, and the resource definitions can sometimes lead to unexpected errors.

Solution:

• Update Bicep CLI: Ensure that you are using the latest version of the Bicep CLI. Newer versions often include bug fixes and support for the latest Azure API versions.
• API Version Alignment: Use consistent API versions across your Bicep template. Check the Azure documentation for the recommended API versions for Azure Network Manager and related resources.
• Test Different API Versions: As mentioned in the original bug report, experimenting with different API versions might help identify if a specific version is causing the issue.

5. Resource Dependencies and Deployment Order

Cause: If the IPAM Pool is not fully provisioned before the VNet deployment is attempted, the NotFound error can occur. This is especially relevant in cross-subscription scenarios where resource provisioning might take longer.

Solution:

• Explicit Dependencies: Use the dependsOn property in Bicep to explicitly define dependencies between resources. This ensures that resources are deployed in the correct order.
• Asynchronous Operations: Monitor the deployment status of the IPAM Pool and ensure it has completed successfully before deploying the VNet. You can use Azure CLI or PowerShell to check the provisioning state of the IPAM Pool.

6. Network Manager Scope Issues

Cause: If Subscription B is not correctly added to the Azure Network Manager's scope, resources in Subscription B will not be able to reference IPAM Pools in Subscription A.

Solution:

• Verify Network Manager Scope: In the Azure Portal, navigate to your Azure Network Manager resource and check the scope settings. Ensure that Subscription B is included in the scope. If it's not, add it to the scope and retry the deployment.

Example: Revised Bicep Template

To address the potential issues, let's revise the Bicep template with some of the suggested solutions:

// Parameters
param location string = resourceGroup().location
param vnetName string = 'myVnet'
param subnetName string = 'mySubnet'
param ipamPoolId string = '/subscriptions/7b4e5b72-e47b-4fd3-8d90-2d9567799c99/resourceGroups/azureNetworkManager-RG/providers/Microsoft.Network/networkManagers/azureNetworkManager/ipamPools/IP-ApplicationPool'

// Existing Resources in Subscription A
resource anmRg 'Microsoft.Resources/resourceGroups@2025-04-01' existing = {
  scope: subscription('7b4e5b72-e47b-4fd3-8d90-2d9567799c99')
  name: 'azureNetworkManager-RG'
}

resource ANM 'Microsoft.Network/networkManagers@2024-10-01' existing = {
  scope: anmRg
  name: 'azureNetworkManager'
}

resource ipamPool 'Microsoft.Network/networkManagers/ipamPools@2024-07-01' existing = {
  scope: ANM
  name: 'IP-ApplicationPool'
}

// VNet in Subscription B
resource ANMnetwork 'Microsoft.Network/virtualNetworks@2024-10-01' = {
  name: vnetName
  location: location
  properties: {
    addressSpace: {
      ipamPoolPrefixAllocations: [
        {
          numberOfIpAddresses: '64'
          pool: {
            id: ipamPoolId // Use the parameter here
          }
        }
      ]
    }
    subnets: [
      {
        name: subnetName
        properties: {
          ipamPoolPrefixAllocations: [
            {
              pool: {
                id: ipamPoolId // Use the parameter here
              }
              numberOfIpAddresses: '32'
            }
          ]
        }
      }
    ]
  }
}

Key improvements in this revised template:

• Parameter for IPAM Pool ID: We've introduced a parameter ipamPoolId to explicitly define the IPAM Pool Resource ID. This makes it easier to manage and update the ID without modifying the core logic of the template.
• Explicit Scopes: The scope property is used to ensure that the existing resources in Subscription A are correctly referenced.
• Simplified Resource References: We've simplified the resource references by using the ipamPoolId parameter directly in the VNet's properties.

Additional Context and Considerations

Different API Versions

As noted in the initial problem description, different API versions can sometimes impact the behavior of resource deployments. It's a good practice to:

• Review Azure Documentation: Consult the official Azure documentation for the recommended API versions for each resource type.
• Experiment with Versions: If you encounter issues, try using a different API version to see if it resolves the problem. However, be cautious when downgrading API versions, as it might introduce compatibility issues.

Monitoring and Logging

Effective monitoring and logging are crucial for troubleshooting deployment issues. Azure Monitor provides tools to:

• Track Deployment Status: Monitor the status of your Bicep deployments and identify any errors or failures.
• View Activity Logs: Examine the activity logs to see the specific operations performed during the deployment and identify any permission-related issues.

Azure Policy

Azure Policy can be used to enforce compliance and prevent misconfigurations. Consider using Azure Policy to:

• Ensure Network Manager Scope: Implement policies to ensure that all relevant subscriptions are included in the scope of your Azure Network Manager.
• Validate IPAM Pool References: Create policies to validate that IPAM Pool references are correct and that the specified pools exist.

Conclusion

Referencing IPAM Pools across subscriptions in Azure Bicep deployments can be challenging, but with a systematic approach to troubleshooting, you can overcome the NotFound error and achieve successful deployments. By verifying Resource IDs, ensuring correct permissions, defining explicit scopes, managing API versions, and handling resource dependencies, you can build robust and reliable infrastructure as code solutions.

Remember to leverage Azure's monitoring and logging tools to gain insights into your deployments and proactively address any issues. By following the best practices outlined in this article, you'll be well-equipped to manage complex network configurations in Azure using Bicep.

For more in-depth information on Azure Network Manager and IPAM, refer to the official Microsoft Azure documentation on Azure Network Manager.