Skip to content

azd-cli_deploy.md

Latest commit

 

History

History
533 lines (419 loc) · 13.4 KB

azd-cli_deploy.md

File metadata and controls

533 lines (419 loc) · 13.4 KB
layout showcase-page
title Azure Developer CLI Deployment
permalink /reference/deploy/azd-cli_deploy/
menubar docs_menu
accent emerald
eyebrow Deployment Reference
description Deploy Simple Chat with Azure Developer CLI when you want the repo's most current, end-to-end supported rollout path.
hero_icons
bi-rocket-takeoff
bi-cloud-arrow-up
bi-box-seam
hero_pills
Recommended deployment path
Provision and deploy together
Container-based runtime
hero_links
label url style
Getting Started
/setup_instructions/
primary
label url style
Upgrade paths
/how-to/upgrade_paths/
secondary
nav_links
prev next
title url
Deployment Reference
/reference/deploy/
title url
Azure CLI with PowerShell
/reference/deploy/azurecli_powershell_deploy/
show_nav true

Azure Developer CLI handles the cleanest end-to-end deployment flow in this repo. Use it when you want infrastructure provisioning, environment configuration, and application deployment to stay in one documented path.

Provision infrastructure

AZD drives the Bicep templates for the required Azure resources instead of making you stitch together the provisioning steps manually.

Capture environment choices

Subscription, region, environment naming, and optional environment settings all stay tied to the AZD environment instead of scattered across ad hoc scripts.

Deploy the app

The current path is container-based App Service, so the image runtime and startup behavior are handled by the deployment model rather than a native Python startup command.

Inspect and iterate

Use AZD commands for logs, monitoring, environment inspection, and upgrade decisions without switching to a separate deployment toolset midstream.

Startup command rule for this path

The repo's AZD workflow deploys a container-based App Service. Do not add a native Python App Service startup command unless you intentionally move away from the container runtime later.

Overview

Azure Developer CLI is Microsoft's tool for streamlined application deployment to Azure. For Simple Chat, azd:

  • Provisions all required Azure resources
  • Configures service connections
  • Deploys the application code
  • Sets up monitoring and logging

This is the primary recommended deployment path for the repo.

Prerequisites

Required Software

  • Azure Developer CLI (install guide)
  • Git for repository cloning
  • Azure CLI (usually installed with azd)

Azure Requirements

  • Azure subscription with contributor access
  • Resource quota for required services in target region
  • Permissions to create service principals (if not using existing)

Supported Environments

  • ✅ Azure Commercial
  • ✅ Azure Government (with environment configuration)
  • ✅ Local development environments
  • ✅ CI/CD pipelines

Quick Start

Runtime Startup Behavior

  • The current azd deployment path in this repo is a container-based App Service deployment.
  • Gunicorn is started by the container entrypoint in application/single_app/Dockerfile.
  • You do not need to populate App Service Stack Settings Startup command when deploying through this azd path.
  • If you later switch to native Python App Service instead, deploy the application/single_app folder and use this startup command:
python -m gunicorn -c gunicorn.conf.py app:app

1. Clone Repository

git clone https://github.com/microsoft/simplechat.git
cd simplechat

2. Initialize and Deploy

# Initialize the project
azd init

# Deploy to Azure
azd up

3. Follow Prompts

The azd up command will prompt for:

  • Subscription selection
  • Target region
  • Environment name (used for resource naming)
  • Additional configuration options

Detailed Deployment Steps

Step 1: Environment Setup

Initialize project:

azd init

Select template (if prompted):

  • Choose "Simple Chat" from available templates
  • Or use the current directory if already cloned

Step 2: Configuration

Set environment variables (optional):

# For Azure Government
azd env set AZURE_ENVIRONMENT usgovernment

# For custom regions
azd env set AZURE_LOCATION "East US 2"

# For specific naming prefix
azd env set RESOURCE_PREFIX "myorg"

