Bicep Expert Assistant

Expert guidance for Azure Bicep infrastructure-as-code development, including best practices, resource type discovery, schema retrieval, and Azure Verified Modules.

Core Capabilities

This skill provides four main functions equivalent to the Bicep MCP Server:

1. Best Practices - Comprehensive Bicep authoring guidelines
2. Resource Type Discovery - List Azure resource types with API versions
3. Schema Retrieval - Get detailed schemas for resource types
4. AVM Metadata - Azure Verified Modules information

Instructions

When User Asks About Bicep Best Practices

Provide guidance from the comprehensive best practices below. Focus on the specific area they're asking about (parameters, variables, resources, modules, naming, security, etc.).

When User Needs Resource Types for a Provider

Run the helper script to list resource types:

# PowerShell
./scripts/get-resource-types.ps1 -Provider "Microsoft.Storage"

# Bash
./scripts/get-resource-types.sh "Microsoft.Storage"

Or use Azure CLI directly:

az provider show --namespace Microsoft.Storage --query "resourceTypes[].{Type:resourceType,ApiVersions:apiVersions[0]}" -o table

When User Needs a Resource Schema

Use Bicep CLI to get the schema:

bicep build-params --stdout <<< "param resourceType string = 'Microsoft.Storage/storageAccounts@2023-05-01'"

Or reference the helper script in scripts/get-resource-schema.ps1

When User Asks About Azure Verified Modules

Provide AVM guidance and help them find appropriate modules from the Bicep Public Registry.

Bicep Best Practices Reference

Parameters

1. Use descriptive names: Parameters should have clear, meaningful names that indicate their purpose

   bicepCopy

   // Good
   param storageAccountName string
   param enableHttpsTrafficOnly bool = true
   
   // Avoid
   param san string
   param flag bool
   

2. Provide descriptions: Always add @description() decorator

   bicepCopy

   @description('The name of the storage account. Must be globally unique.')
   param storageAccountName string
   

3. Set safe defaults: Default values should be secure and cost-effective

   bicepCopy

   @description('The SKU for the storage account')
   @allowed(['Standard_LRS', 'Standard_GRS', 'Standard_ZRS', 'Premium_LRS'])
   param storageAccountSku string = 'Standard_LRS'
   

4. Use constraints wisely: Apply @minLength(), @maxLength(), @minValue(), @maxValue()

   bicepCopy

   @minLength(3)
   @maxLength(24)
   param storageAccountName string
   

5. Use @allowed sparingly: Overly restrictive lists block valid deployments as Azure adds new SKUs

6. Secure sensitive parameters: Use @secure() for secrets

   bicepCopy

   @secure()
   param adminPassword string
   

Variables

1. Use for computed values: Variables simplify complex expressions

   bicepCopy

   var storageAccountName = '${prefix}${uniqueString(resourceGroup().id)}'
   

2. Use for repeated values: Define once, use multiple times

   bicepCopy

   var commonTags = {
     environment: environment
     project: projectName
     deployedBy: 'Bicep'
   }
   

3. Typed variables (Bicep 0.26+): Add types for clarity

   bicepCopy

   var instanceCount int = environment == 'prod' ? 5 : 2
   

Resources

1. Use symbolic names without 'name' suffix:

   bicepCopy

   // Good
   resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' = {
   
   // Avoid
   resource storageAccountName 'Microsoft.Storage/storageAccounts@2023-05-01' = {
   

2. Use latest stable API versions: Check for the most recent stable API version

3. Leverage implicit dependencies: Bicep automatically handles dependencies when you reference resources

   bicepCopy

   resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' = {
     name: storageAccountName
     // ...
   }
   
   resource blobService 'Microsoft.Storage/storageAccounts/blobServices@2023-05-01' = {
     parent: storageAccount  // Implicit dependency
     name: 'default'
   }
   

4. Use existing keyword for references:

   bicepCopy

   resource existingVnet 'Microsoft.Network/virtualNetworks@2023-09-01' existing = {
     name: vnetName
   }
   

Child Resources

1. Use nested declaration (preferred):

   bicepCopy

   resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' = {
     name: storageAccountName
     // ...
   
     resource blobService 'blobServices' = {
       name: 'default'
     }
   }
   

2. Or use parent property:

   bicepCopy

   resource blobService 'Microsoft.Storage/storageAccounts/blobServices@2023-05-01' = {
     parent: storageAccount
     name: 'default'
   }
   

Modules

