|
| 1 | +--- |
| 2 | +description: 'Azure Verified Modules (AVM) and Bicep' |
| 3 | +applyTo: '**/*.bicep, **/*.bicepparam' |
| 4 | +--- |
| 5 | + |
| 6 | +# Azure Verified Modules (AVM) Bicep |
| 7 | + |
| 8 | +## Overview |
| 9 | + |
| 10 | +Azure Verified Modules (AVM) are pre-built, tested, and validated Bicep modules that follow Azure best practices. Use these modules to create, update, or review Azure Infrastructure as Code (IaC) with confidence. |
| 11 | + |
| 12 | +## Module Discovery |
| 13 | + |
| 14 | +### Bicep Public Registry |
| 15 | + |
| 16 | +- Search for modules: `br/public:avm/res/{service}/{resource}:{version}` |
| 17 | +- Browse available modules: `https://github.com/Azure/bicep-registry-modules/tree/main/avm/res` |
| 18 | +- Example: `br/public:avm/res/storage/storage-account:0.30.0` |
| 19 | + |
| 20 | +### Official AVM Index |
| 21 | + |
| 22 | +- **Bicep Resource Modules**: `https://raw.githubusercontent.com/Azure/Azure-Verified-Modules/refs/heads/main/docs/static/module-indexes/BicepResourceModules.csv` |
| 23 | +- **Bicep Pattern Modules**: `https://raw.githubusercontent.com/Azure/Azure-Verified-Modules/refs/heads/main/docs/static/module-indexes/BicepPatternModules.csv` |
| 24 | + |
| 25 | +### Module Documentation |
| 26 | + |
| 27 | +- **GitHub Repository**: `https://github.com/Azure/bicep-registry-modules/tree/main/avm/res/{service}/{resource}` |
| 28 | +- **README**: Each module contains comprehensive documentation with examples |
| 29 | + |
| 30 | +## Module Usage |
| 31 | + |
| 32 | +### From Examples |
| 33 | + |
| 34 | +1. Review module README in `https://github.com/Azure/bicep-registry-modules/tree/main/avm/res/{service}/{resource}` |
| 35 | +2. Copy example code from module documentation |
| 36 | +3. Reference module using `br/public:avm/res/{service}/{resource}:{version}` |
| 37 | +4. Configure required and optional parameters |
| 38 | + |
| 39 | +### Example Usage |
| 40 | + |
| 41 | +```bicep |
| 42 | +module storageAccount 'br/public:avm/res/storage/storage-account:0.30.0' = { |
| 43 | + name: 'storage-account-deployment' |
| 44 | + scope: resourceGroup() |
| 45 | + params: { |
| 46 | + name: storageAccountName |
| 47 | + location: location |
| 48 | + skuName: 'Standard_LRS' |
| 49 | + tags: tags |
| 50 | + } |
| 51 | +} |
| 52 | +``` |
| 53 | + |
| 54 | +### When AVM Module Not Available |
| 55 | + |
| 56 | +If no AVM module exists for a resource type, use native Bicep resource declarations with latest stable API version. |
| 57 | + |
| 58 | +## Naming Conventions |
| 59 | + |
| 60 | +### Module References |
| 61 | + |
| 62 | +- **Resource Modules**: `br/public:avm/res/{service}/{resource}:{version}` |
| 63 | +- **Pattern Modules**: `br/public:avm/ptn/{pattern}:{version}` |
| 64 | +- Example: `br/public:avm/res/network/virtual-network:0.7.2` |
| 65 | + |
| 66 | +### Symbolic Names |
| 67 | + |
| 68 | +- Use lowerCamelCase for all names (variables, parameters, resources, modules) |
| 69 | +- Use resource type descriptive names (e.g., `storageAccount` not `storageAccountName`) |
| 70 | +- Avoid 'name' suffix in symbolic names as they represent the resource, not the resource's name |
| 71 | +- Avoid distinguishing variables and parameters by suffixes |
| 72 | + |
| 73 | +## Version Management |
| 74 | + |
| 75 | +### Version Pinning Best Practices |
| 76 | + |
| 77 | +- Always pin to specific module versions: `:{version}` |
| 78 | +- Use semantic versioning (e.g., `:0.30.0`) |
| 79 | +- Review module changelog before upgrading |
| 80 | +- Test version upgrades in non-production environments first |
| 81 | + |
| 82 | +## Development Best Practices |
| 83 | + |
| 84 | +### Module Discovery and Usage |
| 85 | + |
| 86 | +- ✅ **Always** check for existing AVM modules before creating raw resources |
| 87 | +- ✅ **Review** module documentation and examples before implementation |
| 88 | +- ✅ **Pin** module versions explicitly |
| 89 | +- ✅ **Use** types from modules when available (import types from module) |
| 90 | +- ✅ **Prefer** AVM modules over raw resource declarations |
| 91 | + |
| 92 | +### Code Structure |
| 93 | + |
| 94 | +- ✅ **Declare** parameters at top of file with `@sys.description()` decorators |
| 95 | +- ✅ **Specify** `@minLength()` and `@maxLength()` for naming parameters |
| 96 | +- ✅ **Use** `@allowed()` decorator sparingly to avoid blocking valid deployments |
| 97 | +- ✅ **Set** default values safe for test environments (low-cost SKUs) |
| 98 | +- ✅ **Use** variables for complex expressions instead of embedding in resource properties |
| 99 | +- ✅ **Leverage** `loadJsonContent()` for external configuration files |
| 100 | + |
| 101 | +### Resource References |
| 102 | + |
| 103 | +- ✅ **Use** symbolic names for references (e.g., `storageAccount.id`) not `reference()` or `resourceId()` |
| 104 | +- ✅ **Create** dependencies through symbolic names, not explicit `dependsOn` |
| 105 | +- ✅ **Use** `existing` keyword for accessing properties from other resources |
| 106 | +- ✅ **Access** module outputs via dot notation (e.g., `storageAccount.outputs.resourceId`) |
| 107 | + |
| 108 | +### Resource Naming |
| 109 | + |
| 110 | +- ✅ **Use** `uniqueString()` with meaningful prefixes for unique names |
| 111 | +- ✅ **Add** prefixes since some resources don't allow names starting with numbers |
| 112 | +- ✅ **Respect** resource-specific naming constraints (length, characters) |
| 113 | + |
| 114 | +### Child Resources |
| 115 | + |
| 116 | +- ✅ **Avoid** excessive nesting of child resources |
| 117 | +- ✅ **Use** `parent` property or nesting instead of constructing names manually |
| 118 | + |
| 119 | +### Security |
| 120 | + |
| 121 | +- ❌ **Never** include secrets or keys in outputs |
| 122 | +- ✅ **Use** resource properties directly in outputs (e.g., `storageAccount.outputs.primaryBlobEndpoint`) |
| 123 | +- ✅ **Enable** managed identities where possible |
| 124 | +- ✅ **Disable** public access when network isolation is enabled |
| 125 | + |
| 126 | +### Types |
| 127 | + |
| 128 | +- ✅ **Import** types from modules when available: `import { deploymentType } from './module.bicep'` |
| 129 | +- ✅ **Use** user-defined types for complex parameter structures |
| 130 | +- ✅ **Leverage** type inference for variables |
| 131 | + |
| 132 | +### Documentation |
| 133 | + |
| 134 | +- ✅ **Include** helpful `//` comments for complex logic |
| 135 | +- ✅ **Use** `@sys.description()` on all parameters with clear explanations |
| 136 | +- ✅ **Document** non-obvious design decisions |
| 137 | + |
| 138 | +## Validation Requirements |
| 139 | + |
| 140 | +### Build Validation (MANDATORY) |
| 141 | + |
| 142 | +After any changes to Bicep files, run the following commands to ensure all files build successfully: |
| 143 | + |
| 144 | +```shell |
| 145 | +# Ensure Bicep CLI is up to date |
| 146 | +az bicep upgrade |
| 147 | + |
| 148 | +# Build and validate changed Bicep files |
| 149 | +az bicep build --file main.bicep |
| 150 | +``` |
| 151 | + |
| 152 | +### Bicep Parameter Files |
| 153 | + |
| 154 | +- ✅ **Always** update accompanying `*.bicepparam` files when modifying `*.bicep` files |
| 155 | +- ✅ **Validate** parameter files match current parameter definitions |
| 156 | +- ✅ **Test** deployments with parameter files before committing |
| 157 | + |
| 158 | +## Tool Integration |
| 159 | + |
| 160 | +### Use Available Tools |
| 161 | + |
| 162 | +- **Schema Information**: Use `azure_get_schema_for_Bicep` for resource schemas |
| 163 | +- **Deployment Guidance**: Use `azure_get_deployment_best_practices` tool |
| 164 | +- **Service Documentation**: Use `microsoft.docs.mcp` for Azure service-specific guidance |
| 165 | + |
| 166 | +### GitHub Copilot Integration |
| 167 | + |
| 168 | +When working with Bicep: |
| 169 | + |
| 170 | +1. Check for existing AVM modules before creating resources |
| 171 | +2. Use official module examples as starting points |
| 172 | +3. Run `az bicep build` after all changes |
| 173 | +4. Update accompanying `.bicepparam` files |
| 174 | +5. Document customizations or deviations from examples |
| 175 | + |
| 176 | +## Troubleshooting |
| 177 | + |
| 178 | +### Common Issues |
| 179 | + |
| 180 | +1. **Module Version**: Always specify exact version in module reference |
| 181 | +2. **Missing Dependencies**: Ensure resources are created before dependent modules |
| 182 | +3. **Validation Failures**: Run `az bicep build` to identify syntax/type errors |
| 183 | +4. **Parameter Files**: Ensure `.bicepparam` files are updated when parameters change |
| 184 | + |
| 185 | +### Support Resources |
| 186 | + |
| 187 | +- **AVM Documentation**: `https://azure.github.io/Azure-Verified-Modules/` |
| 188 | +- **Bicep Registry**: `https://github.com/Azure/bicep-registry-modules` |
| 189 | +- **Bicep Documentation**: `https://learn.microsoft.com/azure/azure-resource-manager/bicep/` |
| 190 | +- **Best Practices**: `https://learn.microsoft.com/azure/azure-resource-manager/bicep/best-practices` |
| 191 | + |
| 192 | +## Compliance Checklist |
| 193 | + |
| 194 | +Before submitting any Bicep code: |
| 195 | + |
| 196 | +- [ ] AVM modules used where available |
| 197 | +- [ ] Module versions are pinned |
| 198 | +- [ ] Code builds successfully (`az bicep build`) |
| 199 | +- [ ] Accompanying `.bicepparam` files updated |
| 200 | +- [ ] `@sys.description()` on all parameters |
| 201 | +- [ ] Symbolic names used for references |
| 202 | +- [ ] No secrets in outputs |
| 203 | +- [ ] Types imported/defined where appropriate |
| 204 | +- [ ] Comments added for complex logic |
| 205 | +- [ ] Follows lowerCamelCase naming convention |
0 commit comments