AZD Basics - Understanding Azure Developer CLI

AZD Basics - Core Concepts and Fundamentals

Chapter Navigation:

📚 Course Home: AZD For Beginners
📖 Current Chapter: Chapter 1 - Foundation & Quick Start
⬅️ Previous: Course Overview
➡️ Next: Installation & Setup
🚀 Next Chapter: Chapter 2: AI-First Development

Introduction

This lesson introduces you to Azure Developer CLI (azd), a powerful command-line tool that accelerates your journey from local development to Azure deployment. You'll learn the fundamental concepts, core features, and understand how azd simplifies cloud-native application deployment.

Learning Goals

By the end of this lesson, you will:

Understand what Azure Developer CLI is and its primary purpose
Learn the core concepts of templates, environments, and services
Explore key features including template-driven development and Infrastructure as Code
Understand the azd project structure and workflow
Be prepared to install and configure azd for your development environment

Learning Outcomes

After completing this lesson, you will be able to:

Explain the role of azd in modern cloud development workflows
Identify the components of an azd project structure
Describe how templates, environments, and services work together
Understand the benefits of Infrastructure as Code with azd
Recognize different azd commands and their purposes

What is Azure Developer CLI (azd)?

Azure Developer CLI (azd) is a command-line tool designed to accelerate your journey from local development to Azure deployment. It simplifies the process of building, deploying, and managing cloud-native applications on Azure.

What Can You Deploy with azd?

azd supports a wide range of workloads—and the list keeps growing. Today, you can use azd to deploy:

Workload Type	Examples	Same Workflow?
Traditional applications	Web apps, REST APIs, static sites	✅ `azd up`
Services and microservices	Container Apps, Function Apps, multi-service backends	✅ `azd up`
AI-powered applications	Chat apps with Microsoft Foundry Models, RAG solutions with AI Search	✅ `azd up`
Intelligent agents	Foundry-hosted agents, multi-agent orchestrations	✅ `azd up`

The key insight is that the azd lifecycle stays the same regardless of what you're deploying. You initialize a project, provision infrastructure, deploy your code, monitor your app, and clean up—whether it's a simple website or a sophisticated AI agent.

This continuity is by design. azd treats AI capabilities as another kind of service your application can use, not as something fundamentally different. A chat endpoint backed by Microsoft Foundry Models is, from azd's perspective, just another service to configure and deploy.

🎯 Why Use AZD? A Real-World Comparison

Let's compare deploying a simple web app with database:

❌ WITHOUT AZD: Manual Azure Deployment (30+ minutes)

# Step 1: Create resource group
az group create --name myapp-rg --location eastus

# Step 2: Create App Service Plan
az appservice plan create --name myapp-plan \
  --resource-group myapp-rg \
  --sku B1 --is-linux

# Step 3: Create Web App
az webapp create --name myapp-web-unique123 \
  --resource-group myapp-rg \
  --plan myapp-plan \
  --runtime "NODE:18-lts"

# Step 4: Create Cosmos DB account (10-15 minutes)
az cosmosdb create --name myapp-cosmos-unique123 \
  --resource-group myapp-rg \
  --kind MongoDB

# Step 5: Create database
az cosmosdb mongodb database create \
  --account-name myapp-cosmos-unique123 \
  --resource-group myapp-rg \
  --name tododb

# Step 6: Create collection
az cosmosdb mongodb collection create \
  --account-name myapp-cosmos-unique123 \
  --resource-group myapp-rg \
  --database-name tododb \
  --name todos

# Step 7: Get connection string
CONN_STR=$(az cosmosdb keys list \
  --name myapp-cosmos-unique123 \
  --resource-group myapp-rg \
  --type connection-strings \
  --query "connectionStrings[0].connectionString" -o tsv)

# Step 8: Configure app settings
az webapp config appsettings set \
  --name myapp-web-unique123 \
  --resource-group myapp-rg \
  --settings MONGODB_URI="$CONN_STR"

# Step 9: Enable logging
az webapp log config --name myapp-web-unique123 \
  --resource-group myapp-rg \
  --application-logging filesystem \
  --detailed-error-messages true

# Step 10: Set up Application Insights
az monitor app-insights component create \
  --app myapp-insights \
  --location eastus \
  --resource-group myapp-rg

