cmdb-insight/docs/Core deployment guides/AZURE-ACR-SETUP.md

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)

# 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

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

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:

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:

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

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

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

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