Compare commits

..

2 Commits

Author SHA1 Message Date
gitea cea3f4745c docs(pliki): runbook otwarcia udziału z bazami na zapis
Decyzja właściciela: idziemy wariantem, w którym udział z bazami staje się
zapisywalny. DAN-25 dawał gwarancję, że baz nie da się zmienić przez NFS, a
DAN-27 tę gwarancję z definicji znosi — nie da się mieć obu naraz. Runbook mówi
to wprost i wylicza, co z zabezpieczeń zostaje.

mapall_user: root mimo drwxrwxrwx na katalogu. Samo ro: false wystarczyłoby do
zapisu, bo zmapowany nobody mieści się w prawach „innych" — ale nowe pliki
należałyby wtedy do nobody, a istniejące bazy do root. Mieszana własność zemści
się przy pierwszym zaostrzeniu praw.

Krok 3 z ostrzeżeniem, że rollout restart nie wystarcza: pody się na chwilę
nakładają, więc montowanie NFS nie zostaje bez użytkownika i nowy dziedziczy
uprawnienia sprzed zmiany eksportu. To kosztowało najwięcej czasu przy udziale
astrololo-state.

Krok 4 sprawdza wyszukiwanie JAKO OSTATNI I NAJWAŻNIEJSZY punkt — to jedyne
miejsce, w którym ta zmiana mogłaby przejść niezauważona: przejście na rejestr
plików mogłoby wyłączyć wszystkie bazy i wyglądałoby to jak pusta baza, a nie
jak zepsuty deploy.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-09 12:18:29 +02:00
gitea bb2383b09b feat(dane): udział z bazami zapisywalny — ekran zarządzania plikami (DAN-27)
Ekran „Pliki" pozwala wgrywać bazy, archiwizować je i (dla administratora)
kasować, a stan użycia jest klikany, więc musi przetrwać restart poda. Warstwa
danych musi zatem móc pisać na udziale — dotąd był montowany read-only.