# Step 11: Link App Insights to Web App
INSTRUMENTATION_KEY=$(az monitor app-insights component show \
  --app myapp-insights \
  --resource-group myapp-rg \
  --query "instrumentationKey" -o tsv)

az webapp config appsettings set \
  --name myapp-web-unique123 \
  --resource-group myapp-rg \
  --settings APPINSIGHTS_INSTRUMENTATIONKEY="$INSTRUMENTATION_KEY"

# Step 12: Build application locally
npm install
npm run build

# Step 13: Create deployment package
zip -r app.zip . -x "*.git*" "node_modules/*"

# Step 14: Deploy application
az webapp deployment source config-zip \
  --resource-group myapp-rg \
  --name myapp-web-unique123 \
  --src app.zip

# Step 15: Wait and pray it works 🙏
# (No automated validation, manual testing required)

Problems:

❌ 15+ commands to remember and execute in order
❌ 30-45 minutes of manual work
❌ Easy to make mistakes (typos, wrong parameters)
❌ Connection strings exposed in terminal history
❌ No automated rollback if something fails
❌ Hard to replicate for team members
❌ Different every time (not reproducible)

✅ WITH AZD: Automated Deployment (5 commands, 10-15 minutes)

# Step 1: Initialize from template
azd init --template todo-nodejs-mongo

# Step 2: Authenticate
azd auth login

# Step 3: Create environment
azd env new dev

# Step 4: Preview changes (optional but recommended)
azd provision --preview

# Step 5: Deploy everything
azd up

# ✨ Done! Everything is deployed, configured, and monitored

Benefits:

✅ 5 commands vs. 15+ manual steps
✅ 10-15 minutes total time (mostly waiting for Azure)
✅ Fewer manual mistakes - consistent, template-driven workflow
✅ Secure secret handling - many templates use Azure-managed secret storage
✅ Repeatable deployments - same workflow every time
✅ Fully reproducible - same result every time
✅ Team-ready - anyone can deploy with same commands
✅ Infrastructure as Code - version controlled Bicep templates
✅ Built-in monitoring - Application Insights configured automatically

📊 Time & Error Reduction

Metric	Manual Deployment	AZD Deployment	Improvement
Commands	15+	5	67% fewer
Time	30-45 min	10-15 min	60% faster
Error Rate	~40%	<5%	88% reduction
Consistency	Low (manual)	100% (automated)	Perfect
Team Onboarding	2-4 hours	30 minutes	75% faster
Rollback Time	30+ min (manual)	2 min (automated)	93% faster

Core Concepts

Templates

Templates are the foundation of azd. They contain:

Application code - Your source code and dependencies
Infrastructure definitions - Azure resources defined in Bicep or Terraform
Configuration files - Settings and environment variables
Deployment scripts - Automated deployment workflows

Environments

Environments represent different deployment targets:

Development - For testing and development
Staging - Pre-production environment
Production - Live production environment

Each environment maintains its own:

Azure resource group
Configuration settings
Deployment state

Services

Services are the building blocks of your application:

Frontend - Web applications, SPAs
Backend - APIs, microservices
Database - Data storage solutions
Storage - File and blob storage

Key Features

1. Template-Driven Development

# Browse available templates
azd template list

# Initialize from a template
azd init --template <template-name>

2. Infrastructure as Code

Bicep - Azure's domain-specific language
Terraform - Multi-cloud infrastructure tool
ARM Templates - Azure Resource Manager templates

3. Integrated Workflows

# Complete deployment workflow
azd up            # Provision + Deploy this is hands off for first time setup

# 🧪 NEW: Preview infrastructure changes before deployment (SAFE)
azd provision --preview    # Simulate infrastructure deployment without making changes

azd provision     # Create Azure resources if you update the infrastructure use this
azd deploy        # Deploy application code or redeploy application code once update
azd down          # Clean up resources

🛡️ Safe Infrastructure Planning with Preview

The azd provision --preview command is a game-changer for safe deployments:

Dry-run analysis - Shows what will be created, modified, or deleted
Zero risk - No actual changes are made to your Azure environment
Team collaboration - Share preview results before deployment
Cost estimation - Understand resource costs before commitment

# Example preview workflow
azd provision --preview           # See what will change
# Review the output, discuss with team
azd provision                     # Apply changes with confidence

📊 Visual: AZD Development Workflow

