Skip to content

DeploymentGuide.md

Latest commit

 

History

History
457 lines (319 loc) · 18.7 KB

DeploymentGuide.md

File metadata and controls

457 lines (319 loc) · 18.7 KB
Raw

Deployment Guide

Overview

This guide walks you through deploying the Container Migration Solution Accelerator to Azure. The deployment process takes approximately 10-15 minutes for the default Development/Testing configuration and includes both infrastructure provisioning and application setup.

🆘 Need Help? If you encounter any issues during deployment, check our Troubleshooting Guide for solutions to common problems.

Step 1: Prerequisites & Setup

1.1 Azure Account Requirements

Ensure you have access to an Azure subscription with the following permissions:

Required Permission/Role Scope Purpose
Contributor Subscription level Create and manage Azure resources
User Access Administrator Subscription level Manage user access and role assignments
Role Based Access Control Subscription/Resource Group level Configure RBAC permissions
App Registration Creation Azure Active Directory Create and configure authentication

🔍 How to Check Your Permissions:

Azure Portal
  1. Go to Azure Portal
  2. Navigate to Subscriptions (search for "subscriptions" in the top search bar)
  3. Click on your target subscription
  4. In the left menu, click Access control (IAM)
  5. Scroll down to see the table with your assigned roles - you should see:
    • Contributor
    • User Access Administrator
    • Role Based Access Control Administrator (or similar RBAC role)

For App Registration permissions:

  1. Go to Microsoft Entra ID → Manage → App registrations
  2. Try clicking New registration
  3. If you can access this page, you have the required permissions
  4. Cancel without creating an app registration

📖 Detailed Setup: Follow Azure Account Set Up for complete configuration.

1.2 Check Service Availability & Quota

⚠️ CRITICAL: Before proceeding, ensure your chosen region has all required services available:

Required Azure Services:

Recommended Regions: East US, East US2, Australia East, UK South, France Central

🔍 Check Availability: Use Azure Products by Region to verify service availability.

1.3 Quota Check (Optional)

💡 RECOMMENDED: Check your Azure OpenAI quota availability before deployment for optimal planning.

📖 Follow: Quota Check Instructions to ensure sufficient capacity.

Recommended Configuration:

  • Default: 200k tokens (minimum)
  • Optimal: 500k tokens (recommended for best performance)

Note: When you run azd up, the deployment will automatically show you regions with available quota, so this pre-check is optional but helpful for planning purposes. You can customize these settings later in Step 3.3: Advanced Configuration.

📖 Adjust Quota: Follow Azure AI Model Quota Settings if needed.

Step 2: Choose Your Deployment Environment

Select one of the following options to deploy the Container Migration Solution Accelerator:

Environment Comparison

Option Best For Prerequisites Setup Time
GitHub Codespaces Quick deployment, no local setup required GitHub account ~3-5 minutes
VS Code Dev Containers Fast deployment with local tools Docker Desktop, VS Code ~5-10 minutes
VS Code Web Quick deployment, no local setup required Azure account ~2-4 minutes
Local Environment Enterprise environments, full control All tools individually ~15-30 minutes

💡 Recommendation: For fastest deployment, start with GitHub Codespaces - no local installation required.

Option A: GitHub Codespaces (Easiest)

Open in GitHub Codespaces

  1. Click the badge above (may take several minutes to load)
  2. Accept default values on the Codespaces creation page
  3. Wait for the environment to initialize (includes all deployment tools)
  4. Proceed to Step 3: Configure Deployment Settings
Option B: VS Code Dev Containers

Open in Dev Containers

Prerequisites:

Steps:

  1. Start Docker Desktop
  2. Click the badge above to open in Dev Containers
  3. Wait for the container to build and start (includes all deployment tools)
  4. Proceed to Step 3: Configure Deployment Settings
Option C: Visual Studio Code Web

Open in Visual Studio Code Web

  1. Click the badge above (may take a few minutes to load)

  2. Sign in with your Azure account when prompted

  3. Select the subscription where you want to deploy the solution

  4. Wait for the environment to initialize (includes all deployment tools)

  5. When prompted in the VS Code Web terminal, choose one of the available options shown below:

    VS Code Initial Prompt

  6. Proceed to Step 3: Configure Deployment Settings

