Skip to content

ARM Template Reference

Jump to bottom
Holger Imbery edited this page Sep 19, 2025 · 1 revision

ARM Template Reference

Complete technical reference for the Azure Resource Manager (ARM) template deployment, including interactive configuration options, resource naming conventions, and advanced deployment features.

Interactive Azure Portal Configuration

The ARM template provides a user-friendly deployment experience through the Azure Portal with step-by-step configuration options.

Step 1: Basic Configuration

Project Name (3-15 characters, lowercase letters and numbers only)

  • Base name for all Azure resources
  • Must be globally unique across Azure
  • Example: agentvoice, mycompany, voice2024

Resource Suffix (6 characters, auto-generated)

  • Automatically generated unique identifier
  • Ensures global uniqueness for resource names
  • Combined with project name: agentvoicea1b2c3

Environment

  • dev - Development environment
  • test - Testing/staging environment
  • stage - Staging environment
  • prod - Production environment

Region Selection Choose the Azure region closest to your users for optimal performance:

  • Europe: West Europe, North Europe, UK South
  • North America: East US, West US 2, Central US
  • Asia Pacific: Southeast Asia, East Asia, Australia East

Step 2: App Service Configuration

App Service Plan SKU - Choose based on your performance and scaling needs:

SKU Name Recommended Use Features
F1 Free Development only No custom domains, no SSL, limited compute
D1 Shared Light testing Shared compute, limited
B1 Basic Testing environments Dedicated compute, custom domains, SSL
S1 Standard Production Auto-scaling, deployment slots, custom domains
P1v3 Premium High performance Maximum performance, advanced features

Application Insights (Recommended for Production)

  • Enables advanced monitoring and analytics
  • Tracks application performance and user behavior
  • Required for production troubleshooting
  • Optional for development to control costs

Automated Backup (Requires Basic B1 or higher)

  • Daily automated backups of your application
  • Backup retention configurable
  • Only available on Basic tier and above
  • Recommended for production environments

Step 3: Azure Services Configuration

Communication Services Pricing

  • Free F0: Limited minutes/messages, good for testing
  • Standard S0: Pay-as-you-go, recommended for production

Speech Services Pricing

  • Free F0: Limited transactions, good for testing
  • Standard S0: Pay-as-you-go, recommended for production

Step 4: Optional Configuration

Agent Phone Number (E.164 format, e.g., +1234567890)

  • Phone number for call transfer scenarios
  • Can be configured after deployment
  • Must be in international E.164 format

DirectLine Secret (From Copilot Studio)

  • Bot Framework DirectLine secret from your Copilot Studio agent
  • Can be configured after deployment using PowerShell scripts
  • Required for bot conversation functionality

Health Check API Key

  • Auto-generated if not provided
  • Used to secure monitoring endpoints
  • 32-character secure key for production monitoring

Resource Naming Convention

The ARM template uses a consistent naming convention for all Azure resources:

Naming Pattern

{resource-type}-{projectName}{randomSuffix}-{environment}

Resource Naming Table

Resource Type Naming Pattern Example
Resource Group rg-{project}{suffix}-{env} rg-agentvoicea1b2c3-prod
App Service Plan asp-{project}{suffix}-{env} asp-agentvoicea1b2c3-prod
App Service app-{project}{suffix}-{env} app-agentvoicea1b2c3-prod
Key Vault kv-{project}{suffix}-{env} kv-agentvoicea1b2c3-prod
Communication Services acs-{project}{suffix}-{env} acs-agentvoicea1b2c3-prod
Speech Services cs-{project}{suffix}-{env} cs-agentvoicea1b2c3-prod
Application Insights ai-{project}{suffix}-{env} ai-agentvoicea1b2c3-prod
Log Analytics Workspace law-{project}{suffix}-{env} law-agentvoicea1b2c3-prod

Unique Suffix Generation

  • 6-character random suffix ensures global uniqueness
  • Combines lowercase letters and numbers
  • Automatically generated during deployment
  • Same suffix used across all resources in the deployment

Template Files Reference

Core Template Files

azuredeploy.json - Main ARM template

  • Contains all resource definitions and dependencies
  • Includes parameters, variables, resources, and outputs
  • Supports multiple Azure regions and SKU options
  • Implements security best practices and proper resource relationships

