microsoft/hve-core

---
applyTo: '**/bicep/**'
description: 'Instructions for Bicep infrastructure as code implementation - Brought to you by microsoft/hve-core'
maturity: stable
---
# Bicep Instructions

These instructions define conventions for Bicep Infrastructure as Code (IaC) development in this codebase. Bicep files deploy Azure resources declaratively through ARM templates.

> [!NOTE]
> These instructions target Bicep 0.36+ and include generally available features through January 2026. The `providers` keyword is deprecated; use `extension` instead.

## MCP Tools

Bicep MCP tools provide schema information and best practices:

<!-- <reference-mcp-tools> -->
| Tool | Purpose | Parameters |
|------|---------|------------|
| `mcp_bicep_experim_get_az_resource_type_schema` | Retrieves the schema for a specific Azure resource type and API version | `azResourceType`, `apiVersion` (both required) |
| `mcp_bicep_experim_list_az_resource_types_for_provider` | Lists all available resource types for a provider namespace | `providerNamespace` (required) |
| `mcp_bicep_experim_get_bicep_best_practices` | Returns current Bicep authoring best practices | None |
<!-- </reference-mcp-tools> -->

## Project Structure

Organize Bicep files in a dedicated folder (e.g., `infra/`, `deploy/`, or environment-specific names):

<!-- <example-project-structure> -->
```text
main.bicep                    # Main orchestration
main.bicepparam               # Parameter values
types.bicep                   # Shared type definitions
README.md                     # Documentation
modules/                      # Reusable sub-modules
  networking.bicep
  storage.bicep
  compute.bicep
```
<!-- </example-project-structure> -->

File organization:

* `main.bicep` - Primary resource definitions and orchestration
* `types.bicep` - Shared type definitions and default values
* `modules/` - Reusable sub-modules for logical grouping

## Coding Standards

### File and Naming

* File and folder names: `kebab-case`
* Parameters: `camelCase`
* Types: `PascalCase`
* Metadata information appears at the top of each file
* Hardcoded values for resource names, locations, or other configurable items are not permitted

### Documentation and Comments

Every parameter and type includes a `@description()` decorator:

* Descriptions are short sentences ending with a period
* Non-obvious behaviors are explained: `'The description. (Updates a something not obvious when set)'`

Section headers use `/* */` comment blocks with whitespace for visual separation.

### Parameters and Types

<!-- <conventions-parameters> -->
Parameter conventions:

* Define related parameter types in `types.bicep`
* Use `??` (null coalescing) and `.?` (safe dereference) instead of ternary operators with null checks
* Organize parameters by functional grouping, then alphabetically within groups

Functional groupings organize parameters by their purpose:

| Group | Description | Examples |
| ----- | ----------- | -------- |
| Identity | Authentication and authorization | Managed identity names, RBAC assignments |
| Networking | Network connectivity and security | VNet names, subnet configurations, private endpoints |
| Storage | Data persistence | Storage account settings, container names |
| Monitoring | Observability and diagnostics | Log Analytics workspace, diagnostic settings |
| Compute | Processing resources | VM sizes, instance counts, scaling rules |
| Security | Encryption and secrets | Key Vault names, encryption settings |

* Boolean parameters start with `should` or `is`
* Required parameters have no defaults
* Empty string defaults are not permitted; use `null` instead
* Sensitive parameters include `@secure()`

For existing resources, prefer name parameters over resource IDs:

```bicep
param identityName string?
resource identity 'Microsoft.ManagedIdentity/userAssignedIdentities@2023-01-31' existing = if (!empty(identityName)) {
  name: identityName!
}
```
<!-- </conventions-parameters> -->

### Resource Naming

