Known Issues

If you deploy multiple instances of the same module (e.g., DNS entries, role assignments, etc.) you should invoke the module using a loop, as opposed to separate references to the same module. The reason comes down the way that ARM interprets these references: Each reference of a module is restored to its full ARM size. That means, if you invoke the same module 3 separate time, you will find that this module’s full template is added as a nested deployment 3 separate times. Using a loop instead, the reference is only added once and invoked as many times as your loop has entries.

For example, you should refactor the code

targetScope = 'subscription'

@description('The principal to assign the roles to.')
param principalId string

module testDeployment1 'br/public:avm/res/authorization/role-assignment/sub-scope:0.1.0' = {
  params: {
    principalId: principalId
    roleDefinitionIdOrName: 'Contributor'
  }
}
module testDeployment2 'br/public:avm/res/authorization/role-assignment/sub-scope:0.1.0' = {
  params: {
    principalId: principalId
    roleDefinitionIdOrName: 'Role Based Access Control Administrator'
  }
}

to

targetScope = 'subscription'

@description('The principal to assign the roles to.')
param principalId string

var rolesToAssign = [
  'Contributor'
  'Role Based Access Control Administrator'
]

module testDeployment 'br/public:avm/res/authorization/role-assignment/sub-scope:0.1.0' = [
  for role in rolesToAssign: {
    params: {
      principalId: principalId
      roleDefinitionIdOrName: role
    }
  }
]

For this example, the compiled JSON of first version has a size of 18kb, the second 10kb.

Using AVM modules can come with a lot of advantages compared to a native resource deployment. This can be as simple as being a ‘module’ deployment, enabling you to deploy to multiple scopes in the same template at once, all the way to encapsulating entire solution into a single invocation and hence drastically reducing the complexity of your own solution template.

However, they also come with certain limitations. For one, that you’re dependent on the module providing you all the features you need, but moreover, that the very same features are always part of the module, whether you use them or not, hence contributing to your solution template’s size.

With this in mind, our recommendation is to only use AVM modules if you use any of its features, hence justifying the added size.

Recommendations

• Only use the br/public:avm/res/resources/resource-group resource if you deploy resource groups with role assignments
• Only use the br/public/avm/res|ptn/authorization/(...) modules if you benefit from their scope flexibility
• When facing challenges with the template size, start replacing individual module references with their native counter-part under consideration of the size-reduction (considering large modules like API-Management, Storage Account, etc.) and the complexity of re-implementing the required features yourself. The good news: For the latter you can cherry-pick the parts of the AVM template you need.

Probably the most uncomfortable option. If you cannot deploy your solution in one go, it may make sense to split it into logical chunks that you can deploy separately and optionally in sequence (e.g., in your workflow).

This approach comes with a few drawbacks such as the potentially longer deployment time and less intuitive resolution of interdependencies. In other words, if many of your module deployments use each other’s outputs and you split them into multiple templates, you’d need to create ’existing’ references in the later deployments to get the same outputs.

For example, splitting the following two resources

module acr 'br/public:avm/res/container-registry/registry:0.9.3' = {
  params: {
    name: 'myContainerRegistry'
  }
}

module key 'br/public:avm/res/key-vault/vault/key:0.1.0'= {
  params: {
    name: 'myKey'
    keyVaultName: 'keyVaultName'
    roleAssignments: [
      {
        principalId: acr.outputs.systemAssignedMIPrincipalId!
        roleDefinitionIdOrName: 'Key Vault Crypto Service Encryption User'
      }
    ]
  }
}

in two templates requires you to either add an output for the first resource’s identity to the first template and pass it to the second, or create an existing reference in the second template akin to

resource acr 'Microsoft.ContainerRegistry/registries@2025-04-01' existing = {
  name: 'myContainerRegistry'
}

module key 'br/public:avm/res/key-vault/vault/key:0.1.0'= {
  params: {
    name: 'myKey'
    keyVaultName: 'keyVaultName'
    roleAssignments: [
      {
        principalId: acr.identity.principalId
        roleDefinitionIdOrName: 'Key Vault Crypto Service Encryption User'
      }
    ]
  }
}