aloitus dokumentaatio
This commit is contained in:
moilanik
@@ -0,0 +1,199 @@
|
||||
# Raporttivarasto — MinIO
|
||||
|
||||
> Kuuluu arkkitehtuuriin: [architecture.md](architecture.md). Tämä dokumentti määrittelee testiraporttien tallennuksen, URL-rakenteen, autentikoinnin ja retention policyn.
|
||||
|
||||
---
|
||||
|
||||
## Miksi MinIO
|
||||
|
||||
Gitea Actionsin sisäänrakennettu artifact-järjestelmä ei tue HTML-selailtavuutta (vain ZIP-lataus), ja artifactien retentio on aikapohjainen (oletus 90 vrk). Jenkins-versiossa raportit olivat selailtavissa suoraan buildista ja pysyivät build-historian mukana.
|
||||
|
||||
MinIO täyttää tämän aukon:
|
||||
|
||||
- **S3-yhteensopiva** — standardi API, laaja työkalutuki (`mc`, `s3cmd`, AWS SDK)
|
||||
- **Staattinen web-hosting** — HTML-raportit renderöityvät selaimessa suoraan bucketista
|
||||
- **Kubernetes-natiivi** — yksi binääri, helppo deployata samaan klusteriin
|
||||
- **Ei per-repo-konfiguraatiota** — yksi bucket palvelee kaikkia projekteja
|
||||
- **Ennustettava URL** — polku rakentuu deterministisesti reposta ja commitista
|
||||
|
||||
## URL-rakenne
|
||||
|
||||
```
|
||||
{MINIO_BASE}/{repo_slug}/{commit_short}/{report_type}/index.html
|
||||
```
|
||||
|
||||
| Osa | Lähde | Esimerkki |
|
||||
|-----|-------|-----------|
|
||||
| `MINIO_BASE` | Gitea org variable `MINIO_BASE_URL` | `https://reports.smith.keskikuja.site` |
|
||||
| `repo_slug` | `GITHUB_REPOSITORY` → slug | `temperature-store` |
|
||||
| `commit_short` | `GITHUB_SHA` → 8 merkkiä | `abc12345` |
|
||||
| `report_type` | Raportin tyyppi | `cucumber`, `jacoco`, `junit`, `site` |
|
||||
|
||||
URL rakennetaan `push-reports.sh`-skriptissä ja POSTataan Gitea-commitin statusviestiin `url`-kenttään.
|
||||
|
||||
## Staattinen web-hosting
|
||||
|
||||
MinIO-bucket konfiguroidaan staattiseksi web-sivustoksi:
|
||||
|
||||
```bash
|
||||
mc anonymous set download minio/reports
|
||||
mc website create minio/reports --region us-east-1
|
||||
```
|
||||
|
||||
Bucketin rakenne:
|
||||
|
||||
```
|
||||
reports/
|
||||
├── temperature-store/
|
||||
│ ├── abc12345/
|
||||
│ │ ├── cucumber/
|
||||
│ │ │ └── overview-features.html
|
||||
│ │ ├── jacoco/
|
||||
│ │ │ └── index.html
|
||||
│ │ └── site/
|
||||
│ │ └── index.html
|
||||
│ └── def67890/
|
||||
│ └── ...
|
||||
├── user-service/
|
||||
│ └── ...
|
||||
```
|
||||
|
||||
Jokaisella buildilla on oma `{commit_short}`-hakemistonsa — ei race conditionia rinnakkaisten buildien välillä.
|
||||
|
||||
## Autentikointi: OIDC + Traefik middleware
|
||||
|
||||
Raporttien tulee olla katseltavissa ilman erillistä kirjautumista (muuten commitin statusviestin URL-linkki ei toimi suoraan). Samalla julkinen bucket halutaan suojata.
|
||||
|
||||
**Ratkaisu:** MinIO asetetaan Traefik reverse-proxyn taakse. Traefik middleware hoitaa OIDC-autentikoinnin, jossa:
|
||||
|
||||
1. Käyttäjä klikkaa raportin URL:ää commitin statusviestistä
|
||||
2. Traefik ohjaa OIDC-kirjautumiseen (Gitea OAuth2 provider)
|
||||
3. Onnistuneen kirjautumisen jälkeen käyttäjä ohjataan raporttiin
|
||||
4. Session säilyy — ei tarvitse kirjautua jokaista raporttia varten
|
||||
|
||||
```
|
||||
Selain ──→ Traefik ──→ OIDC middleware ──→ Gitea OAuth2
|
||||
│
|
||||
└──→ MinIO (bucket reports, static web)
|
||||
```
|
||||
|
||||
**CI-pusku ohittaa OIDC:n:** Workflow'n `push-reports.sh` käyttää MinIO:n S3 API:a suoraan access key + secret key -parilla (Gitea org secrets). CI-liikenne ei kulje julkisen ingressin kautta — `mc`-työkalu puhuu suoraan MinIO-palvelulle klusterin sisällä.
|
||||
|
||||
## Retention policy
|
||||
|
||||
Pelkkä aikaperustainen retentio ("poista yli 90 vrk vanhat") ei riitä. Retention policyn pitää huomioida:
|
||||
|
||||
| Kriteeri | Kuvaus |
|
||||
|----------|--------|
|
||||
| **Aika** | Raportti säilyy X päivää buildin jälkeen |
|
||||
| **Branch** | `master`-branchin raportit säilyvät pidempään kuin feature-branchien |
|
||||
| **Tagi** | Version kanssa tagitun commitin raportteja ei poisteta koskaan |
|
||||
| **Viimeisin N** | Jokaisesta branchista säilytetään vähintään N uusinta raporttia |
|
||||
|
||||
**Toteutus:** Retention policy konfiguroidaan **ConfigMap:lla**, jonka siivousskripti lukee. ConfigMap on osa MinIO-deploymentin Kubernetes-manifestia.
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: ConfigMap
|
||||
metadata:
|
||||
name: minio-report-retention
|
||||
data:
|
||||
retention.yaml: |
|
||||
rules:
|
||||
- branch: "master"
|
||||
maxAgeDays: 365
|
||||
keepMin: 20
|
||||
- branch: "feature/*"
|
||||
maxAgeDays: 90
|
||||
keepMin: 5
|
||||
- tagged: true
|
||||
maxAgeDays: -1 # ei koskaan poisteta
|
||||
keepMin: -1
|
||||
- default:
|
||||
maxAgeDays: 90
|
||||
keepMin: 3
|
||||
```
|
||||
|
||||
Siivoussripti ajetaan CronJobina (esim. kerran päivässä):
|
||||
|
||||
1. Listaa kaikki bucketin objektit
|
||||
2. Parsii polusta `repo_slug` ja `commit_short`
|
||||
3. Hakee Gitea API:sta commitin metadata (branch, onko tagattu)
|
||||
4. Soveltaa ConfigMapin retention-sääntöjä
|
||||
5. Poistaa vanhentuneet objektit `mc rm`:llä
|
||||
|
||||
## Raporttien pushaus workflow'sta
|
||||
|
||||
`push-reports.sh`:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Käyttö: push-reports.sh <report_type> <source_dir>
|
||||
# Esim: push-reports.sh cucumber target/cucumber-report/
|
||||
|
||||
REPORT_TYPE=$1
|
||||
SOURCE_DIR=$2
|
||||
TARGET="minio/reports/${GITHUB_REPOSITORY}/${GITHUB_SHA::8}/${REPORT_TYPE}/"
|
||||
|
||||
mc cp --recursive "$SOURCE_DIR" "$TARGET"
|
||||
|
||||
echo "${MINIO_BASE_URL}/${GITHUB_REPOSITORY}/${GITHUB_SHA::8}/${REPORT_TYPE}/index.html"
|
||||
```
|
||||
|
||||
Skripti palauttaa URL:n, joka syötetään `report-status.sh`:lle commit-statusviestin `url`-kenttään.
|
||||
|
||||
## Konfiguraatio Giteassa
|
||||
|
||||
| Secret / Variable | Tyyppi | Sisältö |
|
||||
|---|---|---|
|
||||
| `MINIO_ACCESS_KEY` | Org secret | MinIO access key |
|
||||
| `MINIO_SECRET_KEY` | Org secret | MinIO secret key |
|
||||
| `MINIO_BASE_URL` | Org variable | `https://reports.smith.keskikuja.site` |
|
||||
|
||||
Workflow lukee nämä automaattisesti — projekti ei määrittele niitä `ci-flow-values.yaml`:ssa.
|
||||
|
||||
## MinIO-deployment (viitteellinen)
|
||||
|
||||
Minimalistinen Kubernetes-deployment samassa klusterissa:
|
||||
|
||||
```yaml
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: minio-reports
|
||||
spec:
|
||||
replicas: 1
|
||||
template:
|
||||
spec:
|
||||
containers:
|
||||
- name: minio
|
||||
image: minio/minio:latest
|
||||
args: ["server", "/data", "--console-address", ":9001"]
|
||||
env:
|
||||
- name: MINIO_ROOT_USER
|
||||
valueFrom:
|
||||
secretKeyRef:
|
||||
name: minio-secrets
|
||||
key: access-key
|
||||
- name: MINIO_ROOT_PASSWORD
|
||||
valueFrom:
|
||||
secretKeyRef:
|
||||
name: minio-secrets
|
||||
key: secret-key
|
||||
ports:
|
||||
- containerPort: 9000 # S3 API
|
||||
- containerPort: 9001 # Console UI
|
||||
volumeMounts:
|
||||
- name: data
|
||||
mountPath: /data
|
||||
volumes:
|
||||
- name: data
|
||||
persistentVolumeClaim:
|
||||
claimName: minio-reports-pvc
|
||||
```
|
||||
|
||||
## Huomioitavaa
|
||||
|
||||
- **Bucketin luonti ja web-hostingin aktivointi** tehdään kerran deploymentin yhteydessä. Ei per build.
|
||||
- **URL on deterministinen** — raportin URL voidaan generoida jo ennen kuin raportti on pushattu. Jos raporttihakemistoa ei ole (esim. testit skipattiin), linkki johtaa 404:ään.
|
||||
- **Indeksitiedoston nimi** riippuu raporttityypistä: Cucumber → `overview-features.html`, JaCoCo → `index.html`, Maven Site → `index.html`. `push-reports.sh`:n vastuulla varmistaa, että indeksitiedosto löytyy.
|
||||
Reference in New Issue
Block a user