graph LR
    A[azd init] -->|Initialize project| B[azd auth login]
    B -->|Authenticate| C[azd env new]
    C -->|Create environment| D{First deployment?}
    D -->|Yes| E[azd up]
    D -->|No| F[azd provision --preview]
    F -->|Review changes| G[azd provision]
    E -->|Provisions & deploys| H[Resources running]
    G -->|Updates infrastructure| H
    H -->|Monitor| I[azd monitor]
    I -->|Make code changes| J[azd deploy]
    J -->|Redeploy code only| H
    H -->|Cleanup| K[azd down]
    
    style A fill:#e1f5fe
    style E fill:#c8e6c9
    style F fill:#fff9c4
    style H fill:#c5e1a5
    style K fill:#ffcdd2

Workflow Explanation:

Init - Start with template or new project
Auth - Authenticate with Azure
Environment - Create isolated deployment environment
Preview - 🆕 Always preview infrastructure changes first (safe practice)
Provision - Create/update Azure resources
Deploy - Push your application code
Monitor - Observe application performance
Iterate - Make changes and redeploy code
Cleanup - Remove resources when done

4. Environment Management

# Create and manage environments
azd env new <environment-name>
azd env select <environment-name>
azd env list

5. Extensions and AI Commands

azd uses an extension system to add capabilities beyond the core CLI. This is especially useful for AI workloads:

# List available extensions
azd extension list

# Install the Foundry agents extension
azd extension install azure.ai.agents

# Initialize an AI agent project from a manifest
azd ai agent init -m agent-manifest.yaml

# Start the MCP server for AI-assisted development (Alpha)
azd mcp start

Extensions are covered in detail in Chapter 2: AI-First Development and the AZD AI CLI Commands reference.

📁 Project Structure

A typical azd project structure:

my-app/
├── .azd/                    # azd configuration
│   └── config.json
├── .azure/                  # Azure deployment artifacts
├── .devcontainer/          # Development container config
├── .github/workflows/      # GitHub Actions
├── .vscode/               # VS Code settings
├── infra/                 # Infrastructure code
│   ├── main.bicep        # Main infrastructure template
│   ├── main.parameters.json
│   └── modules/          # Reusable modules
├── src/                  # Application source code
│   ├── api/             # Backend services
│   └── web/             # Frontend application
├── azure.yaml           # azd project configuration
└── README.md

🔧 Configuration Files

azure.yaml

The main project configuration file:

name: my-awesome-app
metadata:
  template: my-template@1.0.0

services:
  web:
    project: ./src/web
    language: js
    host: appservice
  api:
    project: ./src/api
    language: js
    host: appservice

hooks:
  preprovision:
    shell: pwsh
    run: echo "Preparing to provision..."

.azure/config.json

Environment-specific configuration:

{
  "version": 1,
  "defaultEnvironment": "dev",
  "environments": {
    "dev": {
      "subscriptionId": "your-subscription-id",
      "location": "eastus"
    }
  }
}

🎪 Common Workflows with Hands-On Exercises

💡 Learning Tip: Follow these exercises in order to build your AZD skills progressively.

🎯 Exercise 1: Initialize Your First Project

Goal: Create an AZD project and explore its structure

Steps:

# Use a proven template
azd init --template todo-nodejs-mongo

# Explore the generated files
ls -la  # View all files including hidden ones

# Key files created:
# - azure.yaml (main config)
# - infra/ (infrastructure code)
# - src/ (application code)

✅ Success: You have azure.yaml, infra/, and src/ directories

🎯 Exercise 2: Deploy to Azure

Goal: Complete end-to-end deployment

Steps:

# 1. Authenticate
az login && azd auth login

# 2. Create environment
azd env new dev
azd env set AZURE_LOCATION eastus

# 3. Preview changes (RECOMMENDED)
azd provision --preview

# 4. Deploy everything
azd up

# 5. Verify deployment
azd show    # View your app URL

Expected Time: 10-15 minutes
✅ Success: Application URL opens in browser

🎯 Exercise 3: Multiple Environments

Goal: Deploy to dev and staging

Steps:

# Already have dev, create staging
azd env new staging
azd env set AZURE_LOCATION westus2
azd up

# Switch between them
azd env list
azd env select dev

✅ Success: Two separate resource groups in Azure Portal

🛡️ Clean Slate: `azd down --force --purge`

When you need to completely reset:

azd down --force --purge

What it does:

--force: No confirmation prompts
--purge: Deletes all local state and Azure resources

Use when:

Deployment failed mid-way
Switching projects
Need fresh start

🎪 Original Workflow Reference

Starting a New Project

# Method 1: Use existing template
azd init --template todo-nodejs-mongo

# Method 2: Start from scratch
azd init

# Method 3: Use current directory
azd init .

Development Cycle

# Set up development environment
azd auth login
azd env new dev
azd env select dev

# Deploy everything
azd up

# Make changes and redeploy
azd deploy

# Clean up when done
azd down --force --purge # command in the Azure Developer CLI is a **hard reset** for your environment—especially useful when you're troubleshooting failed deployments, cleaning up orphaned resources, or prepping for a fresh redeploy.

Understanding `azd down --force --purge`

The azd down --force --purge command is a powerful way to completely tear down your azd environment and all associated resources. Here's a breakdown of what each flag does:

--force

Skips confirmation prompts.
Useful for automation or scripting where manual input isn’t feasible.
Ensures the teardown proceeds without interruption, even if the CLI detects inconsistencies.

--purge

Deletes all associated metadata, including: Environment state Local .azure folder Cached deployment info Prevents azd from "remembering" previous deployments, which can cause issues like mismatched resource groups or stale registry references.

Why use both?

When you've hit a wall with azd up due to lingering state or partial deployments, this combo ensures a clean slate.

It’s especially helpful after manual resource deletions in the Azure portal or when switching templates, environments, or resource group naming conventions.

Managing Multiple Environments

# Create staging environment
azd env new staging
azd env select staging
azd up

# Switch back to dev
azd env select dev

# Compare environments
azd env list

🔐 Authentication and Credentials

Understanding authentication is crucial for successful azd deployments. Azure uses multiple authentication methods, and azd leverages the same credential chain used by other Azure tools.

Azure CLI Authentication (`az login`)

Before using azd, you need to authenticate with Azure. The most common method is using Azure CLI:

# Interactive login (opens browser)
az login

# Login with specific tenant
az login --tenant <tenant-id>

# Login with service principal
az login --service-principal -u <app-id> -p <password> --tenant <tenant-id>

# Check current login status
az account show

# List available subscriptions
az account list --output table

# Set default subscription
az account set --subscription <subscription-id>

Authentication Flow

Interactive Login: Opens your default browser for authentication
Device Code Flow: For environments without browser access
Service Principal: For automation and CI/CD scenarios
Managed Identity: For Azure-hosted applications

DefaultAzureCredential Chain

DefaultAzureCredential is a credential type that provides a simplified authentication experience by automatically trying multiple credential sources in a specific order:

Credential Chain Order

graph TD
    A[DefaultAzureCredential] --> B[Environment Variables]
    B --> C[Workload Identity]
    C --> D[Managed Identity]
    D --> E[Visual Studio]
    E --> F[Visual Studio Code]
    F --> G[Azure CLI]
    G --> H[Azure PowerShell]
    H --> I[Interactive Browser]

1. Environment Variables

# Set environment variables for service principal
export AZURE_CLIENT_ID="<app-id>"
export AZURE_CLIENT_SECRET="<password>"
export AZURE_TENANT_ID="<tenant-id>"

2. Workload Identity (Kubernetes/GitHub Actions)

Used automatically in:

Azure Kubernetes Service (AKS) with Workload Identity
GitHub Actions with OIDC federation
Other federated identity scenarios

3. Managed Identity

For Azure resources like:

Virtual Machines
App Service
Azure Functions
Container Instances

# Check if running on Azure resource with managed identity
az account show --query "user.type" --output tsv
# Returns: "servicePrincipal" if using managed identity

4. Developer Tools Integration

Visual Studio: Automatically uses signed-in account
VS Code: Uses Azure Account extension credentials
Azure CLI: Uses az login credentials (most common for local development)

AZD Authentication Setup

# Method 1: Use Azure CLI (Recommended for development)
az login
azd auth login  # Uses existing Azure CLI credentials

# Method 2: Direct azd authentication
azd auth login --use-device-code  # For headless environments

# Method 3: Check authentication status
azd auth login --check-status

# Method 4: Logout and re-authenticate
azd auth logout
azd auth login

Authentication Best Practices

For Local Development

# 1. Login with Azure CLI
az login

# 2. Verify correct subscription
az account show
az account set --subscription "Your Subscription Name"

# 3. Use azd with existing credentials
azd auth login

