eveAI/documentation/evie_object_storage_governance.md

Evie Object Storage Governance (Optie 3)

Doel: 1 bucket per omgeving (staging / prod), met prefixen per tenant. Duidelijke scheiding van datatypes (documents vs assets), lage beheerlast, goed schaalbaar.

---

1) Structuur & naamgeving

Buckets (per omgeving)

• staging: evie-staging
• prod: evie-prod

Buckets zijn S3-compatibel op Scaleway (https://s3.<regio>.scw.cloud). Houd buckets "plat" (alle tenants als prefix).

Prefix layout (per tenant)

<bucket>/
  tenant-<tenantId>/
    documents/
      <subfolders naar keuze>...
    assets/
      <subfolders naar keuze>...

Conventies - Tenant prefix: tenant-<tenantId> (tenantId = interne stabiele sleutel; geen PII). - Datatypes: documents/ en assets/ (harde scheiding). - Bestandsnamen: snake-case of kebab-case; voeg optioneel datum/uuid toe bij uploads die kunnen conflicteren.

---

2) Toegang & secrets

IAM-model

• Één IAM Application per omgeving
  • evie-staging-app → keys in staging k8s Secret\
  • evie-prod-app → keys in prod k8s Secret\
• Toegang alleen tot het eigen bucket (evie-staging of evie-prod).

App-side secrets (env)

• S3_ENDPOINT=https://s3.<regio>.scw.cloud
• S3_BUCKET=evie-<env>
• S3_ACCESS_KEY=***
• S3_SECRET_KEY=***
• S3_REGION=<regio> (bv. fr-par)
• (optioneel) S3_FORCE_PATH_STYLE=false

Presigned uploads: genereer server-side presigned URL's per tenant/prefix; geef nooit de master-keys aan de client.

---

3) Policies (conceptueel)

• Bucket policy: sta alleen requests toe met geldige credentials van de Evie-app van die omgeving.
• Prefix scope (in app-logica): alle reads/writes moeten met pad beginnen op tenant-<tenantId>/....
• Optioneel (later): extra policy-groepen voor specifieke workflows (vb. tijdelijke ingest job).

Belangrijk: autorisatie op tenantniveau afdwingen in je applicatie (context = tenantId). Nooit paden samenstellen vanuit user input zonder whitelisting/validation.

---

4) Lifecycle & retentie

Doel: kosten beheersen, assets sneller "kouder", documenten langer bewaren.

---

Scope (Filter) Regel

---

tenant-*/assets/ → One Zone-IA na 30 dagen

tenant-*/assets/ → Glacier/Archive na 180 dagen (optioneel)

tenant-*/documents/ → Standard (geen transition) of IA na 180d

tenant-*/documents/ (tijdelijke Expire (delete) na 7--14 dagen previews)

Lifecycle definieer je per bucket met prefix filters, zodat regels verschillend zijn voor assets/ en documents/.

---

5) CORS & distributie

• CORS: indien browser direct upload/download doet, whitelist de domeinen van je app (origin), en methodes GET, PUT, POST. Alleen benodigde headers toestaan.
• Publieke distributie (indien nodig):
  • Kleine public-reads via presigned URL's (aanbevolen).\
  • Of activeer publieke read op een specifieke public/-prefix (niet op de hele bucket).\
  • Overweeg een CDN/edge-lag via Scaleway Edge Services voor veelgevraagde assets.

---

6) Observability & beheer

• Logging/metrics:
  • App: log alle S3 calls met tenantId + object key.\
  • Platform: gebruik Scaleway Cockpit voor capacity & request metrics.
• Quota & limieten:
  • 1 bucket per omgeving beperkt "bucket-sprawl".\
  • Objecten en totale grootte zijn praktisch onbeperkt; plan wel lifecycle om groei te managen.
• Monitoring:
  • Alerts op snelgroeiende assets-prefixen, high error rates (4xx/5xx), en mislukte lifecycle-transities.

---

7) Operationele workflows

Tenant aanmaken

1. DB schema provisionen.
2. (S3) Geen nieuwe bucket; enkel prefix: tenant-<id>/documents/ en tenant-<id>/assets/ zijn impliciet.
3. (Optioneel) Init bestanden/placeholder objecten.
4. App-config linkt de tenant aan zijn prefix (centrale mapping).

Upload (app -> S3)

1. App valideert tenantId en datatype (documents|assets).\
2. App construeert canonical path: tenant-<id>/<datatype>/<...>\
3. App genereert presigned PUT (tijdelijk) en geeft terug aan frontend.\
4. Frontend uploadt rechtstreeks naar S3 met presigned URL.

Download / Serve

• Interne downloads: app signed GET of server-side stream.\
• Externe/public: presigned GET met korte TTL of via public-only prefix + CDN.

Opruimen & lifecycle

• Tijdelijke artefacten: app scheduled cleanup (of lifecycle "Expiration").\
• Archivering: lifecycle transitions per prefix.

---

8) Beveiliging

• Least privilege: IAM-keys enkel voor het bucket van de omgeving.\
• Encryptie: server-side encryption (default) volstaat vaak; overweeg KMS als apart key-beleid nodig is.\
• Auditing: log alle write-operaties met gebruikers- en tenantcontext.\
• Backups: documenten zijn de "bron"? Zo ja, S3 is primaire opslag en RAG-index kan herbouwd worden. Anders: definieer export/replica-strategie.

---

9) Migratie van MinIO → Scaleway

1. Freeze window (kort): pauzeer uploads of werk met duale write (MinIO + S3) gedurende migratie.\
2. Sync: gebruik rclone of mc mirror om minio://bucket/tenant-*/{documents,assets}/ → s3://evie-<env>/tenant-*/....\
3. Verifieer: random checksums / sample reads per tenant.\
4. Switch: zet S3_ENDPOINT en keys naar Scaleway; laat nieuwe writes enkel naar S3 gaan.\
5. Decom: na grace-periode MinIO uitfaseren.

---

10) Checklist (TL;DR)

• Buckets: evie-staging, evie-prod.\
• Prefix: tenant-<id>/{documents,assets}/.\
• IAM: 1 Application per omgeving; keys in k8s Secret.\
• Policy: alleen app-toegang; app dwingt prefix-scope per tenant af.\
• Lifecycle: assets sneller koud, docs langer.\
• CORS: alleen noodzakelijke origins/methods.\
• Presigned URLs voor browser interacties.\
• Logging/metrics/alerts ingericht.\
• Migratiepad van MinIO uitgewerkt en getest.