From ae2be1ca3539fd2638dea0bd44b687bfb7b9311b Mon Sep 17 00:00:00 2001 From: moilanik Date: Sun, 28 Jun 2026 09:21:20 +0300 Subject: [PATCH] dokumentti muutoksia --- gitea-reports/docs/design-rationale.md | 230 ++++++--------------- gitea-reports/docs/implementation-notes.md | 43 ---- gitea-reports/docs/tech-stack.md | 10 +- 3 files changed, 64 insertions(+), 219 deletions(-) delete mode 100644 gitea-reports/docs/implementation-notes.md diff --git a/gitea-reports/docs/design-rationale.md b/gitea-reports/docs/design-rationale.md index 5e7c483..9936c2c 100644 --- a/gitea-reports/docs/design-rationale.md +++ b/gitea-reports/docs/design-rationale.md @@ -1,198 +1,90 @@ # Design Rationale — gitea-reports -> Miksi gitea-reports on rakennettu näin. Arvot, periaatteet ja reunaehdot. -> -> Tämä dokumentti on **normatiivinen** `gitea-reports/`-alikansiolle. Se ei kuvaa juuren -> `gitea-ci-library`-kirjastoa eikä sen workfloweja. -> -> Liittyvät dokumentit: [architecture.md](architecture.md), [tech-stack.md](tech-stack.md), [secrets.md](secrets.md). +Miksi gitea-reports on rakennettu näin. Periaatteet, jotka pitävät arkkitehtuurin koossa. +Teknologiavalinnat ovat näiden periaatteiden seurauksia — eivät erillisiä preferenssejä. ---- +Tämä dokumentti on normatiivinen. Arkkitehtuurin tulee noudattaa sen periaatteita. +Ehdotus, joka on ristiriidassa dokumentin kanssa, on konflikti — ei hiljainen ohitus. -## Miksi tämä on olemassa +## The problem this solves -### Ongelma +CI-testiajoista syntyy HTML-raportteja. Gitea ei tarjoa web-selaimella selattavaa arkistoa +näille raporteille. -CI-testiajoista syntyy HTML-raportteja. Esimerkiksi Cucumber-testiraportti toimii -elävänä dokumentaationa git commitin tilasta. +Vaihtoehdot eivät sovi: +- **Gitea Actions artifactit**: vain ZIP-lataus — HTML ei renderöidy selaimessa +- **Gitea pages-branch**: yksi branch per repo; rinnakkaiset buildit törmäävät +- **Gitea Releases**: sotkee julkaisuhistorian sadoilla CI-buildien raporteilla -Gitea ei tarjoa web-selaimella selattavaa arkistoa näille HTML-raporteille. +## How this is solved -gitea-reports ratkaisee tämän ongelman. +Yksi klusteri, yksi apex-host, monta Gitea-repoa. URL on suoraan FS-polku: +`/{owner}/{repo}/{branch}/{sha8}/{suite}/`. Ei rewritea, ei subdomain-per-owner, +ei slugia. -| Vaihtoehto | Miksi ei riitä | -|---|---| -| **Gitea Actions -artifactit** | Vain ZIP-lataus — HTML ei renderöidy selaimessa | -| **Gitea `pages`-branch** | Yksi branch per repo; rinnakkaiset buildit törmäävät saman branchin pushissa | -| **Gitea Releases** | Sotkee julkaisuhistorian satojen CI-buildien raporteilla | +Palvelu on read/write -jaettu: luku ja julkaisu eri sovelluksilla, eri porteilla, +eri Traefik-säännöillä. -### Ongelma URL:ssa (hylätty malli) +## Why selvä URL + Gitea-yhteensopiva polku -Alkuvaiheen malli sitoi hostin repoon: `https://{owner}.{host}/{repo}/...` -(subdomain per owner). Julkinen linkki piti sitten “kääntää” Gitea-tyyliseksi poluksi -Traefik-rewritellä (`/{owner}/{repo}/...` → eri `Host` + lyhyempi polku). +Repo tunnistetaan polusta `/{owner}/{repo}/...`, ei hostista. Kaikki URL-taso +(branch, sha8, suite) on suoraan FS-polku. Tämä mahdollistaa yhden TLS-sertifikaatin, +yhden IngressRouten ja URL:n, joka on suoraan kopioitavissa commit-statusiin ilman +rewritea. -Tämä oli ongelmallinen: +**Hylätty:** subdomain-per-owner (`{owner}.pages...`). Vaati per-owner Traefik- +rewritea ja wildcard-TLS:ää. Julkaisu-URL ja luku-URL olivat eri muodossa — kehittäjälle +vaikea ymmärtää ja debugata. -- per-owner middleware / rewrite kube-resursseina -- julkaisu-URL ja lukemis-URL eri muodossa -- wildcard-TLS tai monimutkainen cert-hallinta -- vaikea selittää kehittäjälle mistä host tulee +## Why luku ja kirjoitus eri sovelluksilla -### Ratkaisu — `selvä_url` + Gitea-yhteensopiva polku +Yksi binary, joka palvelee sekä lukua että kirjoitusta samassa prosessissa, on +yksinkertainen mutta yhdistää kaksi eri asiaa. Tässä arkkitehtuurissa nginx palvelee +staattisia tiedostoja; Python-skripti purkaa tar.gz-julkaisun PV:lle. Ne eivät tiedä +toisistaan. -URL rakennetaan kahdesta erillisestä osasta, ei yhdestä sekavasta kaavasta: +Luku ei tarvitse julkaisulogiikkaa. Julkaisu ei tarvitse optimoitua staattista +palvelua. Erottamalla ne kumpikin voidaan valita parhaaseen tarkoitukseensa. -| Osa | Mistä | Esimerkki | -|-----|-------|-----------| -| **Selvä URL** | Organisaation kiinteä pages-host | `https://pages.example.com` | -| **Gitea-yhteensopiva polku** | Repo (`{owner}/{repo}`) + commit | `/acme-corp/backend-api/reports/abc12345/index.html` | +## Why security klusterin reunalla — ei sovelluksessa -**Julkinen linkki** = selvä URL + polku (yksi merkkijono commit-statusiin, ei rewritea): +Sovellus on "tyhmä": se palvelee mitä PV:llä on ja kirjoittaa mitä sille annetaan. +Valtuutus tapahtuu yksinomaan Traefik BasicAuth -middlewaressa. -`https://pages.example.com/acme-corp/backend-api/reports/abc12345/index.html` +Tämä mahdollistaa: +- Julkaisu- ja lukuoikeuksien erillisen hallinnan eri Traefik-säännöillä +- Sovelluksen vaihtamisen ilman turvallisuusauditointia +- Token-rotaation ilman sovelluksen uudelleenkäynnistystä -Polku vastaa Gitea Pages -käytäntöä (`/{owner}/{repo}/...`). Host on aina sama — -ei `{owner}.pages...`-subdomainia. +**Hylätty:** sovelluksen sisäinen forge-auth (Gitea PAT, DNS TXT -haaste). +Sitoo sovelluksen tiettyyn autentikointimekanismiin ja vaatii laajat oikeudet +(`write:repository`) pelkkää raporttijulkaisua varten. -**Konkreettinen esimerkki (nykyinen ympäristö):** +## Why retention erillisenä CronJobina -| Elementti | Arvo | -|-----------|------| -| **Gitea-instanssi** | `gitea.app.keskikuja.site` | -| **Repo** | `niko/gitea-ci-library` | -| **Haara** | `plan/0003-alkaa-käyttämään-itseään-commit-raportti` | -| **Commit SHA** | `14cf2eaeed8a4033bc37c52b0b4c29f25b253ceb` | -| **Raportin nimi** | `cucumber` (esim.) | -| **Gitea commit -URL** | `https://gitea.app.keskikuja.site/niko/gitea-ci-library/commit/14cf2eaeed8a4033bc37c52b0b4c29f25b253ceb` | -| **Raportin julkinen URL** | `https://ci-reports.helm-dev.keskikuja.site/niko/gitea-ci-library/commit/14cf2eaeed8a4033bc37c52b0b4c29f25b253ceb/cucumber/index.html` | +Retention ei tarvitse olla aina käynnissä — se ajetaan kerran vuorokaudessa. +CronJob lukee PV:tä suoraan (find, ls, stat), ei HTTP API:n kautta. Tämä pitää +retention poissa podin kriittiseltä polulta (luku/julkaisu). -Tämä varmistaa, että CI-statuslinkki on suoraan luettavissa ilman domain-rewriteä: raportin polku peilaa täsmälleen Gitean commit-polun rakennetta (`/{owner}/{repo}/commit/{sha}/{raportin-nimi}/`). Koska yksi ajo tuottaa useita raportteja, raportin nimi erottaa ne toisistaan. +**Hylätty:** sidecar samassa podissa. Sidecar kuluttaa resursseja aina, ja +retention-logiikka sekoittuu julkaisu- ja lukukoodiin. -Julkaisija (CI tai muu asiakas) lähettää tar-arkiston PATCH/PUT:lla. Lukija hakee -HTML:n GET:llä. Ei Gitea-git-integraatiota eikä `pages`-branchia. +## Why yksi token, kaksi säilöä -**Codebergin security-malli ei sovellu tähän käyttöön** — forge-auth (Gitea PAT + -`write:repository`), DNS TXT -haaste ja muut gitea-reportsin sisäänrakennetut valtuutus- -mekanismit on ohitettu kokonaan (`PAGES_INSECURE=1`). Niiden sijaan Kubernetes-kerros -hoitaa rajauksen: Traefik BasicAuth julkaisuun, cert-manager TLS:ään, erillinen -publish-token ([secrets.md](secrets.md)). Sovellus palvelee sisältöä; klusteri päättää -kuka saa kirjoittaa. +Sama plaintext-arvo: htpasswd-hashina K8s Secretissä (Traefik lukee), plaintextina +Gitea Actions Secretissä (julkaisija lukee). Yksi rotaatio päivittää molemmat. ---- +Token antaa vain julkaisuoikeuden tähän palveluun — ei Gitea PAT:ia eikä +`write:repository`-oikeutta. -## Suunnitteluperiaatteet +## Why PVC suoraan FS-muodossa -### 1. Selvä URL + Gitea-yhteensopiva polku +Ei objektivarastoa, ei HTTP API:a retentionille. Sisältö on suoraan luettavissa +kubectl exec + ls/find. Yksinkertaisin mahdollinen tallennusmuoto. Yksi replica, +ei synkronointia. -Julkinen osoite = kiinteä apex-host + polku `/{owner}/{repo}/reports/{sha8}/...`. -Apex-juuri `/` on tyhjä tarkoituksella — ei landing-sivua. +## References -**Miksi:** Kehittäjä näkee Gitea-tyylisen polun; infra näkee yhden hostin. Ei Traefik- -rewritea, ei per-owner subdomaineja, ei erillistä “julkaisu-URL vs. lukemis-URL” -kaavaa. -Yksi TLS-sertifikaatti, yksi IngressRoute, yksi PVC. - -### 2. Sovelluksen sisäinen security kytketty pois, Traefik hoitaa rajauksen - -`gitea-reports`-sovelluksen koko sisäinen security-mekanismi on kytketty pois päältä (`PAGES_INSECURE=1`). Kirjoitusoikeuden validointi tapahtuu yksinomaan Kubernetes-reunalla Traefik BasicAuth -middlewaren avulla. Sovellus palvelee sisältöä sokeana; klusteri päättää, kuka saa kirjoittaa. - -### 3. Julkaisu ja luku erotettu - -Julkaisu (PATCH/PUT) vaatii Traefik BasicAuthin. Luku (GET/HEAD) on erillinen reitti — katso [Luku-auth](#luku-auth) alla. - -**Miksi:** Koska sovellus ei validoi julkaisuoikeuksia, kirjoitusoikeus on eksplisiittisesti eriytetty Traefik Middlewaressä (`gitea-reports-publish-auth`). - -### 4. Yksi publish-token, kaksi säilöä - -Sama plaintext-token: klusterin Secretissä htpasswd-hashina, julkaisijan secret-holvissa -(esim. CI-alustan Actions-secret). - -**Miksi:** Ei Gitea PAT:ia eikä `write:repository` -oikeutta. Token antaa vain -julkaisuoikeuden tähän palveluun. Yksi arvo, kaksi paikkaa — ks. [secrets.md](secrets.md). - -### 5. Secretit erillisessä hallinnassa - -`gitea-reports-publish-auth` luodaan ennen käyttöönottoa — ei osana sovelluksen konfiguraatiotiedostoja. - -**Miksi:** Salaisuudet eivät kulje versionoiduissa arvoissa. Rotaatio ja SealedSecrets -pysyvät operaattorin hallussa. Ks. [secrets.md](secrets.md). - -### 6. Minimaalinen parametrisointi - -Instance-arvot (`host`, `issuer`, PVC) `{env}-values.yaml`:ssa. Resurssinimet, -secret-nimet ja Traefik-wire kovakoodattu templatessa. - -**Miksi:** Parametrisoi vain se, mikä vaihtelee instanssien välillä (host, TLS-issuer, -levy). Vakioidut nimet ja wire pysyvät ennustettavina kaikissa asennuksissa. - ---- - -## Puutteet - -Tietoisesti avoimet asiat — eivät estä nykyistä julkaisu- ja lukumallia. - -### Luku-auth - -Julkaisu on suojattu (Traefik BasicAuth). **Luku ei ole:** GET/HEAD on julkinen — kuka -tuntee URL:n voi lukea raportin. - -Tavoite: Traefik OIDC GET/HEAD-reitille (Gitea OAuth2 -provider). Session säilyy — -commit-statuslinkki toimii kirjautumisen jälkeen ilman uutta julkaisuoikeutta. - -Ei toteutettu. Julkaisu- ja luku-reitit pysyvät erillisinä; OIDC lisätään vain lukupuolelle. - -### Retention - -Sidecar samassa podissa (HTTP localhost:3000), ajaa retention-cleanup.sh -24h välein: - -| Sääntö | Konfiguroitavissa? | Kuvaus | -|--------|-------------------|--------| -| **Poistettu branch** | Ei — aina | Jos `.meta.branch` ei ole Giteassa enää, raportti poistetaan | -| **maxAgeDays** | Kyllä (`dev-values`) | Aktiivisen branchin raportit vanhemmat kuin N päivää | -| **keepMin** | Kyllä (`dev-values`) | Aktiivisella branchilla pidetään vähintään N uusinta | - -Poistettujen branchien siivous ei tarvitse parametreja. Jäljelle jääneille -branchille säännöt tulevat `retention.rules` (`branches.default` + -`branches.{name}`). - -Ei PVC-skaalausta — sidecar lukee manifestin HTTP:lla ja poistaa whiteout -PATCHilla. Ei K8s API -oikeuksia. - -Secret: `gitea-reports-retention-gitea` — Gitea PAT branch-tarkistukseen. -Ks. [secrets.md](secrets.md). - ---- - -## Rajat - -- **Ei forge-integraatiota** — ei `pages`-branchia, ei Gitea API -hakua, ei forge-authia -- **Ei julkaisijalogiikkaa** — kuka julkaisee ja milloin on julkaisijan vastuulla -- **Ei sisäverkon ohitusjulkaisua** — julkaisu kulkee julkisen ingressin kautta (BasicAuth) - ---- - -## Teknologiavalinnat - -| Valinta | Miksi | -|---------|-------| -| **Codeberg gitea-reports** `0.9.1` | Natiivi apex index-site + tar-pohjainen PATCH/PUT -julkaisu | -| **Filesystem + PVC** | Yksinkertainen, yksi replica, ei erillistä objektivarastoa | -| **Traefik IngressRoute + Middleware** | Julkaisuauth erillään sovelluksesta; GET/HEAD eri säännöllä | -| **cert-manager** | TLS automaattisesti (`gitea-reports-tls`) | -| **Helm v3** | Toistettava asennus; instanssikohtaiset arvot erillisessä values-tiedostossa | - ---- - -## Mitä tietoisesti hylättiin - -| Hylätty | Syy | -|---------|-----| -| **deadnews/gitea-pages** | Vetää sisällön Gitea API:sta — ei sopinut CI-push-malliin | -| **Gitea `pages`-branch** | Race condition rinnakkaisissa buildeissa | -| **Per-owner subdomain** (`{owner}.pages...`) | Ongelmallinen URL; vaatii rewrite-middlewarea polun kääntämiseen | -| **Traefik path→host -rewrite** | Korvattu apex + Gitea-polulla — yksi selvä URL commit-linkissä | -| **Gitea forge-auth / PAT** | `write:repository` liian laaja oikeus vain raporttijulkaisuun | -| **DNS TXT -haaste julkaisuun** | Operatiivinen kompleksisuus ilman hyötyä BasicAuthiin verrattuna | -| **Helm-managed publish Secret** | Arvot values-tiedostoihin on kielletty; manuaalinen lähde totuudelle | -| **Image tag `v0.9.1`** | Oikea tagi on `0.9.1` (ei `v`-etuliitettä) | +- [architecture.md](architecture.md) — komponentit ja vuokaavio +- [tech-stack.md](tech-stack.md) — teknologiavalinnat listana +- [secrets.md](secrets.md) — secret-arkkitehtuuri ja käyttöönotto diff --git a/gitea-reports/docs/implementation-notes.md b/gitea-reports/docs/implementation-notes.md deleted file mode 100644 index c980080..0000000 --- a/gitea-reports/docs/implementation-notes.md +++ /dev/null @@ -1,43 +0,0 @@ -# Implementation Notes - -Teknisiä huomioita git-pages 0.9.1:n käyttäytymisestä, joita ei ole ilmeistä -dokumentaatiosta. - -## Storage v2 (Protobuf manifest) - -Git-pages 0.9.1 käyttää v2-arkkitehtuuria. Kaikki sisältö on pakattu -Protobuf-manifestiin (`site/{host}/.index`), ei flat-FS:nä. Tästä seuraa: - -- Tiedostoja ei voi etsiä tai poistaa `find`/`rm`-komennoilla -- `.git-pages/manifest.json` listaa kaikki tiedostot (ProtoJSON) -- `.git-pages/archive.tar` antaa koko sisällön (saattaa truncata HTTP/2:ssa) - -## Host-header - -Git-pages valitsee sivuston Host-headerin perusteella. Ilman oikeaa Hostia -palauttaa 404. - -- Ulkoiset requestit: Traefik välittää alkuperäisen Hostin automaattisesti -- Sidecar/localhost: `-H "Host: ci-reports.helm-dev.keskikuja.site"` - -## PATCH ja directory-entryt - -Jos PATCH-tar sisältää directory-entryn (tyyppi directory, tar typeflag '5'), -se **korvaa** koko hakemiston dokumentaation mukaan. Tar saa sisältää vain -file- ja symlink-entryjä, jotta PATCH toimii odotetusti. - -## Whiteout — tiedostojen poisto - -Ainoa tapa poistaa tiedostoja ilman koko sivuston PUT-korvausta: - -- Tarissa character device entry (`CHRTYPE`, tar typeflag '4') -- `devmajor=0`, `devminor=0` -- PATCH:ataan sivuston juureen - -## .init — ensimmäinen julkaisu - -Ensimmäinen julkaisu vaatii PUTin, joka luo `.index`-tiedoston. Tämän jälkeen -PATCH riittää. - -Helm-chartin post-install -job hoitaa tämän automaattisesti: -consumerien publish-scriptien ei tarvitse tuntea asennuksen tilaa. diff --git a/gitea-reports/docs/tech-stack.md b/gitea-reports/docs/tech-stack.md index e9f91dd..9a66297 100644 --- a/gitea-reports/docs/tech-stack.md +++ b/gitea-reports/docs/tech-stack.md @@ -9,13 +9,9 @@ | Teknologia | Versio | Käyttö | |---|---|---| -| **gitea-reports** (Codeberg) | `0.9.1` | Staattinen sisältö, apex index-site (`/.index`), HTTP PATCH/PUT -julkaisu | -| **Filesystem storage** | — | Sisältö PVC:llä (`/app/data`) | -| **TOML** | — | Sovellusconfig ConfigMapissa (`config.toml`) | - -Image: `codeberg.org/gitea-reports/gitea-reports:0.9.1` (ei `v`-etuliitettä tagissa). - -Chart ajaa `PAGES_INSECURE=1` — julkaisuvaltuutus Traefik Middlewaressä, ei forge-authia. +| **nginx** | alpine | Staattinen tiedostopalvelin (GET/HEAD) | +| **Python** | 3-alpine | PUT-vastaanotto + tar.gz-purku PV:lle | +| **Filesystem storage** | — | Sisältö PVC:llä | ---