cmdb-insight/docs/Core deployment guides/AZURE-PIPELINES.md

Azure Pipelines Usage Guide

Guide for using the separate build and deployment pipelines.

📋 Quick Reference

Pipeline Variables

Variable	Description	Example
acrName	Azure Container Registry name	zdlas
repositoryName	Docker repository name	cmdb-insight
dockerRegistryServiceConnection	ACR service connection name	zuyderland-cmdb-acr-connection
resourceGroup	Azure resource group	rg-cmdb-insight-prod
backendAppName	Backend App Service name	cmdb-backend-prod
frontendAppName	Frontend App Service name	cmdb-frontend-prod
azureSubscription	Azure service connection for deployment	zuyderland-cmdb-subscription
deployToProduction	Enable/disable deployment	true or false
useDeploymentSlots	Use staging slots for zero-downtime	true or false

Required Service Connections

1. Docker Registry Connection (for ACR)

   • Type: Docker Registry → Azure Container Registry
   • Name: Match dockerRegistryServiceConnection variable
   • Authentication: Service Principal (not Managed Identity)

2. Azure Resource Manager Connection (for App Service deployment)

   • Type: Azure Resource Manager
   • Name: Match azureSubscription variable
   • Authentication: Managed Identity or Service Principal

---

📋 Pipeline Files

1. azure-pipelines.yml - Build and Push Images

Purpose: Builds Docker images and pushes them to Azure Container Registry.

What it does:

• ✅ Builds backend Docker image
• ✅ Builds frontend Docker image
• ✅ Pushes both to ACR with tags: $(Build.BuildId) and latest

When to use:

• First time setup (to test image building)
• After code changes (to build new images)
• Before deployment (to ensure images are in ACR)

Configuration:

variables:
  acrName: 'zdlas'  # Your ACR name
  repositoryName: 'cmdb-insight'
  dockerRegistryServiceConnection: 'zuyderland-cmdb-acr-connection'

2. azure-pipelines-deploy.yml - Deploy to App Service

Purpose: Deploys existing images from ACR to Azure App Services.

What it does:

• ✅ Deploys backend container to App Service
• ✅ Deploys frontend container to App Service
• ✅ Restarts both App Services
• ✅ Verifies deployment with health checks

When to use:

• After images are built and pushed to ACR
• When you want to deploy/update the application
• For production deployments

Configuration:

variables:
  acrName: 'zdlas'  # Your ACR name
  resourceGroup: 'rg-cmdb-insight-prod'  # Your resource group
  backendAppName: 'cmdb-backend-prod'  # Your backend app name
  frontendAppName: 'cmdb-frontend-prod'  # Your frontend app name
  azureSubscription: 'zuyderland-cmdb-subscription'  # Azure service connection
  imageTag: 'latest'  # Image tag to deploy

🚀 Workflow

Step 1: Build and Push Images

1. Configure azure-pipelines.yml:

   • Update acrName with your ACR name
   • Update dockerRegistryServiceConnection with your service connection name

2. Create Pipeline in Azure DevOps:

   • Go to Pipelines → New pipeline
   • Select Existing Azure Pipelines YAML file
   • Choose azure-pipelines.yml
   • Run the pipeline

3. Verify Images in ACR:

   az acr repository list --name zdlas
   az acr repository show-tags --name zdlas --repository cmdb-insight/backend
   az acr repository show-tags --name zdlas --repository cmdb-insight/frontend
   

Step 2: Deploy Application

1. Ensure App Services exist:

   • Backend App Service: cmdb-backend-prod
   • Frontend App Service: cmdb-frontend-prod
   • See AZURE-NEW-SUBSCRIPTION-SETUP.md for setup instructions

2. Configure azure-pipelines-deploy.yml:

   • Update all variables with your Azure resource names
   • Create Azure service connection for App Service deployment
   • Create production environment in Azure DevOps

3. Create Deployment Pipeline:

   • Go to Pipelines → New pipeline
   • Select Existing Azure Pipelines YAML file
   • Choose azure-pipelines-deploy.yml
   • Run the pipeline

4. Verify Deployment:

   • Check backend: https://cmdb-backend-prod.azurewebsites.net/api/health
   • Check frontend: https://cmdb-frontend-prod.azurewebsites.net

🔧 Setup Requirements

For Build Pipeline (azure-pipelines.yml)

