- ci-engine.yml: 2 dummy test stepiä + agnostinen publish-stage (skannaa .meta-tiedostot, PATCH raportit, postaa status + linkki) - publish-git-pages.sh: palauta BASE URL (ilman index.html) - .meta-formaatti: lisää context, description, state kentät
This commit is contained in:
moilanik
+207
-66
@@ -1,96 +1,237 @@
|
||||
# Secrets - Prerequisites
|
||||
# Secrets — git-pages
|
||||
|
||||
`git-pages` requires the following Kubernetes Secrets to exist before the cluster
|
||||
consumers can use them. These secrets are not managed by Helm — create them manually or
|
||||
via external secret management (SealedSecrets, External Secrets Operator, Vault).
|
||||
## Quick Start
|
||||
|
||||
TLS (`git-pages-tls`) is issued by cert-manager — not a manual prerequisite.
|
||||
### Vaihe 1: Secret-arkkitehtuuri
|
||||
|
||||
---
|
||||
Järjestelmässä on kaksi loogista salaista arvoa. Publish-token jaetaan kahteen K8s-secretiin (Traefik-yhteensopivuus):
|
||||
|
||||
## Secret Inventory
|
||||
| Looginen nimi | K8s | Gitea |
|
||||
|---|---|---|
|
||||
| `report_publish_api_token` (htpasswd) | `git-pages-publish-auth` (users) | - |
|
||||
| `report_publish_api_token` (plaintext) | `git-pages-publish-token` (token) | Actions Secret: `GIT_PAGES_PUBLISH_TOKEN` |
|
||||
| `reports_retention_read_token` | `git-pages-retention-gitea` (token) | PAT: `CI-REPORTS_READ_FOR_RETENTION` |
|
||||
|
||||
| Secret | Keys | Consumers | Required |
|
||||
|--------|------|-----------|----------|
|
||||
| `git-pages-publish-auth` | `users` | Traefik Middleware `git-pages-publish-auth` | Always |
|
||||
| `git-pages-retention-gitea` | `token` | CronJob `git-pages-retention` | Always |
|
||||
**Huomio:** Publish-token jaetaan kahteen secretiin, koska Traefik BasicAuth middleware vaatii single-key secretin sekä on muodossa, missä sitä ei saa takaisin. Jokainen repo mikä raportteja käyttää, tarvitsee selväkielisen arvon, joka on "ylimääräisessä" secretissä.
|
||||
|
||||
---
|
||||
### Vaihe 2: Luo Gitea PAT (retention)
|
||||
|
||||
## Tokens
|
||||
|
||||
### Publish token
|
||||
|
||||
Ei Gitea PAT. Satunnainen merkkijono (`GIT_PAGES_PUBLISH_TOKEN`), joka menee kahteen paikkaan:
|
||||
|
||||
| Paikka | Muoto |
|
||||
|--------|-------|
|
||||
| Kubernetes `git-pages-publish-auth` | htpasswd: `publish:<hash>` |
|
||||
| Gitea Actions secret `GIT_PAGES_PUBLISH_TOKEN` | sama plaintext |
|
||||
|
||||
CI käyttää sitä Traefik BasicAuthiin. Ei git-kirjoitusoikeutta.
|
||||
|
||||
**Vienti Giteaan:** Organization or Repository → Settings → Actions → Secrets →
|
||||
`GIT_PAGES_PUBLISH_TOKEN` = publish-tokenin plaintext (org secret, jos usea repo julkaisee).
|
||||
|
||||
### Retention token
|
||||
|
||||
Gitea PAT CronJobille. CronJob listaa branchit repokohtaisesti
|
||||
(`GET /api/v1/repos/{owner}/{repo}/branches`) ja poistaa raportit, joiden `.meta.branch`
|
||||
ei ole enää Giteassa.
|
||||
|
||||
Tarvitaan vain **`read:repository`**. Ei `write:repository`. Tokenin omistajan täytyy
|
||||
nähdä kaikki repot, joista raportteja on levyllä.
|
||||
|
||||
**Ei viedä Giteaan** — vain Kubernetes Secret `git-pages-retention-gitea`.
|
||||
|
||||
**PAT Giteassa (read only):**
|
||||
**Avaa Gitea browserissa:**
|
||||
|
||||
1. Kirjaudu Gitea-käyttäjällä, jolla on luku kaikkiin raporttirepoihin
|
||||
2. **Settings** → **Applications** → **Generate New Token**
|
||||
3. Token name: esim. `git-pages-retention`
|
||||
4. Scopes: valitse vain **`read:repository`** — älä valitse `write:repository` eikä muita
|
||||
5. **Generate Token** → kopioi token heti (näytetään vain kerran)
|
||||
6. Aseta shelliin: `export GITEA_RETENTION_TOKEN='gitea_pat_…'`
|
||||
3. Token name: `CI-REPORTS_READ_FOR_RETENTION`
|
||||
4. Scopes: valitse vain **`read:repository`**
|
||||
5. **Generate Token** → **kopioi token heti** (näytetään vain kerran)
|
||||
6. Tallenna token talteen (`GITEA_RETENTION_TOKEN`)
|
||||
|
||||
---
|
||||
### Vaihe 3: Generoi publish-token
|
||||
|
||||
## Create Secrets
|
||||
**Palaa terminaalille:**
|
||||
|
||||
```bash
|
||||
GITEA_RETENTION_TOKEN="<from Gitea>"
|
||||
|
||||
GIT_PAGES_PUBLISH_TOKEN="$(openssl rand -base64 24)"
|
||||
echo "Publish-token generoitu. Tallennetaan K8s-secretiin Vaiheessa 4."
|
||||
echo "$GIT_PAGES_PUBLISH_TOKEN"
|
||||
```
|
||||
|
||||
### Vaihe 4: Luo K8s secrets
|
||||
|
||||
```bash
|
||||
NS=git-pages
|
||||
|
||||
# Publish
|
||||
GIT_PAGES_PUBLISH_TOKEN="$(openssl rand -base64 24)"
|
||||
|
||||
# 1. Publish-auth: htpasswd (Traefik BasicAuth - vaatii single-key secretin)
|
||||
kubectl create secret generic git-pages-publish-auth \
|
||||
--from-literal=users="$(docker run --rm httpd:2-alpine htpasswd -nb publish "$GIT_PAGES_PUBLISH_TOKEN")" \
|
||||
-n $NS
|
||||
-n "$NS"
|
||||
|
||||
echo "Gitea Actions → GIT_PAGES_PUBLISH_TOKEN:"
|
||||
echo "$GIT_PAGES_PUBLISH_TOKEN"
|
||||
# 2. Publish-token: plaintext (luetaan README:stä Giteaan viedessä)
|
||||
kubectl create secret generic git-pages-publish-token \
|
||||
--from-literal=token="$GIT_PAGES_PUBLISH_TOKEN" \
|
||||
-n "$NS"
|
||||
|
||||
# Retention (PAT luotu yllä Giteassa)
|
||||
# 3. Retention (käyttää Vaiheessa 2 luotua PAT:ia)
|
||||
kubectl create secret generic git-pages-retention-gitea \
|
||||
--from-literal=token="$GITEA_RETENTION_TOKEN" \
|
||||
-n $NS
|
||||
-n "$NS"
|
||||
|
||||
kubectl get secrets -n $NS
|
||||
kubectl get secrets -n "$NS"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Secret Management (Production)
|
||||
### Seuraava: Helm-asennus
|
||||
|
||||
Secrets can be created manually with the snippets above, or migrated to a secret management
|
||||
solution. The `kubectl create` blocks are the rolling source — replace them with the target
|
||||
tool's equivalent when ready:
|
||||
Palaa takaisin [README.md](../README.md#käyttöönotto) ja jatka kohdasta "Instanssin values-tiedosto".
|
||||
|
||||
| Approach | Replaces `kubectl create` with |
|
||||
|----------|-------------------------------|
|
||||
| Manual rotation | Re-run the same snippets with new values |
|
||||
| SealedSecrets | `kubeseal` encrypted manifest |
|
||||
| External Secrets Operator | `ExternalSecret` CR pointing to the vault |
|
||||
| Vault / other | Vault agent / CSI driver injection |
|
||||
---
|
||||
|
||||
Structure of `docs/secrets.md` stays identical regardless of the chosen approach.
|
||||
## Secret Arkkitehtuuri
|
||||
|
||||
### Loogiset salaisuudet
|
||||
|
||||
| Looginen nimi | K8s | Gitea |
|
||||
|---|---|---|
|
||||
| `report_publish_api_token` | `git-pages-publish-auth` (htpasswd) | Actions Secret: `GIT_PAGES_PUBLISH_TOKEN` |
|
||||
| `reports_retention_read_token` | `git-pages-retention-gitea` (token) | PAT: `CI-REPORTS_READ_FOR_RETENTION` |
|
||||
|
||||
### Secret Reference Architecture
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
subgraph "Publish Flow"
|
||||
P1["Actions Secret<br/>GIT_PAGES_PUBLISH_TOKEN"]
|
||||
P2["K8s Secret<br/>git-pages-publish-auth"]
|
||||
P1 -->|token| TRAEFIK
|
||||
P2 -->|htpasswd| TRAEFIK
|
||||
TRAEFIK["Traefik BasicAuth"]
|
||||
end
|
||||
|
||||
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
|
||||
end
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Data Flow
|
||||
|
||||
### Flow 1: Julkaisu (Publish)
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Actions as Gitea Actions
|
||||
participant Traefik as Traefik
|
||||
participant K8sAuth as K8s Secret<br/>git-pages-publish-auth
|
||||
participant K8sToken as K8s Secret<br/>git-pages-publish-token
|
||||
participant GP as git-pages
|
||||
|
||||
Note over Actions: 1. Lue plaintext-token
|
||||
Actions->>K8sToken: lue token-avain
|
||||
K8sToken-->>Actions: plaintext token
|
||||
|
||||
Note over Actions: 2. Lähettää raportin
|
||||
Actions->>Traefik: PUT / + BasicAuth<br/>publish:TOKEN + repo-url
|
||||
Traefik->>K8sAuth: lue users (htpasswd)
|
||||
K8sAuth-->>Traefik: publish:$apr1$...
|
||||
alt Token match
|
||||
Traefik->>GP: välitä
|
||||
GP-->>Traefik: 200 OK
|
||||
Traefik-->>Actions: 200 OK
|
||||
else Token ei match
|
||||
Traefik-->>Actions: 401 Unauthorized
|
||||
end
|
||||
```
|
||||
|
||||
**Kaksi secretiä (Traefik-yhteensopivuus):**
|
||||
- `git-pages-publish-auth` = `users` (htpasswd, Traefik käyttää)
|
||||
- `git-pages-publish-token` = `token` (plaintext, luetaan Giteaan viedessä)
|
||||
|
||||
---
|
||||
|
||||
### Flow 2: Luku (Read)
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Browser as Selain
|
||||
participant Traefik as Traefik
|
||||
participant GP as git-pages
|
||||
|
||||
Browser->>Traefik: GET /OWNER/REPO/commit/SHA/raportti/index.html
|
||||
Traefik->>GP: välitä (ei authia)
|
||||
GP-->>Traefik: HTML
|
||||
Traefik-->>Browser: HTML
|
||||
```
|
||||
|
||||
GET/HEAD-reitillä ei ole Middlewarea. Luku on julkinen, jos URL tunnetaan.
|
||||
|
||||
---
|
||||
|
||||
### Flow 3: Retention (Siivous)
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant CronJob as CronJob<br/>git-pages-retention
|
||||
participant K8sSecret as K8s Secret<br/>git-pages-retention-gitea
|
||||
participant GiteaAPI as Gitea API
|
||||
participant PVC as PVC /app/data
|
||||
|
||||
Note over CronJob: 1. Lue PAT
|
||||
CronJob->>K8sSecret: lue token
|
||||
K8sSecret-->>CronJob: Gitea PAT
|
||||
|
||||
Note over CronJob: 2. Skaalaa deployment 0:aan
|
||||
CronJob->>PVC: lue .meta-tiedostot
|
||||
|
||||
Note over CronJob: 3. Kysy branch-lista
|
||||
CronJob->>GiteaAPI: GET /api/v1/repos/OWNER/REPO/branches
|
||||
GiteaAPI-->>CronJob: branch names
|
||||
|
||||
Note over CronJob: 4. Vertaa ja poista
|
||||
CronJob->>PVC: poista vanhentuneet
|
||||
|
||||
Note over CronJob: 5. Skaalaa deployment 1:een
|
||||
```
|
||||
|
||||
**Huomio:** Retention-PAT:in omistajalla on oltava lukuoikeus KAIKKIIN repoihin,
|
||||
joista raportteja on PVC:llä.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- **"secret not found"** — luiko secretit ennen Helm-asennusta?
|
||||
- **"401 Unauthorized"** — onko Gitea Actions secret oikea?
|
||||
- **"found 2 elements for secret"** — Traefik vaatii single-key secretin. Varmista että `git-pages-publish-auth` sisältää vain `users`-avaimen.
|
||||
- **"token hukkuu"** — generoi uusi token (Vaihe 3) ja päivitä molemmat publish-secretit:
|
||||
```bash
|
||||
# 1. Generoi uusi
|
||||
GIT_PAGES_PUBLISH_TOKEN="$(openssl rand -base64 24)"
|
||||
|
||||
# 2. Päivitä K8s secrets (molemmat)
|
||||
NS=git-pages
|
||||
kubectl delete secret git-pages-publish-auth -n "$NS"
|
||||
kubectl delete secret git-pages-publish-token -n "$NS"
|
||||
|
||||
kubectl create secret generic git-pages-publish-auth \
|
||||
--from-literal=users="$(docker run --rm httpd:2-alpine htpasswd -nb publish "$GIT_PAGES_PUBLISH_TOKEN")" \
|
||||
-n "$NS"
|
||||
|
||||
kubectl create secret generic git-pages-publish-token \
|
||||
--from-literal=token="$GIT_PAGES_PUBLISH_TOKEN" \
|
||||
-n "$NS"
|
||||
|
||||
# 3. Päivitä Gitea Actions secret jokaisessa repoissa (luke README:stä)
|
||||
```
|
||||
|
||||
## Automatisointi: useamman repon salaisuuden lisääminen
|
||||
|
||||
Jos repoja on monta, voit käyttää Gitea API:ta (vaatii admin-tokenin):
|
||||
|
||||
```bash
|
||||
ADMIN_TOKEN="<gitea-admin-token>"
|
||||
NS=git-pages
|
||||
|
||||
# Lue plaintext-token erillisestä secretistä
|
||||
TOKEN=$(kubectl get secret git-pages-publish-token -n "$NS" -o jsonpath='{.data.token}' | base64 -d)
|
||||
|
||||
for repo in "owner/repo1" "owner/repo2" "owner/repo3"; do
|
||||
curl -X POST "https://gitea.example.com/api/v1/repos/$repo/actions/secrets" \
|
||||
-H "Authorization: token $ADMIN_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "{\"name\":\"GIT_PAGES_PUBLISH_TOKEN\",\"data\":\"$TOKEN\"}"
|
||||
done
|
||||
```
|
||||
|
||||
Tai `tea` CLI:lla (Gitea:n virallinen CLI):
|
||||
|
||||
```bash
|
||||
tea actions secrets add --repo owner/repo1 GIT_PAGES_PUBLISH_TOKEN "$TOKEN"
|
||||
tea actions secrets add --repo owner/repo2 GIT_PAGES_PUBLISH_TOKEN "$TOKEN"
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user