# 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:**
```yaml
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:**
```yaml
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**:
   ```bash
   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

```bash
# 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

```bash
# 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

```bash
# 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!