cmdb-insight/docs/AZURE-PIPELINES-USAGE.md

# Azure Pipelines Usage Guide

Guide for using the separate build and deployment pipelines.

## 📋 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

**Issue**: "ACR not found"
- **Solution**: Check `acrName` variable matches your ACR name

### Deployment Pipeline Fails

**Issue**: "App Service not found"
- **Solution**: Verify app names match your Azure resources

**Issue**: "Environment not found"
- **Solution**: Create `production` environment in Azure DevOps

**Issue**: "Image not found in ACR"
- **Solution**: Run build pipeline first to push images to ACR

## ✅ 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!