Option D: Local Environment

Required Tools:

Setup Steps:

  1. Install all required deployment tools listed above
  2. Clone the repository: 
    azd init -t microsoft/Container-Migration-Solution-Accelerator/
  3. Open the project folder in your terminal
  4. Proceed to Step 3: Configure Deployment Settings

PowerShell Users: If you encounter script execution issues, run:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

Step 3: Configure Deployment Settings

Review the configuration options below. You can customize any settings that meet your needs, or leave them as defaults to proceed with a standard deployment.

3.1 Choose Deployment Type (Optional)

Aspect Development/Testing (Default) Production
Configuration File main.parameters.json (sandbox) Copy main.waf.parameters.json to main.parameters.json
Security Controls Minimal (for rapid iteration) Enhanced (production best practices)
Cost Lower costs Cost optimized
Use Case POCs, development, testing Production workloads
Framework Basic configuration Well-Architected Framework
Features Core functionality Reliability, security, operational excellence

To use production configuration:

Copy the contents from the production configuration file to your main parameters file:

Option 1: Manual Copy (Recommended for beginners)
  1. Navigate to the infra folder in your project
  2. Open main.waf.parameters.json in a text editor (like Notepad, VS Code, etc.)
  3. Select all content (Ctrl+A) and copy it (Ctrl+C)
  4. Open main.parameters.json in the same text editor
  5. Select all existing content (Ctrl+A) and paste the copied content (Ctrl+V)
  6. Save the file (Ctrl+S)
Option 2: Using Command Line

For Linux/macOS/Git Bash:

# Copy contents from production file to main parameters file
cat infra/main.waf.parameters.json > infra/main.parameters.json

For Windows PowerShell:

# Copy contents from production file to main parameters file
Get-Content infra/main.waf.parameters.json | Set-Content infra/main.parameters.json

3.2 Set VM Credentials (Optional - Production Deployment Only)

Note: This section only applies if you selected Production deployment type in section 3.1. VMs are not deployed in the default Development/Testing configuration.

By default, random GUIDs are generated for VM credentials. To set custom credentials:

azd env set AZURE_ENV_VM_ADMIN_USERNAME <your-username>
azd env set AZURE_ENV_VM_ADMIN_PASSWORD <your-password>

3.3 Advanced Configuration (Optional)

Configurable Parameters

Customize these settings by following Parameter Customization Guide:

Setting Description Default
Azure Region Primary deployment region Resource Group location
Secondary Location Fallback region for Cosmos DB -
Deployment Type Infrastructure configuration GlobalStandard
o3 Model AI model selection o3
o3 Model Version Model version 2025-04-16
o3 Model Capacity Token capacity 200k
Reuse Existing Resources

To optimize costs and integrate with your existing Azure infrastructure, you can configure the solution to reuse compatible resources already deployed in your subscription.

Supported Resources for Reuse:

  • Log Analytics Workspace: Integrate with your existing monitoring infrastructure by reusing an established Log Analytics workspace for centralized logging and monitoring. Configuration Guide

  • Azure AI Foundry Project: Leverage your existing AI Foundry project and deployed models to avoid duplication and reduce provisioning time. Configuration Guide

Key Benefits:

  • Cost Optimization: Eliminate duplicate resource charges
  • Operational Consistency: Maintain unified monitoring and AI infrastructure
  • Faster Deployment: Skip resource creation for existing compatible services
  • Simplified Management: Reduce the number of resources to manage and monitor

Important Considerations:

  • Ensure existing resources meet the solution's requirements and are in compatible regions
  • Review access permissions and configurations before reusing resources
  • Consider the impact on existing workloads when sharing resources

Step 4: Deploy the Solution

💡 Before You Start: If you encounter any issues during deployment, check our Troubleshooting Guide for common solutions.

4.1 Authenticate with Azure

azd auth login

For specific tenants:

azd auth login --tenant-id <tenant-id>