For CI/CD Pipelines

# GitHub Actions example
- name: Azure Login
  uses: azure/login@v1
  with:
    creds: ${{ secrets.AZURE_CREDENTIALS }}

- name: Deploy with azd
  run: |
    azd auth login --client-id ${{ secrets.AZURE_CLIENT_ID }} \
                    --client-secret ${{ secrets.AZURE_CLIENT_SECRET }} \
                    --tenant-id ${{ secrets.AZURE_TENANT_ID }}
    azd up --no-prompt

For Production Environments

Use Managed Identity when running on Azure resources
Use Service Principal for automation scenarios
Avoid storing credentials in code or configuration files
Use Azure Key Vault for sensitive configuration

Common Authentication Issues and Solutions

Issue: "No subscription found"

# Solution: Set default subscription
az account list --output table
az account set --subscription "<subscription-id>"
azd env set AZURE_SUBSCRIPTION_ID "<subscription-id>"

Issue: "Insufficient permissions"

# Solution: Check and assign required roles
az role assignment list --assignee $(az account show --query user.name --output tsv)

# Common required roles:
# - Contributor (for resource management)
# - User Access Administrator (for role assignments)

Issue: "Token expired"

# Solution: Re-authenticate
az logout
az login
azd auth logout
azd auth login

Authentication in Different Scenarios

Local Development

# Personal development account
az login
azd auth login

Team Development

# Use specific tenant for organization
az login --tenant contoso.onmicrosoft.com
azd auth login

Multi-tenant Scenarios

# Switch between tenants
az login --tenant tenant1.onmicrosoft.com
# Deploy to tenant 1
azd up

az login --tenant tenant2.onmicrosoft.com  
# Deploy to tenant 2
azd up

Security Considerations

Credential Storage: Never store credentials in source code
Scope Limitation: Use least-privilege principle for service principals
Token Rotation: Regularly rotate service principal secrets
Audit Trail: Monitor authentication and deployment activities
Network Security: Use private endpoints when possible

Troubleshooting Authentication

# Debug authentication issues
azd auth login --check-status
az account show
az account get-access-token

# Common diagnostic commands
whoami                          # Current user context
az ad signed-in-user show      # Azure AD user details
az group list                  # Test resource access

Understanding `azd down --force --purge`

Discovery

azd template list              # Browse templates
azd template show <template>   # Template details
azd init --help               # Initialization options

Project Management

azd show                     # Project overview
azd env list                # Available environments and selected default
azd config show            # Configuration settings

Monitoring

azd monitor                  # Open Azure portal monitoring
azd monitor --logs           # View application logs
azd monitor --live           # View live metrics
azd pipeline config          # Set up CI/CD

Best Practices

1. Use Meaningful Names

# Good
azd env new production-east
azd init --template web-app-secure

# Avoid
azd env new env1
azd init --template template1

2. Leverage Templates

Start with existing templates
Customize for your needs
Create reusable templates for your organization

3. Environment Isolation

Use separate environments for dev/staging/prod
Never deploy directly to production from local machine
Use CI/CD pipelines for production deployments

4. Configuration Management

Use environment variables for sensitive data
Keep configuration in version control
Document environment-specific settings

Learning Progression

Beginner (Week 1-2)

Install azd and authenticate
Deploy a simple template
Understand project structure
Learn basic commands (up, down, deploy)

Intermediate (Week 3-4)

Customize templates
Manage multiple environments
Understand infrastructure code
Set up CI/CD pipelines

Advanced (Week 5+)

Create custom templates
Advanced infrastructure patterns
Multi-region deployments
Enterprise-grade configurations

Next Steps

📖 Continue Chapter 1 Learning:

Installation & Setup - Get azd installed and configured
Your First Project - Complete hands-on tutorial
Configuration Guide - Advanced configuration options

🎯 Ready for Next Chapter?

Chapter 2: AI-First Development - Start building AI applications

Additional Resources

🙋 Frequently Asked Questions

General Questions

Q: What's the difference between AZD and Azure CLI?

A: Azure CLI (az) is for managing individual Azure resources. AZD (azd) is for managing entire applications:

# Azure CLI - Low-level resource management
az webapp create --name myapp --resource-group rg
az sql server create --name myserver --resource-group rg
# ...many more commands needed

# AZD - Application-level management
azd up  # Deploys entire app with all resources

Think of it this way:

