bicep

# 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:

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

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

Or use Azure CLI directly:
```bash
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:
```bash
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
   ```bicep
   // Good
   param storageAccountName string
   param enableHttpsTrafficOnly bool = true

   // Avoid
   param san string
   param flag bool
   ```

2. **Provide descriptions**: Always add `@description()` decorator
   ```bicep
   @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
   ```bicep
   @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()`
   ```bicep
   @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
   ```bicep
   @secure()
   param adminPassword string
   ```

### Variables

1. **Use for computed values**: Variables simplify complex expressions
   ```bicep
   var storageAccountName = '${prefix}${uniqueString(resourceGroup().id)}'
   ```

2. **Use for repeated values**: Define once, use multiple times
   ```bicep
   var commonTags = {
     environment: environment
     project: projectName
     deployedBy: 'Bicep'
   }
   ```

3. **Typed variables** (Bicep 0.26+): Add types for clarity
   ```bicep
   var instanceCount int = environment == 'prod' ? 5 : 2
   ```

### Resources

1. **Use symbolic names without 'name' suffix**:
   ```bicep
   // 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
   ```bicep
   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**:
   ```bicep
   resource existingVnet 'Microsoft.Network/virtualNetworks@2023-09-01' existing = {
     name: vnetName
   }
   ```

### Child Resources

1. **Use nested declaration** (preferred):
   ```bicep
   resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' = {
     name: storageAccountName
     // ...

     resource blobService 'blobServices' = {
       name: 'default'
     }
   }
   ```

2. **Or use parent property**:
   ```bicep
   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
   ```bicep
   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
   ```bicep
   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**:
   ```bicep
   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
   ```bicep
   output storageAccountId string = storageAccount.id
   output primaryEndpoints object = storageAccount.properties.primaryEndpoints
   ```

2. **Never output secrets**: Use Key Vault references instead
   ```bicep
   // 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**:
   ```
   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

```bicep
// 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
```bicep
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
```bicep
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
```bicep
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