Bicep Module Create

Purpose

This skill defines a production-ready workflow for creating reusable Bicep modules following Azure Verified Modules (AVM) conventions with typed parameters, conditional deployments, outputs, and testing. It enforces full six-phase coverage, WAF-aligned quality gates, and reproducible delivery outcomes.

Inputs

Prerequisites

• Bicep CLI installed (az bicep install or standalone).
• Azure subscription for deployment validation.
• Understanding of the target resource's ARM API schema.
• AVM module index reviewed for existing modules.

Full Phases Coverage

Phase 1: Discover

• Check AVM module index — does a verified module already exist?
• Review the ARM API spec for the target resource type.
• Identify required vs optional properties.
• Determine deployment scope (resourceGroup, subscription, managementGroup).

Phase 2: Design

• Define the module interface:

// modules/cognitive-services.bicep
@description('Name of the Cognitive Services account')
param name string

@description('Location for the resource')
param location string = resourceGroup().location

@description('SKU name')
@allowed(['F0', 'S0', 'S1'])
param skuName string = 'S0'

@description('Enable public network access')
param publicNetworkAccess bool = false

@description('Tags to apply')
param tags object = {}

• Define outputs for downstream consumers:

output id string = account.id
output endpoint string = account.properties.endpoint
output principalId string = account.identity.principalId

Phase 3: Implement

• Create the module file with full resource definition:

resource account 'Microsoft.CognitiveServices/accounts@2024-10-01' = {
  name: name
  location: location
  kind: 'OpenAI'
  sku: { name: skuName }
  tags: tags
  identity: { type: 'SystemAssigned' }
  properties: {
    customSubDomainName: name
    publicNetworkAccess: publicNetworkAccess ? 'Enabled' : 'Disabled'
    networkAcls: {
      defaultAction: publicNetworkAccess ? 'Allow' : 'Deny'
    }
  }
}

• Add conditional resources (private endpoint, diagnostic settings).
• Create a main.bicep consumer example showing module invocation.
• Add bicepconfig.json with linting rules.

Phase 4: Validate

• Run az bicep build — zero errors, zero warnings.
• Run az bicep lint with strict rules enabled.
• Execute az deployment group what-if to validate against a real subscription.
• Test with minimum parameters and with all optional parameters.

az deployment group what-if \
  --resource-group rg-test \
  --template-file modules/cognitive-services.bicep \
  --parameters name=test-oai skuName=S0

Phase 5: Deploy

• Deploy to a dev resource group and verify resource creation.
• Validate outputs are correct (endpoint, principalId).
• Test module consumption from a parent template.
• Publish to internal Bicep registry if applicable.

Phase 6: Operate

• Version the module and track breaking changes in CHANGELOG.md.
• Monitor for new API versions — update @api-version annually.
• Review parameter defaults when Azure pricing or features change.
• Run automated deployment tests in CI/CD pipeline.

WAF-Aligned Quality Gates

Reliability

• Retry, timeout, and fallback behavior are validated.
• Dependency health checks and alerting are active.
• Degraded operation paths are tested and documented.

Security

• Secrets are externalized via Key Vault or Managed Identity.
• Least-privilege RBAC is enforced on all resources.
• Audit trails capture all critical operations.

Cost Optimization

• Resource sizing is evidence-based and right-sized.
• Expensive operations are measured and optimized.
• Budget alerts are configured per resource group.

Operational Excellence

• CI/CD pipelines validate before every deployment.
• Runbooks and rollback procedures are current and tested.
• Metrics and traces support rapid root-cause diagnosis.

Performance Efficiency

• SLO targets are explicit, monitored, and alerted.
• Hot paths are benchmarked under realistic load.
• Operational overhead is minimized.

Responsible AI

• Content safety filters are applied where AI is used.
• Model outputs are transparent and explainable to users.
• Human escalation exists for high-impact or ambiguous decisions.

Deliverables

Completion Checklist

• [ ] Phase 1 discovery documented with scope and success criteria.
• [ ] Phase 2 design approved with tradeoff rationale.
• [ ] Phase 3 implementation reviewed and merged.
• [ ] Phase 4 validation passed with evidence collected.
• [ ] Phase 5 staged rollout completed through all environments.
• [ ] Phase 6 operate handoff accepted by operations team.

Troubleshooting

Symptom: Deployment fails in staging but works in dev

• Compare environment configuration (feature flags, network rules, RBAC).
• Verify service principal permissions match between environments.
• Check for region-specific resource availability differences.

Symptom: Quality metrics degrade after deployment

• Compare baseline metrics with post-deployment measurements.
• Check for configuration drift between environments.
• Roll back and isolate the change that caused degradation.

Symptom: Monitoring gaps or missing telemetry

• Verify instrumentation is deployed to all service instances.
• Check sampling rates — increase temporarily for debugging.
• Confirm diagnostic settings route to the correct Log Analytics workspace.

Definition of Done

The skill is complete when all six phases have objective evidence, quality gates pass, and another engineer can reproduce outcomes without tribal knowledge.

Metadata

• Category: Infrastructure
• WAF Pillars: Reliability, Security, Operational Excellence
• Maintainer: FAI Skill System
• Review cadence: Quarterly and after major platform changes