Resource names follow [Azure naming conventions](https://learn.microsoft.com/azure/cloud-adoption-framework/ready/azure-best-practices/resource-naming):

<!-- <conventions-resource-naming> -->
| Pattern | Example |
|---------|---------|
| Hyphens allowed | `{abbrev}-${common.resourcePrefix}-{optional}-${common.environment}-${common.instance}` |
| No hyphens | `{abbrev}${common.resourcePrefix}{optional}${common.environment}${common.instance}` |
| Length restricted | `'{abbrev}${uniqueString(common.resourcePrefix, {optional}, common.environment, common.instance)}'` |
<!-- </conventions-resource-naming> -->

### Outputs

* Every output includes a meaningful `@description()`
* Conditional resources require conditional output expressions
* Nullable outputs use the `?` type modifier: `output id string? = condition ? resource.id : null`

### Resource Scoping

* Default `targetScope` is `'resourceGroup'`; use `'subscription'` or `'managementGroup'` for cross-resource-group or policy deployments
* Use symbolic references for `scope:` (not ID strings): `scope: resourceGroup('networking-rg')`
* Existing resources use `existing =` syntax
* Cross-resource-group deployments use sub-modules with `scope:` property

## Module Conventions

| Aspect | Main Module | Sub-Module |
| ------ | ----------- | ---------- |
| Location | `bicep/main.bicep` | `bicep/modules/{name}.bicep` |
| Parameters | Include defaults when sensible | No defaults (parent provides all values) |
| Resources | Defined in `main.bicep` | Scoped to specific functionality |
| References | Orchestrates sub-modules | Cannot reference other sub-modules directly |
| Lookups | Receive resource names for `existing` lookups (not IDs) | Inherit scope from parent |

## Type System

### Shared Types

Types define configuration with `@export()` for reuse across modules:

<!-- <example-types> -->
```bicep
@export()
@description('Common deployment configuration.')
type DeploymentConfig = {
  @description('Resource name prefix.')
  prefix: string

  @description('Azure region for resources.')
  location: string

  @description('Environment: dev, test, or prod.')
  environment: 'dev' | 'test' | 'prod'
}

@export()
var deploymentDefaults = {
  prefix: 'myapp'
  location: 'eastus2'
  environment: 'dev'
}
```
<!-- </example-types> -->

Type conventions:

* All types and default values include `@export()` and `@description()`
* Sensitive values include `@secure()`
* Type literals (e.g., `'dev' | 'test' | 'prod'`) constrain parameters with known valid values
* Use `@sealed()` to prevent extra properties on configuration types (strict enforcement)
* Use `@discriminator('propertyName')` for type-safe unions with multiple variants (e.g., `@discriminator('type') type pet = cat | dog`)
* Prefer `resourceInput<>` and `resourceOutput<>` over open `object` types for resource configurations

### Resource-Derived Types

Resource-derived types provide compile-time validation for resource inputs and outputs:

<!-- <example-resource-derived-types> -->
```bicep
@description('Storage account input configuration.')
type storageAccountInput = resourceInput<'Microsoft.Storage/storageAccounts@2023-05-01'>

@description('Storage account output properties.')
type storageAccountOutput = resourceOutput<'Microsoft.Storage/storageAccounts@2023-05-01'>

@description('Accepts any valid storage account configuration.')
param storageConfig storageAccountInput
```
<!-- </example-resource-derived-types> -->

Resource-derived types validate property names and types against the resource schema at compile time.

## User-Defined Functions

<!-- <example-user-defined-functions> -->
```bicep
@export()
@description('Generates a storage account name within the 3-24 character Azure limit.')
func getStorageAccountName(prefix string, environment string, instance string) string =>
  take('st${prefix}${environment}${instance}', 24)
```
<!-- </example-user-defined-functions> -->

Function conventions:

* All exported functions include `@export()` and `@description()`
* Place shared functions in a `functions.bicep` file within the module
* Use lambda syntax (`=>`) for single-expression functions
* Function names follow `camelCase` naming
* Import shared functions using standard syntax: `import { functionName } from 'shared/functions.bicep'`

## Built-in Functions

Bicep 0.36+ includes these additional built-in functions:

| Function | Purpose | Example |
| -------- | ------- | ------- |
| `parseUri(uri)` | Parses URI into components (scheme, host, port, path, query) | `parseUri('https://example.com/path?q=1').host` |
| `buildUri(scheme, host, path?, port?, query?)` | Constructs URI from components | `buildUri('https', 'api.example.com', '/v1', 443)` |
| `loadDirectoryFileInfo(path)` | Gets file metadata from directory at compile time | `loadDirectoryFileInfo('./configs/')` |
| `deployer().userPrincipalName` | Gets the deploying user's principal | `deployer().userPrincipalName` |

## Resource Decorators

Use `@onlyIfNotExists()` for idempotent deployments where existing resources must be preserved. The decorator creates resources only when they do not already exist.

## File Organization

Every Bicep file includes metadata at the top:

```bicep
metadata name = 'Module Name'
metadata description = 'Description of what this module deploys and how it works.'
```

Section order with `/* */` comment headers:

1. Metadata and imports
2. Common parameters
3. Module-specific parameters (grouped by functionality)
4. Variables (when needed)
5. Resources
6. Modules
7. Outputs

## API Versioning

| Guideline | Details |
| --------- | ------- |
| Discover versions | Use `mcp_bicep_experim_list_az_resource_types_for_provider` and `get_az_resource_type_schema` |
| Version consistency | Identical resource types within a file use the same API version |
| New resources | Use the latest stable API version |
| Existing resources | Retain API version unless significant changes warrant upgrade |

## Best Practices

<!-- <reference-best-practices> -->
Best practices retrieved via `mcp_bicep_experim_get_bicep_best_practices`:

| Category | Practice |
| -------- | -------- |
| Modules | Omit `name` field for `module` statements (auto-generated GUID prevents concurrency issues) |
| Parameters | Group logically related values into single `param`/`output` with user-defined types |
| Params Files | Use `.bicepparam` files with variables and expressions instead of `.json` |
| Resources | Use `parent` property instead of `/` in child resource names |
| Resources | Add `existing` resources for parents when defining child resources without parent present |
| Resources | Diagnostic codes `BCP036`, `BCP037`, `BCP081` may indicate hallucinated types/properties |
| Types | Avoid open types (`array`, `object`); prefer user-defined types |
| Types | Use typed variables: `var foo string = 'value'` |
| Syntax | Prefer `.?` with `??` over `!` or verbose ternary: `a.?b ?? c` |

Parameters Files (`.bicepparam`) support variables and expressions:

<!-- <example-bicepparam> -->
```bicep
using 'main.bicep'

var rgPrefix = 'myapp'
param resourceGroupName = '${rgPrefix}-rg'
param tags = { environment: 'prod', costCenter: 'engineering' }
param location = 'eastus2'
```
<!-- </example-bicepparam> -->
<!-- </reference-best-practices> -->

## Experimental Features

> [!CAUTION]
> Experimental features require explicit opt-in via `bicepconfig.json` and may change or be removed in future releases.

| Feature | Config Key | Syntax Example |
| ------- | ---------- | -------------- |
| Testing Framework | `testFramework` | `test storageTest 'tests/storage.tests.bicep' = { params: { location: 'eastus' } }` |
| Assertions | `assertions` | `assert locationValid = location != 'centralus'` |
| Parameter Validation | `userDefinedConstraints` | `@validate(length(value) >= 3 && length(value) <= 24) param storageName string` |

Enable features in `bicepconfig.json`: `{ "experimentalFeaturesEnabled": { "featureName": true } }`

## Validation

* Search codebase for existing Bicep patterns before implementing
* Use MCP tools or Microsoft docs (`learn.microsoft.com/azure/templates/{provider}/{type}`) for schema reference
* Run `az bicep build` and address all diagnostic warnings and errors before committing