Review configuration:

azd env get-values

Step 3: Deploy Resources

Full deployment:

azd up

This command:

  1. Provisions infrastructure using Bicep templates
  2. Configures services with proper connections
  3. Deploys application code to App Service
  4. Sets up monitoring and logging
  5. Outputs connection information

Step 4: Verify Deployment

Check deployment status:

azd show

Get application URL:

azd env get-values | grep APP_URL

Test application:

  • Open the provided URL in browser
  • Verify login functionality
  • Test basic chat functionality

Configuration Options

Environment Variables

Set these before running azd up to customize deployment:

Core Settings:

# Deployment region
azd env set AZURE_LOCATION "East US"

# Resource naming prefix  
azd env set RESOURCE_PREFIX "simplechat"

# Environment type (affects SKUs)
azd env set ENVIRONMENT_TYPE "dev|staging|prod"

Service Configuration:

# Enable specific features
azd env set ENABLE_CONTENT_SAFETY "true"
azd env set ENABLE_IMAGE_GENERATION "true"
azd env set ENABLE_REDIS_CACHE "true"

# Set service tiers
azd env set APP_SERVICE_SKU "P1v3"
azd env set COSMOS_DB_THROUGHPUT "1000"
azd env set SEARCH_SKU "standard"

Azure Government:

azd env set AZURE_ENVIRONMENT "usgovernment"
azd env set AZURE_LOCATION "USGov Virginia"

Resource Sizing

Development/Testing:

azd env set ENVIRONMENT_TYPE "dev"
# Uses: B1 App Service, 400 RU/s Cosmos, Basic Search

Production:

azd env set ENVIRONMENT_TYPE "prod"
# Uses: P1v3 App Service, 1000 RU/s Cosmos, Standard Search

Custom Sizing:

azd env set APP_SERVICE_SKU "P2v3"
azd env set COSMOS_DB_THROUGHPUT "4000" 
azd env set SEARCH_SKU "standard2"
azd env set OPENAI_SKU "S0"

Post-Deployment Configuration

Access Admin Settings

  1. Navigate to deployed application
  2. Sign in with Azure AD account
  3. Assign admin role if needed: 
    # Get app registration details
azd env get-values | grep APP_REGISTRATION

# Assign admin role in Azure AD

Configure Application Features

Required configurations:

  • Test all service connections in Admin Settings
  • Configure default system prompt
  • Set up document classification (optional)
  • Enable additional features as needed

Recommended configurations:

  • Set up Content Safety thresholds
  • Configure file size limits
  • Set conversation history limits
  • Enable enhanced citations

Set Up Monitoring

Application Insights:

  • Automatically configured by azd
  • Access through Azure Portal
  • Set up custom alerts and dashboards

Azure Monitor:

  • Configure alerts for resource health
  • Set up cost monitoring and budgets
  • Create dashboards for operational metrics

Advanced Configuration

Custom Bicep Parameters

Modify infrastructure by editing infra/main.parameters.json:

{
    "parameters": {
        "environmentName": "prod-simple-chat",
        "location": "East US",
        "appServiceSku": "P1v3",
        "cosmosDbThroughput": 1000,
        "searchSku": "standard",
        "enableContentSafety": true,
        "enableRedisCache": true
    }
}

Multi-Environment Deployment

Development environment:

azd env select dev
azd up

Production environment:

azd env select prod
azd env set ENVIRONMENT_TYPE "prod"
azd up

CI/CD Integration

GitHub Actions workflow: {% raw %}

- name: Azure Dev CLI Deploy
  uses: Azure/azure-dev-cli@v1
  with:
    azure-credentials: ${{ secrets.AZURE_CREDENTIALS }}
  run: |
    azd auth login --client-id "${{ secrets.AZURE_CLIENT_ID }}" \
                   --client-secret "${{ secrets.AZURE_CLIENT_SECRET }}" \
                   --tenant-id "${{ secrets.AZURE_TENANT_ID }}"
    azd deploy

