Skip to content

README.md

Latest commit

 

History

History
650 lines (507 loc) · 29.3 KB

README.md

File metadata and controls

650 lines (507 loc) · 29.3 KB

Examples - Practical AZD Templates and Configurations

Learning by Example - Organized by Chapter

📍 IMPORTANT: Local vs External Examples
This repository contains 4 complete local examples with full implementations:

  • Microsoft Foundry Models Chat (gpt-4.1 deployment with chat interface)
  • Container Apps (Simple Flask API + Microservices)
  • Database App (Web + SQL Database)
  • Retail Multi-Agent (Enterprise AI Solution)

Additional examples are external references to Azure-Samples repositories that you can clone.

Introduction

This directory provides practical examples and references to help you learn Azure Developer CLI through hands-on practice. The Retail Multi-Agent scenario is a complete, production-ready implementation included in this repository. Additional examples reference official Azure Samples that demonstrate various AZD patterns.

Complexity Rating Legend

  • ⭐ Beginner - Basic concepts, single service, 15-30 minutes
  • ⭐⭐ Intermediate - Multiple services, database integration, 30-60 minutes
  • ⭐⭐⭐ Advanced - Complex architecture, AI integration, 1-2 hours
  • ⭐⭐⭐⭐ Expert - Production-ready, enterprise patterns, 2+ hours

🎯 What's Actually in This Repository

✅ Local Implementation (Ready to Use)

Microsoft Foundry Models Chat Application 🆕

Complete gpt-4.1 deployment with chat interface included in this repo

  • Location: examples/azure-openai-chat/
  • Complexity: ⭐⭐ (Intermediate)
  • What's Included:
    • Complete Microsoft Foundry Models deployment (gpt-4.1)
    • Python command-line chat interface
    • Key Vault integration for secure API keys
    • Bicep infrastructure templates
    • Token usage and cost tracking
    • Rate limiting and error handling

Quick Start:

# Navigate to example
cd examples/azure-openai-chat

# Deploy everything
azd up

# Install dependencies and start chatting
pip install -r src/requirements.txt
python src/chat.py

Technologies: Microsoft Foundry Models, gpt-4.1, Key Vault, Python, Bicep

Container App Examples 🆕

Comprehensive container deployment examples included in this repo

  • Location: examples/container-app/
  • Complexity: ⭐-⭐⭐⭐⭐ (Beginner to Advanced)
  • What's Included:

Quick Start:

# View master guide
cd examples/container-app

# Deploy simple Flask API
cd simple-flask-api
azd up

# Deploy microservices example
cd ../microservices
azd up

Technologies: Azure Container Apps, Docker, Python Flask, Node.js, C#, Go, Application Insights

Retail Multi-Agent Solution 🆕

Complete production-ready implementation included in this repo

  • Location: examples/retail-multiagent-arm-template/
  • Complexity: ⭐⭐⭐⭐ (Advanced)
  • What's Included:
    • Complete ARM deployment template
    • Multi-agent architecture (Customer + Inventory)
    • Microsoft Foundry Models integration
    • AI Search with RAG
    • Comprehensive monitoring
    • One-click deployment script

Quick Start:

cd examples/retail-multiagent-arm-template
./deploy.sh -g myResourceGroup

Technologies: Microsoft Foundry Models, AI Search, Container Apps, Cosmos DB, Application Insights

🔗 External Azure Samples (Clone to Use)

The following examples are maintained in official Azure-Samples repositories. Clone them to explore different AZD patterns:

Simple Applications (Chapters 1-2)

Template Repository Complexity Services
Python Flask API Local: simple-flask-api ⭐ Python, Container Apps, Application Insights
Microservices Local: microservices ⭐⭐⭐⭐ Multi-service, Service Bus, Cosmos DB, SQL
Node.js + MongoDB todo-nodejs-mongo ⭐ Express, Cosmos DB, Container Apps
React + Functions todo-csharp-sql-swa-func ⭐ Static Web Apps, Functions, SQL
Python Flask Container container-apps-store-api ⭐ Python, Container Apps, API

How to use:

# Clone any example
git clone https://github.com/Azure-Samples/todo-nodejs-mongo
cd todo-nodejs-mongo

