infrastructure/docs/platform/llm-server/encoding/GNENC-001-PLAN_Architecture.md

Arbeitsentwurf

Dokumenten-ID: GNENC-001-PLAN Titel: CPU-basiertes Video-Encoding auf dem KI-Server Stand: 2026-10-05 Status: Nicht finaler Arbeitsentwurf zur Persistierung der Planungsentscheidung

1. Zweck und Abgrenzung

Der physische Server ghostnet-ki soll neben den KI-Workloads einen getrennten Workload zum Encoding von Videodateien ausführen. Der Encoding-Workload gehört nicht zum LLM-Stack. Seine fachliche Architektur, Bedienung und späteren SOPs werden deshalb in diesem eigenen Dokumentationsbereich geführt.

Ansible, Podman, Betriebssystem und hostweite Ressourcenregeln bleiben gemeinsame Plattformbestandteile. Sie werden weiterhin ausschließlich im Infrastructure-Repository verwaltet, damit nicht mehrere Repositories unabhängig konkurrierende Sollzustände auf denselben Host anwenden.

2. Bestätigte Entscheidungen

Thema	Entscheidung	Nachweisgrenze
Repository	Host- und Deployment-Ansible bleibt im bestehenden Infrastructure-Repository	angenommen
Dokumentation	Encoding liegt unter docs/platform/llm-server/encoding/ und verwendet die Kennung GNENC	umgesetzt
Ausführungsidentität	eigenes gesperrtes Konto gn-encoding, UID/GID 982	eingerichtet und mit rootless Podman geprüft
Containertrennung	eigener rootless Podman-Store und eigener rootverwalteter Quadlet-Pfad	eingerichtet; Grundzustand per Ansible verwaltet und verifiziert; noch keine Workload definiert
Rechenressource	Encoding ist nach Betreiberfestlegung rein CPU-basiert und erhält keinen GPU-Zugriff	Planungsentscheidung; reale Last noch nicht gemessen
Parallelität	darf parallel zu AI Production oder AI Testing laufen	Planungsentscheidung
Zeitsteuerung	automatische Ausführung ausschließlich außerhalb der Stoßzeiten, zunächst nachts	Richtung festgelegt; konkrete Uhrzeiten fehlen
Anwendungen	konkrete Encoder, Images, Profile und Queue sind noch nicht gewählt	offen

3. Zielbild

flowchart LR
    HOST[ghostnet-ki]
    PROD[gnai-production\nrootless Podman]
    TEST[gnai-testing\nrootless Podman]
    ENC[gn-encoding\nrootless Podman]
    GPU[beide GPUs]
    CPU[CPU / I-O Budget]
    TIMER[nächtliche systemd-Zeitsteuerung]

    HOST --> PROD
    HOST --> TEST
    HOST --> ENC
    PROD --> GPU
    TEST --> GPU
    ENC --> CPU
    TIMER --> ENC

AI Production und AI Testing bleiben untereinander exklusiv. Der Encoding-Workload ist von dieser KI-Umschaltung unabhängig und darf parallel zur jeweils aktiven KI-Umgebung laufen. Hostwartung kann weiterhin einen Stopp aller Workloads erfordern.

4. Ressourcen- und Zeitsteuerung

Die nächtliche Einplanung allein schützt Production nicht vollständig: Ein Encoding-Lauf kann länger dauern als sein Startfenster, und Inferenz benötigt trotz GPU-Schwerpunkt CPU für Tokenisierung, Netzwerk und Begleitdienste. Die spätere Encoding-Unit soll deshalb mindestens verwalten:

• ein eindeutig definiertes Zeitfenster mit Zeitzone;
• Verhalten bei verpasstem Start, Neustart und überlangem Lauf;
• maximale CPU-Nutzung oder CPU-Gewichtung;
• niedrigere Scheduling-Priorität gegenüber interaktiven Diensten;
• I/O-Gewichtung und freien Speicher;
• geordneten Abbruch beziehungsweise Abschluss am Ende des erlaubten Fensters;
• Begrenzung auf genau einen gleichzeitigen Encoding-Job.

Konkrete Grenzwerte werden erst nach einem repräsentativen Encoding-Test unter gleichzeitiger Inferenzlast festgelegt. gn-encoding erhält keine Mitgliedschaft in GPU-Gruppen und keine /dev/kfd- oder /dev/dri-Weitergabe.

5. Repository-Grenzen

Am 19.10.2026 wurde das LLM-Server-Projekt fachlich in ein Hauptverzeichnis pro Aufgabe aufgeteilt; die Struktur folgt den Bereichen unter docs/platform/llm-server/:

llm-server/
├── host/ansible/                 # gemeinsame Plattform des physischen Servers
│   ├── playbooks/
│   │   ├── host.yml              # host_baseline, podman_runtime (shared), workload_accounts, amd_gpu_access
│   │   ├── preflight.yml
│   │   ├── bootstrap-deploy-account.yml
│   │   ├── verify-deploy-access.yml
│   │   └── verify-rocm-container.yml
│   └── roles/
│       ├── host_baseline/
│       ├── workload_accounts/
│       ├── amd_gpu_access/
│       └── rocm_container_probe/
├── llm/                          # LLM-Stack; entsteht mit dem AI-Vertical-Slice (GNAI-001 Meilenstein 2)
└── encoding/ansible/             # CPU-Encoding-Workload
    ├── playbooks/
    │   └── video-encoding.yml    # video_encoding
    └── roles/
        └── video_encoding/

host.yml verwaltet ausschließlich gemeinsame Plattformzustände; die gemeinsame Rolle workload_accounts legt dabei auch das Konto gn-encoding an. video-encoding.yml verwaltet den Encoding-spezifischen Zustand des Kontos gn-encoding — seine Pfade, Images, Quadlets, Timer und Health Checks — und setzt die Host-Baseline voraus. Ein künftiges ai.yml im llm/-Projekt darf nur KI-Zustände verändern. Ein späteres site.yml kann die unterstützte Gesamtkonfiguration in definierter Reihenfolge anwenden.

Ein separates Quellcode-Repository wird erst benötigt, wenn eigene Encoding-Software, eine Oberfläche oder ein Queue-Dienst entwickelt wird. Ein solches Repository erzeugt ein versioniertes Artefakt oder Image; ausschließlich das Infrastructure-Repository legt fest, welche Version auf dem Server läuft.

6. Aktueller Implementierungsstand

Die gemeinsame Rolle workload_accounts hat am 20.09.2026 eingerichtet:

Konto:       gn-encoding (UID/GID 982)
Konfiguration: /etc/ghostnet-encoding
Daten:         /var/lib/ghostnet-encoding
Eingang:       /var/lib/ghostnet-encoding/input
Ausgang:       /var/lib/ghostnet-encoding/output
Arbeitsdaten:  /var/lib/ghostnet-encoding/work
Quadlets:      /etc/containers/systemd/users/982
Podman-Store:  /var/lib/ghostnet-encoding/.local/share/containers/storage

Passwort und interaktive Shell sind gesperrt. Der systemd-User-Manager läuft dank Linger unabhängig von einer Anmeldung. Der Podman-Store wurde als rootless und getrennt von beiden KI-Stores geprüft. Es wurden noch keine Images oder Container angelegt.

Am 19.10.2026 wurde das Encoding-Ansible-Projekt unter llm-server/encoding/ansible/ eingerichtet. video-encoding.yml verwaltet und verifiziert seitdem den Encoding-Grundzustand: Konto-Identität und Passwort- sperre, subordinate ID-Bereiche, Verzeichnisstruktur, Quadlet-Verzeichnis, Linger und aktiver User-Manager, getrennter rootless Podman-Store sowie die CPU-Isolation (keine GPU-Gruppenmitgliedschaft, kein Lesezugriff auf /dev/kfd oder DRM-Render-Nodes). Solange die offenen Entscheidungen in Abschnitt 7 nicht getroffen sind, stellt die Rolle zusätzlich sicher, dass weder Quadlet-Dateien noch Container für gn-encoding existieren. Check-Mode und zwei aufeinanderfolgende Läufe meldeten jeweils ok=30 changed=0 failed=0.

7. Offene Entscheidungen

1. Welcher Encoder und welches fest versionierte Container-Image werden genutzt?
2. Welche Codecs, Qualitätsprofile und Hardwarekompatibilitäten sind erforderlich?
3. Woher kommen Eingabedateien, und wie werden fertige Dateien abgeholt?
4. Welches konkrete nächtliche Zeitfenster und welche Zeitzone gelten?
5. Darf ein laufender Job das Zeitfenster überschreiten oder wird er gestoppt?
6. Welche CPU-, Speicher- und I/O-Grenzen schützen die KI-Dienste?
7. Wie werden Warteschlange, Wiederholung, Teilresultate und Fehler behandelt?
8. Welche Aufbewahrungs-, Backup- und Löschregeln gelten für Video- und Arbeitsdateien?
9. Welche Statusanzeige oder Benachrichtigung benötigen Nutzer?

Diese Werte werden nicht vorab in Playbooks angenommen.