143 lines
4.7 KiB
Markdown
143 lines
4.7 KiB
Markdown
# Architecture — git-pages
|
|
|
|
> Komponentit, datavirrat ja rajapinnat. Miksi näin on rakennettu: [design-rationale.md](design-rationale.md).
|
|
> Secretit: [secrets.md](secrets.md). Teknologiat: [tech-stack.md](tech-stack.md).
|
|
|
|
Tämä dokumentti koskee vain `git-pages/`-palvelua — ei juuren `gitea-ci-library`-kirjastoa.
|
|
|
|
---
|
|
|
|
## Yleiskuvaus
|
|
|
|
git-pages on jaettu **HTML-raporttiarkisto**: yksi apex-host, monta Gitea-repoa, commit-kohtaiset
|
|
raporttipolut. Julkaisija (esim. CI) puskaa sisällön tar-arkistona; lukija avaa raportin
|
|
selaimella commit-linkistä.
|
|
|
|
Codeberg git-pages ajaa `PAGES_INSECURE=1` — sovellus ei tee forge-authia. Julkaisu- ja
|
|
TLS-rajaukset ovat Kubernetes-kerroksessa (Traefik, cert-manager, Secretit).
|
|
|
|
---
|
|
|
|
## Komponentit
|
|
|
|
| Komponentti | Rooli |
|
|
|-------------|-------|
|
|
| **git-pages Pod** | Codeberg git-pages `0.9.1`, filesystem-storage `/app/data` |
|
|
| **retention sidecar** | Samassa podissa, HTTP API localhost:3000, siivoaa vanhat raportit |
|
|
| **PVC** | Raporttisisältö (storage v2 — `.index` + blob) |
|
|
| **Service** | ClusterIP :3000 git-pagesille |
|
|
| **Traefik IngressRoute** | Julkaisu (PATCH/PUT + BasicAuth) ja luku (GET/HEAD) eri säännöillä |
|
|
| **Traefik Middleware** | `git-pages-publish-auth` (BasicAuth), HTTPS-redirect |
|
|
| **cert-manager Certificate** | TLS → Secret `git-pages-tls` |
|
|
|
|
| Secret | Rooli |
|
|
|--------|-------|
|
|
| `git-pages-publish-auth` | htpasswd julkaisuun (Traefik) |
|
|
| `git-pages-publish-token` | plaintext token (Gitea Actions -secretiin vietäväksi) |
|
|
| `git-pages-retention-gitea` | Gitea PAT branch-tarkistukseen (sidecar)
|
|
|
|
---
|
|
|
|
## URL ja sisältö
|
|
|
|
Julkinen osoite:
|
|
|
|
```
|
|
https://ci-reports.helm-dev.keskikuja.site/niko/gitea-ci-library/reports/f4baa286/cucumber/index.html
|
|
└────────── selvä URL ─────────┘ └───────────────── Gitea-yhteensopiva polku ─────────────────────────┘
|
|
```
|
|
|
|
Levyllä (apex index-site):
|
|
|
|
```
|
|
/app/data/site/{host}/
|
|
.index # Protobuf-manifesti (storage v2 — kaikki tiedostot tässä yhdessä tiedostossa)
|
|
```
|
|
|
|
Tiedostot eivät ole flat-FS:nä — katso `implementation-notes.md`.
|
|
|
|
Apex-juuri `/` on tyhjä — ei landing-sivua.
|
|
|
|
---
|
|
|
|
## Järjestelmäkaavio
|
|
|
|
```mermaid
|
|
flowchart TB
|
|
subgraph ext["Ulkoiset"]
|
|
PUB["Julkaisija\n(CI)"]
|
|
BR["Selain"]
|
|
GITEA["Gitea API\n(branch-lista)"]
|
|
end
|
|
|
|
subgraph edge["Reuna"]
|
|
TRAEFIK["Traefik\nIngressRoute + Middleware"]
|
|
CM["cert-manager\nTLS"]
|
|
end
|
|
|
|
subgraph cluster["git-pages Pod"]
|
|
GP["git-pages\n(kontti)"]
|
|
RT["retention sidecar\n(kontti)\nHTTP API localhost:3000"]
|
|
PVC["PVC /app/data"]
|
|
end
|
|
|
|
PUB -->|"PATCH/PUT + BasicAuth\ntar"| TRAEFIK
|
|
BR -->|"GET/HEAD"| TRAEFIK
|
|
TRAEFIK --> GP
|
|
CM --> TRAEFIK
|
|
GP --> PVC
|
|
RT -->|"reads .git-pages/manifest.json\nHTTP localhost"| GP
|
|
RT -->|"check branches"| GITEA
|
|
```
|
|
|
|
---
|
|
|
|
## Julkaisu
|
|
|
|
1. Julkaisija paketoi `{owner}/{repo}/reports/{sha8}/` tar-arkistoksi (sis. `.meta`)
|
|
2. `PATCH` tai `PUT` apex-URL:iin (`https://{host}/`) + `Content-Type: application/x-tar`
|
|
3. Traefik tarkistaa BasicAuth (`publish` + token) → välittää git-pagesille
|
|
4. git-pages kirjoittaa PVC:lle
|
|
|
|
Julkaisu kulkee aina julkisen ingressin kautta — ei suoraa ClusterIP-kirjoitusta ulkopuolelta.
|
|
|
|
---
|
|
|
|
## Luku
|
|
|
|
1. Selain avaa commit-statuslinkin (GET/HEAD)
|
|
2. Traefik välittää git-pagesille ilman julkaisu-Middlewarea
|
|
3. git-pages palauttaa HTML:n polusta
|
|
|
|
Luku-auth (OIDC) ei ole toteutettu — GET/HEAD on julkinen, jos URL tunnetaan.
|
|
Katso [design-rationale.md — Luku-auth](design-rationale.md#luku-auth).
|
|
|
|
---
|
|
|
|
## Retention
|
|
|
|
Sidecar-kontti samassa podissa, ajaa retention-cleanup.sh 24h välein:
|
|
|
|
1. Lukee `.git-pages/manifest.json` HTTP:lla localhost:3000
|
|
2. Etsii `.meta`-tiedostot, tarkistaa iän ja branchin
|
|
3. **Poistettu branch** — jos `.meta.branch` ei ole Giteassa → whiteout PATCH
|
|
4. **Aktiivinen branch** — `maxAgeDays` + `keepMin` (`retention.rules`)
|
|
5. Whiteout-tar → PATCH localhost:3000 — poistaa raportit
|
|
|
|
Gitea API: `GET /api/v1/repos/{owner}/{repo}/branches/{branch}` — `read:repository` PAT.
|
|
Katso [secrets.md](secrets.md).
|
|
|
|
---
|
|
|
|
## Rajapinnat
|
|
|
|
| Suunta | Protokolla | Auth | Kuvaus |
|
|
|--------|------------|------|--------|
|
|
| Julkaisija → Traefik | HTTPS PATCH/PUT | BasicAuth `publish` | tar → apex site |
|
|
| Selain → Traefik | HTTPS GET/HEAD | — (tänään) | HTML-raportti |
|
|
| Sidecar → Gitea | HTTPS GET | PAT `read:repository` | branch-tarkistus per repo |
|
|
| Sidecar → git-pages | HTTP :3000 | — (PAGES_INSECURE) | manifestin luku + whiteout PATCH |
|
|
| Traefik → git-pages | HTTP :3000 | — | sisäverkko |
|
|
|
|
git-pages ei käytä Gitea forge-API:a julkaisuun eikä `pages`-branchia.
|