# Deploy
azd up

AI Application Examples (Chapters 2, 5, 8)

Template Repository Complexity Focus
Microsoft Foundry Models Chat Local: azure-openai-chat ⭐⭐ gpt-4.1 deployment
AI Chat Quickstart get-started-with-ai-chat ⭐⭐ Basic AI chat
AI Agents get-started-with-ai-agents ⭐⭐ Agent framework
Search + OpenAI Demo azure-search-openai-demo ⭐⭐⭐ RAG pattern
Contoso Chat contoso-chat ⭐⭐⭐⭐ Enterprise AI

Database & Advanced Patterns (Chapters 3-8)

Template Repository Complexity Focus
C# + SQL todo-csharp-sql ⭐⭐ Database integration
Python + Cosmos todo-python-mongo-swa-func ⭐⭐ NoSQL serverless
Java Microservices java-microservices-aca-lab ⭐⭐⭐ Multi-service
ML Pipeline mlops-v2 ⭐⭐⭐⭐ MLOps

Learning Goals

By working through these examples, you will:

  • Practice Azure Developer CLI workflows with realistic application scenarios
  • Understand different application architectures and their azd implementations
  • Master Infrastructure as Code patterns for various Azure services
  • Apply configuration management and environment-specific deployment strategies
  • Implement monitoring, security, and scaling patterns in practical contexts
  • Build experience with troubleshooting and debugging real deployment scenarios

Learning Outcomes

Upon completing these examples, you will be able to:

  • Deploy various application types using Azure Developer CLI confidently
  • Adapt provided templates to your own application requirements
  • Design and implement custom infrastructure patterns using Bicep
  • Configure complex multi-service applications with proper dependencies
  • Apply security, monitoring, and performance best practices in real scenarios
  • Troubleshoot and optimize deployments based on practical experience

Directory Structure

Azure Samples AZD Templates (linked externally):
├── todo-nodejs-mongo/       # Node.js Express with MongoDB
├── todo-csharp-sql-swa-func/ # React SPA with Static Web Apps  
├── container-apps-store-api/ # Python Flask containerized app
├── todo-csharp-sql/         # C# Web API with Azure SQL
├── todo-python-mongo-swa-func/ # Python Functions with Cosmos DB
├── java-microservices-aca-lab/ # Java microservices with Container Apps
└── configurations/          # Common configuration examples
    ├── environment-configs/
    ├── bicep-modules/
    └── scripts/

Quick Start Examples

💡 New to AZD? Start with example #1 (Flask API) - it takes ~20 minutes and teaches core concepts.

For Beginners

  1. Container App - Python Flask API (Local) ⭐
    Deploy a simple REST API with scale-to-zero
    Time: 20-25 minutes | Cost: $0-5/month
    You'll Learn: Basic azd workflow, containerization, health probes
    Expected Outcome: Working API endpoint returning "Hello, World!" with monitoring

  2. Simple Web App - Node.js Express ⭐
    Deploy a Node.js Express web application with MongoDB
    Time: 25-35 minutes | Cost: $10-30/month
    You'll Learn: Database integration, environment variables, connection strings
    Expected Outcome: Todo list app with create/read/update/delete functionality

  3. Static Website - React SPA ⭐
    Host a React static website with Azure Static Web Apps
    Time: 20-30 minutes | Cost: $0-10/month
    You'll Learn: Static hosting, serverless functions, CDN deployment
    Expected Outcome: React UI with API backend, automatic SSL, global CDN