createUiDefinition.json - Interactive Portal Interface

  • Defines the user-friendly deployment form in Azure Portal
  • Provides dropdown menus, validation, and help text
  • Implements conditional visibility for advanced options
  • Generates proper parameter validation and user guidance

azuredeploy.parameters.json - Default Parameter Values

  • Contains default values for template parameters
  • Used for automated deployments and testing
  • Provides example values for all configurable options

metadata.json - Template Metadata

  • Contains template description and categorization
  • Used by Azure Marketplace and template galleries
  • Includes cost estimation tags and compatibility information

Deployment Outputs

The ARM template provides these useful outputs after successful deployment:

Primary Outputs

  • Web App URL: Direct link to your deployed application (https://app-name.azurewebsites.net)
  • Key Vault Name: For configuration management and secret storage
  • Resource Names: Complete list of all created Azure resource names
  • Application Insights Name: For monitoring and analytics (if enabled)

Naming Convention Output

{
  "resourceGroup": "rg-agentvoicea1b2c3-prod",
  "appService": "app-agentvoicea1b2c3-prod", 
  "keyVault": "kv-agentvoicea1b2c3-prod",
  "communicationServices": "acs-agentvoicea1b2c3-prod",
  "cognitiveServices": "cs-agentvoicea1b2c3-prod"
}

Post-Deployment Instructions

The template automatically provides next-step instructions:

  1. Download the latest release package from GitHub
  2. Run setup-configuration.ps1 to configure remaining secrets
  3. Deploy application code using deploy-application.ps1

Cost Analysis and SKU Guidance

Free Tier Limitations (F0 SKUs)

Communication Services F0

  • Limited to specific number of minutes/messages per month
  • Sufficient for development and light testing
  • No SLA guarantees
  • Upgrade to S0 for production workloads

Speech Services F0

  • Limited number of transactions per month
  • May have transaction rate limiting
  • No SLA guarantees
  • Upgrade to S0 for production workloads

App Service F1

  • Limited always-on time (may sleep when inactive)
  • No custom domains or SSL certificates
  • Shared compute resources
  • Not suitable for production workloads

Production Recommendations

App Service: Standard S1 or Higher

  • Dedicated compute resources
  • Auto-scaling capabilities
  • Custom domains and SSL certificates
  • Deployment slots for blue-green deployments
  • 99.95% SLA

Communication Services: S0 (Pay-as-you-go)

  • Unlimited usage with per-transaction billing
  • Full SLA coverage
  • Global scale and reliability
  • Advanced features and API access

Speech Services: S0 (Pay-as-you-go)

  • Unlimited transactions with per-use billing
  • Advanced voice models and customization
  • Full SLA coverage
  • Custom neural voice options

Cost Optimization Strategies

Development Environment

  • Use F0 tiers for all services
  • Disable Application Insights
  • Use F1 App Service for development testing
  • Estimated cost: $0-$10/month

Testing Environment

  • Use F0 for Communication and Speech Services
  • Use B1 for App Service (reliable testing)
  • Enable Application Insights for debugging
  • Estimated cost: $15-$30/month

Production Environment

  • Use S0 for Communication and Speech Services
  • Use S1 or higher for App Service
  • Enable Application Insights and backup
  • Estimated cost: $50-$200/month (depends on usage)

Security Configuration Details

HTTPS Enforcement

  • All App Services automatically configured for HTTPS-only
  • HTTP requests automatically redirected to HTTPS
  • TLS 1.2 minimum version enforced
  • Custom SSL certificates supported

Managed Identity Configuration

  • System-assigned managed identity automatically enabled
  • No passwords or certificates to manage
  • Automatic Azure Active Directory integration
  • Secure access to Azure services without storing credentials

Key Vault Access Policies

The template configures appropriate access policies:

  • App Service Managed Identity: Get, List permissions on secrets
  • User Principal: Full administrative access for configuration
  • RBAC Integration: Supports both access policies and RBAC models

Soft Delete Protection

  • Key Vault soft delete automatically enabled
  • 90-day retention period for deleted secrets
  • Protection against accidental deletion
  • Recovery procedures available through Azure Portal or CLI

Troubleshooting Deployment Issues

Common Deployment Failures

"Name already exists" Error

  • Resource names must be globally unique across Azure
  • Template includes unique suffix to prevent conflicts
  • Try using a different project name if conflicts persist
  • Check if previous deployments in same region used similar names

Permission Errors

  • Ensure you have Contributor access to the subscription/resource group
  • Verify User Access Administrator role for Key Vault access policy assignment
  • Check subscription limits and quotas haven't been exceeded

Region Availability Issues

  • Some SKUs may not be available in all Azure regions
  • Communication Services has limited regional availability
  • Speech Services availability varies by region
  • Use deployment validation to check region compatibility

Key Vault Purge Protection

  • Template automatically configures appropriate purge protection
  • If deployment fails due to soft-deleted Key Vault, wait 90 days or contact support
  • Use unique naming to avoid conflicts with previously deleted resources

Post-Deployment Issues

Application Not Starting

  • Check Application Insights for startup errors and exceptions
  • Verify all required secrets are populated in Key Vault
  • Use show-environment.ps1 script to validate configuration
  • Check App Service logs in Azure Portal

Configuration Errors

  • Ensure DirectLine secret is correctly configured in Key Vault
  • Verify phone number is in proper E.164 format
  • Check that Copilot Studio agent is published and accessible
  • Validate ACS phone number is properly provisioned

Phone Number Issues

  • Follow the phone number acquisition guide in Quick Installation
  • Ensure Event Grid subscription is properly configured
  • Verify webhook endpoint URL is correct
  • Check ACS resource permissions and configuration

Key Vault Access Issues

Problem: "Unauthorized" errors when accessing Key Vault secrets after ARM deployment

Root Causes:

  • ARM deployment failed to set Key Vault access policies correctly
  • Object ID not provided during deployment
  • Additional users need access after deployment
  • Access policies corrupted or overwritten

Solution: Use the troubleshooting script to fix access policies:

# Get your Object ID
$objectId = az ad signed-in-user show --query id -o tsv

# Fix Key Vault access
.\scripts\fix-keyvault-access.ps1 -KeyVaultName "kv-yourproject-prod" -UserObjectId $objectId

When to use this script:

  • ARM deployment didn't set access policies correctly
  • Need to add additional users to Key Vault access after deployment
  • Troubleshooting "unauthorized" errors when accessing Key Vault secrets
  • Emergency access restoration for Key Vault secrets

Script capabilities:

  • Adds comprehensive secret permissions (get, list, set, delete)
  • Validates Object ID format and requirements
  • Provides clear success/failure feedback
  • Includes next steps guidance for verification

Template Customization

Parameter Modification

To customize the template for your organization:

  1. Modify azuredeploy.parameters.json with your default values
  2. Update createUiDefinition.json to customize the deployment interface
  3. Adjust resource configurations in azuredeploy.json as needed
  4. Test deployment in a development subscription before production use

Advanced Customization Options

  • Custom domain configuration for App Service
  • Private endpoint integration for enhanced security
  • Azure DevOps pipeline integration for automated deployments
  • Multi-environment deployment with parameter files

Integration with Infrastructure as Code

  • Bicep conversion: ARM templates can be converted to Bicep format
  • Terraform integration: Use ARM template outputs in Terraform workflows
  • Azure DevOps: Integrate with Azure DevOps pipelines for CI/CD
  • GitHub Actions: Use with GitHub Actions for automated deployment

Compatibility and Requirements

Azure Subscription Requirements

  • Any Azure subscription tier: Free, Pay-as-you-go, Enterprise, CSP
  • Subscription limits: Ensure sufficient quota for chosen SKUs
  • Regional availability: Verify all services available in target region

Tool Requirements

  • Azure Portal: For interactive deployment (recommended)
  • Azure CLI 2.0+: For automated deployments and post-deployment scripts
  • PowerShell 5.1+: For post-deployment configuration scripts
  • Git: For cloning repository and accessing latest release packages

Application Runtime

  • .NET 9.0: Application runs on latest .NET version
  • Windows App Service: Template creates Windows-based App Service
  • WebSocket support: Required for real-time audio streaming
  • HTTPS: All communication encrypted with TLS 1.2+

Related Documentation

For additional information, see these related guides:

Support Resources

ACSforMCS Documentation

Home

Getting Started

Advanced

Development

Quick Actions

External Links

Demo

Clone this wiki locally