az = Operating on individual Lego bricks
azd = Working with complete Lego sets

Q: Do I need to know Bicep or Terraform to use AZD?

A: No! Start with templates:

# Use existing template - no IaC knowledge needed
azd init --template todo-nodejs-mongo
azd up

You can learn Bicep later to customize infrastructure. Templates provide working examples to learn from.

Q: How much does it cost to run AZD templates?

A: Costs vary by template. Most development templates cost $50-150/month:

# Preview costs before deploying
azd provision --preview

# Always cleanup when not using
azd down --force --purge  # Removes all resources

Pro tip: Use free tiers where available:

App Service: F1 (Free) tier
Microsoft Foundry Models: Azure OpenAI 50,000 tokens/month free
Cosmos DB: 1000 RU/s free tier

Q: Can I use AZD with existing Azure resources?

A: Yes, but it's easier to start fresh. AZD works best when it manages the full lifecycle. For existing resources:

# Option 1: Import existing resources (advanced)
azd init
# Then modify infra/ to reference existing resources

# Option 2: Start fresh (recommended)
azd init --template matching-your-stack
azd up  # Creates new environment

Q: How do I share my project with teammates?

A: Commit the AZD project to Git (but NOT the .azure folder):

# Already in .gitignore by default
.azure/        # Contains secrets and environment data
*.env          # Environment variables

# Team members then:
git clone <your-repo>
azd auth login
azd env new <their-name>-dev
azd up

Everyone gets identical infrastructure from the same templates.

Troubleshooting Questions

Q: "azd up" failed halfway. What do I do?

A: Check the error, fix it, then retry:

# View detailed logs
azd show

# Common fixes:

# 1. If quota exceeded:
azd env set AZURE_LOCATION "westus2"  # Try different region

# 2. If resource name conflict:
azd down --force --purge  # Clean slate
azd up  # Retry

# 3. If auth expired:
az login
azd auth login
azd up

Most common issue: Wrong Azure subscription selected

az account list --output table
az account set --subscription "<correct-subscription>"

Q: How do I deploy just code changes without reprovisioning?

A: Use azd deploy instead of azd up:

azd up          # First time: provision + deploy (slow)

# Make code changes...

azd deploy      # Subsequent times: deploy only (fast)

Speed comparison:

azd up: 10-15 minutes (provisions infrastructure)
azd deploy: 2-5 minutes (code only)

Q: Can I customize the infrastructure templates?

A: Yes! Edit the Bicep files in infra/:

# After azd init
cd infra/
code main.bicep  # Edit in VS Code

# Preview changes
azd provision --preview

# Apply changes
azd provision

Tip: Start small - change SKUs first:

// infra/main.bicep
sku: {
  name: 'B1'  // Change to 'P1V2' for production
}

Q: How do I delete everything AZD created?

A: One command removes all resources:

azd down --force --purge

# This deletes:
# - All Azure resources
# - Resource group
# - Local environment state
# - Cached deployment data

Always run this when:

Finished testing a template
Switching to different project
Want to start fresh

Cost savings: Deleting unused resources = $0 charges

Q: What if I accidentally deleted resources in Azure Portal?

A: AZD state can get out of sync. Clean slate approach:

# 1. Remove local state
azd down --force --purge

# 2. Start fresh
azd up

# Alternative: Let AZD detect and fix
azd provision  # Will create missing resources

Advanced Questions

Q: Can I use AZD in CI/CD pipelines?

A: Yes! GitHub Actions example:

# .github/workflows/deploy.yml
name: Deploy with AZD

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      
      - name: Install azd
        run: curl -fsSL https://aka.ms/install-azd.sh | bash
      
      - name: Azure Login
        run: |
          azd auth login \
            --client-id ${{ secrets.AZURE_CLIENT_ID }} \
            --client-secret ${{ secrets.AZURE_CLIENT_SECRET }} \
            --tenant-id ${{ secrets.AZURE_TENANT_ID }}
      
      - name: Deploy
        run: azd up --no-prompt

Q: How do I handle secrets and sensitive data?

A: AZD integrates with Azure Key Vault automatically:

# Secrets are stored in Key Vault, not in code
azd env set DATABASE_PASSWORD "$(openssl rand -base64 32)"

# AZD automatically:
# 1. Creates Key Vault
# 2. Stores secret
# 3. Grants app access via Managed Identity
# 4. Injects at runtime