{% endraw %}

Management Commands

Upgrade Decision Guide

Use the command that matches the type of change you are making.

If you changed... Use Why
Application code only azd deploy Recommended default for routine container upgrades
Infrastructure only azd provision Updates Azure resources without treating the release like a full app deployment
Application code and infrastructure together azd up Runs the combined deployment flow

Do not assume azd up is required for every release. For normal code-only container updates, start with azd deploy.

Application Lifecycle

Deploy application updates:

azd deploy

Recommended for routine container-based application upgrades when infrastructure is unchanged.

Provision infrastructure changes:

azd provision

Use azd provision --preview first when you want to review infrastructure impact before applying it.

Full redeployment:

azd down --purge
azd up

Do not use this as a standard upgrade flow. This is a destructive reprovisioning path.

Environment Management

List environments:

azd env list

Switch environments:

azd env select <environment-name>

View configuration:

azd env get-values

Monitoring and Logs

Show deployment info:

azd show

Monitor application:

azd monitor

View logs:

# Application logs
azd logs

# Infrastructure logs  
azd logs --infrastructure

Troubleshooting

Common Issues

Authentication failures:

# Re-authenticate
azd auth login

# Check subscription access
az account show

Resource quota issues:

# Check quotas in target region
az vm list-usage --location "East US" --output table

# Try different region
azd env set AZURE_LOCATION "West US 2"

Deployment failures:

# Check deployment logs
azd show --output json

# View detailed logs
azd logs --infrastructure

Service-Specific Issues

Azure OpenAI not available:

  • Verify Azure OpenAI is available in target region
  • Check subscription whitelist status
  • Request access through Azure portal

App Service deployment issues:

  • Check App Service logs in Azure portal
  • Verify application settings configuration
  • Check for startup errors in Application Insights

Cosmos DB connection issues:

  • Verify firewall settings allow App Service
  • Check connection string configuration
  • Test connectivity from App Service console

Recovery Procedures

Rollback deployment:

# Get previous deployment
azd show --output json

# Redeploy specific version
git checkout <previous-version-tag>
azd deploy

Clean slate redeployment:

# Remove all resources
azd down --purge

# Redeploy from scratch
azd up

Best Practices

Pre-Deployment

  • ✅ Verify Azure subscription quotas in target region
  • ✅ Plan resource naming conventions
  • ✅ Review cost estimates for selected SKUs
  • ✅ Prepare Azure AD configuration requirements

During Deployment

  • ✅ Monitor deployment progress for errors
  • ✅ Note down important URLs and connection strings
  • ✅ Verify each service comes online successfully
  • ✅ Document any custom configurations applied

Post-Deployment

  • ✅ Test all application functionality end-to-end
  • ✅ Configure monitoring and alerting
  • ✅ Set up backup procedures for critical data
  • ✅ Document operational procedures for team

Security

  • ✅ Review and configure Azure AD app registration
  • ✅ Set up proper RBAC roles for users
  • ✅ Enable managed identities where possible
  • ✅ Configure network security if required

Cost Optimization

Right-Sizing Resources

Monitor and adjust:

  • Review cost reports after 30 days of usage
  • Adjust service tiers based on actual utilization
  • Use autoscaling for variable workloads
  • Consider reserved instances for predictable usage

Cost-effective configurations:

# Development environments
azd env set APP_SERVICE_SKU "B1"
azd env set COSMOS_DB_THROUGHPUT "400"
azd env set SEARCH_SKU "basic"

# Production with cost optimization
azd env set ENABLE_REDIS_CACHE "false"  # Start without Redis
azd env set COSMOS_DB_AUTOSCALE "true"  # Use autoscale for variable load

This Azure Developer CLI approach provides the fastest path from zero to a fully functional Simple Chat deployment with minimal manual configuration required.