Finding Tenant ID:

  1. Open the Azure Portal.
  2. Navigate to Microsoft Entra ID from the left-hand menu.
  3. Under the Overview section, locate the Tenant ID field. Copy the value displayed.

4.2 Start Deployment

azd up

During deployment, you'll be prompted for:

  1. Environment name (e.g., "conmig") - Must be 3-16 characters long, alphanumeric only
  2. Azure subscription selection
  3. Region selection (choose one with adequate quota)

Expected Duration: 4-6 minutes

Deployment Issues: If you encounter errors or timeouts, try a different region as there may be capacity constraints. For detailed error solutions, see our Troubleshooting Guide.

4.3 Get Application URL

After successful deployment:

  1. Open Azure Portal
  2. Navigate to your resource group
  3. Find the Container App with "frontend" in the name
  4. Copy the Application URI

⚠️ Important: Complete Post-Deployment Steps before accessing the application.

Step 5: Post-Deployment Configuration

5.1 Configure Authentication (Required)

This step is mandatory for application access:

  1. Follow App Authentication Configuration
  2. Wait up to 10 minutes for authentication changes to take effect

5.2 Verify Deployment

  1. Access your application using the URL from Step 4.3
  2. Upload sample YAML files from the /data folder
  3. Test the migration functionality

Step 6: Clean Up (Optional)

Remove All Resources

azd down

Note: If you deployed with enableRedundancy=true and Log Analytics workspace replication is enabled, you must first disable replication before running azd down else resource group delete will fail. Follow the steps in Handling Log Analytics Workspace Deletion with Replication Enabled, wait until replication returns false, then run azd down.

Manual Cleanup (if needed)

If deployment fails or you need to clean up manually:

Managing Multiple Environments

Recover from Failed Deployment

If your deployment failed or encountered errors, here are the steps to recover:

Recover from Failed Deployment

If your deployment failed or encountered errors:

  1. Try a different region: Create a new environment and select a different Azure region during deployment
  2. Clean up and retry: Use azd down to remove failed resources, then azd up to redeploy
  3. Check troubleshooting: Review Troubleshooting Guide for specific error solutions
  4. Fresh start: Create a completely new environment with a different name

Example Recovery Workflow:

# Remove failed deployment (optional)
azd down

# Create new environment (3-16 chars, alphanumeric only)
azd env new conmigretry

# Deploy with different settings/region
azd up

Creating a New Environment

If you need to deploy to a different region, test different configurations, or create additional environments:

Create a New Environment

Create Environment Explicitly:

# Create a new named environment (3-16 characters, alphanumeric only)
azd env new <new-environment-name>

# Select the new environment
azd env select <new-environment-name>

# Deploy to the new environment
azd up

Example:

# Create a new environment for production (valid: 3-16 chars)
azd env new conmigprod

# Switch to the new environment
azd env select conmigprod

# Deploy with fresh settings
azd up

Environment Name Requirements:

  • Length: 3-16 characters
  • Characters: Alphanumeric only (letters and numbers)
  • Valid examples: conmig, test123, myappdev, prod2024
  • Invalid examples: co (too short), my-very-long-environment-name (too long), test_env (underscore not allowed), myapp-dev (hyphen not allowed)
Switch Between Environments

List Available Environments:

azd env list

Switch to Different Environment:

azd env select <environment-name>

View Current Environment:

azd env get-values

Best Practices for Multiple Environments

  • Use descriptive names: conmigdev, conmigprod, conmigtest (remember: 3-16 chars, alphanumeric only)
  • Different regions: Deploy to multiple regions for testing quota availability
  • Separate configurations: Each environment can have different parameter settings
  • Clean up unused environments: Use azd down to remove environments you no longer need

Next Steps

🚀 Get Started: Follow the Sample Workflow to explore the application features.

📚 Learn More:

Need Help?

Deploy Your local changes

To Deploy your local changes rename the below files.

Rename azure.yaml to azure_custom2.yaml and azure_custom.yaml to azure.yaml. Go to infra directory Rename main.bicep to main_custom2.bicep and main_custom.bicep to main.bicep. Continue with the deploying steps.