ŚWIADOMY KOSZT: znika jedna warstwa obrony w głąb. Przejęcie warstwy danych
pozwala teraz nie tylko odczytać bazy, ale i je zmienić. Zostaje reszta: token
międzywarstwowy, szyfrowane łącze, ograniczenie eksportu NFS do konkretnych
hostów (DAN-25) oraz to, że kasować może wyłącznie konto administracyjne (PRE-27).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-07 14:39:43 +02:00
6 changed files with 153 additions and 304 deletions
+133
View File
@@ -0,0 +1,133 @@
# Zarządzanie plikami baz — otwarcie udziału na zapis (DAN-27)
Ekran „Pliki" pozwala wgrywać bazy, archiwizować je i (dla administratora)
kasować, a stan użycia jest **klikany**, więc musi być trwały. Wymaga to zapisu
do udziału z bazami — a ten jest dziś wyeksportowany tylko do odczytu.
---
## Co świadomie tracimy
DAN-25 dawał gwarancję, że **baz nie da się zmienić przez NFS**. DAN-27 tę
gwarancję z definicji znosi — nie da się mieć obu naraz.
**Co zostaje:**
| zabezpieczenie | działa nadal |
|---|---|
| eksport zawężony do trzech węzłów k8s | ✅ |
| token międzywarstwowy | ✅ |
| szyfrowane łącze prezentacja ↔ logika ↔ dane | ✅ |
| kasowanie plików wyłącznie z konta administracyjnego (PRE-27) | ✅ |
| dziennik audytowy (kto, kiedy, co) | ✅ |
Ryzyko, które przybywa: **przejęcie warstwy danych pozwala teraz nie tylko
odczytać bazy, ale i je zmienić.**
---
## Krok 1 — otwórz udział na zapis
```bash
midclt call sharing.nfs.query '[["path","=","/mnt/Tank1/astrololo"]]' \
| python3 -c "import sys,json;[print(s['id'], '| ro:', s['ro'], '| mapall:', s.get('mapall_user')) for s in json.load(sys.stdin)]"
```
Weź `id` i podstaw za `<ID>`:
```bash
midclt call sharing.nfs.update <ID> '{"ro": false, "mapall_user": "root", "mapall_group": "root"}'
```
> **Dlaczego `mapall_user`, skoro katalog ma `drwxrwxrwx`?** Samo `ro: false`
> wystarczyłoby do zapisu — zmapowany `nobody` mieści się w prawach „innych".
> Ale nowe pliki należałyby wtedy do `nobody`, a istniejące bazy do `root`.
> Mieszana własność zemści się przy pierwszym zaostrzeniu praw. `mapall_user:
> root` daje spójność i jest tym samym ustawieniem, co na udziale `astrololo-state`.
```bash
midclt call service.restart nfs
```
Sprawdź, że zmiana **faktycznie trafiła do jądra** — sama konfiguracja to za mało:
```bash
sudo exportfs -v | grep -A1 "Tank1/astrololo "
```
Przy `/mnt/Tank1/astrololo` musi być `rw`, nie `ro`.
---
## Krok 2 — zmerguj oba PR-y
* aplikacja: `feat/zarzadzanie-plikami`
* deploy: `feat/pliki-zapis` (zdejmuje `readOnly` z montowania w podzie)
Bez tego drugiego pod nadal montuje udział tylko do odczytu, choćby serwer
pozwalał pisać.
---
## Krok 3 — przeładuj warstwę danych PRZEZ ZERO REPLIK
> ⚠️ **`rollout restart` NIE WYSTARCZY.** Stary i nowy pod na chwilę
> współistnieją, więc montowanie NFS ani na moment nie zostaje bez użytkownika
> i nowy pod dziedziczy uprawnienia sprzed zmiany eksportu. To kosztowało
> najwięcej czasu przy udziale `astrololo-state` — patrz
> [README-stan-prezentacji.md](README-stan-prezentacji.md).
```bash
kubectl -n astrololo scale deploy/data --replicas=0
kubectl -n astrololo wait --for=delete pod -l app=data --timeout=90s
kubectl -n astrololo scale deploy/data --replicas=1
kubectl -n astrololo rollout status deploy/data
```
---
## Krok 4 — sprawdź, w tej kolejności
**Czy warstwa danych może pisać:**
```bash
kubectl -n astrololo exec deploy/data -- sh -c 'touch /app/data_files/proba && echo ZAPIS-OK && rm /app/data_files/proba'
```
**Czy powstał plik stanu i czy bazy zostały przyjęte jako aktywne:**
```bash
kubectl -n astrololo exec deploy/data -- sh -c 'cat /app/data_files/.files-state.json' | head -20
```
Oczekiwane: każda baza ze `"status": "active"`. Przy pierwszym uruchomieniu bazy
zastane na udziale są przyjmowane automatycznie — **bez tego wyszukiwanie
przestałoby cokolwiek znajdować**, bo plik bez wpisu w rejestrze nie bierze
udziału w wynikach.
**Czy wyszukiwanie NADAL DZIAŁA** — to jest najważniejszy sprawdzian tego
wdrożenia, bo właśnie tu zmiana mogłaby przejść niezauważona:
```bash
kubectl -n astrololo logs deploy/data --tail=20
```
a potem w przeglądarce: zakładka **Sygnifikatory**, dowolne wyszukanie. Musi
zwracać wyniki jak przedtem. Jeśli nagle nic nie znajduje — zajrzyj do
`.files-state.json` z komendy wyżej.
**Czy ekran „Pliki" działa:** zakładka **Pliki**, lista baz, przełącznik przy
każdej. Wgraj testowy plik, zarchiwizuj go, skasuj.
---
## Odkręcenie
```bash
midclt call sharing.nfs.update <ID> '{"ro": true, "mapall_user": null, "mapall_group": null}'
midclt call service.restart nfs
```
plus cofnięcie deploy `feat/pliki-zapis`. Ekran „Pliki" zostanie, ale wgrywanie
i kasowanie przestaną działać — a stan użycia przestanie się zapisywać, więc bazy
będą przyjmowane od nowa przy każdym starcie (czyli wszystkie aktywne).
-279
View File
@@ -1,279 +0,0 @@
# Udział na stan prezentacji — `astrololo-state`
Potrzebny do kont zakładanych z ekranu „Konta" (PRE-27). **Bez niego pod
`presentation` nie wstanie.**
---
## Dlaczego osobny udział, a nie podkatalog
Pierwsza wersja montowała `/mnt/Tank1/astrololo` z `subPath: presentation-state`
i pod stanął w `CreateContainerConfigError`:
```
failed to create subPath directory for volumeMount "state" of container "presentation"
```
Przyczyna była podwójna i za każdym razem ta sama: udział z bazami jest
wyeksportowany **`ro: true` z `root_squash`** (patrz runbook DAN-25 w repo
aplikacji). Zatem:
1. kubelet nie mógł utworzyć podkatalogu — bo udział jest tylko do odczytu,
2. a gdyby nawet mógł, aplikacja i tak nie zapisałaby tam pliku kont.
**Osobny udział rozwiązuje to bez ruszania DAN-25.** Udział z bazami zostaje tylko
do odczytu; konta dostają własne, małe miejsce. Przy okazji znika `subPath`, czyli
znika potrzeba, żeby kubelet cokolwiek zakładał — katalog istnieje, bo jest
korzeniem udziału.
---
## Krok 1 — dataset i udział na TrueNAS
Po SSH na NAS (192.168.1.34). Konwencja jak w DAN-25: **nie edytujemy
`/etc/exports` ręcznie**, tylko przez `midclt`.
```bash
# dataset
sudo zfs create Tank1/astrololo-state
```
Jeśli `Tank1` nie jest pulą ZFS albo wolisz zwykły katalog:
```bash
sudo mkdir -p /mnt/Tank1/astrololo-state
```
### Właściciel i prawa — TU JEST NAJCZĘSTSZY BŁĄD
Kontenery aplikacji działają **jako root** (`uid=0`), a NFS domyślnie stosuje
**`root_squash`**: root z klienta NIE jest rootem na udziale — ląduje jako
`nobody`. Świeży dataset ma prawa `drwxrwx--- root root`, czyli **nic dla
„innych"** — i dlatego zapis odbija się o `Permission denied`, mimo że `ls`
w podzie pokazuje `root root`.
To myli, bo `ls` pokazuje właściciela KATALOGU, a nie to, kim jest dla serwera
proces, który próbuje pisać.
Do wyboru dwa rozwiązania. Oba trzeba ustawić **przy eksporcie** (niżej), tu
tylko przygotowujemy katalog.
**A. Prościej — bez zakładania użytkownika.** Katalog zostaje `root:root 770`,
a przy eksporcie ustawiamy `mapall_user: "root"`. To wyłącza squash **dla tego
jednego udziału**. Zasięg jest wąski: eksportowany jest wyłącznie ten katalog,
montują go tylko trzy węzły k8s, leży w nim jeden plik. Nic nie trzeba robić —
świeży dataset ma już właściwe prawa.
**B. Czyściej — dedykowany użytkownik.** Zakładasz w UI TrueNAS
nieuprzywilejowanego użytkownika (np. `astrololo`), a potem:
```bash
sudo chown -R astrololo:astrololo /mnt/Tank1/astrololo-state
sudo chmod 770 /mnt/Tank1/astrololo-state
```
i przy eksporcie podstawiasz go w `mapall_user`. Efekt ten sam, bez oddawania
roota — kosztem jednego użytkownika więcej do pamiętania.
> Istniejących użytkowników sprawdzisz przez:
> `midclt call user.query | python3 -c "import sys,json;[print(u['uid'], u['username']) for u in json.load(sys.stdin)]"`
> **Czego NIE robić:** `chmod 777`. Zadziała, ale uczyni katalog zapisywalnym dla
> każdego lokalnego użytkownika NAS-a — a leżą tam hashe haseł, więc jest to plik
> wrażliwszy niż same bazy Excela.
### Eksport NFS
> **Najpierw sprawdź, czy udziału już nie ma.** `sharing.nfs.create` odmawia
> z komunikatem `Export conflict`, jeśli ten sam katalog jest już eksportowany —
> wtedy trzeba go **zaktualizować**, nie tworzyć.
```bash
midclt call sharing.nfs.query '[["path","=","/mnt/Tank1/astrololo-state"]]' \
| python3 -m json.tool
```
**Pusta lista `[]`** — udziału nie ma, twórz:
```bash
midclt call sharing.nfs.create '{
"path": "/mnt/Tank1/astrololo-state",
"comment": "astrololo — stan prezentacji (konta PRE-27)",
"hosts": ["192.168.1.73", "192.168.1.80", "192.168.1.81"],
"enabled": true,
"ro": false,
"mapall_user": "root",
"mapall_group": "root"
}'
```
**Coś zwróciło** — weź `id` z wyniku i zaktualizuj (podstaw `<ID>`):
```bash
midclt call sharing.nfs.update <ID> '{
"hosts": ["192.168.1.73", "192.168.1.80", "192.168.1.81"],
"enabled": true,
"ro": false,
"mapall_user": "root",
"mapall_group": "root"
}'
```
> Wybrałeś wariant B? Podstaw swojego użytkownika zamiast `root` w obu polach.
| ustawienie | po co |
|---|---|
| `hosts` zawężone | te same trzy węzły k8s co w DAN-25 — nikt inny nie zamontuje |
| `ro: false` | **musi być zapisywalny**, inaczej konta się nie zapiszą |
| `mapall_user` | cały ruch z tych hostów pisze jako JEDEN użytkownik, niezależnie od UID w kontenerze — bez tego `root_squash` zamienia roota z poda na `nobody`, który nie ma praw do katalogu |
> Podstaw swoje adresy węzłów, jeśli się zmieniły. Aktualne:
> `kubectl get nodes -o wide`
---
### Sprawdź, co serwer FAKTYCZNIE eksportuje
Konfiguracja udziału i stan eksportu to **dwie różne rzeczy**: zapisana
konfiguracja nie znaczy, że usługa ją przeładowała. To jest prawda:
```bash
sudo exportfs -v | grep -A1 astrololo
```
Muszą być **dwa** wpisy: `/mnt/Tank1/astrololo` (z `ro`) oraz
`/mnt/Tank1/astrololo-state` (z `rw`), oba z listą trzech węzłów.
Jeśli `astrololo-state` **nie ma na liście**, mimo że `sharing.nfs.query` go
pokazuje — usługa nie przeładowała eksportów:
```bash
midclt call service.restart nfs
sudo exportfs -v | grep astrololo-state
```
---
## Krok 2 — sprawdź z węzła, ZANIM wdrożysz
To jest ten test, którego zabrakło za pierwszym razem:
```bash
ssh 192.168.1.73 'sudo mount -t nfs 192.168.1.34:/mnt/Tank1/astrololo-state /mnt/test \
&& sudo touch /mnt/test/proba && echo "ZAPIS DZIAŁA" \
&& sudo rm /mnt/test/proba; sudo umount /mnt/test'
```
Musi wypisać **`ZAPIS DZIAŁA`**.
| co widzisz | co to znaczy |
|---|---|
| `Permission denied` przy `touch` | montowanie działa, brakuje praw — wróć do właściciela katalogu i `mapall_user` |
| `access denied by server while mounting` | serwer nie wpuszcza w ogóle: sprawdź `exportfs -v` (czy eksport istnieje i przeładowany), `enabled: true` w udziale oraz czy adres węzła jest na liście `hosts` |
| `No such file or directory` | katalog `/mnt/Tank1/astrololo-state` nie istnieje na NAS-ie |
| montuje się tylko z `-o vers=3` | negocjacja wersji: dopisz `mountOptions` w manifeście albo włącz NFSv4 w `midclt call nfs.config` |
Adresy węzłów sprawdzisz przez `kubectl get nodes -o wide` — jeśli któryś się
zmienił od czasu DAN-25, lista `hosts` jest nieaktualna i to wystarczy, żeby
serwer odmówił.
---
## Krok 3 — wdróż i sprawdź
```bash
kubectl apply -k astrololo
kubectl -n astrololo rollout status deploy/presentation
```
Sprawdź, że aplikacja faktycznie umie tam zapisać — załóż konto testowe
na ekranie „Konta", a potem:
```bash
kubectl -n astrololo exec deploy/presentation -- ls -l /app/state/
```
Oczekiwane: plik `accounts.json`.
---
## Jeśli mimo wszystko `Permission denied`
Trzy komendy, w tej kolejności:
```bash
kubectl -n astrololo exec deploy/presentation -- sh -c 'id; ls -ld /app/state; touch /app/state/proba && echo ZAPIS-OK || echo ZAPIS-NIE'
```
```bash
midclt call sharing.nfs.query '[["path","=","/mnt/Tank1/astrololo-state"]]' \
| python3 -c "import sys,json;[print('ro:', s['ro'], '| mapall:', s.get('mapall_user'), '| hosts:', s['hosts']) for s in json.load(sys.stdin)]"
```
```bash
sudo ls -ld /mnt/Tank1/astrololo-state
```
Zestaw, który DZIAŁA: kontener jako `uid=0(root)`, udział z `ro: false`
i `mapall: root`, katalog `drwxrwx--- root root`.
### ⚠️ Po zmianie eksportu `rollout restart` NIE WYSTARCZA
To kosztowało najwięcej czasu przy pierwszym wdrożeniu, więc zapisane wprost.
**Objaw:** eksport poprawiony, `service.restart nfs` wykonany, pod zrestartowany —
a zapis z poda nadal odbija się o `Permission denied`. Przy czym **ręczne
zamontowanie tego samego eksportu z tego samego węzła działa** i pozwala pisać.
**Co z tym zrobić:** doprowadzić do stanu, w którym ŻADEN pod nie trzyma tego
montowania.
```bash
kubectl -n astrololo scale deploy/presentation --replicas=0
kubectl -n astrololo wait --for=delete pod -l app=presentation --timeout=90s
kubectl -n astrololo scale deploy/presentation --replicas=1
kubectl -n astrololo rollout status deploy/presentation
```
`rollout restart` tego nie osiąga, bo stary i nowy pod na chwilę WSPÓŁISTNIEJĄ —
w logu widać `1 old replicas are pending termination`. Montowanie ani na moment
nie zostaje bez użytkownika. (W ArgoCD ten sam skutek daje `force delete` poda.)
**Dlaczego (hipoteza, nie potwierdzona u źródła):** jądro współdzieli strukturę
montowania NFS między montowania tego samego eksportu na węźle, razem z cache
odpowiedzi ACCESS. Nowy pod podpina się do żywego montowania i dziedziczy
odpowiedź sprzed zmiany eksportu.
**Test, który rozstrzyga, czy winny jest serwer czy klient** — montaż ręczny
z węzła, z pominięciem Kubernetesa:
```bash
ssh <węzeł> 'sudo mkdir -p /mnt/t && sudo mount -t nfs 192.168.1.34:/mnt/Tank1/astrololo-state /mnt/t \
&& sudo touch /mnt/t/proba && echo SERWER-OK || echo SERWER-NIE; sudo umount /mnt/t'
```
`SERWER-OK` przy jednoczesnym `Permission denied` w podzie znaczy, że konfiguracja
NAS-a jest dobra i **nie ma czego na nim poprawiać** — problem jest po stronie
klienta.
Osobno pamiętaj: sama zmiana konfiguracji udziału nie przeładowuje eksportów.
Po każdej zmianie `midclt call service.restart nfs`.
---
## Odkręcenie
```bash
# ID udziału
midclt call sharing.nfs.query | python3 -c "import sys,json;[print(s['id'], s.get('path')) for s in json.load(sys.stdin)]"
midclt call sharing.nfs.delete <ID>
```
---
## Uwaga na przyszłość: DAN-27 uderzy w tę samą ścianę
Zarządzanie plikami baz (wgrywanie, archiwizacja, kasowanie) wymaga zapisu do
**udziału z bazami** — a ten jest `ro: true`. Ten runbook tego **nie rozwiązuje**
i celowo nie rusza DAN-25: to osobna decyzja, bo oznacza rezygnację z gwarancji,
że baz nie da się zmienić przez NFS. Patrz PR `feat/pliki-zapis`.
+4 -8
View File
@@ -23,15 +23,11 @@ Ten plik **celowo nie jest w `kustomization.yaml`**: resource stoi w ns `argocd`
(poza namespace docelowym aplikacji), a to konfiguracja kontrolera, który wdraża tę
aplikację — nakładamy go ręcznie, w repo trzymamy dla odtwarzalności i historii.
## ⚠️ Udział `astrololo-state` — wymagany przez konta (PRE-27)
## Pliki baz — udział otwarty na zapis (DAN-27)
Pod `presentation` **nie wstanie bez niego** (`CreateContainerConfigError:
failed to create subPath directory`). Osobny runbook:
**[README-stan-prezentacji.md](README-stan-prezentacji.md)**.
Krótko: udział z bazami jest wyeksportowany `ro` (DAN-25), więc konta nie mogą tam
mieszkać — dostają własny, mały udział `/mnt/Tank1/astrololo-state`, zapisywalny,
zawężony do tych samych węzłów.
Runbook: **[README-pliki.md](README-pliki.md)**. Ekran „Pliki" wymaga zapisu do
udziału z bazami, więc znosi gwarancję z DAN-25, że baz nie da się zmienić przez
NFS. Co zostaje z zabezpieczeń i jak to wdrożyć — w runbooku.
## ⚠️ Sekret `astrololo-auth` — utwórz PRZED wdrożeniem
+10 -1
View File
@@ -47,9 +47,18 @@ spec:
volumeMounts:
- name: cache
mountPath: /app/.cache
# ZAPISYWALNY od DAN-27. Wcześniej read-only, bo warstwa danych tylko
# czytała bazy — teraz ekran „Pliki" pozwala je wgrywać, archiwizować
# i (dla administratora) kasować, a stan użycia jest KLIKANY, więc musi
# przetrwać restart poda.
#
# ŚWIADOMY KOSZT: znika jedna warstwa obrony w głąb. Przejęcie warstwy
# danych pozwala teraz nie tylko odczytać bazy, ale i je zmienić.
# Zostaje reszta: token międzywarstwowy, szyfrowane łącze, ograniczenie
# eksportu NFS do konkretnych hostów (DAN-25) i to, że kasować może
# wyłącznie konto administracyjne (PRE-27).
- name: excel
mountPath: /app/data_files
readOnly: true
resources:
requests: { cpu: "100m", memory: "256Mi" }
limits: { cpu: "500m", memory: "512Mi" }
+1 -1
View File
@@ -16,4 +16,4 @@ images:
- name: gitea.czernobog.pl/gitea/astrololo-render
newTag: aec3f843
- name: gitea.czernobog.pl/gitea/astrololo-presentation
newTag: a8339659
newTag: baf4e0e3
+5 -15
View File
@@ -66,20 +66,12 @@ spec:
- name: ACCOUNTS_FILE
value: "/app/state/accounts.json"
volumeMounts:
# OSOBNY UDZIAŁ, nie podkatalog udziału z bazami. Pierwsza wersja
# montowała /mnt/Tank1/astrololo z subPath — i nie wstała:
# „failed to create subPath directory”. Powód był podwójny i oba razy
# ten sam brak: udział z bazami jest wyeksportowany `ro: true`
# z `root_squash` (DAN-25), więc (1) kubelet nie mógł utworzyć
# podkatalogu, a (2) gdyby nawet mógł, aplikacja i tak nie zapisałaby
# tam pliku kont.
#
# Osobny udział rozwiązuje to bez naruszania DAN-25: udział z bazami
# ZOSTAJE tylko do odczytu, a konta mają własne, małe miejsce.
# Przy okazji znika subPath, czyli znika potrzeba, żeby kubelet
# cokolwiek zakładał — katalog istnieje, bo jest korzeniem udziału.
# subPath, NIE cały udział: prezentacja dostaje wyłącznie własny
# podkatalog i nie widzi baz interpretacyjnych. Zamontowanie tu całego
# /mnt/Tank1/astrololo obeszłoby bokiem zamknięcie dostępu z DAN-25.
- name: state
mountPath: /app/state
subPath: presentation-state
resources:
requests: { cpu: "100m", memory: "128Mi" }
limits: { cpu: "300m", memory: "256Mi" }
@@ -87,9 +79,7 @@ spec:
- name: state
nfs:
server: 192.168.1.34
# Udział WYŁĄCZNIE na stan prezentacji (konta z PRE-27). Wymaga
# utworzenia na TrueNAS — patrz README-stan-prezentacji.md.
path: /mnt/Tank1/astrololo-state
path: /mnt/Tank1/astrololo
---
apiVersion: v1
kind: Service