pieter/eveAI
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

- Staging cluster werkend tot op phase 6 van cluster-install.md, inclusief HTTPS, Bunny, verificatie service.

Browse Source
This commit is contained in:
Josako
2025-08-29 17:50:14 +02:00
parent 2a4c9d7b00
commit 25ab9ccf23
23 changed files with 1525 additions and 889 deletions
Download Patch File Download Diff File Expand all files Collapse all files

578
documentation/Production Setup/cluster-install.md
View File

@@ -1,158 +1,514 @@
# Cluster Install
# EveAI Cluster Installation Guide (Updated for Modular Kustomize Setup)
## Fase 1: Ingress Controller Setup
### Stap 1: Installeer de NGINX Ingress Controller
## Prerequisites
```
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.8.2/deploy/static/provider/cloud/deploy.yaml
### Required Tools
```bash
# Verify required tools are installed
kubectl version --client
kustomize version
helm version
# Configure kubectl for Scaleway cluster
scw k8s kubeconfig install <cluster-id>
kubectl cluster-info
```
### Stap 2: Verifieer de Installatie
Kijk of de namespace is aangemaakt
### Scaleway Prerequisites
- Kubernetes cluster running
- Managed services configured (PostgreSQL, Redis, MinIO)
- Secrets stored in Scaleway Secret Manager:
- `eveai-app-keys`, `eveai-mistral`, `eveai-object-storage`
- `eveai-openai`, `eveai-postgresql`, `eveai-redis`, `eveai-redis-certificate`
- Flexible IP address (LoadBalancer)
- Eerst een loadbalancer aanmaken met publiek IP
- Daarna de loadbalancer verwijderen maar flexible IPs behouden
- Dit externe IP is het IP adres dat moet worden verwerkt in ingress-values.yaml!
```
kubectl get namespaces | grep ingress-nginx
## New Modular Deployment Process
### Phase 1: Infrastructure Foundation
Deploy core infrastructure components in the correct order:
```bash
# 1. Deploy namespaces
kubectl apply -f scaleway/manifests/base/infrastructure/00-namespaces.yaml
# 2. Add NGINX Ingress Helm repository
helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update
# 3. Deploy NGINX ingress controller via Helm
helm install ingress-nginx ingress-nginx/ingress-nginx \
--namespace ingress-nginx \
--create-namespace \
--values scaleway/manifests/base/infrastructure/ingress-values.yaml
# 4. Wait for ingress controller to be ready
kubectl wait --namespace ingress-nginx \
--for=condition=ready pod \
--selector=app.kubernetes.io/component=controller \
--timeout=300s
# 5. Add cert-manager Helm repository
helm repo add jetstack https://charts.jetstack.io
helm repo update
# 6. Install cert-manager CRDs
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.15.3/cert-manager.crds.yaml
# 7. Deploy cert-manager via Helm
helm install cert-manager jetstack/cert-manager \
--namespace cert-manager \
--create-namespace \
--values scaleway/manifests/base/infrastructure/cert-manager-values.yaml
# 8. Wait for cert-manager to be ready
kubectl wait --namespace cert-manager \
--for=condition=ready pod \
--selector=app.kubernetes.io/name=cert-manager \
--timeout=300s
# 9. Deploy cluster issuers
kubectl apply -f scaleway/manifests/base/infrastructure/03-cluster-issuers.yaml
```
Check of de pods worden gestart
### Phase 2: Verification Infrastructure Components
```
```bash
# Verify ingress controller
kubectl get pods -n ingress-nginx
kubectl get svc -n ingress-nginx
# Verify cert-manager
kubectl get pods -n cert-manager
kubectl get clusterissuers
# Check LoadBalancer external IP
kubectl get svc -n ingress-nginx ingress-nginx-controller
```
Check de services (dit is het belangrijkste!)
### Phase 3: Monitoring Stack (Optional but Recommended)
```
kubectl get services -n ingress-nginx
#### Add Prometheus Community Helm Repository
```bash
# Add Prometheus community Helm repository
helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm repo update
# Verify chart availability
helm search repo prometheus-community/kube-prometheus-stack
```
Je zou zoiets als dit moeten zien:
#### Create Monitoring Values File
```
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
ingress-nginx-controller NodePort 10.43.xxx.xxx <none> 80:30080/TCP,443:30443/TCP 1m
Create `scaleway/manifests/base/monitoring/prometheus-values.yaml`:
#### Deploy Monitoring Stack
```bash
# Install complete monitoring stack via Helm
helm install monitoring prometheus-community/kube-prometheus-stack \
--namespace monitoring \
--create-namespace \
--values scaleway/manifests/base/monitoring/prometheus-values.yaml
# Monitor deployment progress
kubectl get pods -n monitoring -w
# Wait until all pods show STATUS: Running
```
Watch de pods tot ze ready zijn
#### Verify Monitoring Deployment
```
kubectl get pods -n ingress-nginx -w
```bash
# Check Helm release
helm list -n monitoring
# Verify all components are running
kubectl get all -n monitoring
# Check persistent volumes are created
kubectl get pvc -n monitoring
# Check ServiceMonitor CRDs are available (for application monitoring)
kubectl get crd | grep monitoring.coreos.com
```
Stop met Ctrl+C als je dit ziet:
#### Enable cert-manager Monitoring Integration
```
ingress-nginx-controller-xxx 1/1 Running 0 2m
```bash
# Enable Prometheus monitoring in cert-manager now that ServiceMonitor CRDs exist
helm upgrade cert-manager jetstack/cert-manager \
--namespace cert-manager \
--set prometheus.enabled=true \
--set prometheus.servicemonitor.enabled=true \
--reuse-values
```
Check de NodePorts, dit is cruciaal voor je Scaleway LoadBalancer configuratie:
#### Access Monitoring Services
```
kubectl get service ingress-nginx-controller -n ingress-nginx -o yaml | grep nodePort
##### Grafana Dashboard
```bash
# Port forward to access Grafana
kubectl port-forward -n monitoring svc/monitoring-grafana 3000:80
# Access via browser: http://localhost:3000
# Username: admin
# Password: admin123 (from values file)
```
Of een overzichtelijker weergave:
##### Prometheus UI
```bash
# Port forward to access Prometheus
kubectl port-forward -n monitoring svc/monitoring-prometheus 9090:9090 &
# Access via browser: http://localhost:9090
# Check targets: http://localhost:9090/targets
```
#### Cleanup Commands (if needed)
If you need to completely remove monitoring for a fresh start:
```bash
# Uninstall Helm release
helm uninstall monitoring -n monitoring
# Remove namespace
kubectl delete namespace monitoring
# Remove any remaining cluster-wide resources
kubectl get clusterroles | grep monitoring | awk '{print $1}' | xargs -r kubectl delete clusterrole
kubectl get clusterrolebindings | grep monitoring | awk '{print $1}' | xargs -r kubectl delete clusterrolebinding
```
#### What we installed
With monitoring successfully deployed:
- Grafana provides pre-configured Kubernetes dashboards
- Prometheus collects metrics from all cluster components
- ServiceMonitor CRDs are available for application-specific metrics
- AlertManager handles alert routing and notifications
### Phase 4: Secrets
#### Stap 1: Installeer External Secrets Operator
```bash
# Add Helm repository
helm repo add external-secrets https://charts.external-secrets.io
helm repo update
# Install External Secrets Operator
helm install external-secrets external-secrets/external-secrets \
--namespace external-secrets-system \
--create-namespace
# Verify installation
kubectl get pods -n external-secrets-system
# Check CRDs zijn geïnstalleerd
kubectl get crd | grep external-secrets
```
#### Stap 2: Maak Scaleway API credentials aan
Je hebt Scaleway API credentials nodig voor de operator:
```bash
# Create secret with Scaleway API credentials
kubectl create secret generic scaleway-credentials \
--namespace eveai-staging \
--from-literal=access-key="JOUW_SCALEWAY_ACCESS_KEY" \
--from-literal=secret-key="JOUW_SCALEWAY_SECRET_KEY"
```
**Note:** Je krijgt deze credentials via:
- Scaleway Console → Project settings → API Keys
- Of via `scw iam api-key list` als je de CLI gebruikt
#### Stap 3: Verifieer SecretStore configuratie
Verifieer bestand: `scaleway/manifests/base/secrets/scaleway-secret-store.yaml`. Daar moet de juiste project ID worden ingevoerd.
#### Stap 4: Verifieer ExternalSecret resource
Verifieer bestand: `scaleway/manifests/base/secrets/eveai-external-secrets.yaml`
**Belangrijk:**
- Scaleway provider vereist `key: name:secret-name` syntax
- SSL/TLS certificaten kunnen niet via `dataFrom/extract` worden opgehaald
- Certificaten moeten via `data` sectie worden toegevoegd
#### Stap 5: Deploy secrets
```bash
# Deploy SecretStore
kubectl apply -f scaleway/manifests/base/secrets/scaleway-secret-store.yaml
# Deploy ExternalSecret
kubectl apply -f scaleway/manifests/base/secrets/eveai-external-secrets.yaml
```
#### Stap 6: Verificatie
```bash
# Check ExternalSecret status
kubectl get externalsecrets -n eveai-staging
# Check of het Kubernetes secret is aangemaakt
kubectl get secret eveai-secrets -n eveai-staging
# Check alle keys in het secret
kubectl get secret eveai-secrets -n eveai-staging -o jsonpath='{.data}' | jq 'keys'
# Check specifieke waarde (base64 decoded)
kubectl get secret eveai-secrets -n eveai-staging -o jsonpath='{.data.DB_HOST}' | base64 -d
# Check ExternalSecret events voor troubleshooting
kubectl describe externalsecret eveai-external-secrets -n eveai-staging
```
#### Stap 7: Gebruik in deployment
Je kunt nu deze secrets gebruiken in de deployment van de applicatie services die deze nodig hebben (TODO):
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: eveai-app
namespace: eveai-staging
spec:
template:
spec:
containers:
- name: eveai-app
envFrom:
- secretRef:
name: eveai-secrets # Alle environment variables uit één secret
# Je Python code gebruikt gewoon environ.get('DB_HOST') etc.
```
#### Stap 8: Redis certificaat gebruiken in Python
Voor SSL Redis connecties met het certificaat:
```python
# In je config.py
import tempfile
import ssl
import redis
from os import environ
class StagingConfig(Config):
REDIS_CERT_DATA = environ.get('REDIS_CERT')
def create_redis_connection(self):
if self.REDIS_CERT_DATA:
# Schrijf certificaat naar tijdelijk bestand
with tempfile.NamedTemporaryFile(mode='w', delete=False, suffix='.pem') as f:
f.write(self.REDIS_CERT_DATA)
cert_path = f.name
# Redis connectie met SSL certificaat
return redis.from_url(
self.REDIS_BASE_URI,
ssl_cert_reqs=ssl.CERT_REQUIRED,
ssl_ca_certs=cert_path
)
else:
return redis.from_url(self.REDIS_BASE_URI)
# Gebruik voor session Redis
SESSION_REDIS = property(lambda self: self.create_redis_connection())
```
#### Scaleway Secret Manager Vereisten
Voor deze setup moeten je secrets in Scaleway Secret Manager correct gestructureerd zijn:
**JSON secrets (eveai-postgresql, eveai-redis, etc.):**
```json
{
"DB_HOST": "your-postgres-host.rdb.fr-par.scw.cloud",
"DB_USER": "eveai_user",
"DB_PASS": "your-password",
"DB_NAME": "eveai_staging",
"DB_PORT": "5432"
}
```
**SSL/TLS Certificaat (eveai-redis-certificate):**
```
-----BEGIN CERTIFICATE-----
MIIDGTCCAgGg...z69LXyY=
-----END CERTIFICATE-----
```
#### Voordelen van deze setup
- **Automatische sync**: Secrets worden elke 5 minuten geüpdatet
- **Geen code wijzigingen**: Je `environ.get()` calls blijven werken
- **Secure**: Credentials zijn niet in manifests, alleen in cluster
- **Centralized**: Alle secrets in Scaleway Secret Manager
- **Auditable**: External Secrets Operator logt alle acties
- **SSL support**: TLS certificaten worden correct behandeld
#### File structuur
```
scaleway/manifests/base/secrets/
├── scaleway-secret-store.yaml
└── eveai-external-secrets.yaml
```
### Phase 5: TLS en Network setup
#### Deploy HTTP ACME ingress
Om het certificaat aan te maken, moet in de DNS-zone een A-record worden aangemaakt dat rechtstreeks naar het IP van de loadbalancer wijst.
We maken nog geen CNAME aan naar Bunny.net. Anders gaat bunny.net het ACME proces mogelijks onderbreken.
Om het certificaat aan te maken, moeten we een HTTP ACME ingress gebruiken. Anders kan het certificaat niet worden aangemaakt.
```
kubectl apply -f scaleway/manifests/base/networking/ingress-http-acme.yaml
```
Check of het certificaat is aangemaakt (READY moet true zijn):
```
kubectl get certificate evie-staging-tls -n eveai-staging
# of met meer detail
kubectl -n eveai-staging describe certificate evie-staging-tls
```
Dit kan even duren. Maar zodra het certificaat is aangemaakt, kan je de de https-only ingress opzetten:
```
kubectl apply -f scaleway/manifests/base/networking/ingress-https.yaml
```
Om bunny.net te gebruiken:
- Nu kan het CNAME-record dat verwijst naar de Bunny.net Pull zone worden aangemaakt.
- In bunny.net moet in de pull-zone worden verwezen naar de loadbalancer IP via het HTTPS-protocol.
### Phase 6: Verification Service
Deze service kan ook al in Phase 5 worden geïnstalleerd om te verifiëren of de volledige netwerkstack (over bunny, certificaat, ...) werkt.
```bash
# Deploy verification service
kubectl apply -k scaleway/manifests/base/applications/verification/
### Phase 7: Complete Staging Deployment
```bash
# Deploy everything using the staging overlay
kubectl apply -k scaleway/manifests/overlays/staging/
# Verify complete deployment
kubectl get all -n eveai-staging
kubectl get ingress -n eveai-staging
kubectl get certificates -n eveai-staging
```
## Verification and Testing
### Check Infrastructure Status
```bash
# Verify ingress controller
kubectl get pods -n ingress-nginx
kubectl describe service ingress-nginx-controller -n ingress-nginx
# Verify cert-manager
kubectl get pods -n cert-manager
kubectl get clusterissuers
# Check certificate status (may take a few minutes to issue)
kubectl describe certificate evie-staging-tls -n eveai-staging
```
Je zoekt naar iets zoals:
### Test Services
```bash
# Get external IP from LoadBalancer
kubectl get svc -n ingress-nginx ingress-nginx-controller
```
HTTP: Port 80 → NodePort 30080 (of een ander hoog nummer)
HTTPS: Port 443 → NodePort 30443 (of een ander hoog nummer)
```
### Stap 3: Check de scaleway loadbalancer
Er werd normaal gezien automatisch een loadbalancer aangemaakt. Check of dit klopt. Deze is automatisch correct geconfigureerd en kan niet worden aangepast.
# Test HTTPS access (replace with your domain)
curl -k https://evie-staging.askeveai.com/verify/health
curl -k https://evie-staging.askeveai.com/verify/info
### Stap 4: Verifieer de firewall rules
- Ga in de console naar Compute - CPU & GPU Instances
- Ga naar de security groups tab
- Klik op de security group voor je cluster (Kapsule Default Security Group)
- Ga naar de rules tab, en check of de poort (3xxxx) is toegevoegd aan de firewall rules, en voeg die toe indien nog niet aanwezig.
- Stel dit eerst in voor de volledige ipv4 range
### Stap 4: Test de Basis Setup
Test of de ingress controller intern bereikbaar is (vervang de IP en NodePort door je eigen):
```
kubectl run test-pod --image=curlimages/curl -it --rm -- curl -H "Host: evie.askeveai.com" http://172.16.16.5:31127
# Test monitoring (if deployed)
kubectl port-forward -n monitoring svc/monitoring-grafana 3000:80
# Access Grafana at http://localhost:3000 (admin/admin123)
```
Er moet een 404 boodschap komen (dat is goed! Het betekent dat nginx draait)
## DNS Configuration
Test of de ingress controller extern bereikbaar is (pas IP aan):
### Update DNS Records
- Create A-record pointing to LoadBalancer external IP
- Or set up CNAME if using CDN
```
curl -H "Host: evie.askeveai.com" http://51.159.204.52
```
### Test Domain Access
```bash
# Test domain resolution
nslookup evie-staging.askeveai.com
## Fase 2: Deploy test applicatie
We hebben een kleine test applicatie geïntegreerd in staging-test-setup.yaml. Installeer deze via:
```
kubectl apply -f staging-test-setup.yaml
```
En check met
```
curl -H "Host: evie-staging.askeveai.com" http://51.159.204.52/verify/
```
### Later Uitbreiden
Wanneer je echte services deploy, uncomment je de relevante ingress paths en deploy je de bijbehorende services. De verify service blijft beschikbaar voor debugging.
Deze setup geeft je een professionele staging environment met ingebouwde monitoring en debug capabilities.
## Fase 3: Configureer DNS
Maak het juist A-record aan in de DNS zone. Dit moet verwijzen naar de publieke IP van de loadbalancer.
Je kan testen met:
```
curl http://evie-staging.askeveai.com/verify/
```
In de browser zal dit waarschijnlijk niet werken, omdat de site nog niet is beveiligd met SSL.
## Fase 4: Bunny CDN Setup
Eerst zorg je dat Bunny klaar is om te werken.
- Creëer een Pull zone - evie-staging
- Origin = http://[IP van load balancer]
- Host header = evie-staging.askeveai.com
- Force SSL - Aan
Daarna wijzig je A-record in de DNS zone. (waarschijnlijk verwijderen en CNAME record toevoegen)
## Fase 5: Introductie Secure communication
### Installatie van SSL Certificaat in de bunny pull zone
- Voeg een hostname toe aan de bunny pull zone (evie-staging.askeveai.com)
- Voeg een SSL certificaat toe aan de bunny pull zone (volg gewoon de instructies)
- Enable Force SSL
Je kan checken met:
```
# Test HTTPS access via domain
curl https://evie-staging.askeveai.com/verify/
```
### Installatie cert-manager in de cluster
## CDN Setup (Bunny.net - Optional)
```
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.2/cert-manager.crds.yaml
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.2/cert-manager.yaml
### Configure Pull Zone
- Create Pull zone: evie-staging
- Origin: https://[LoadBalancer-IP] (note HTTPS!)
- Host header: evie-staging.askeveai.com
- Force SSL: Enabled
### Update DNS for CDN
- Change A-record to CNAME pointing to CDN endpoint
- Or update A-record to CDN IP
## Key Differences from Old Setup
### Advantages of New Modular Approach
1. **Modular Structure**: Separate infrastructure from applications
2. **Environment Management**: Easy staging/production separation
3. **HTTPS-First**: TLS certificates managed automatically
4. **Monitoring Integration**: Prometheus/Grafana via Helm charts
5. **Scaleway Integration**: Managed services secrets support
6. **Maintainability**: Clear separation of concerns
### Migration Benefits
- **Organized**: Base configurations with environment overlays
- **Scalable**: Easy to add new services or environments
- **Secure**: HTTPS-only from deployment start
- **Observable**: Built-in monitoring stack
- **Automated**: Less manual intervention required
## Troubleshooting
### Common Issues
```bash
# Certificate not issued
kubectl describe certificate evie-staging-tls -n eveai-staging
kubectl logs -n cert-manager deployment/cert-manager
# Ingress not accessible
kubectl describe ingress eveai-staging-ingress -n eveai-staging
kubectl logs -n ingress-nginx deployment/ingress-nginx-controller
# Check events for issues
kubectl get events -n eveai-staging --sort-by='.lastTimestamp'
```
En het cert-manager-setup.yaml manifest toepassen (zorgen dat email adres en domein correct zijn)
```
kubectl apply -f cert-manager-setup.yaml
```
For detailed troubleshooting, refer to the main deployment guide: `documentation/scaleway-deployment-guide.md`