For Intermediate Users

  1. Microsoft Foundry Models Chat Application (Local) ⭐⭐
    Deploy gpt-4.1 with chat interface and secure API key management
    Time: 35-45 minutes | Cost: $50-200/month
    You'll Learn: Microsoft Foundry Models deployment, Key Vault integration, token tracking
    Expected Outcome: Working chat application with gpt-4.1 and cost monitoring

  2. Container App - Microservices (Local) ⭐⭐⭐⭐
    Production-ready multi-service architecture
    Time: 45-60 minutes | Cost: $50-150/month
    You'll Learn: Service communication, message queuing, distributed tracing
    Expected Outcome: 2-service system (API Gateway + Product Service) with monitoring

  3. Database App - C# with Azure SQL ⭐⭐
    Web application with C# API and Azure SQL Database
    Time: 30-45 minutes | Cost: $20-80/month
    You'll Learn: Entity Framework, database migrations, connection security
    Expected Outcome: C# API with Azure SQL backend, automatic schema deployment

  4. Serverless Function - Python Azure Functions ⭐⭐
    Python Azure Functions with HTTP triggers and Cosmos DB
    Time: 30-40 minutes | Cost: $10-40/month
    You'll Learn: Event-driven architecture, serverless scaling, NoSQL integration
    Expected Outcome: Function app responding to HTTP requests with Cosmos DB storage

  5. Microservices - Java Spring Boot ⭐⭐⭐
    Multi-service Java application with Container Apps and API gateway
    Time: 60-90 minutes | Cost: $80-200/month
    You'll Learn: Spring Boot deployment, service mesh, load balancing
    Expected Outcome: Multi-service Java system with service discovery and routing

Microsoft Foundry Templates

  1. Microsoft Foundry Models Chat App - Local Example ⭐⭐
    Complete gpt-4.1 deployment with chat interface
    Time: 35-45 minutes | Cost: $50-200/month
    Expected Outcome: Working chat application with token tracking and cost monitoring

  2. Azure Search + OpenAI Demo ⭐⭐⭐
    Intelligent chat application with RAG architecture
    Time: 60-90 minutes | Cost: $100-300/month
    Expected Outcome: RAG-powered chat interface with document search and citations

  3. AI Document Processing ⭐⭐
    Document analysis using Azure AI services
    Time: 40-60 minutes | Cost: $20-80/month
    Expected Outcome: API extracting text, tables, and entities from uploaded documents

  4. Machine Learning Pipeline ⭐⭐⭐⭐
    MLOps workflow with Azure Machine Learning
    Time: 2-3 hours | Cost: $150-500/month
    Expected Outcome: Automated ML pipeline with training, deployment, and monitoring

Real-World Scenarios

Retail Multi-Agent Solution 🆕

Complete Implementation Guide

A comprehensive, production-ready multi-agent customer support solution that demonstrates enterprise-grade AI application deployment with AZD. This scenario provides:

  • Complete Architecture: Multi-agent system with specialized customer service and inventory management agents
  • Production Infrastructure: Multi-region Microsoft Foundry Models deployments, AI Search, Container Apps, and comprehensive monitoring
  • Ready-to-Deploy ARM Template: One-click deployment with multiple configuration modes (Minimal/Standard/Premium)
  • Advanced Features: Red teaming security validation, agent evaluation framework, cost optimization, and troubleshooting guides
  • Real Business Context: Retailer customer support use case with file uploads, search integration, and dynamic scaling

Technologies: Microsoft Foundry Models (gpt-4.1, gpt-4.1-mini), Azure AI Search, Container Apps, Cosmos DB, Application Insights, Document Intelligence, Bing Search API

Complexity: ⭐⭐⭐⭐ (Advanced - Enterprise Production Ready)

Perfect for: AI developers, solution architects, and teams building production multi-agent systems

Quick Start: Deploy the complete solution in under 30 minutes using the included ARM template with ./deploy.sh -g myResourceGroup

📋 Usage Instructions

Prerequisites

Before running any example:

  • ✅ Azure subscription with Owner or Contributor access
  • ✅ Azure Developer CLI installed (Installation Guide)
  • ✅ Docker Desktop running (for container examples)
  • ✅ Appropriate Azure quotas (check example-specific requirements)

💰 Cost Warning: All examples create real Azure resources that incur charges. See individual README files for cost estimates. Remember to run azd down when done to avoid ongoing costs.

Running Examples Locally

  1. Clone or Copy Example

    # Navigate to desired example
cd examples/simple-web-app

  2. Initialize AZD Environment

    # Initialize with existing template
azd init

# Or create new environment
azd env new my-environment

  3. Configure Environment

    # Set required variables
azd env set AZURE_LOCATION eastus
azd env set AZURE_SUBSCRIPTION_ID your-subscription-id

  4. Deploy

    # Deploy infrastructure and application