Never commit:

.azure/ folder (contains environment data)
.env files (local secrets)
Connection strings

Q: Can I deploy to multiple regions?

A: Yes, create environment per region:

# East US environment
azd env new prod-eastus
azd env set AZURE_LOCATION eastus
azd up

# West Europe environment
azd env new prod-westeurope
azd env set AZURE_LOCATION westeurope
azd up

# Each environment is independent
azd env list

For true multi-region apps, customize Bicep templates to deploy to multiple regions simultaneously.

Q: Where can I get help if I'm stuck?

AZD Documentation: https://learn.microsoft.com/azure/developer/azure-developer-cli/
GitHub Issues: https://github.com/Azure/azure-dev/issues
Discord: Azure Discord - #azure-developer-cli channel
Stack Overflow: Tag azure-developer-cli
This Course: Troubleshooting Guide

Pro tip: Before asking, run:

azd show       # Shows current state
azd version    # Shows your version

Include this info in your question for faster help.

🎓 What's Next?

You now understand AZD fundamentals. Choose your path:

🎯 For Beginners:

Next: Installation & Setup - Install AZD on your machine
Then: Your First Project - Deploy your first app
Practice: Complete all 3 exercises in this lesson

🚀 For AI Developers:

Skip to: Chapter 2: AI-First Development
Deploy: Start with azd init --template get-started-with-ai-chat
Learn: Build while you deploy

🏗️ For Experienced Developers:

Review: Configuration Guide - Advanced settings
Explore: Infrastructure as Code - Bicep deep dive
Build: Create custom templates for your stack

Chapter Navigation:

📚 Course Home: AZD For Beginners
📖 Current Chapter: Chapter 1 - Foundation & Quick Start
⬅️ Previous: Course Overview
➡️ Next: Installation & Setup
🚀 Next Chapter: Chapter 2: AI-First Development

FilesExpand file tree

azd-basics.md

Latest commit

History

azd-basics.md

File metadata and controls

AZD Basics - Understanding Azure Developer CLI

AZD Basics - Core Concepts and Fundamentals

Introduction

Learning Goals

Learning Outcomes

What is Azure Developer CLI (azd)?

What Can You Deploy with azd?

🎯 Why Use AZD? A Real-World Comparison

❌ WITHOUT AZD: Manual Azure Deployment (30+ minutes)

✅ WITH AZD: Automated Deployment (5 commands, 10-15 minutes)

📊 Time & Error Reduction

Core Concepts

Templates

Environments

Services

Key Features

1. Template-Driven Development

2. Infrastructure as Code

3. Integrated Workflows

🛡️ Safe Infrastructure Planning with Preview

📊 Visual: AZD Development Workflow

4. Environment Management

5. Extensions and AI Commands

📁 Project Structure

🔧 Configuration Files

azure.yaml

.azure/config.json

🎪 Common Workflows with Hands-On Exercises

🎯 Exercise 1: Initialize Your First Project

🎯 Exercise 2: Deploy to Azure

🎯 Exercise 3: Multiple Environments

🛡️ Clean Slate: azd down --force --purge

🎪 Original Workflow Reference

Starting a New Project

Development Cycle

Understanding azd down --force --purge

Why use both?

Managing Multiple Environments

🔐 Authentication and Credentials

Azure CLI Authentication (az login)

Authentication Flow

DefaultAzureCredential Chain

Credential Chain Order

1. Environment Variables

2. Workload Identity (Kubernetes/GitHub Actions)

3. Managed Identity

4. Developer Tools Integration

AZD Authentication Setup

Authentication Best Practices

For Local Development

For CI/CD Pipelines

For Production Environments

Common Authentication Issues and Solutions

Issue: "No subscription found"

Issue: "Insufficient permissions"

Issue: "Token expired"

Authentication in Different Scenarios

Local Development

Team Development

Multi-tenant Scenarios

Security Considerations

Troubleshooting Authentication

Understanding azd down --force --purge

Discovery

Project Management

Monitoring

Best Practices

1. Use Meaningful Names

2. Leverage Templates

3. Environment Isolation

4. Configuration Management

Learning Progression

Beginner (Week 1-2)

Intermediate (Week 3-4)

🛡️ Clean Slate: `azd down --force --purge`

Understanding `azd down --force --purge`

Azure CLI Authentication (`az login`)

Understanding `azd down --force --purge`