In most Infrastructure as Code teams, Bicep quality checks start to look mature as soon as linting and deployment validation are in place. In practice, there is still a blind spot: logic-level testing of exported functions, types, and variables.

Most teams validate by deploying to a subscription and checking outcomes afterwards. That is useful, but it is also slow and expensive when what you actually want to verify is pure logic. A shared Bicep library changes, everything still compiles, and then a downstream module fails later in a deployment pipeline because a naming function or constructor behaviour subtly changed. That is exactly the type of issue we normally catch early in application development with unit tests.

If you maintain shared Bicep libraries, this gap hurts quickly:

• Naming functions drift without anyone noticing
• Type constructors change and break downstream modules
• Refactors feel risky because feedback loops are too long

I wanted a way to unit test Bicep logic directly, without deploying anything.

Introducing BicepConsoleTTK

To solve that problem, I created BicepConsoleTTK (Bicep Console Test Tool Kit).

It is a Pester-based framework that executes Bicep expressions through the Bicep console REPL, so you can assert outputs in fast, repeatable unit tests.

Repository:

At a high level, the toolkit gives you two commands:

• Import-Bicep: reads one or more Bicep files and extracts the exports you ask for
• Invoke-BicepExpression: runs those declarations plus your expression in bicep console and returns the result

Why This Approach Works

This lets you test Bicep logic in isolation, before template deployment.

Practical outcomes:

• Faster feedback during development
• More confidence when refactoring shared functions
• Cleaner CI pipelines for template libraries
• Better separation between unit tests (logic) and integration tests (deployment)

Features

• Familiar import syntax (named imports and wildcard imports)
• Multi-file import composition with preserved order
• Deduplication when the same member is imported multiple ways
• Setup declarations for multi-step scenarios
• Pipeline input support
• Cleaner Bicep console error reporting
• CI/CD-friendly, non-interactive execution

Prerequisites

• PowerShell 5.1 (Desktop) or 7+
• Pester 5.x
• Bicep CLI 0.42.1+
• bicep available on your PATH

Installation

From PowerShell Gallery

Install-Module -Name BicepConsoleTTK -Repository PSGallery

In your test file:

BeforeAll {
	Import-Module BicepConsoleTTK -Force
}

From Source

git clone https://github.com/Andrew-D-Wilson/bicep-console-test-framework.git
Import-Module "$PSScriptRoot/../src/BicepConsoleTTK" -Force

Copilot Integration

This repository ships two complementary artefacts that teach GitHub Copilot how to write BicepConsoleTTK tests.

Agent Skill (Recommended)

The .github/skills/bicepconsolettk/SKILL.md file is a GitHub Copilot agent skill. When Copilot is working in agent mode, it automatically loads this skill whenever the task is related to writing Bicep tests, injecting the full authoring guide into its context.

The skill is discovered automatically from .github/skills/ in any repository that contains it.

VS Code Instructions File

The bicepconsolettk.instructions.md file is a VS Code Copilot custom instructions file.

To use it in your own repository:

1. Copy the file to .github/instructions/bicepconsolettk.instructions.md
2. Keep applyTo: "**/*.Tests.ps1" so it is scoped to Pester test files
3. Ask Copilot to generate or refactor tests in your *.Tests.ps1 files

With both artefacts in place, Copilot gets better guidance in both agent-driven workflows and editor-scoped instruction workflows.

Usage

1. Import exports from Bicep files

$imports = Import-Bicep @(
	"import {coreParams, newCoreParams} from '$PSScriptRoot/../shared/Types.bicep'",
	"import {basicResource}             from '$PSScriptRoot/../shared/NamingFunctions.bicep'"
)

2. Evaluate an expression

$result = Invoke-BicepExpression -b $imports -e "newCoreParams('uksouth', 'uks', 'prod', 'myapp')"

3. Use setup declarations when needed

$setupDeclarations = @(
	"var projectNameStart = 'hello'",
	"var projectNameComplete = '`${projectNameStart}world'",
	"var coreParameters coreParams = newCoreParams('uksouth', 'uks', 'dev', projectNameComplete)"
)

$result = Invoke-BicepExpression -b $imports -s $setupDeclarations -e "basicResource('aks', coreParameters)"

Example Pester Test

BeforeAll {
	Import-Module BicepConsoleTTK -Force
}