azd up

  5. Verify Deployment

    # Get service endpoints
azd env get-values

# Test the endpoint (example)
curl https://your-app-url.azurecontainer.io/health

    Expected Success Indicators:

    • ✅ azd up completes without errors
    • ✅ Service endpoint returns HTTP 200
    • ✅ Azure Portal shows "Running" status
    • ✅ Application Insights receiving telemetry

⚠️ Issues? See Common Issues for deployment troubleshooting

Adapting Examples

Each example includes:

  • README.md - Detailed setup and customization instructions
  • azure.yaml - AZD configuration with comments
  • infra/ - Bicep templates with parameter explanations
  • src/ - Sample application code
  • scripts/ - Helper scripts for common tasks

🎯 Learning Objectives

Example Categories

Basic Deployments

  • Single-service applications
  • Simple infrastructure patterns
  • Basic configuration management
  • Cost-effective development setups

Advanced Scenarios

  • Multi-service architectures
  • Complex networking configurations
  • Database integration patterns
  • Security and compliance implementations

Production-Ready Patterns

  • High availability configurations
  • Monitoring and observability
  • CI/CD integration
  • Disaster recovery setups

📖 Example Descriptions

Simple Web App - Node.js Express

Technologies: Node.js, Express, MongoDB, Container Apps
Complexity: Beginner
Concepts: Basic deployment, REST API, NoSQL database integration

Static Website - React SPA

Technologies: React, Azure Static Web Apps, Azure Functions, Cosmos DB
Complexity: Beginner
Concepts: Static hosting, serverless backend, modern web development

Container App - Python Flask

Technologies: Python Flask, Docker, Container Apps, Container Registry, Application Insights
Complexity: Beginner
Concepts: Containerization, REST API, scale-to-zero, health probes, monitoring
Location: Local Example

Container App - Microservices Architecture

Technologies: Python, Node.js, C#, Go, Service Bus, Cosmos DB, Azure SQL, Container Apps
Complexity: Advanced
Concepts: Multi-service architecture, service communication, message queuing, distributed tracing
Location: Local Example

Database App - C# with Azure SQL

Technologies: C# ASP.NET Core, Azure SQL Database, App Service
Complexity: Intermediate
Concepts: Entity Framework, database connections, web API development

Serverless Function - Python Azure Functions

Technologies: Python, Azure Functions, Cosmos DB, Static Web Apps
Complexity: Intermediate
Concepts: Event-driven architecture, serverless computing, full-stack development

Microservices - Java Spring Boot

Technologies: Java Spring Boot, Container Apps, Service Bus, API Gateway
Complexity: Intermediate
Concepts: Microservices communication, distributed systems, enterprise patterns

Microsoft Foundry Examples

Microsoft Foundry Models Chat App

Technologies: Microsoft Foundry Models, Cognitive Search, App Service
Complexity: Intermediate
Concepts: RAG architecture, vector search, LLM integration

AI Document Processing

Technologies: Azure AI Document Intelligence, Storage, Functions
Complexity: Intermediate
Concepts: Document analysis, OCR, data extraction

Machine Learning Pipeline

Technologies: Azure ML, MLOps, Container Registry
Complexity: Advanced
Concepts: Model training, deployment pipelines, monitoring

🛠 Configuration Examples

The configurations/ directory contains reusable components:

Environment Configurations

  • Development environment settings
  • Staging environment configurations
  • Production-ready configurations
  • Multi-region deployment setups

Bicep Modules

  • Reusable infrastructure components
  • Common resource patterns
  • Security-hardened templates
  • Cost-optimized configurations

Helper Scripts

  • Environment setup automation
  • Database migration scripts
  • Deployment validation tools
  • Cost monitoring utilities

🔧 Customization Guide

Adapting Examples for Your Use Case

  1. Review Prerequisites

    • Check Azure service requirements
    • Verify subscription limits
    • Understand cost implications

  2. Modify Configuration

    • Update azure.yaml service definitions
    • Customize Bicep templates
    • Adjust environment variables

  3. Test Thoroughly

    • Deploy to development environment first
    • Validate functionality
    • Test scaling and performance

  4. Security Review

    • Review access controls
    • Implement secrets management
    • Enable monitoring and alerting