1. Use modules for reusability: Break large templates into focused modules

   bicepCopy

   module storageModule 'modules/storage.bicep' = {
     name: 'storageDeployment'
     params: {
       storageAccountName: storageAccountName
       location: location
     }
   }
   

2. Use Azure Verified Modules: Leverage pre-built, tested modules from the Bicep Registry

   bicepCopy

   module storage 'br/public:avm/res/storage/storage-account:0.9.0' = {
     name: 'storageDeployment'
     params: {
       name: storageAccountName
       location: location
     }
   }
   

3. Version your modules: Always pin to specific versions

Naming Conventions

1. Use camelCase for parameters, variables, and symbolic names
2. Use uniqueString() for unique names:
   bicepCopy

   var storageAccountName = 'st${uniqueString(resourceGroup().id)}'
   

3. Add prefixes for context: Include environment, project, or region prefixes
4. Follow Azure naming constraints: Check character limits and allowed characters

Outputs

1. Expose essential values: Output what consumers need

   bicepCopy

   output storageAccountId string = storageAccount.id
   output primaryEndpoints object = storageAccount.properties.primaryEndpoints
   

2. Never output secrets: Use Key Vault references instead

   bicepCopy

   // WRONG - Never do this
   output connectionString string = storageAccount.listKeys().keys[0].value
   

Security Best Practices

1. Use managed identities instead of credentials where possible
2. Enable HTTPS/TLS for all services
3. Use private endpoints for sensitive resources
4. Apply least privilege with RBAC assignments
5. Enable diagnostic logging and monitoring
6. Use Key Vault for secrets management
7. Enable encryption at rest and in transit

Code Organization

1. File structure:

   Copy

   project/
   ├── main.bicep           # Entry point
   ├── main.bicepparam      # Parameters file
   ├── modules/
   │   ├── networking.bicep
   │   ├── storage.bicep
   │   └── compute.bicep
   └── tests/
       └── main.tests.bicep
   

2. Order of elements in files:

   • Target scope (if not resourceGroup)
   • Parameters
   • Variables
   • Resources
   • Modules
   • Outputs

3. Comments: Use // for single-line, /* */ for multi-line

Azure Verified Modules (AVM)

What is AVM?

Azure Verified Modules are pre-built, tested Bicep modules maintained by Microsoft that follow best practices and the Well-Architected Framework.

Using AVM Modules

// Reference from Bicep Public Registry
module storage 'br/public:avm/res/storage/storage-account:0.9.0' = {
  name: 'storageDeployment'
  params: {
    name: 'mystorageaccount'
    location: location
  }
}

Finding AVM Modules

1. Browse: https://azure.github.io/Azure-Verified-Modules/indexes/bicep/
2. GitHub: https://github.com/Azure/bicep-registry-modules
3. Registry: mcr.microsoft.com for container images

Module Types

• Resource Modules (avm/res/): Single Azure resource with all configurations
• Pattern Modules (avm/ptn/): Multi-resource patterns for common scenarios
• Utility Modules (avm/utl/): Helper types and functions

Common Resource Type Examples

Storage Account

resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' = {
  name: storageAccountName
  location: location
  sku: {
    name: 'Standard_LRS'
  }
  kind: 'StorageV2'
  properties: {
    accessTier: 'Hot'
    supportsHttpsTrafficOnly: true
    minimumTls  }
}

Virtual Network

resource vnet 'Microsoft.Network/virtualNetworks@2023-09-01' = {
  name: vnetName
  location: location
  properties: {
    addressSpace: {
      addressPrefixes: ['10.0.0.0/16']
    }
    subnets: [
      {
        name: 'default'
        properties: {
          addressPrefix: '10.0.1.0/24'
        }
      }
    ]
  }
}

Key Vault

resource keyVault 'Microsoft.KeyVault/vaults@2023-07-01' = {
  name: keyVaultName
  location: location
  properties: {
    tenantId: subscription().tenantId
    sku: {
      family: 'A'
      name: 'standard'
    }
    enableRbacAuthorization: true
    enableSoftDelete: true
    softDeleteRetentionInDays: 90
  }
}

When to Use This Skill

• Writing or reviewing Bicep templates
• Looking up Azure resource types and API versions
• Finding the correct schema for a resource type
• Using Azure Verified Modules
• Applying Bicep best practices
• Deploying Azure infrastructure with IaC

Keywords

bicep, azure, arm, infrastructure as code, iac, resource manager, deployment, template, module, avm, azure verified modules, resource type, schema, api version, storage account, virtual network, key vault, best practices