Required:

• ✅ Docker Registry service connection (for ACR)
• ✅ ACR exists and is accessible
• ✅ Service connection has push permissions

Setup:

1. Create Docker Registry service connection:
   • Project Settings → Service connections → New service connection
   • Choose Docker Registry → Azure Container Registry
   • Select your ACR
   • Name: zuyderland-cmdb-acr-connection

For Deployment Pipeline (azure-pipelines-deploy.yml)

Required:

• ✅ Azure Resource Manager service connection
• ✅ App Services exist in Azure
• ✅ production environment created in Azure DevOps
• ✅ Images exist in ACR

Setup:

1. Create Azure service connection:

   • Project Settings → Service connections → New service connection
   • Choose Azure Resource Manager
   • Select your subscription
   • Name: zuyderland-cmdb-subscription

2. Create environment:

   • Pipelines → Environments → Create environment
   • Name: production
   • (Optional) Add approvals for manual control

📝 Typical Usage Scenarios

Scenario 1: First Time Setup

# 1. Build and push images
# Run azure-pipelines.yml → Images in ACR

# 2. Create App Services (manual or via script)
# See AZURE-NEW-SUBSCRIPTION-SETUP.md

# 3. Deploy application
# Run azure-pipelines-deploy.yml → App deployed

Scenario 2: Code Update

# 1. Push code to main branch
git push origin main

# 2. Build pipeline runs automatically
# azure-pipelines.yml → New images in ACR

# 3. Deploy new version
# Run azure-pipelines-deploy.yml → App updated

Scenario 3: Deploy Specific Version

# 1. Update azure-pipelines-deploy.yml
imageTag: 'v1.0.0'  # Or specific build ID

# 2. Run deployment pipeline
# Deploys specific version

🔄 Combining Pipelines (Future)

Once you're comfortable with both pipelines, you can:

1. Combine them into one pipeline with conditional deployment
2. Use deployment slots for zero-downtime updates
3. Add approval gates for production deployments

See azure-pipelines-slots.yml for an advanced example with deployment slots.

🛠️ Troubleshooting

Build Pipeline Fails

Issue: "Service connection not found"

• Solution: Verify service connection name matches dockerRegistryServiceConnection variable
• Check: Project Settings → Service connections → Verify name matches

Issue: "ACR not found"

• Solution: Check acrName variable matches your ACR name
• Verify: az acr list --query "[].name"

Issue: "MSI Authentication Error" / "Could not fetch access token for Managed Service Principal"

• Solution: Service connection must use Service Principal authentication (not Managed Identity)
• Recreate service connection: Docker Registry → Azure Container Registry → Use Service Principal
• See docs/AZURE-SERVICE-CONNECTION-TROUBLESHOOTING.md for details

Issue: "Permission denied"

• Solution: Verify service connection has correct permissions
• Check ACR admin is enabled: az acr update --name <acr-name> --admin-enabled true

Deployment Pipeline Fails

Issue: "App Service not found"

• Solution: Verify app names match your Azure resources
• Check: az webapp list --query "[].name"

Issue: "Environment not found"

• Solution: Create production environment in Azure DevOps
• Pipelines → Environments → Create environment

Issue: "Image not found in ACR"

• Solution: Run build pipeline first to push images to ACR
• Verify: az acr repository show-tags --name <acr-name> --repository cmdb-insight/backend

Repository Not Found

Issue: "No matching repositories were found" when creating pipeline

• Solution 1: Check repository exists in Azure DevOps → Repos → Files
• Solution 2: Push code to Azure DevOps: git push azure main
• Solution 3: Use "Other Git" option in pipeline wizard with repository URL
• Solution 4: Verify you're in the correct project (check project name in dropdown)
• See docs/AZURE-SERVICE-CONNECTION-TROUBLESHOOTING.md for details

✅ Checklist

Build Pipeline Setup

• Docker Registry service connection created
• azure-pipelines.yml variables configured
• Pipeline created in Azure DevOps
• Test run successful
• Images visible in ACR

Deployment Pipeline Setup

• Azure Resource Manager service connection created
• production environment created
• App Services exist in Azure
• azure-pipelines-deploy.yml variables configured
• Deployment pipeline created in Azure DevOps
• Test deployment successful

---

Workflow: Build first → Deploy second → Verify success!