📊 Comparison Matrix

Example Services Database Auth Monitoring Complexity
Microsoft Foundry Models Chat (Local) 2 ❌ Key Vault Full ⭐⭐
Python Flask API (Local) 1 ❌ Basic Full ⭐
Microservices (Local) 5+ ✅ Enterprise Advanced ⭐⭐⭐⭐
Node.js Express Todo 2 ✅ Basic Basic ⭐
React SPA + Functions 3 ✅ Basic Full ⭐
Python Flask Container 2 ❌ Basic Full ⭐
C# Web API + SQL 2 ✅ Full Full ⭐⭐
Python Functions + SPA 3 ✅ Full Full ⭐⭐
Java Microservices 5+ ✅ Full Full ⭐⭐
Microsoft Foundry Models Chat 3 ✅ Full Full ⭐⭐⭐
AI Document Processing 2 ❌ Basic Full ⭐⭐
ML Pipeline 4+ ✅ Full Full ⭐⭐⭐⭐
Retail Multi-Agent (Local) 8+ ✅ Enterprise Advanced ⭐⭐⭐⭐

🎓 Learning Path

Recommended Progression

  1. Start with Simple Web App

    • Learn basic AZD concepts
    • Understand deployment workflow
    • Practice environment management

  2. Try Static Website

    • Explore different hosting options
    • Learn about CDN integration
    • Understand DNS configuration

  3. Move to Container App

    • Learn containerization basics
    • Understand scaling concepts
    • Practice with Docker

  4. Add Database Integration

    • Learn database provisioning
    • Understand connection strings
    • Practice secrets management

  5. Explore Serverless

    • Understand event-driven architecture
    • Learn about triggers and bindings
    • Practice with APIs

  6. Build Microservices

    • Learn service communication
    • Understand distributed systems
    • Practice complex deployments

🔍 Finding the Right Example

By Technology Stack

By Architecture Pattern

By Complexity Level

  • Beginner: Python Flask API (Local), Node.js Express Todo, React SPA + Functions
  • Intermediate: Microsoft Foundry Models Chat (Local), C# Web API + SQL, Python Functions + SPA, Java Microservices, Microsoft Foundry Models Chat App, AI Document Processing
  • Advanced: ML Pipeline
  • Enterprise Production-Ready: Microservices (Local) (Multi-service with message queuing), Retail Multi-Agent Solution (Complete multi-agent system with ARM template deployment)

📚 Additional Resources

Documentation Links

Community Examples

Best Practices

🤝 Contributing Examples

Have a useful example to share? We welcome contributions!

Submission Guidelines

  1. Follow the established directory structure
  2. Include comprehensive README.md
  3. Add comments to configuration files
  4. Test thoroughly before submitting
  5. Include cost estimates and prerequisites

Example Template Structure

example-name/
├── README.md           # Detailed setup instructions
├── azure.yaml          # AZD configuration
├── infra/              # Infrastructure templates
│   ├── main.bicep
│   └── modules/
├── src/                # Application source code
├── scripts/            # Helper scripts
├── .gitignore         # Git ignore rules
└── docs/              # Additional documentation

Pro Tip: Start with the simplest example that matches your technology stack, then gradually work your way up to more complex scenarios. Each example builds on concepts from the previous ones!

🚀 Ready to Start?

Your Learning Path

  1. Complete Beginner? → Start with Flask API (⭐, 20 mins)
  2. Have Basic AZD Knowledge? → Try Microservices (⭐⭐⭐⭐, 60 mins)
  3. Building AI Apps? → Start with Microsoft Foundry Models Chat (⭐⭐, 35 mins) or explore Retail Multi-Agent (⭐⭐⭐⭐, 2+ hours)
  4. Need Specific Tech Stack? → Use Finding the Right Example section above

Next Steps

  • ✅ Review Prerequisites above
  • ✅ Choose an example matching your skill level (see Complexity Legend)
  • ✅ Read the example's README thoroughly before deploying
  • ✅ Set a reminder to run azd down after testing
  • ✅ Share your experience via GitHub Issues or Discussions

Need Help?

Navigation

Last Updated: November 2025 | Report Issues | Contribute Examples