Bert Hausmans
f4399a8e4e
- Reorganize docs into 'Core deployment guides' and 'Setup and configuration' subdirectories - Consolidate redundant documentation files (ACR, pipelines, deployment guides) - Add documentation consolidation plan - Update backend database factory and logger services - Update migration script and docker-compose configurations - Add PostgreSQL setup script
379 lines
11 KiB
Markdown
379 lines
11 KiB
Markdown
# Azure Container Registry - Quick Start Guide
|
|
|
|
Snelstart guide om zelf Azure Container Registry aan te maken en te configureren voor productie.
|
|
|
|
## 🚀 Stap 1: Azure Container Registry Aanmaken
|
|
|
|
### Optie A: Met Script (Aanbevolen)
|
|
|
|
```bash
|
|
# Run het script
|
|
./scripts/create-acr.sh
|
|
|
|
# Of met custom parameters:
|
|
./scripts/create-acr.sh rg-cmdb-gui zuyderlandcmdbacr westeurope Basic
|
|
```
|
|
|
|
Het script doet automatisch:
|
|
- ✅ Checkt of je ingelogd bent bij Azure
|
|
- ✅ Maakt resource group aan (als nodig)
|
|
- ✅ Controleert of ACR naam beschikbaar is
|
|
- ✅ Maakt ACR aan met Basic SKU
|
|
- ✅ Toont credentials
|
|
- ✅ Test Docker login
|
|
|
|
### Optie B: Handmatig via Azure CLI
|
|
|
|
```bash
|
|
# Login bij Azure
|
|
az login
|
|
|
|
# Resource group aanmaken
|
|
az group create --name rg-cmdb-gui --location westeurope
|
|
|
|
# Check of naam beschikbaar is
|
|
az acr check-name --name zuyderlandcmdbacr
|
|
|
|
# ACR aanmaken (Basic SKU - ~€5/maand)
|
|
az acr create \
|
|
--resource-group rg-cmdb-gui \
|
|
--name zuyderlandcmdbacr \
|
|
--sku Basic \
|
|
--admin-enabled true
|
|
|
|
# Credentials ophalen
|
|
az acr credential show --name zuyderlandcmdbacr
|
|
```
|
|
|
|
### Optie C: Via Azure Portal
|
|
|
|
1. Ga naar [Azure Portal](https://portal.azure.com)
|
|
2. Klik **"Create a resource"**
|
|
3. Zoek **"Container Registry"**
|
|
4. Klik **"Create"**
|
|
5. Vul in:
|
|
- **Resource group**: `rg-cmdb-gui` (of maak nieuwe)
|
|
- **Registry name**: `zuyderlandcmdbacr` (moet uniek zijn, alleen kleine letters en cijfers, **geen streepjes**)
|
|
- **Location**: `West Europe`
|
|
- **SKU**: `Basic` ⭐ (aanbevolen - ~€5/maand)
|
|
- **Domain name label scope**:
|
|
- **"Unsecure"** ⭐ (aanbevolen) - DNS naam wordt: `zuyderlandcmdbacr.azurecr.io`
|
|
- **"Resource Group Reuse"** (voor extra security) - DNS naam wordt: `zuyderlandcmdbacr-abc123.azurecr.io` (met hash)
|
|
- ⚠️ **Let op**: Als je een hash gebruikt, moet je alle configuraties aanpassen met de volledige DNS naam!
|
|
- **Role assignment permissions mode**:
|
|
- **"RBAC Registry Permissions"** ⭐ (aanbevolen - eenvoudigst)
|
|
- **"RBAC Registry + ABAC Repository Permissions"** (alleen als je per-repository permissions nodig hebt)
|
|
6. Klik **"Review + create"** → **"Create"**
|
|
|
|
**💡 Aanbeveling:** Kies **"Unsecure"** voor de eenvoudigste setup. Zie `docs/AZURE-ACR-DNL-SCOPE.md` voor details.
|
|
|
|
**Noteer je ACR naam!** Je hebt deze nodig voor de volgende stappen.
|
|
|
|
---
|
|
|
|
## 🔧 Stap 2: Pipeline Variabelen Aanpassen
|
|
|
|
Pas `azure-pipelines.yml` aan met jouw ACR naam:
|
|
|
|
```yaml
|
|
variables:
|
|
# Pas deze aan naar jouw ACR naam
|
|
acrName: 'zuyderlandcmdbacr' # ← Jouw ACR naam hier
|
|
|
|
repositoryName: 'cmdb-insight'
|
|
|
|
# Service connection naam (maak je in volgende stap)
|
|
dockerRegistryServiceConnection: 'zuyderland-cmdb-acr-connection'
|
|
|
|
imageTag: '$(Build.BuildId)'
|
|
```
|
|
|
|
**Commit en push:**
|
|
```bash
|
|
git add azure-pipelines.yml
|
|
git commit -m "Configure ACR in pipeline"
|
|
git push origin main
|
|
```
|
|
|
|
---
|
|
|
|
## 🔗 Stap 3: Service Connection Aanmaken in Azure DevOps
|
|
|
|
Deze connection geeft Azure DevOps toegang tot je ACR.
|
|
|
|
1. **Ga naar je Azure DevOps project**
|
|
2. Klik op **⚙️ Project Settings** (onderaan links)
|
|
3. Ga naar **Service connections** (onder Pipelines)
|
|
4. Klik op **"New service connection"**
|
|
5. Kies **"Docker Registry"**
|
|
6. Kies **"Azure Container Registry"**
|
|
7. Vul in:
|
|
- **Azure subscription**: Selecteer je Azure subscription
|
|
- **Azure container registry**: Selecteer je ACR (bijv. `zuyderlandcmdbacr`)
|
|
- **Service connection name**: `zuyderland-cmdb-acr-connection`
|
|
- **Description**: Optioneel (bijv. "ACR for CMDB GUI")
|
|
8. Klik **"Save"**
|
|
|
|
**✅ Noteer de service connection naam!** Deze moet overeenkomen met `dockerRegistryServiceConnection` in `azure-pipelines.yml`.
|
|
|
|
---
|
|
|
|
## 🎯 Stap 4: Pipeline Aanmaken en Run
|
|
|
|
1. **Ga naar je Azure DevOps project**
|
|
2. Klik op **Pipelines** (links in het menu)
|
|
3. Klik op **"New pipeline"** of **"Create Pipeline"**
|
|
4. Kies **"Azure Repos Git"** (of waar je code staat)
|
|
5. Selecteer je repository: **"CMDB Insight"**
|
|
6. Kies **"Existing Azure Pipelines YAML file"**
|
|
7. Selecteer:
|
|
- **Branch**: `main`
|
|
- **Path**: `/azure-pipelines.yml`
|
|
8. Klik **"Continue"**
|
|
9. **Review** de pipeline configuratie
|
|
10. Klik **"Run"** om de pipeline te starten
|
|
|
|
---
|
|
|
|
## ✅ Stap 5: Verifiëren
|
|
|
|
### In Azure Portal:
|
|
1. Ga naar je **Container Registry** (`zuyderlandcmdbacr`)
|
|
2. Klik op **"Repositories"**
|
|
3. Je zou moeten zien:
|
|
- `cmdb-insight/backend`
|
|
- `cmdb-insight/frontend`
|
|
4. Klik op een repository om de tags te zien (bijv. `latest`, `123`)
|
|
|
|
### Via Azure CLI:
|
|
```bash
|
|
# Lijst repositories
|
|
az acr repository list --name zuyderlandcmdbacr
|
|
|
|
# Lijst tags voor backend
|
|
az acr repository show-tags --name zuyderlandcmdbacr --repository cmdb-insight/backend
|
|
|
|
# Lijst tags voor frontend
|
|
az acr repository show-tags --name zuyderlandcmdbacr --repository cmdb-insight/frontend
|
|
```
|
|
|
|
---
|
|
|
|
## 🐳 Stap 6: Images Lokaal Testen (Optioneel)
|
|
|
|
```bash
|
|
# Login bij ACR
|
|
az acr login --name zuyderlandcmdbacr
|
|
|
|
# Pull images
|
|
docker pull zuyderlandcmdbacr.azurecr.io/cmdb-insight/backend:latest
|
|
docker pull zuyderlandcmdbacr.azurecr.io/cmdb-insight/frontend:latest
|
|
|
|
# Test run (met docker-compose)
|
|
docker-compose -f docker-compose.prod.acr.yml pull
|
|
docker-compose -f docker-compose.prod.acr.yml up -d
|
|
```
|
|
|
|
---
|
|
|
|
## 📋 Checklist
|
|
|
|
- [ ] Azure Container Registry aangemaakt
|
|
- [ ] ACR naam genoteerd
|
|
- [ ] `azure-pipelines.yml` variabelen aangepast
|
|
- [ ] Service Connection aangemaakt in Azure DevOps
|
|
- [ ] Pipeline aangemaakt en gerund
|
|
- [ ] Images succesvol gebouwd en gepusht
|
|
- [ ] Images geverifieerd in Azure Portal
|
|
|
|
---
|
|
|
|
## 🔄 Automatische Triggers
|
|
|
|
De pipeline triggert automatisch bij:
|
|
|
|
1. **Push naar `main` branch** → Bouwt `latest` tag
|
|
2. **Git tags die beginnen met `v*`** → Bouwt versie tag (bijv. `v1.0.0`)
|
|
|
|
**Voorbeeld:**
|
|
```bash
|
|
# Tag aanmaken en pushen
|
|
git tag v1.0.0
|
|
git push origin v1.0.0
|
|
# → Pipeline triggert automatisch en bouwt versie 1.0.0
|
|
```
|
|
|
|
---
|
|
|
|
## 🚨 Troubleshooting
|
|
|
|
### Pipeline Fails: "Service connection not found"
|
|
|
|
**Oplossing:**
|
|
- Controleer of de service connection naam in `azure-pipelines.yml` overeenkomt met de naam in Azure DevOps
|
|
- Ga naar Project Settings → Service connections en verifieer de naam
|
|
|
|
### Pipeline Fails: "ACR not found"
|
|
|
|
**Oplossing:**
|
|
- Controleer of de `acrName` variabele correct is in `azure-pipelines.yml`
|
|
- Verifieer dat de ACR bestaat: `az acr list`
|
|
|
|
### Pipeline Fails: "Permission denied"
|
|
|
|
**Oplossing:**
|
|
- Controleer of de service connection de juiste permissions heeft
|
|
- Verifieer dat je Azure subscription toegang heeft tot de ACR
|
|
- Probeer de service connection opnieuw aan te maken
|
|
|
|
### ACR Naam Niet Beschikbaar
|
|
|
|
**Oplossing:**
|
|
- ACR namen moeten uniek zijn wereldwijd
|
|
- Probeer een andere naam:
|
|
- `zuyderlandcmdbacr1`
|
|
- `zuyderlandcmdbprod`
|
|
- `cmdbzuyderlandacr`
|
|
- `zuyderlandcmdbgui`
|
|
|
|
---
|
|
|
|
## 💰 Kosten & SKU Keuze
|
|
|
|
**Aanbeveling: Basic SKU** ⭐ (~€5/maand)
|
|
|
|
### Basic SKU (Aanbevolen voor jouw situatie)
|
|
|
|
**Inclusief:**
|
|
- ✅ **10GB storage** - Ruim voldoende voor backend + frontend images met meerdere versies
|
|
- ✅ **1GB/day webhook throughput** - Voldoende voor CI/CD
|
|
- ✅ **Unlimited pulls** - Geen extra kosten voor image pulls
|
|
- ✅ **Admin user enabled** - Voor development/productie
|
|
- ✅ **RBAC support** - Role-based access control
|
|
- ✅ **Content trust** - Image signing support
|
|
- ✅ **Kosten: ~€5/maand**
|
|
|
|
**Limitaties:**
|
|
- ❌ Geen geo-replicatie
|
|
- ❌ Geen security scanning (vulnerability scanning)
|
|
- ❌ Geen content trust storage
|
|
|
|
**Wanneer gebruiken:**
|
|
- ✅ **Jouw situatie** - 20 gebruikers, corporate tool
|
|
- ✅ Development en productie omgevingen
|
|
- ✅ Kleine tot middelgrote teams
|
|
- ✅ Budget-conscious deployments
|
|
|
|
### Standard SKU (~€20/maand)
|
|
|
|
**Inclusief (alles van Basic +):**
|
|
- 100GB storage
|
|
- 10GB/day webhook throughput
|
|
- Geo-replicatie
|
|
- **Niet nodig voor jouw situatie**
|
|
|
|
### Premium SKU (~€50/maand)
|
|
|
|
**Inclusief (alles van Standard +):**
|
|
- 500GB storage
|
|
- Security scanning
|
|
- Private endpoints
|
|
- **Overkill voor 20 gebruikers**
|
|
|
|
**Voor jouw situatie (20 gebruikers): Basic is perfect!** ✅
|
|
|
|
---
|
|
|
|
## 🔐 Permissions Mode
|
|
|
|
**Aanbeveling: RBAC Registry Permissions** ⭐
|
|
|
|
### RBAC Registry Permissions (Aanbevolen)
|
|
|
|
**Hoe het werkt:**
|
|
- Permissions worden ingesteld op **registry niveau**
|
|
- Alle repositories binnen de registry delen dezelfde permissions
|
|
- Gebruikers hebben toegang tot alle repositories of geen
|
|
|
|
**Voordelen:**
|
|
- ✅ **Eenvoudig** - Minder complexiteit
|
|
- ✅ **Makkelijk te beheren** - Eén set permissions voor de hele registry
|
|
- ✅ **Voldoende voor de meeste scenario's** - Perfect voor jouw situatie
|
|
- ✅ **Standaard keuze** - Meest gebruikte optie
|
|
|
|
**Wanneer gebruiken:**
|
|
- ✅ **Jouw situatie** - 20 gebruikers, corporate tool
|
|
- ✅ Kleine tot middelgrote teams
|
|
- ✅ Alle repositories hebben dezelfde toegangsvereisten
|
|
- ✅ Eenvoudige permission structuur gewenst
|
|
|
|
### RBAC Registry + ABAC Repository Permissions
|
|
|
|
**Wanneer gebruiken:**
|
|
- Als je per-repository permissions nodig hebt
|
|
- Grote teams met verschillende toegangsvereisten
|
|
- Complexe permission structuur
|
|
|
|
**Voor jouw situatie: RBAC Registry Permissions is perfect!** ✅
|
|
|
|
---
|
|
|
|
## 🔄 Shared ACR Setup (Optioneel)
|
|
|
|
Als je al een ACR hebt voor andere applicaties, kun je deze hergebruiken:
|
|
|
|
**Voordelen:**
|
|
- ✅ **Cost Savings**: Eén ACR voor alle applicaties (€5-20/month vs multiple ACRs)
|
|
- ✅ **Centralized Management**: All images in one place
|
|
- ✅ **Easier Collaboration**: Teams can share images
|
|
|
|
**Hoe het werkt:**
|
|
- ACR is shared, maar elke applicatie gebruikt een **unique repository name**
|
|
- Repository name (`cmdb-insight`) scheidt jouw app van anderen
|
|
- Images zijn georganiseerd per applicatie: `acr.azurecr.io/app-name/service:tag`
|
|
|
|
**Voorbeeld structuur:**
|
|
```
|
|
zuyderlandacr.azurecr.io/
|
|
├── cmdb-insight/ ← Deze applicatie
|
|
│ ├── backend:latest
|
|
│ └── frontend:latest
|
|
├── other-app/ ← Andere applicatie
|
|
│ └── api:latest
|
|
└── shared-services/ ← Gedeelde base images
|
|
└── nginx:latest
|
|
```
|
|
|
|
**Setup:**
|
|
```bash
|
|
# Gebruik bestaande ACR
|
|
ACR_NAME="your-existing-acr"
|
|
ACR_RESOURCE_GROUP="rg-shared-services"
|
|
|
|
# Verifieer dat het bestaat
|
|
az acr show --name $ACR_NAME --resource-group $ACR_RESOURCE_GROUP
|
|
|
|
# Update pipeline variabelen met bestaande ACR naam
|
|
```
|
|
|
|
---
|
|
|
|
## 📚 Meer Informatie
|
|
|
|
- **Deployment Guide**: `docs/AZURE-APP-SERVICE-DEPLOYMENT.md`
|
|
- **Azure DevOps Setup**: `docs/AZURE-DEVOPS-SETUP.md`
|
|
- **Deployment Guide**: `docs/PRODUCTION-DEPLOYMENT.md`
|
|
|
|
---
|
|
|
|
## 🎯 Volgende Stappen
|
|
|
|
Nu je images in ACR staan, kun je ze deployen naar:
|
|
|
|
1. **Azure Container Instances (ACI)** - Eenvoudig, snel
|
|
2. **Azure App Service (Container)** - Managed service
|
|
3. **Azure Kubernetes Service (AKS)** - Voor complexere setups
|
|
4. **VM met Docker Compose** - Volledige controle
|
|
|
|
Zie `docs/AZURE-APP-SERVICE-DEPLOYMENT.md` voor deployment opties.
|