Azure / Azure/bicep

Proposal - Option to embed a module reference instead of inlining the nested deployment

Open
#11,899 2 comments 4 reactions 0 assignees View on GitHub
discussion enhancement proposal
Dominant language
Bicep
Stars
3.6k
Forks
830
Avg merge
1d 21m
Merged PRs (30d)
79

Description

## Problem Statement
Registry modules in Bicep are very popular for code reuse, but with a complex deployment hierarchy, they can often cause the size of the template to grow quickly. This increases the likelihood of running into the dreaded [maximum template size error](https://learn.microsoft.com/en-us/azure/azure-resource-manager/templates/best-practices#template-limits), which has no workaround.

## Possible Solution
Similar to the way Template Specs are handled, provide an option to embed a link to the registry module instead of the module itself.

For example, for the following:
```bicep
module mcrModule 'br/public:samples/hello-world:1.0.1' = {
...
}
```

Instead of generating:
```json
"template": {
...embedded registry content
}
```

We could generate:
```json
"templateLink": {
"ref": "mcr.microsoft.com/bicep/samples/hello-world:1.0.1"
}
```

This would require giving the Deployment engine the ability to pull down modules on behalf of the user.

## Notes
- The editor experience and validation for consuming a module should be no different to today's experience (other than possibly the ability to opt-in/out of the behavior).
- OCI artifacts are technically mutable, even if generally users avoid re-publishing with the same tag. We may want to give users the ability to fail a deployment if that happens (for example, embedding a content hash and failing at runtime the hash doesn't match).

Contributor guide

Open the contributing guide

Research direction

Start by reviewing how Bicep registry modules are currently embedded in generated ARM templates and how Template Specs use templateLink references. Define the opt-in behavior, deployment-engine requirements, and handling of mutable OCI tags or content hashes. Done means nested registry modules can be referenced without inlining while preserving validation and editor behavior.

Written by the indexing model from the issue text.

Assessment

Tech stack
azure
Domain
cloud, infrastructure
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
28/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.