Add Azure deployment automation and documentation
- Add separate deployment pipeline (azure-pipelines-deploy.yml) for App Service deployment - Add advanced pipeline with deployment slots (azure-pipelines-slots.yml) - Restore azure-pipelines.yml to build-only (no deployment) - Add comprehensive Azure setup documentation: - AZURE-NEW-SUBSCRIPTION-SETUP.md: Complete step-by-step Azure resource setup - AZURE-RESOURCES-OVERVIEW.md: Quick reference for all Azure resources - AZURE-ACR-SHARED-SETUP.md: Guide for shared Container Registry - AZURE-ACR-NAMING-RECOMMENDATION.md: Naming recommendations for Zuyderland - AZURE-PIPELINE-DEPLOYMENT.md: Automated deployment setup guide - AZURE-PIPELINE-QUICK-REFERENCE.md: Quick reference for pipeline variables - AZURE-PIPELINES-USAGE.md: Guide for using build and deployment pipelines - Add setup script (scripts/setup-azure-resources.sh) for automated resource creation - Support for shared ACR across multiple applications
This commit is contained in:
222
docs/AZURE-PIPELINES-USAGE.md
Normal file
222
docs/AZURE-PIPELINES-USAGE.md
Normal file
@@ -0,0 +1,222 @@
|
||||
# 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!
|
||||
Reference in New Issue
Block a user