Describe "Naming Functions" {
	BeforeAll {
		$script:imports = Import-Bicep @(
			"import {coreParams, newCoreParams} from '$PSScriptRoot/../shared/Types.bicep'",
			"import {basicResource, csResource} from '$PSScriptRoot/../shared/NamingFunctions.bicep'"
		)
	}

	It "basicResource includes abbreviation, project, environment and location" {
		$result = Invoke-BicepExpression -b $script:imports `
			-e "basicResource('aks', newCoreParams('uksouth', 'uks', 'dev', 'myapp'))"

		$result | Should -Be "'aks-myapp-dev-uksouth'"
	}
}

Run tests with:

Invoke-Pester -Path ./tests

How It Works (Short Version)

Import-Bicep parses import strings, resolves file paths, and extracts exported declarations from source files.

Invoke-BicepExpression sends those declarations and your expression into bicep console, captures output, and translates console noise into readable exceptions when failures occur.

That gives you deterministic, fast unit tests focused on logic instead of deployment orchestration.

Where This Fits in Your Testing Strategy

Use BicepConsoleTTK for:

• Function output verification
• Naming convention enforcement
• Shared type constructor validation
• Regression checks during refactoring

Still keep deployment/integration tests for:

• Resource runtime behavior
• Policy and RBAC interactions
• End-to-end environment validation

Both layers matter. This tool improves the unit-testing layer.

In Short

BicepConsoleTTK helps you test Bicep exports the same way you test application code: quickly, repeatedly, and early.

If your team relies on shared Bicep libraries, this can remove a lot of friction from your delivery pipeline while increasing confidence in every change.

⚠️ NOTE

Microsoft guidance is clear that Azure RBAC should be used for data plane authorization moving forward, instead of legacy access policies

• Azure role-based access control (Azure RBAC) vs. access policies (legacy)
• Provide access to Key Vault keys, certificates, and secrets with Azure role-based access control

Problem Space

When multiple applications share a single Azure Key Vault, access policy management can become an unexpected source of deployment risk → and the root cause is easy to miss.

// BICEP
resource KeyVaultDeploy 'Microsoft.KeyVault/vaults@2025-05-01' = {
  name: ''
  location: ''
  properties: {
    ...
    accessPolicies: []
    ...
  }
}

The accessPolicies property on the Microsoft.KeyVault/vaults ARM resource is a required field. In a shared Key Vault scenario, where the vault is owned and deployed by one application, the natural thing to do is set this to an empty array as the application does not own the other applications access policies, so it does not declare them.

This is where the problem begins.

When ARM deploys the Key Vault resource with accessPolicies set to an empty array [], it treats that as the desired state for the vault. Any access policies that existed previously (including those belonging to other applications) are removed.

Here is how the failure pattern plays out in practice:

1. Application A owns the Key Vault and deploys it with accessPolicies: [].
2. Immediately after, Application A’s IaC deploys its own access policies via a separate step (for example, using the Microsoft.KeyVault/vaults/accessPolicies child resource). Access is restored for Application A without apparent issue.
3. Application B’s access policies have been silently removed — it never re-deploys the key vault, only its own access policy step.
4. Application B fails at runtime when attempting secret, key, or certificate operations — authorization errors with no obvious cause.
5. Application B is re-deployed, its access policies are restored, and both applications work again — until the next time Application A’s pipeline runs.

This cycle repeats silently. Each Application A deployment is an outage for Application B, and the connection between the two is not obvious unless you know to look for it.

This can happen if you have the following setup:

• Multiple applications or pipelines sharing a Key Vault
• The Key Vault instance deployed as part of one application’s IaC
• Access configured through Key Vault access policies
• Each application’s pipeline independently managing only its own policy entries

Workarounds (Still Using Access Policies)

If moving to RBAC immediately is not possible, the following workarounds address the underlying coupling problem — but each comes with trade-offs.

1. Move the Key Vault to a Core Resources Deployment

Extract the Key Vault resource into a dedicated core infrastructure deployment, separate from any application pipeline. Application pipelines then only manage their own access policy entries against the pre-existing vault.

Benefits:

• The vault is no longer redeployed as part of application changes
• Eliminates the empty accessPolicies overwrite problem
• Makes ownership of the shared resource explicit

Trade-off:

• When the core resources deployment runs (for environment rebuilds, configuration changes, or disaster recovery), all dependent applications will need to be re-deployed afterwards to restore their access policy entries. This creates an operational dependency that must be planned for and communicated clearly across teams.

2. Provision a Separate Key Vault Per Application

Give each application its own dedicated Key Vault, eliminating the shared resource entirely.

Benefits:

• No cross-application policy coupling — each key vault is fully owned by one application
• Reduces blast radius of deployment mistakes
• Cleaner isolation and tenancy boundaries

Trade-offs:

• More key vaults to provision, monitor, rotate secrets in, and govern
• Increases operational overhead for certificate and secret lifecycle management
• Harder to get a unified view of secrets across the estate

This option improves isolation but does not solve the root-cause pattern; it just limits the blast radius per key vault.

The Real Solution: Move to Azure RBAC

The correct long-term fix is to stop using access policies for Key Vault data plane authorization entirely and adopt Azure RBAC role assignments.

With RBAC:

• Role assignments are additive and independently managed — assigning a role for Application B does not affect Application A’s assignments
• Authorization state is managed through Azure’s centralized RBAC model, consistent with the rest of the Azure platform
• Microsoft explicitly recommends RBAC over access policies for new and migrating workloads

The deployment pattern becomes:

1. Deploy the Key Vault resource. The accessPolicies field becomes irrelevant.
2. Each application independently deploys Microsoft.Authorization/roleAssignments scoped to the vault for its own managed identity or service principal.
3. An application deployment wont affect another application’s authorization.
4. A redeploy of the Key Vault resource won’t remove existing application’s authorizations.

Practical migration approach:

1. Enable the RBAC permission model on the Key Vault IaC (enableRbacAuthorization: true).
2. Map existing access policy permissions to the appropriate built-in Key Vault RBAC roles (for example Key Vault Secrets User, Key Vault Certificates User).
   • Assign roles to the required identities at the appropriate scope (Key Vault, Key Vault Secret/Certificate).
3. Remove legacy access policy configuration from all IaC templates.
4. Deploy IaC and Validate application behavior against the new authorization model.

Useful Microsoft documentation:

• RBAC vs access policy comparison and recommendation
• RBAC implementation guidance for Key Vault

Closing Thoughts

The empty accessPolicies: [] pattern is easy to arrive at — the field is required, the application does not own the other policies, so an empty array seems reasonable. In a single-application setup it causes no problems. In a shared-vault, multi-application setup it causes silent, repeating outages that are hard to diagnose without knowing where to look.

The workarounds described here reduce the risk while a migration is planned, but neither fully resolves the underlying problem.

The right answer is Azure RBAC. Role assignments are independent, additive, and do not interfere with each other across application boundaries. Moving to RBAC removes this class of problem entirely.

As Bicep adoption grows, so does the complexity of the environments and teams using it. Without clear authoring practices, Bicep codebases can quickly become inconsistent, hard to maintain, and error-prone. In this post I wanted to share some practical authoring practices and anti-patterns to help you and your team write better Bicep code.

Why Define and Stick to Your Authoring Practices

Defining and following authoring practices ensures:

• Consistency across your codebase and team
• Easier onboarding for new contributors
• Fewer errors and less technical debt
• Improved maintainability and clarity

Below are some key practices and common anti-patterns to consider.

Authoring Practices

1. Folder Structure

Organise your Bicep files in a logical folder structure. For example, group modules by resource type or deployment context. This makes navigation and reuse easier:

├── modules/
│   ├── storage/
│   └── networking/
├── main.bicep
├── parameters/

2. Template Structure

Keep your templates clean and modular. Use modules for reusable components, and keep your main entry point focused on orchestration. Avoid putting everything in a single file.

3. Well Defined Names

Use clear, descriptive names for resources, parameters, and variables. Avoid abbreviations that aren’t widely understood. For example, prefer storageAccountName over saName.

4. Descriptions

Add descriptions to parameters, outputs, and resources. This helps users understand intent and usage:

@description('Configurable name for the application storage account')
param storageAccountName string

5. Comments

Use comments to explain why something is done, not what is done. Avoid echoing the code. Good comments provide context or rationale.

6. Constraints and Metadata

Leverage allowed values, min/max length, and metadata to enforce constraints and provide guidance:

@minLength(3)
@maxLength(24)
@allowed([ 'dev' 'test' 'prod' ])
param environment string

Make sure to use these where there is a specific need, over constraining parameters can equally cause issues.

7. Contracts

Define clear contracts for your modules: what parameters are required, what outputs are provided, and what assumptions are made. Document these in the module and in a README.

8. README

Modules and major orchestrating templates should have a README explaining its purpose and usage. This is invaluable for onboarding and reuse.

9. Bicep Linting

Use Bicep linting as part of your authoring workflow to catch issues early and enforce consistency. Define team linting rules in bicepconfig.json, run lint checks locally during development, and enforce them in CI to prevent low-quality or non-compliant templates from being merged.

10. AI-Generated Templates and Conformance

If you are using AI to generate Bicep, treat your authoring practices as executable guardrails rather than optional guidance.

Start by defining a clear generation contract in your prompt and repository standards:

• Require a specific folder structure and file naming convention
• Require module contracts (documented params/outputs and assumptions)
• Require descriptions, meaningful names, and no dead code
• Require lint-clean output before a template is considered complete

Then enforce conformance automatically in CI:

• Validate formatting and linting on every pull request
• Fail builds when lint rules are violated
• Optionally add policy checks (for example, naming, locations, and SKUs)
• Require human review for architectural decisions, not just syntax correctness

Finally, use a feedback loop. When reviewers find repeated AI mistakes, update your prompt template, lint configuration, and module examples so the next generation cycle improves by default.

Anti-Patterns

1. Premature Abstraction

Don’t create modules or abstractions before you have a real need. Over-abstraction leads to unnecessary complexity and maintenance overhead.

2. Over-Specification

Avoid making every resource parameter configurable if it’s not needed. Too many parameters can confuse users and make templates harder to use.

3. Echo Comments

Comments that simply restate the code add no value. For example:

// Set the storage account name
param storageAccountName string

Instead, explain why a value is needed or any constraints.

4. Dead Code

Remove unused parameters, variables, and resources. Dead code clutters templates and can cause confusion or errors.

5. Generic Copy-Paste Documentation

Avoid boilerplate documentation that doesn’t reflect the actual template. Tailor docs and comments to the specific module or resource.

6. Poorly Defined Names

Names like var1 or resource2 make templates hard to understand. Use meaningful, descriptive names everywhere.

Conclusion

Establishing and following authoring practices for Bicep will help your team deliver infrastructure as code that is robust, maintainable, and easy to understand. Avoid common anti-patterns, and invest in clarity and documentation.

There have been few times where I have landed into this particular predicament whereby either by my own doing or through the use of another’s code base, a deep nested or thoroughly utilised (parameter/variable/or other defined item) has been created with the same name as a Bicep function. As by Murphy’s law, its only once you have reached this point of no return that you realise that your items name conflicts.

Now if you are like many in your unawares, your thoughts and actions will conclude to a singular one of ’that sucks… followed by a nasty refactor'.

Solution - Namespaces

Namespaces are a declarative scope in which identifiers such as the names of types, functions, and variables can be declared. These namespaces are used to organise code into logical groups and to prevent name collisions such as the one you are currently experiencing.

Thankfully, in Bicep there are two namespaces where all functions are split, az and sys.

• az | Contains functions that are specific to an Azure deployment such as:
  • deployment
  • environment
  • resourceGroup
  • subscription
• sys | Contains functions that are used to construct values, and decorators for parameters and resource loops. This includes but is not limited to:
  • [Array] concat
  • [File] loadJsonContent
  • [Lambda] filter
  • [Logical] bool
  • [Numeric] int
  • [String] contains

To make use of these namespaces, simply add the namespace identifier in front of the function. The example below shows a real world example of this issue where a parameter name ‘environment’ has been extensively utilised in this template and many others. This particular template is being used to deploy an AuthProvider in API Management, and the author wishes to utilise the environment function for the authentication.loginEndpoint. Without the use of the az namespace, the environment parameter would need to be refactored both in this template and wider templates for consistency.

/******************************************
Bicep Template: Function Namespace Example
Author: Andrew Wilson
******************************************/

targetScope = 'resourceGroup'

// ** Parameters **
// ****************

@description('The environment to deploy the resources to.')
@allowed([
  'dev'
  'test'
  'prod'
])
param environment string = 'dev'

...

// ** Resources **
// ***************

...

// Create a new Auth Provider in APIM Credential Manager
resource AuthorizationProvider 'Microsoft.ApiManagement/service/authorizationProviders@2024-05-01' = {
  ...
  properties: {
    ...
    oauth2: {
      ...
      grantTypes: {
        clientCredentials: {
          loginUri: az.environment().authentication.loginEndpoint
        }
      }
    }
  }
}

As always, have a play, and happy Bicep-ing!

Building on our previous exploration of Typed Variables, today we’re diving into one of my favorite patterns for creating maintainable and reusable Bicep templates: the Shared Variable File Pattern. This approach transforms your templates from being tightly coupled to specific configurations into truly agnostic, environment-ready solutions.

The beauty of this pattern lies in its simplicity - by extracting configuration data into external JSON or YAML files, you can create templates that adapt without modification. When combined with typed variables, this approach becomes even more powerful, providing compile-time validation and enhanced developer experience.

Why Use Config Files?

Before diving into the implementation, let’s understand why this pattern is so valuable:

1. Separation of Concerns: Keep your infrastructure logic separate from configuration data
2. Reduced Template Complexity: Remove large, complex variable definitions from your templates for better readability
3. Reusability: Share common configurations across multiple templates without duplication
4. Team Collaboration: Non-technical team members can modify configurations without touching Bicep code

The Pattern in Action

Traditional Approach (What We Want to Avoid)

Traditionally, you might embed all configuration directly in your Bicep template:

var nsgRules = [
  {
    name: 'AllowManagementEndpoint'
    properties: {
      description: 'Management endpoint for Azure portal and PowerShell'
      sourceAddressPrefix: 'ApiManagement'
      sourcePortRange: '*'
      destinationAddressPrefix: 'VirtualNetwork'
      destinationPortRange: '3443'
      protocol: 'Tcp'
      access: 'Allow'
      priority: 100
      direction: 'Inbound'
    }
  }
  {
    name: 'AllowAzureInfrastructureLoadBalancer'
    properties: {
      description: 'Azure Infrastructure Load Balancer'
      sourceAddressPrefix: 'AzureLoadBalancer'
      sourcePortRange: '*'
      destinationAddressPrefix: 'VirtualNetwork'
      destinationPortRange: '6390'
      protocol: 'Tcp'
      access: 'Allow'
      priority: 110
      direction: 'Inbound'
    }
  }
  // ... many more rules
]

This approach has several downsides:

• Templates become bloated and hard to read
• Changes require modifying Bicep code
• No separation between infrastructure logic and configuration data

Modern Approach with Config Files

Let’s transform this using the shared variable file pattern combined with typed variables.

Step 1: Create Your Config File

Create the configuration file for your deployment:

configs/nsg-rules.json

{
  "securityRules": [
    {
      "name": "AllowManagementEndpoint",
      "properties": {
        "description": "Management endpoint for Azure portal and PowerShell",
        "sourceAddressPrefix": "ApiManagement",
        "sourcePortRange": "*",
        "destinationAddressPrefix": "VirtualNetwork",
        "destinationPortRange": "3443",
        "protocol": "Tcp",
        "access": "Allow",
        "priority": 100,
        "direction": "Inbound"
      }
    },
    {
      "name": "AllowDeveloperAccess",
      "properties": {
        "description": "Allow developer access from corporate network",
        "sourceAddressPrefix": "10.0.0.0/8",
        "sourcePortRange": "*",
        "destinationAddressPrefix": "VirtualNetwork",
        "destinationPortRange": "443",
        "protocol": "Tcp",
        "access": "Allow",
        "priority": 200,
        "direction": "Inbound"
      }
    }
  ]
}

Step 2: Define Typed Variables

Create a user-defined type to ensure your config files match the expected structure:

// User-Defined Types
// ******************

@sealed()
@description('Defines the structure for NSG security rule properties.')
type nsgSecurityRuleProperties = {
  @description('Description of the security rule.')
  description: string
  @description('Source address prefix or tag.')
  sourceAddressPrefix: string
  @description('Source port range.')
  sourcePortRange: string
  @description('Destination address prefix or tag.')
  destinationAddressPrefix: string
  @description('Destination port range.')
  destinationPortRange: string
  @description('Network protocol (Tcp, Udp, or *).')
  protocol: 'Tcp' | 'Udp' | '*'
  @description('Access type (Allow or Deny).')
  access: 'Allow' | 'Deny'
  @description('Priority value (100-4096).')
  priority: int
  @description('Direction (Inbound or Outbound).')
  direction: 'Inbound' | 'Outbound'
}

@sealed()
@description('Defines the structure for NSG security rule.')
type nsgSecurityRule = {
  @description('Name of the security rule.')
  name: string
  @description('Properties of the security rule.')
  properties: nsgSecurityRuleProperties
}

@sealed()
@description('Defines the structure for NSG configuration file.')
type nsgConfig = {
  @description('Array of security rules.')
  securityRules: nsgSecurityRule[]
}

Step 3: Load and Use Configuration

Now your Bicep template becomes clean and agnostic:

// Parameters
// **********

@description('Environment to deploy to.')
param environment string

// Variables
// *********

// Load configuration with full type safety
var nsgConf nsgConfig = loadJsonContent('./configs/nsg-rules.json')

// Resources
// *********

resource networkSecurityGroup 'Microsoft.Network/networkSecurityGroups@2024-01-01' = {
  name: 'nsg-apim'
  location: resourceGroup().location
  properties: {
    securityRules: nsgConfig.securityRules
  }
}

Advanced Techniques

Multi-Component Configuration Files

You can organise multiple configuration aspects in a single file and load only what you need:

configs/apim-config.json

{
  "networking": {
    "securityRules": [...],
    "subnets": [...]
  },
  "apim": {
    "sku": {
      "name": "Developer",
      "capacity": 1
    },
    "policies": [...]
  },
  "monitoring": {
    "logAnalytics": {...},
    "alerts": [...]
  }
}

Load specific sections using JSONPath:

// Load only the networking configuration
var networkingConfig = loadJsonContent('./configs/apim-config.json', 'networking')

// Load only the APIM configuration
var apimConfig = loadJsonContent('./configs/apim-config.json', 'apim')

Best Practices

1. Use Typed Variables: Define user-defined types for your configuration structures - this provides compile-time validation and excellent IntelliSense support
2. Logical File Organisation: Create separate config files for different aspects (networking, security, monitoring) rather than one monolithic file
3. Validate Early: Let typed variables catch configuration mismatches during authoring, not deployment
4. Size Considerations: Remember that loaded content is included in the generated ARM template (4MB limit)
5. Version Control: Keep config files in source control alongside your Bicep templates

Real-World Benefits

This pattern has transformed how I approach Bicep development:

• Faster Development: IntelliSense support with typed variables makes configuration editing a breeze
• Fewer Deployment Failures: Compile-time validation catches configuration errors before deployment
• Better Team Collaboration: Operations teams can modify configs without touching infrastructure code
• Easier Maintenance: Changes to configuration don’t require Bicep code modifications

Summary

The shared variable file pattern, enhanced with typed variables, creates a powerful combination for building maintainable, agnostic Bicep templates. By separating configuration from infrastructure logic, you gain flexibility, reusability, and compile-time safety that makes your Infrastructure as Code truly robust. Happy Bicep-ing!

One of my core goals when writing IaC templates is ensuring reusability of common components, resources, and in this case, configuration. More often than not, I see configuration that is broadly common between resources (except for one or two properties) being duplicated throughout templates. This duplication means that changing a single property value requires updates across the entire codebase—a change that’s not trivial to manage unless you’re well-versed with the codebase and understand all areas where the configuration is implemented.

This pattern becomes particularly problematic as your infrastructure grows in complexity. Consider scenarios where you need to update a common tag value, modify a naming convention, or adjust a configuration parameter across dozens of resources. Without proper abstraction, these seemingly simple changes can become error-prone maintenance nightmares.

In this post, I’ll demonstrate two powerful Bicep techniques to transform static, duplicated configuration into dynamic, reusable patterns that will make your templates more maintainable and less prone to configuration drift.

Common Configuration Scenarios

Before diving into solutions, let’s examine two common scenarios where static configuration creates maintenance headaches:

Scenario 1: Resource Tagging

Every Azure resource should be properly tagged for governance, cost tracking, and management. However, I frequently see templates where tags are copy-pasted across resources, creating maintenance debt:

resource storageAccount 'Microsoft.Storage/storageAccounts@2025-01-01' = {
  // ... other properties
  tags: {
    BusinessUnit: 'BicepTipsAndTricks'
    Version: deployment().properties.template.contentVersion
    Environment: environment
    Region: region
    ResourceName: 'Storage Account'
    'hidden-title': 'Bicep Tips and Tricks Storage'
  }
  // ... other properties
}

This approach works for a single resource, but imagine maintaining this across 50+ resources. When the business unit name changes or you need to add a new compliance tag, you’re looking at a significant refactoring effort.

Scenario 2: Complex Configuration Structures

Complex JSON configurations, such as Consumption Logic App workflow definitions, often contain embedded values that need to vary between environments or deployments:

{
    "definition": {
        "$schema": "https://schema.management.azure.com/providers/Microsoft.Logic/schemas/2016-06-01/workflowdefinition.json#",
        "actions": {
            "Condition_-_Morning_or_Afternoon": {
                "actions": {
                    "Terminate_-_Afternoon": {
                        "inputs": {
                            "runStatus": "Succeeded"
                        },
                        "runAfter": {},
                        "type": "Terminate"
                    }
                },
                "else": {
                    "actions": {
                        "Terminate_-_Morning": {
                            "inputs": {
                                "runStatus": "Succeeded"
                            },
                            "runAfter": {},
                            "type": "Terminate"
                        }
                    }
                },
                "expression": {
                    "and": [
                        {
                            "greaterOrEquals": [
                                "@utcNow('H:mm:ss')",
                                "12:00:00" // ← Currently hard-coded static configuration
                            ]
                        }
                    ]
                },
                "runAfter": {},
                "type": "If"
            }
        },
        "contentVersion": "1.0.0.0",
        "outputs": {},
        "parameters": {},
        "triggers": {
            "Recurrence_-_Start": {
                "evaluatedRecurrence": {
                    "frequency": "Day",
                    "interval": 1, // ← Currently hard-coded static configuration
                    "schedule": {
                        "hours": [
                            "11"
                        ]
                    }
                },
                "recurrence": {
                    "frequency": "Hour",
                    "interval": "2" // ← Currently hard-coded static configuration
                },
                "type": "Recurrence"
            }
        }
    },
    "parameters": {}
}

In this Consumption Logic App workflow, the recurrence interval, evaluatedRecurrence interval, and condition time values are hard-coded. If you need different intervals or values for different environments (perhaps more frequent polling in production), you’d need to maintain separate configuration files or manually edit values during deployment.

My Recommended Approaches

Approach 1: Union Function for Object Composition

The union() function is perfect for combining base configuration with resource-specific overrides. This approach works exceptionally well for scenarios like tagging, where you have a core set of common properties and some resource-specific additions.

The Problem: Without union, you end up repeating common tags across every resource:

// Bad: Repeated configuration
resource storageAccount 'Microsoft.Storage/storageAccounts@2025-01-01' = {
  tags: {
    BusinessUnit: 'BicepTipsAndTricks'
    Version: deployment().properties.template.contentVersion
    Environment: environment
    Region: region
    ResourceName: 'Storage Account'
    'hidden-title': 'Bicep Tips and Tricks Storage'
  }
}

resource keyVault 'Microsoft.KeyVault/vaults@2023-07-01' = {
  tags: {
    BusinessUnit: 'BicepTipsAndTricks'  // Duplicated!
    Version: deployment().properties.template.contentVersion  // Duplicated!
    Environment: environment  // Duplicated!
    Region: region  // Duplicated!
    ResourceName: 'Key Vault'
    'hidden-title': 'Bicep Tips and Tricks Key Vault'
  }
}

The Solution: Use union to combine base and specific configurations:

// Good: Centralized common configuration
// ** Parameters **
@description('The environment to deploy to')
param environment string = 'dev'

@description('The Azure region to deploy to')
param region string = 'UkSouth'

// ** Variables **
var coreTags = {
  BusinessUnit: 'BicepTipsAndTricks'
  Version: deployment().properties.template.contentVersion
  Environment: environment
  Region: region
}

// Create resource-specific tag combinations
var storageAccountTags = union(coreTags, {
  ResourceName: 'Storage Account'
  'hidden-title': 'Bicep Tips and Tricks Storage'
})

var keyVaultTags = union(coreTags, {
  ResourceName: 'Key Vault'
  'hidden-title': 'Bicep Tips and Tricks Key Vault'
  DataClassification: 'Confidential'  // Additional tag specific to Key Vault
})

// ** Resources **
resource storageAccount 'Microsoft.Storage/storageAccounts@2025-01-01' = {
  name: 'mystorageaccount'
  location: region
  tags: storageAccountTags
  sku: {
    name: 'Standard_LRS'
  }
  kind: 'StorageV2'
}

resource keyVault 'Microsoft.KeyVault/vaults@2023-07-01' = {
  name: 'mykeyvault'
  location: region
  tags: keyVaultTags
  properties: {
    sku: {
      family: 'A'
      name: 'standard'
    }
    tenantId: subscription().tenantId
  }
}

Key Benefits:

• Single source of truth: Common tags are defined once in coreTags
• Easy maintenance: Update business unit name? Change it in one place
• Flexible: Each resource can still have unique tags

Approach 2: Token Replacement for Complex Configurations

For complex JSON configurations that need dynamic values, token replacement provides an elegant solution. This approach is particularly powerful when working with imported JSON files that contain configuration.

The Problem: Static values embedded in complex configurations:

The Solution: Use token placeholders and replacement functions.

First, modify your JSON configuration file to use tokens:

{
    "definition": {
        "$schema": "https://schema.management.azure.com/providers/Microsoft.Logic/schemas/2016-06-01/workflowdefinition.json#",
        "actions": {
            "Condition_-_Morning_or_Afternoon": {
                "actions": {
                    "Terminate_-_Afternoon": {
                        "inputs": {
                            "runStatus": "Succeeded"
                        },
                        "runAfter": {},
                        "type": "Terminate"
                    }
                },
                "else": {
                    "actions": {
                        "Terminate_-_Morning": {
                            "inputs": {
                                "runStatus": "Succeeded"
                            },
                            "runAfter": {},
                            "type": "Terminate"
                        }
                    }
                },
                "expression": {
                    "and": [
                        {
                            "greaterOrEquals": [
                                "@utcNow('H:mm:ss')",
                                "__schedule_time__"  // ← Token for schedule time
                            ]
                        }
                    ]
                },
                "runAfter": {},
                "type": "If"
            }
        },
        "contentVersion": "1.0.0.0",
        "outputs": {},
        "parameters": {},
        "triggers": {
            "Recurrence_-_Start": {
                "evaluatedRecurrence": {
                    "frequency": "Day",
                    "interval": 1,
                    "schedule": {
                        "hours": [
                            "__schedule_hour__"  // ← Token for schedule hour
                        ]
                    }
                },
                "recurrence": {
                    "frequency": "Hour",
                    "interval": "__interval__"  // ← Token for interval
                },
                "type": "Recurrence"
            }
        }
    },
    "parameters": {}
}

Then, create a robust token replacement system in your Bicep template:

// ** Imported Types and Functions **
@description('Token Replacement Definition')
@sealed()
@export()
type TokenReplacement = {
  @description('Token to be replaced')
  token: string
  @description('Replacement value')
  replacement: string
}

@description('String Tokens Replacement Function')
@export()
func stringTokensReplacement(stringValue string, tokenReplacements TokenReplacement[]) string =>
  reduce(tokenReplacements, stringValue, (current, next) => replace(string(current), next.token, next.replacement))

// ** Parameters **
@description('The interval for the Logic App trigger')
param logicAppInterval int = 2

@description('The schedule hour for the Logic App trigger')
param scheduleHour int = 11

@description('The schedule time for condition comparison')
param scheduleTime string = '12:00:00'

@description('The environment for deployment')
param environment string = 'dev'

// ** Variables **
var logicAppConsumptionWorkflow = loadJsonContent('./logicAppConsumptionWorkflow.json')

// Define all token replacements in one place
var tokenReplacements = [
  {
    token: '__interval__'
    replacement: string(logicAppInterval)
  }
  {
    token: '__schedule_hour__'
    replacement: string(scheduleHour)
  }
  {
    token: '__schedule_time__'
    replacement: scheduleTime
  }
]

// Apply all token replacements
var processedWorkflowDefinition = json(stringTokensReplacement(
  string(logicAppConsumptionWorkflow),
  tokenReplacements
))

// ** Resources **
resource logicApp 'Microsoft.Logic/workflows@2023-12-01' = {
  name: 'my-dynamic-logic-app-${environment}'
  location: resourceGroup().location
  properties: {
    definition: processedWorkflowDefinition.definition
    parameters: processedWorkflowDefinition.parameters
  }
}

Key Benefits:

• Environment-specific values: Different intervals for dev/test/prod
• Centralized configuration: All replacements defined in one place
• Scalable: Easy to add new tokens as requirements grow
• Version control friendly: JSON templates remain clean and readable

Summary

Transforming static configuration into dynamic, reusable patterns is essential for maintainable Infrastructure as Code. Use the union() function when combining common configuration with resource-specific properties (like tags), and token replacement for complex JSON configurations that need dynamic values injected. Both approaches centralize configuration management, reduce duplication, and make your Bicep templates more maintainable across environments. The next time you find yourself copy-pasting configuration, choose the right pattern and eliminate that technical debt!

In late May this year, an exciting but semi overlooked feature was released, and I absolutely love it - Typed Variables!

Prior to this release, variable types were inferred through the value, which is fine for most statically defined content within a template, but there are cases that I will go through in this post where typing your variables really does make a big difference.

Why Use Typed Variables

Before I get going, let me walk through why you should consider using typed variables:

1. Fail-Fast Error Detection: Typed variables enable the Bicep compiler to validate assigned values against declared types during authoring and compilation. This helps catch mistakes early, reducing deployment failures.
2. Clearer Intent: Declaring types communicates your intent directly in the code, making it obvious how each variable should be used and what kind of data it should hold.
3. Enhanced IntelliSense Support: Editors like Visual Studio Code offer richer autocompletion and validation for typed variables, speeding up development and reducing errors.
4. Safer Refactoring: When you change variable values or types, the compiler immediately flags mismatches, making refactoring safer and more predictable.

Setup

Defining a typed variable is as simple as the following:

var <variable-name> <data-type> = <variable-value>

⚠️ Note: Requires Bicep version 0.36.X or later.

Typed variables support both the standard set of base data types - string, int, bool, object, array - or for the more advanced, User-defined data types and Resource-derived types.

My Top Two Use Cases

1. Clear Intent

The first major use case for typed variables is improving code clarity and maintainability, especially when working with functions that return complex objects. Without type declarations, it can be difficult to understand what a function returns or how to properly use the resulting variable.

Consider this example with a custom function:

Un-Typed Variable

// ** Functions **
// ***************

func myFunction(param1 string, param2 int) object => {
  property1: param1
  property2: param2
}

// ** Variables **
// ***************

// Un-typed - No IntelliSense on variable use or expectation of variable type.
var variable = myFunction('example', 42)

In this un-typed scenario, several issues arise:

• Unclear return type: The function returns a generic object, making it unclear what properties are available
• No IntelliSense support: When using variable., your editor can’t help you with autocompletion
• Hidden intent: Other developers (or future you) must examine the function implementation to understand what it returns
• Error-prone usage: Typos in property names won’t be caught until deployment time

Now let’s see how typed variables solve these problems:

Typed Variable

// User Defined-Types
// *********************

@sealed()
@description('Defines the structure for myFunction output.')
type myFunctionOutputType = {
  @description('The first property of the output.')
  property1: string
  @description('The second property of the output.')
  property2: int
}

// ** Functions **
// ***************

func myFunction(param1 string, param2 int) myFunctionOutputType => {
  property1: param1
  property2: param2
}

// ** Variables **
// ***************

// Typed - Includes IntelliSense, code clarity, and refactor safety on variable use.
var typedVariable myFunctionOutputType = myFunction('example', 42)

The typed approach delivers immediate improvements:

• Crystal clear intent: The type definition explicitly documents what the function returns and what each property represents
• Enhanced developer experience: Full IntelliSense support when working with the variable, including property names and descriptions
• Compile-time safety: Any mismatch between the function’s actual return value and the declared type will be caught during authoring and compilation
• Better maintainability: Changes to the function’s return structure must be reflected in the type definition, ensuring consistency across the codebase
• Team collaboration: New team members can quickly understand the data structure without diving into function implementations

This pattern is especially valuable in larger Bicep templates where functions might be defined in one section and used much later in the file, or using imported functions as discussed earlier in the series.

2. File functions

One of the most powerful applications of typed variables is when working with Bicep’s file functions such as loadJsonContent() and loadYamlContent(). Without typed variables, these functions return as an Any object, providing no compile-time validation for the loaded content.

Let’s look at a practical example where we’re loading configuration data from an external JSON file:

JSON config file

{
	"sku": {
		"name": "Standard",
		"tier": "Standard"
	},
	"kind": "StorageV2",
	"properties": {
		"supportsHttpsTrafficOnly": true
	}
}

Un-Typed Variable

// ** Variables **
// ***************

var resourceConfig = loadJsonContent('./Config/resource.config.json')

With the un-typed approach above, resourceConfig is treated as a generic object. This means:

• No compile-time validation of the JSON structure
• No documentation about what the configuration should contain

Now let’s see how typed variables transform this experience:

// User Defined-Types
// *********************

@sealed()
@description('Defines the structure for importing a JSON File resource with SKU, kind, and properties.')
type resourceImportType = {
  @description('The SKU details for the resource.')
  sku: {
    @description('The name of the SKU.')
    name: string
    @description('The tier of the SKU (e.g., Standard, Premium).')
    tier: string
  }
  @description('The kind of the resource.')
  kind: string
  @description('The properties of the resource.')
  properties: {
    @description('Indicates whether only HTTPS traffic is supported.')
    supportsHttpsTrafficOnly: bool
  }
}

// ** Variables **
// ***************

var typedResourceConfig resourceImportType = loadJsonContent('./Config/resource.config.json')

With the typed variable approach, we gain several significant benefits:

• Compile-time validation: If the JSON file doesn’t match the defined structure, Bicep will catch this during authoring and compilation
• Rich IntelliSense: When you type typedResourceConfig., your editor will show you the available properties with their descriptions
• Self-documenting code: The type definition serves as living documentation of the expected configuration structure
• Refactoring safety: If you change the type definition, all usages will be validated automatically

This approach is particularly valuable when working with complex configuration files or when multiple team members need to understand the expected data structure.

Summary

Typed variables are a game changer for Bicep development, offering compile-time validation, enhanced IntelliSense, and self-documenting code that makes your templates more robust and maintainable. Make sure to give them a try, and happy Bicep-ing!

In Bicep templates, we sometimes encounter scenarios where certain parameters should be mandatory based on the value of another parameter. For example, when deploying to production environments, you might require additional configuration parameters that are optional for development environments.

One of the common ways in which I have seen this handled is through documentation, which can lead to deployment failures and inconsistent configurations across environments. This post explores how to implement fail-fast validation using Bicep’s built-in capabilities to enforce these conditional requirements at deployment time.

Example of a Documentation-Only Approach

Handling conditional parameter requirements through documentation alone:

@description('Environment to deploy to')
@allowed([
  'dev'
  'test'
  'prod'
])
param environment string

@description('Resource configuration - REQUIRED for prod environment!')
param resourceConfig string = ''

// Additional parameters that should be required in prod
@description('Monitoring configuration - REQUIRED for prod environment!')
param monitoringConfig object = {}

@description('Backup configuration - REQUIRED for prod environment!')
param backupRetentionDays int = 0

Problems with this approach:

• No enforcement at deployment time
• Deployments can succeed with missing critical configuration
• Relies on human memory and documentation
• Inconsistent environments due to missing parameters
• Production issues from misconfiguration

Recommended Approach: Fail-Fast Validation

I would recommend using the Bicep fail() function combined with conditional logic to validate parameters early in the deployment process. This approach provides immediate feedback and prevents deployments with invalid configurations, such as in the following examples:

• Production environments - Storage deployments requiring backup retention settings for production
• Key Vault requiring network access rules when public access is disabled

@description('Environment to deploy to')
@allowed([
  'dev'
  'test'
  'prod'
])
param environment string

@description('''Resource Configuration:
                - **Optional** When environment is dev / test.
                - **Required** When environment is prod.''')
param resourceConfig string = ''

@description('Resource Configuration Validation Result')
var resourceConfig_Result = environment == 'prod' && empty(resourceConfig)
  ? fail('resourceConfig is required to deploy this template in the prod Environment.')
  : {
      value: resourceConfig
      valueProvided: !empty(resourceConfig)
    }

⚠️ Note: Make deployment failures informative and actionable, helping your team understand exactly what’s needed to fix the issue.

Why this approach is useful

• Enforces deployment rules: Prevents deployment in “prod” if critical configuration is missing, ensuring required configuration is provided before any resources are created.
• Fail-fast validation: Catches configuration errors at the start of deployment, saving time and preventing partial deployments.
• Conditional resource creation: You can use the valueProvided property to conditionally deploy resources or set properties only when configuration is supplied.
• Parameter validation: Centralizes validation logic, making it easier to maintain and extend checks for other environments or parameters in the future.
• Compliance requirements: Ensures production environments always meet security and operational standards.

Summary

Conditional mandatory parameters in Bicep templates are a powerful way to enforce deployment standards and prevent configuration errors. Remember to make deployment failures informative and actionable, helping your team understand exactly what’s needed to fix the issue. Hope this helps, and happy Bicep-ing!

This week is a simple one, but works wonders in maintainability and consistency.

There are often cases where you will need to define static values that don’t change frequently, if at all, and more importantly, you seem to be setting these up frequently for multiple templates. Here are some examples that I have seen:

1. Multi-Environment Deployments

   Different environments (dev, staging, prod) that share common configuration but need environment-specific values:

   var environmentConfig = {
     dev: {
       sku: 'Basic'
     }
     staging: {
       sku: 'Standard'
     }
     prod: {
       sku: 'Premium'
     }
   }
   

2. Organisational Standards

   When you need to enforce company-wide conventions and policies.

   var mandatoryTags = {
     costCenter: 'IT-001'
     dataClassification: 'internal'
     businessUnit: 'engineering'
     version: deployment().properties.template.contentVersion
   }
   

3. Object or Resource Configurations

   When you have configurations that would be repeated across multiple templates.

   var subnetConfigurations = [
     {
       name: 'web-subnet'
       addressPrefix: '10.0.1.0/24'
       serviceEndpoints: ['Microsoft.Storage', 'Microsoft.KeyVault']
     }
     {
       name: 'api-subnet'
       addressPrefix: '10.0.2.0/24'
       serviceEndpoints: ['Microsoft.Sql', 'Microsoft.KeyVault']
     }
   ]
   
   // OR
   
   var keyVaultSecretsUserRoleDefId = '4633458b-17de-408a-b874-0445c86b69e6'
   

You might think, “Hey, the values don’t change very often, so what’s the big deal? So what if I set them up many times across my templates?” Not to be a pessimist, but it’s usually at this point that Murphy’s Law comes into effect and the values will need to change! Would you not rather there be a single point where you can update these values and they ripple through your templates like a stone hitting water?

Well, you can. Simply put, Shared Variables.

Recommended Approach

My recommended approach is to leverage Bicep Imports. Create a Common folder within your IaC directory, and then a variables.bicep file within:

IaC
  ↳ Common
    ↳ variables.bicep
  ↳ main.bicep

This will form the basis of your shared variables that can be used across your deployment templates.

Then find all the relevant candidates and move these across to the shared variables template. Include the @export() decorator to each variable; this is used to allow the variable to be imported into other Bicep files.

For Example

/**********************************
  Bicep Template: Shared Variables
  Author: Andrew Wilson
***********************************/

@export()
@description('Shared Variable for environment configurations')
var environmentConfig = {
  dev: {
    sku: 'Basic'
  }
  staging: {
    sku: 'Standard'
  }
  prod: {
    sku: 'Premium'
  }
}

@export()
@description('Shared Variable for tagging resources')
var mandatoryTags = {
  costCenter: 'IT-001'
  dataClassification: 'internal'
  businessUnit: 'engineering'
  version: deployment().properties.template.contentVersion
}

@export()
@description('Shared Variable for resource configuration')
var subnetConfigurations = [
  {
    name: 'web-subnet'
    addressPrefix: '10.0.1.0/24'
    serviceEndpoints: ['Microsoft.Storage', 'Microsoft.KeyVault']
  }
  {
    name: 'api-subnet'
    addressPrefix: '10.0.2.0/24'
    serviceEndpoints: ['Microsoft.Sql', 'Microsoft.KeyVault']
  }
]

@export()
@description('Shared Variable for Key Vault Secrets User Role Definition ID')
var keyVaultSecretsUserRoleDefId = '4633458b-17de-408a-b874-0445c86b69e6'

These can then be used in your deployment templates as follows:

/***************************************
Bicep Template: Main Deploy
Author: Andrew Wilson
****************************************/

targetScope = 'resourceGroup'

// ** Shared Imports **
// ********************

import { keyVaultSecretsUserRoleDefId } from './Common/variables.bicep'

// ** Parameters **
// ****************

...

// ** Variables **
// ***************

...

// ** Resources **
// ***************

resource roleassignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(logicAppName, keyVaultSecretsUserRoleDefId)
  properties: {
    roleDefinitionId: resourceId('Microsoft.Authorization/roleDefinitions', keyVaultSecretsUserRoleDefId)
    ...
  }
}

Best Practices for Using Shared Variables

1. Keep it Simple: Only share variables that are common and stable.
2. Tight Control: Treat shared variables as critical infrastructure code.
3. Documentation: Clearly document and describe what each variable represents or is used for.
4. Selective Imports: Don’t import everything with *; be selective about what needs to be imported into deployment templates.

When NOT to Use Shared Variables

• For values that change frequently or are deployment-specific
• For simple, one-off configurations
• For sensitive values (use parameters or Key Vault references instead)

Summary

Shared variables help eliminate duplication and improve consistency across your Bicep templates. This simple approach gives you a single point of truth for common configurations, making updates easier and reducing the risk of inconsistencies across environments. Hope this helps, and happy Bicep-ing!

One of my bugbears is seeing either a complete lack of naming conventions or manual naming mechanisms that introduce human error through mistakes and misunderstandings. Naming conventions are incredibly important, but equally critical is how they’re implemented and maintained. Let’s explore a better approach.

What is a Naming Convention and Why Do We Need One?

A naming convention is a set of rules for naming Resource Groups and Resources (among other Azure components). These rules define the structure and composition of names, ensuring clarity, consistency, and compliance with Azure naming requirements such as length limits, valid characters, and scope uniqueness.

Common components that make up resource names include:

• Location
• Environment
• Project Prefix
• Resource Abbreviation

Naming conventions aren’t one-size-fits-all and require tailoring to your specific needs. Any changes should be considered across all systems to maintain a single source of truth. Well-defined naming conventions significantly improve the readability and maintainability of your Azure estate, aligning with best practices outlined in the Cloud Adoption Framework.

Example convention: {Resource Type}-{Project}-{Environment}-{Location}
Result: LogicAppName: logic-btt-dev-ukwest

Anti-patterns to Avoid

Hard-coded resource names:

name: 'MyLogicApp'

Issues: Poor maintainability, readability, consistency, and convention adherence

Hard-coded naming variables:

var lgName = 'MyLogicApp'

Issues: Poor maintainability across templates, inconsistency, and no convention

Hard-coded naming convention:

var lgName = 'logic-${project}-${environment}-${location}'

Issues: Poor maintainability across templates, template inconsistency, and scattered convention logic

Recommended Approach

My recommended approach leverages User-defined functions to provide consistent and maintainable naming conventions. Combined with Bicep Imports, this ensures consistency across all templates.

For enhanced maintainability, I also recommend implementing centralized core parameters with types and constructors. This approach significantly reduces the number of function parameters needed for each naming operation.

Implementation Structure

Create a Common folder within your IaC directory:

IaC
  ↳ Common
    ↳ types.bicep
    ↳ nameConventionFunctions.bicep
  ↳ main.bicep

• types.bicep - Contains core parameter user-defined types and constructor functions
• nameConventionFunctions.bicep - Contains naming convention functions

Core Types Setup

/**********************************
  Bicep Template: Shared Types
  Author: Andrew Wilson
***********************************/

// ** User Defined Types and Constructors **
// *****************************************

// TYPE: Core Parameters
// *********************

@export()
@description('Core Parameters Definition for Bicep Templates')
@sealed()
type coreParams = {
  @description('Location to deploy resources to')
  location: string
  @description('Location Short Name for resource naming')
  locationShortName: string
  @description('Environment to deploy to')
  environment: string
  @description('Project Prefix for resource naming')
  projectPrefix: string
}

@export()
@description('Core Parameters Constructor')
func newCoreParams(
  location string,
  locationShortName string,
  environment string,
  projectPrefix string
) coreParams => {
  location: location
  locationShortName: locationShortName
  environment: environment
  projectPrefix: projectPrefix
}

Naming Convention Functions

I’ve structured my naming conventions using these key parameters:

• Resource Abbreviation - Identifies the resource type (Azure abbreviations reference)
• Project Prefix - Identifies the project
• Environment - Identifies the deployment environment
• Location - Identifies the deployment location (optional for global resources)
• Context - Describes the resource’s purpose (optional)

The following functions cover some common naming scenarios:

/*******************************************
  Bicep Template: Name Constructor Functions
  Author: Andrew Wilson
*******************************************/

// ** Shared Imports **
// ********************

import { coreParams } from './types.bicep'

// Resource Name Constructors
//***************************

// Basic
@export()
@description('Generates a resource name based on the provided parameters (used for common usage resources)')
func basicResource(resourceAbbreviation string, coreParameters coreParams) string =>
  '${resourceAbbreviation}-${coreParameters.projectPrefix}-${coreParameters.environment}-${coreParameters.location}'

@export()
@description('Generates a resource name based on the provided parameters but ignoring the location (used for common usage resources that are not location specific)')
func unlocalisedBasicResource(resourceAbbreviation string, coreParameters coreParams) string =>
  '${resourceAbbreviation}-${coreParameters.projectPrefix}-${coreParameters.environment}'

// Context Specific
@export()
@description('Generates a Context Specific Resource Name based on the provided parameters')
func csResource(resourceAbbreviation string, coreParameters coreParams, contextName string) string =>
  '${resourceAbbreviation}-${coreParameters.projectPrefix}-${contextName}-${coreParameters.environment}-${coreParameters.location}'

// Resource Group
@export()
@description('Generates a Resource Group name based on the provided parameters')
func resourceGroup(contextName string, coreParameters coreParams) string =>
  'rg-${coreParameters.projectPrefix}-${contextName}-${coreParameters.environment}-${coreParameters.location}'

@export()
@description('Generates a Resource Group name based on the provided parameters but without an env specified')
func resourceGroupNonEnvSpecific(contextName string, coreParameters coreParams) string =>
  'rg-${coreParameters.projectPrefix}-${contextName}-${coreParameters.location}-shared'

// Storage Account
@export()
@description('Generates a Storage Account Resource Name based on the provided parameters')
func storageAccountResource(coreParameters coreParams, contextName string?) string =>
  empty(contextName)
    ? 'st${coreParameters.projectPrefix}${coreParameters.environment}${coreParameters.locationShortName}'
    : 'st${coreParameters.projectPrefix}${contextName}${coreParameters.environment}${coreParameters.locationShortName}'

Usage Example

Here’s how to use these functions in your main deployment template:

/***************************************
Bicep Template: Main Deploy
Author: Andrew Wilson
****************************************/

targetScope = 'resourceGroup'

// ** Shared Imports **
// ********************

import { newCoreParams } from './Common/types.bicep'
import * as newName from './Common/nameConventionFunctions.bicep'

// ** Parameters **
// ****************

@description('Location to deploy resources to')
param location string

@description('Location Short Name for resource naming')
param locationShortName string

@description('Environment to deploy to')
param environment string = 'dev'

@description('Project Prefix for resource naming')
param projectPrefix string = 'myproject'

// ** Variables **
// ***************

var coreParameters = newCoreParams(location, locationShortName, environment, projectPrefix)

// Standard Logic App Resource Names
var logicAppName = newName.basicResource('logic', coreParameters)
var appServicePlanName = newName.csResource('asp', coreParameters, 'lg')
var storageAccountName = newName.storageAccountResource(coreParameters, 'lg')

// ** Resources **
// ***************

...

Generated Names:

• Logic App: logic-myproject-dev-ukwest
• App Service Plan: asp-myproject-lg-dev-ukwest
• Storage Account: stmyprojectlgdevukw

Summary

Implementing a robust naming convention is crucial for Azure resource management, but the mechanism matters just as much as the convention itself. By using Bicep user-defined functions combined with centralized core parameters, you can:

• Eliminate human error from manual naming processes
• Ensure consistency across all templates and environments
• Improve maintainability with centralized naming logic
• Enhance readability of your Infrastructure as Code
• Align with best practices from the Cloud Adoption Framework

This approach transforms naming from a scattered, error-prone process into a centralized, reliable system that scales with your infrastructure needs. The initial setup investment pays dividends in reduced maintenance overhead and improved deployment reliability. Happy Bicep-ing!

When building IaC templates we strive to enable them to be environment agnostic, configurable even. One of the mechanisms that we do this is through lots of “Core Parameters” that disseminate the fundamental details of our deployment and resources. The number of core parameters is often variable but the verdict is always true, three or more usually does the trick. These Core Parameters are passed into the main deployment template and any other sub deployment template (Module) too. These may include but are not limited to:

• Environment
• Location/Region
• Project/Application Prefix

But why am I going on about this, why is it a problem. Well it’s not a problem as much as it’s a readability and maintainability issue. Think about it, every template now requires three or more core parameters defined, with every module call having to define them as parameters to be passed in. Following this, if there is a change, the change will need to occur everywhere, and let’s hope that the descriptions/metadata has been kept up to date too!

My recommendation to resolve this issue involves three Bicep concepts:

1. User-defined data types
2. User-defined functions
3. Imports

Recommendation broken down

1. Define our source of truth Core Parameters | User-defined data type

User-defined data types provide us a way to define our own data object containing all the core parameters that we use throughout such as the following:

// Bicep

@description('Core Parameters Definition for Bicep Templates')
@sealed()
type coreParams = {
  @description('Location to deploy resources to')
  location: string
  @description('Environment to deploy to')
  environment: string
  @description('Project Prefix for resource naming')
  projectPrefix: string
}

The decorator @sealed() means that you are only permitting the use of properties specifically included in the type definition. This helps with making sure there is only one single source of truth for the coreParams definition.

The type definition means that we can pass through a single parameter to our deployment templates, and manage change in a single place.

2. Create a Constructor to setup our Core Parameters | User-defined function

To aid in the initialization of the coreParams type, I typically create a user-defined function (Constructor) which sets up the initial state by assigning values to the respective properties. This ensures the Core Params object starts in a valid, predictable state. The function would look like this:

// Bicep

@description('Core Parameters Constructor')
func newCoreParams(
  location string,
  environment string,
  projectPrefix string
) coreParams => {
  location: location
  environment: environment
  projectPrefix: projectPrefix
}

3. Promote Shared Use of the Type and Constructor | Imports

The user defined type and function alone would not make this an effective recommendation due to the duplication of both the type and function definition on all templates. However, due to the recent introduction of exports and imports, we can continue on the path of a single and reusable single source of truth.

To make this work, what I would suggest is to create a new folder in your IaC location called Common, in this folder create a new bicep file called types.bicep. This is the shared bicep file that we are going to use for our new type and constructor.

An example of this setup is as follows:

• IaC → Common → types.bicep

Shared Types Template

// Bicep

/**********************************
  Bicep Template: Shared Types
  Author: Andrew Wilson
***********************************/

// ** User Defined Types and Constructors **
// *****************************************

// TYPE: Core Parameters
// *********************

@export()
@description('Core Parameters Definition for Bicep Templates')
@sealed()
type coreParams = {
  @description('Location to deploy resources to')
  location: string
  @description('Environment to deploy to')
  environment: string
  @description('Project Prefix for resource naming')
  projectPrefix: string
}

@export()
@description('Core Parameters Constructor')
func newCoreParams(
  location string,
  environment string,
  projectPrefix string
) coreParams => {
  location: location
  environment: environment
  projectPrefix: projectPrefix
}

The @export() decorator is used to allow the type and function to be imported into other Bicep files.

Now we can use the import syntax in our main and sub deployment (module) templates, allowing use of the single defined type and function. In the main template we import the constructor and assign the initialized object to our coreParameters variable. For our sub deployment (module) templates we import the coreParams type so we can use it as a parameter definition. Both combined allow simplified module reference definitions and assignments. This can be seen in the following example templates:

Main Deployment Template

// Bicep

/***************************************
Bicep Template: Main Deploy
Author: Andrew Wilson
****************************************/

targetScope = 'resourceGroup'

// ** Shared Imports **
// ********************

import { newCoreParams } from './Common/types.bicep'

// ** Parameters **
// ****************

@description('Location to deploy resources to')
param location string = resourceGroup().location

@description('Environment to deploy to')
param environment string = 'dev'

@description('Project Prefix for resource naming')
param projectPrefix string = 'myProject'

// ** Variables **
// ***************

var coreParameters = newCoreParams(location, environment, projectPrefix)

// ** Resources **
// ***************

@description('Demonstration of the core parameters being passed to a submodule')
module subDeploy './subDeploy.bicep' = {
  name: 'subDeploy'
  params: {
    coreParameters: coreParameters
  }
}

Sub Deployment (Module) Template

// Bicep

/***************************************
Bicep Template: Resources Deploy
Author: Andrew Wilson
****************************************/

targetScope = 'resourceGroup'

// ** Shared Imports **
// ********************

import { coreParams } from './Common/types.bicep'

// ** Parameters **
// ****************

@description('Core Parameters for the deployment')
param coreParameters coreParams

// ** Variables **
// ****************

@description('The name of the resource to deploy')
var resourceName = '${coreParameters.projectPrefix}-${coreParameters.environment}-resource'

Summary

Managing core parameters in Bicep templates can quickly become unwieldy as your infrastructure grows. By leveraging user-defined types, constructors, and imports, you can centralize your parameter definitions, improve readability, and simplify maintenance. This approach ensures consistency across your deployments and makes future changes easier to manage. Happy Bicep-ing!

For those who know me well, starting a bicep tips and tricks series would not be a surprise to them. The moment the Bicep language was introduced, I knew I would be completely obsessed. I love writing bicep templates and even more the clever refinement to make them reusable, configurable, manageable, readable… I really enjoy sharing my experiences with Bicep, so here it begins on the wider front. From one Bicep nerd to another, I hope you find these tips useful, happy templating!

Why is versioning important

Versioning is a fundamental practice in software development that helps us manage change effectively. It provides a structured way to track and communicate updates, ensuring clarity and consistency throughout the development lifecycle.

• Why apply a version to your templates?

  Applying versioning to templates ensures you can track changes, maintain consistency, and know exactly which version of your infrastructure code was used for any deployment. It supports best practices like binary promotion, simplifies troubleshooting, and helps teams coordinate updates and rollbacks with confidence.

• Why apply the version as a tag to Azure Resources?

  Tagging Azure resources with the template version gives you direct visibility into what was deployed, right from the Azure portal or API. This makes audits, governance, and troubleshooting much easier, as you can instantly see which template version created or updated a resource. It also helps correlate infrastructure changes with application releases and supports compliance requirements for traceability.

ARM templates have a Json property right at the top of the file underneath $schema called contentVersion. By default and if never changed, this will always be 1.0.0.0. As part of our versioning practice we can make sure that the templates that we deploy make use of the same version that is applied to other built artifacts. This allows us to track deployments and their respective templates through versions.

How to version templates using Azure DevOps

As part of a YAML CI/CD pipeline I typically have a build stage, with a inner Test and Version ARM Templates Job. The focus of the job is to do two things:

1. Using the az cli - Build the Bicep templates
   • I also include the Bicep linting file, this means that as the templates are being transpiled into ARM I am also getting any build errors and warnings. I output these as logissues to the Azure DevOps Pipeline for visibility.
2. Version the built ARM JSON artifacts to support Binary promotion and align with versioning practices.

I use the following tasks to complete the tasks:

1. AzureCLI@2 - used to build the Bicep templates (transpile into ARM) and log any warnings or errors.
2. VersionJSONFile@3 - used to version stamp the ARM templates.
3. CopyFiles@2 - Used to copy the versioned ARM artifacts to the staging directory.
4. PublishPipelineArtifact@1 - used to publish the ARM artifacts to the pipeline so they can be downloaded in future deployment stages.

Here is a sample YAML template:

# Yaml

...

- task: AzureCLI@2
  displayName: 'Build Bicep Files'
  inputs:
    azureSubscription: 'xxyyzz'
    scriptType: 'ps'
    scriptLocation: 'inlineScript'
    useGlobalConfig: true
    powershellerrorActionPreference: 'continue'
    inlineScript: |
      # create folder if it doesn't exist
      if (!(Test-Path -Path $(Build.SourcesDirectory)\{YourPath}\IAC\ARMOutput)) {
        New-Item -ItemType Directory -Path $(Build.SourcesDirectory)\{YourPath}\IAC\ARMOutput
      }
      write-host "Build the Bicep file"
      $output = az bicep build --file $(Build.SourcesDirectory)\{YourPath}\IAC\template.azuredeploy.bicep --outdir $(Build.SourcesDirectory)\{YourPath}\IAC\ARMOutput 2>&1      
  
      write-host "Process the output"
      $output | foreach-object {
         if ($_ -match 'Error') {
            Write-Host "##vso[task.logissue type=error]$_"
         } 
         if ($_ -match 'Warning') {
             Write-Host "##vso[task.logissue type=warning]$_"
         }
      }

- task: VersionJSONFile@3
  displayName: 'Version stamp ARM templates'
  inputs:
    Path: '$(Build.SourcesDirectory)\{YourPath}\IAC\ARMOutput'
    recursion: True
    VersionNumber: $(Build.BuildNumber) # an example versioning option but can also be options like gitversion
    useBuildNumberDirectly: False
    VersionRegex: \d+\.\d+\.\d+\.\d+
    versionForJSONFileFormat: '{1}.{2}.{3}.{4}'
    FilenamePattern: '\w+.json'
    Field: 'contentVersion' # Versioning is applied to the templates contentVersion field
    OutputVersion: OutputedVersion

- task: CopyFiles@2
  displayName: 'Copy ARMOutput to Artifact Staging Directory'
  inputs:
    SourceFolder: '$(Build.SourcesDirectory)\{YourPath}\IAC\ARMOutput'
    Contents: '**/*.json'
    TargetFolder: '$(Build.ArtifactStagingDirectory)/templates'
    flattenFolders: true

- task: PublishPipelineArtifact@1
  displayName: 'Publish ARMOutput as template build artifact'
  inputs:
    targetPath: '$(Build.ArtifactStagingDirectory)/templates'
    publishLocation: 'pipeline'
    artifactName: 'ARMtemplates'

This setup ensures your ARM templates are built, versioned, and published as pipeline artifacts in a repeatable, traceable way. By stamping each template with a version number and making it available as an artifact, you enable binary promotion through environments and make it easy to track exactly which template version was used for each deployment. This improves auditability, supports rollback scenarios, and aligns with best practices for infrastructure as code in CI/CD pipelines.

How to apply the template version as a tag to Azure Resources

Versioning our ARM templates is one part of the transparency and traceability. But it would also be nice to be able to see which template version deployed the Azure Resources from the Azure Resources themselves. We can do this by applying a tag onto our resources and tying it back to our ARM contentVersion property field. We can do this by using the deployment() function as such deployment().properties.template.contentVersion.

On a resource it would look like the following:

// Bicep

resource AppService 'Microsoft.Web/sites@2024-11-01' = {
  name: appServiceName
  location: location
  tags: {
	...
    version: deployment().properties.template.contentVersion
  }
  ...
}

Applying template versioning and tagging resources with the deployed template’s version brings transparency and traceability to your Azure infrastructure. You’ll always know which version of your code and templates are running in each environment, making troubleshooting and governance much easier. These small practices help teams stay organised, reduce deployment risks, and build confidence in their automation. Happy Bicep-ing!

The Bicep existing keyword is a powerful capability that allows us to reference a resource that wasn’t deployed as part of the current Bicep file.

One of the typical use cases that I often see is where a resource is deployed as part of a module called by the parent template, the resource that was deployed as part of the module is then required later in the parent template and therefore an existing resource definition is used. As part of the template configuration there would be an explicit dependency between the existing resource definition and the module reference.

An example diagram of this is shown below:

For Bicep v0.34.1 and lower, there are two scenarios that can be observed when deploying the templates:

• Scenario 1: Successful deployment. The existing resource has been found and the explicit dependency between Existing Resource and Module Ref 1 has been honoured.
• Scenario 2: Deployment Failure. The Resource XYZ under resource group 'XXYYZZ' was not found.. The existing resource has not been found and the explicit dependency between Existing Resource and Module Ref 1 has not been honoured.

For most that fall into scenario 2, without much explanation of what may be going on behind the scenes, their typical solution to this particular problem may be to force the dependency chaining by extracting further of the parent template into a further module.

An example of this can be seen below:

Yes this is a valid solution, but why is there a problem in the first place?

Explanation

It all comes down to whether your template is compiled with symbolic name code generation.

Symbolic Name Code Generation allows the ARM template layer to use a new schema to represent resources as an object dictionary rather than an array of objects. This feature improves the semantic equivalence of the Bicep and ARM templates, resulting in more reliable code generation.

In a symbolic name template, an existing resource can depend on other resources or modules, and this will cause the backend to delay reading the resource until those dependencies are completed. This allows you to deploy a resource in a module, then refer to it with an existing declaration in the module parent. In non-symbolic name templates, existing resources are compiled to reference(resourceId()) expressions and are all handled in the first wave of deployment jobs.

In a non-symbolic name compiled template the existing reference looks like this:

reference(resourceId('Microsoft.xxx/yyy', parameters('resourceName'))), '2023-05-01', 'full')

In a symbolic name compiled template the existing reference and dependencies look like this:

reference('existingResource', '2023-05-01', 'full')

"dependsOn": [
  "existingResource",
  "ModuleRef1"
]

This explains why in some template deployment cases the deployment succeeds and in others it fails (the template is not setup for symbolic name code generation). But how do you enable symbolic name code generation?

Solution

Symbolic name code generation is part of the languageVersion 2.0 functionality and can be enabled automatically by using any of the following Bicep Features:

• user-defined types
• user-defined functions
• compile-time imports
• experimental features

For most of you up until this point like me, you will have unintentionally and thankfully enabled symbolic name code generation by using features as described above and therefore not suffered from the problem case as described.

Symbolic name code generation can also be explicitly enabled by adding the following to your bicepconfig.json:

	"experimentalFeaturesEnabled": {
		"symbolicNameCodegen": true
	 }

Or the preferred option use Bicep v0.34.44 or higher where languageVersion2.0 is used automatically when an existing resource has an explicit DependsOn dependency stipulated.

If you are unsure as to whether your templates are compiled using symbolic name code generation, have a look at the first few lines of your compiled Bicep template. The ARM template should specify languageVersion 2.0 if enabled and missing this line if not.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "languageVersion": "2.0",
  "contentVersion": "1.0.0.0",

Hope this helps and have fun.

There have been few times where I have landed into this particular predicament whereby either by my own doing or through the use of another’s code base, a deep nested or thoroughly utilised (parameter/variable/or other defined item) has been created with the same name as a Bicep function. As by Murphy’s law, its only once you have reached this point of no return that you realise that your items name conflicts.

Now if you are like many in your unawares, your thoughts and actions will conclude to a singular one of ’that sucks… followed by a nasty refactor'.

Solution - Namespaces

Namespaces are a declarative scope in which identifiers such as the names of types, functions, and variables can be declared. These namespaces are used to organise code into logical groups and to prevent name collisions such as the one you are currently experiencing.

Thankfully, in Bicep there are two namespaces where all functions are split, az and sys.

• az | Contains functions that are specific to an Azure deployment such as:
  • deployment
  • environment
  • resourceGroup
  • subscription
• sys | Contains functions that are used to construct values, and decorators for parameters and resource loops. This includes but is not limited to:
  • [Array] concat
  • [File] loadJsonContent
  • [Lambda] filter
  • [Logical] bool
  • [Numeric] int
  • [String] contains

To make use of these namespaces, simply add the namespace identifier in front of the function. The example below shows a real world example of this issue where a parameter name ‘environment’ has been extensively utilised in this template and many others. This particular template is being used to deploy an AuthProvider in API Management, and the author wishes to utilise the environment function for the authentication.loginEndpoint. Without the use of the az namespace, the environment parameter would need to be refactored both in this template and wider templates for consistency.

/******************************************
Bicep Template: Function Namespace Example
Author: Andrew Wilson
******************************************/

targetScope = 'resourceGroup'

// ** Parameters **
// ****************

@description('The environment to deploy the resources to.')
@allowed([
  'dev'
  'test'
  'prod'
])
param environment string = 'dev'

...

// ** Variables **
// ***************

var ApiManagementName = toLower('apim-${projectName}-${environment}-${location}')

// ** Resources **
// ***************

...

// Create a new Auth Provider in APIM Credential Manager
resource AuthorizationProvider 'Microsoft.ApiManagement/service/authorizationProviders@2023-05-01-preview' = {
  ...
  properties: {
    ...
    oauth2: {
      ...
      grantTypes: {
        clientCredentials: {
          loginUri: az.environment().authentication.loginEndpoint
        }
      }
    }
  }
}

As always, have a play, and hope this helps.