docs: POC-katselmus — git-pages retention, ADRt, dokumenttipäivitykset
- ADR 0004: commit-status-periaate (natiivi riittää, API vain custom-linkkiin)
- ADR 0005: provider & consumer -malli (ci-engine.yml lukittu rajapinta)
- docs/design-rationale: uusi periaate 1 "Hyödynnä natiivia",
periaate 2 korjattu (API vain tarvittaessa),
periaate 6 (MinIO→git-pages), teknologiavalinnat poistettu
- docs/config-model: isContainerBuild→isArtifactBuild, Docker-labelit poistettu
- docs/ai-context: monorepo-kuvaus (git-pages oma kokonaisuus, ohut rajapinta)
- docs/architecture, tech-stack, report-hosting, shared-scripts, workflows:
MinIO→git-pages, provider agnostinen build-ekosysteemeille
- docs/adr/: ADRt siirretty decisions/→adr/
- git-pages/docs: retention-osiot päivitetty CronJob→sidecar+HTTP API,
URL-kaava korjattu (reports/{sha8}/)
- git-pages/docs/implementation-notes: uusi (storage v2, Host-header,
whiteout, .init, PATCH+directoryt)
- git-pages/templates/init-job.yaml: post-install init (.index)
- scripts/publish-git-pages.sh: PUT-fallback poistettu (init hoitaa),
palauttaa BASE URL ilman index.html
This commit is contained in:
moilanik
@@ -36,6 +36,11 @@ helm upgrade --install git-pages ./git-pages \
|
||||
-f "$VALUES"
|
||||
```
|
||||
|
||||
Helm ajaa asennuksen jälkeen init-jobin, joka PUTtaa paikanpitäjäsivun
|
||||
git-pagesiin. Tämä luo tarvittavan `.index`-tiedoston — sen jälkeen
|
||||
Gitea Actions -scriptit voivat käyttää suoraan PATCHia ilman
|
||||
PUT-fallbackia.
|
||||
|
||||
---
|
||||
|
||||
## Vie publish-token Gitea Actions-secretiin (per repo)
|
||||
|
||||
@@ -23,42 +23,39 @@ TLS-rajaukset ovat Kubernetes-kerroksessa (Traefik, cert-manager, Secretit).
|
||||
| Komponentti | Rooli |
|
||||
|-------------|-------|
|
||||
| **git-pages Pod** | Codeberg git-pages `0.9.1`, filesystem-storage `/app/data` |
|
||||
| **PVC** | Raporttisisältö (`{owner}/{repo}/reports/{sha8}/…`) |
|
||||
| **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` |
|
||||
| **CronJob `git-pages-retention`** | Päivittäinen siivous (PVC + Gitea branch-lista) |
|
||||
|
||||
| Secret | Rooli |
|
||||
|--------|-------|
|
||||
| `git-pages-publish-auth` | htpasswd julkaisuun (Traefik) |
|
||||
| `git-pages-retention-gitea` | Gitea PAT branch-listaan (CronJob) |
|
||||
| `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 peilaa suoraan Gitean commit-polun rakennetta, lisäten raportin nimen:
|
||||
Julkinen osoite:
|
||||
|
||||
```
|
||||
https://ci-reports.helm-dev.keskikuja.site/niko/gitea-ci-library/commit/14cf2eaeed8a4033bc37c52b0b4c29f25b253ceb/cucumber/index.html
|
||||
└────────────── selvä URL ──────────────┘ └──────────────────────── Gitea-yhteensopiva polku ────────────────────────┘
|
||||
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) polku vastaa URL:ia:
|
||||
Levyllä (apex index-site):
|
||||
|
||||
```
|
||||
/app/data/
|
||||
{owner}/
|
||||
{repo}/
|
||||
commit/
|
||||
{sha}/
|
||||
{raportin-nimi}/
|
||||
index.html
|
||||
.meta # branch, sha, published_at
|
||||
/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.
|
||||
|
||||
---
|
||||
@@ -78,10 +75,10 @@ flowchart TB
|
||||
CM["cert-manager\nTLS"]
|
||||
end
|
||||
|
||||
subgraph cluster["git-pages"]
|
||||
GP["git-pages Pod"]
|
||||
subgraph cluster["git-pages Pod"]
|
||||
GP["git-pages\n(kontti)"]
|
||||
RT["retention sidecar\n(kontti)\nHTTP API localhost:3000"]
|
||||
PVC["PVC /app/data"]
|
||||
CJ["CronJob retention"]
|
||||
end
|
||||
|
||||
PUB -->|"PATCH/PUT + BasicAuth\ntar"| TRAEFIK
|
||||
@@ -89,8 +86,8 @@ flowchart TB
|
||||
TRAEFIK --> GP
|
||||
CM --> TRAEFIK
|
||||
GP --> PVC
|
||||
CJ -->|"read branches"| GITEA
|
||||
CJ --> PVC
|
||||
RT -->|"reads .git-pages/manifest.json\nHTTP localhost"| GP
|
||||
RT -->|"check branches"| GITEA
|
||||
```
|
||||
|
||||
---
|
||||
@@ -119,15 +116,15 @@ Katso [design-rationale.md — Luku-auth](design-rationale.md#luku-auth).
|
||||
|
||||
## Retention
|
||||
|
||||
CronJob `git-pages-retention` (oletus kerran päivässä):
|
||||
Sidecar-kontti samassa podissa, ajaa retention-cleanup.sh 24h välein:
|
||||
|
||||
1. Skaalaa git-pages deployment hetkeksi pois (RWO-PVC)
|
||||
2. Käy läpi `reports/{sha8}/.meta`
|
||||
3. **Poistettu branch** — jos `.meta.branch` ei ole Gitean branch-listassa → poista (aina)
|
||||
4. **Aktiivinen branch** — `maxAgeDays` + `keepMin` (`retention.rules` instanssiarvoissa)
|
||||
5. Skaalaa deployment takaisin
|
||||
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` — `read:repository` PAT.
|
||||
Gitea API: `GET /api/v1/repos/{owner}/{repo}/branches/{branch}` — `read:repository` PAT.
|
||||
Katso [secrets.md](secrets.md).
|
||||
|
||||
---
|
||||
@@ -138,7 +135,8 @@ Katso [secrets.md](secrets.md).
|
||||
|--------|------------|------|--------|
|
||||
| Julkaisija → Traefik | HTTPS PATCH/PUT | BasicAuth `publish` | tar → apex site |
|
||||
| Selain → Traefik | HTTPS GET/HEAD | — (tänään) | HTML-raportti |
|
||||
| CronJob → Gitea | HTTPS GET | PAT `read:repository` | branch-lista per repo |
|
||||
| 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.
|
||||
|
||||
@@ -143,8 +143,8 @@ Ei toteutettu. Julkaisu- ja luku-reitit pysyvät erillisinä; OIDC lisätään v
|
||||
|
||||
### Retention
|
||||
|
||||
CronJob `git-pages-retention` (kerran päivässä) skannaa PVC:n ja poistaa vanhentuneet
|
||||
raportit. Julkaisija kirjoittaa `reports/{sha8}/.meta` (branch, sha, published_at).
|
||||
Sidecar samassa podissa (HTTP localhost:3000), ajaa retention-cleanup.sh
|
||||
24h välein:
|
||||
|
||||
| Sääntö | Konfiguroitavissa? | Kuvaus |
|
||||
|--------|-------------------|--------|
|
||||
@@ -152,13 +152,15 @@ raportit. Julkaisija kirjoittaa `reports/{sha8}/.meta` (branch, sha, published_a
|
||||
| **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` (`default` + `branches.{name}`).
|
||||
Poistettujen branchien siivous ei tarvitse parametreja. Jäljelle jääneille
|
||||
branchille säännöt tulevat `retention.rules` (`branches.default` +
|
||||
`branches.{name}`).
|
||||
|
||||
**Puutteet:** tagattuja commiteja ei suojata erikseen. RWO-PVC vaatii lyhyen katkon
|
||||
(deployment skaalataan 0:ksi ajon ajaksi).
|
||||
Ei PVC-skaalausta — sidecar lukee manifestin HTTP:lla ja poistaa whiteout
|
||||
PATCHilla. Ei K8s API -oikeuksia.
|
||||
|
||||
Secret: `git-pages-retention-gitea` — Gitea PAT branch-listaan. Ks. [secrets.md](secrets.md).
|
||||
Secret: `git-pages-retention-gitea` — Gitea PAT branch-tarkistukseen.
|
||||
Ks. [secrets.md](secrets.md).
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,43 @@
|
||||
# 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.
|
||||
+17
-17
@@ -92,9 +92,9 @@ graph TD
|
||||
subgraph "Retention Flow"
|
||||
R1["K8s Secret<br/>git-pages-retention-gitea"]
|
||||
R2["Gitea PAT<br/>CI-REPORTS_READ_FOR_RETENTION"]
|
||||
R1 -->|token| CJ["CronJob"]
|
||||
R2 -->|API auth| GITEA["Gitea API"]
|
||||
CJ -->|read branches| GITEA
|
||||
R1 -->|token| SC["Sidecar"]
|
||||
SC -->|API auth| GITEA["Gitea API"]
|
||||
SC -->|read branches| GITEA
|
||||
end
|
||||
```
|
||||
|
||||
@@ -157,26 +157,26 @@ GET/HEAD-reitillä ei ole Middlewarea. Luku on julkinen, jos URL tunnetaan.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant CronJob as CronJob<br/>git-pages-retention
|
||||
participant Sidecar as Retention Sidecar
|
||||
participant K8sSecret as K8s Secret<br/>git-pages-retention-gitea
|
||||
participant GiteaAPI as Gitea API
|
||||
participant PVC as PVC /app/data
|
||||
participant GP as git-pages (localhost:3000)
|
||||
|
||||
Note over CronJob: 1. Lue PAT
|
||||
CronJob->>K8sSecret: lue token
|
||||
K8sSecret-->>CronJob: Gitea PAT
|
||||
Note over Sidecar: 1. Lue PAT
|
||||
Sidecar->>K8sSecret: lue token
|
||||
K8sSecret-->>Sidecar: Gitea PAT
|
||||
|
||||
Note over CronJob: 2. Skaalaa deployment 0:aan
|
||||
CronJob->>PVC: lue .meta-tiedostot
|
||||
Note over Sidecar: 2. Lue manifest
|
||||
Sidecar->>GP: GET .git-pages/manifest.json
|
||||
GP-->>Sidecar: sisällysluettelo
|
||||
|
||||
Note over CronJob: 3. Kysy branch-lista
|
||||
CronJob->>GiteaAPI: GET /api/v1/repos/OWNER/REPO/branches
|
||||
GiteaAPI-->>CronJob: branch names
|
||||
Note over Sidecar: 3. Kysy branch
|
||||
Sidecar->>GiteaAPI: GET /api/v1/repos/OWNER/REPO/branches/BRANCH
|
||||
GiteaAPI-->>Sidecar: 200 / 404
|
||||
|
||||
Note over CronJob: 4. Vertaa ja poista
|
||||
CronJob->>PVC: poista vanhentuneet
|
||||
|
||||
Note over CronJob: 5. Skaalaa deployment 1:een
|
||||
Note over Sidecar: 4. Luo whiteout-tar + PATCH
|
||||
Sidecar->>GP: PATCH / (whiteout)
|
||||
GP-->>Sidecar: 200 OK
|
||||
```
|
||||
|
||||
**Huomio:** Retention-PAT:in omistajalla on oltava lukuoikeus KAIKKIIN repoihin,
|
||||
|
||||
@@ -0,0 +1,48 @@
|
||||
{{- if .Values.initJob.enabled }}
|
||||
apiVersion: batch/v1
|
||||
kind: Job
|
||||
metadata:
|
||||
name: {{ include "git-pages.fullname" . }}-init
|
||||
labels:
|
||||
{{- include "git-pages.componentLabels" . | nindent 4 }}
|
||||
annotations:
|
||||
"helm.sh/hook": post-install, post-upgrade
|
||||
"helm.sh/hook-delete-policy": hook-succeeded,before-hook-creation
|
||||
spec:
|
||||
backoffLimit: 5
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
app.kubernetes.io/name: {{ include "git-pages.name" . }}-init
|
||||
app.kubernetes.io/instance: {{ .Release.Name }}
|
||||
spec:
|
||||
restartPolicy: Never
|
||||
containers:
|
||||
- name: init
|
||||
image: "{{ .Values.initJob.image.repository }}:{{ .Values.initJob.image.tag }}"
|
||||
imagePullPolicy: {{ .Values.initJob.image.pullPolicy }}
|
||||
command:
|
||||
- bash
|
||||
- -c
|
||||
- |
|
||||
set -euo pipefail
|
||||
apt-get update -qq && apt-get install -y -qq curl tar >/dev/null
|
||||
echo "Init: waiting for git-pages..."
|
||||
until curl -sf \
|
||||
-H "Host: {{ .Values.ingress.host }}" \
|
||||
-o /dev/null "http://git-pages:3000/.git-pages/health"
|
||||
do sleep 2; done
|
||||
echo "Init: creating placeholder site..."
|
||||
WORK=$(mktemp -d)
|
||||
mkdir -p "$WORK/__init__"
|
||||
echo "initialized" > "$WORK/__init__/index.html"
|
||||
tar cf /tmp/init.tar -C "$WORK" __init__
|
||||
curl -sf -X PUT "http://git-pages:3000/" \
|
||||
-H "Host: {{ .Values.ingress.host }}" \
|
||||
-H "Content-Type: application/x-tar" \
|
||||
--data-binary @/tmp/init.tar -o /dev/null
|
||||
echo "Init: done"
|
||||
env:
|
||||
- name: PAGES_INSECURE
|
||||
value: "1"
|
||||
{{- end }}
|
||||
@@ -37,6 +37,15 @@ ingress:
|
||||
certificate:
|
||||
enabled: true
|
||||
|
||||
# Post-install init job: creates placeholder site so .index exists.
|
||||
# Consumers can use PATCH directly without PUT fallback.
|
||||
initJob:
|
||||
enabled: true
|
||||
image:
|
||||
repository: debian
|
||||
tag: bookworm-slim
|
||||
pullPolicy: IfNotPresent
|
||||
|
||||
# Optional Helm-managed secret — prefer manual create (see docs/secrets.md).
|
||||
publishAuth:
|
||||
create: false
|
||||
|
||||
Reference in New Issue
Block a user