# Eine App für die GenAI-Plattform bauen

So baust du heute ein App-Paket, das die Plattform selbst ausrollen und verdrahten kann: ein Git-Repository mit einem Terraform-Modul und einem Ordner `genai-cli/`. Darin steht, was die App braucht (Redis, LiteLLM, Datenbank, Admin-Zugang, Logo) – den Rest erledigt der Deployment-Workflow.

Stand: 13.10.2026

> [!NOTE] Was dieses Dokument ist
> Die Anleitung beschreibt das Format, das die Plattform **heute** einliest. Eine Einreich-API gibt es noch nicht; neue Apps kommen über das Plattform-Team in den Katalog ([Übergabe](#uebergabe)). Ein einfacheres Paketformat ist in Arbeit – wenn es kommt, wird diese Seite fortgeschrieben, nicht ersetzt.

> [!TIP] Für KI-Assistenten
> Diese Seite gibt es auch als reines Markdown ([app-entwicklung.md](app-entwicklung.md)) und als Einstieg [llms.txt](llms.txt). Die harten Regeln stehen kompakt im Abschnitt [Regeln für KI-Assistenten](#ki-regeln). Eine lauffähige Vorlage liegt unter [vorlage/](vorlage/).

<!-- seite: grundlagen | Grundlagen | Aufbau eines App-Pakets | Was im Repository liegt, wie der Schlüssel geschrieben wird und wie die Plattform dein Modul aufruft. -->

## Auf einen Blick {#ueberblick}

Eine App ist heute ein **Modul-Repository** in der GitLab-Gruppe `genai-plattform/applications`. Die Plattform liest daraus den Ordner `genai-cli/`, erzeugt pro Umgebung die Terragrunt-Dateien und rollt aus.

<div class="flow">
  <div class="step"><b>1 · Du</b>Modul-Repo mit <code>genai-cli/</code>, SemVer-Tag</div>
  <span class="arrow">→</span>
  <div class="step"><b>2 · Plattform-Team</b>importiert das Repo in den App-Katalog</div>
  <span class="arrow">→</span>
  <div class="step"><b>3 · Bestellung</b>App wird für eine Umgebung gewählt, Abhängigkeiten kommen mit</div>
  <span class="arrow">→</span>
  <div class="step"><b>4 · Workflow</b>Secrets erzeugen, Dateien rendern, Terragrunt ausführen</div>
</div>

Was die Plattform für dich übernimmt:

- **Abhängigkeiten** – brauchst du Redis, wird Redis mit ausgerollt und vor deiner App angewendet.
- **Zugangsdaten** – Redis-Passwort, LiteLLM-Schlüssel, Datenbank, S3 und eigene Secrets werden erzeugt, verschlüsselt (SOPS) abgelegt und deiner App als Eingabe übergeben.
- **Domain, TLS, Ingress-Klasse, Pull-Secrets** – kommen aus der Umgebung.
- **Admin-Zugang** – die Umgebung hat einen Admin (E-Mail + Passwort), den deine App übernehmen kann.
- **Katalog-Kachel** – Name, Beschreibung und Logo erscheinen im Katalog und im AI Hub.
- **Pflicht-Labels** – `genai.govdigital.de/*` setzt die Plattform selbst.

## Aufbau des Repositorys {#repo}

<div class="tree">meine-app/
├── main.tf                         <span class="c"># Terraform-Modul: meist ein helm_release</span>
├── variables.tf                    <span class="c"># Eingaben, die die Plattform liefert</span>
├── outputs.tf
├── terraform.tf                    <span class="c"># required_providers, keine provider-Blöcke</span>
├── chart/                          <span class="c"># eigenes Helm-Chart (optional, oder Chart aus Repo)</span>
└── genai-cli/                      <span class="c"># ← das liest die Plattform</span>
    ├── <span class="req">terragrunt.hcl.genai</span>        <span class="c"># Pflicht: wie das Modul in der Umgebung aufgerufen wird</span>
    ├── <span class="req">metadata.json</span>               <span class="c"># Name, Beschreibung, Katalogtexte</span>
    ├── <span class="req">logo.svg</span>                    <span class="c"># oder logo.png</span>
    ├── config.domains.hcl.genai    <span class="c"># öffentliche Adresse</span>
    ├── config.hosts.hcl.genai      <span class="c"># Adresse im Cluster</span>
    ├── config.secrets.hcl.genai    <span class="c"># eigene Secrets, Admin-Login</span>
    ├── config.litellm.hcl.genai    <span class="c"># LiteLLM-Schlüssel</span>
    ├── config.databases.hcl.genai  <span class="c"># verwaltetes Postgres</span>
    ├── config.s3_buckets.hcl.genai <span class="c"># verwalteter S3-Bucket</span>
    └── config.versions.hcl.genai   <span class="c"># App- und Chart-Version</span></div>

| Datei | Pflicht | Wofür |
|---|---|---|
| `terragrunt.hcl.genai` | ja | Aufruf des Moduls: Quelle, Abhängigkeiten, Eingaben. Ohne sie ist das Repo nicht importierbar. |
| `metadata.json` | praktisch ja | Name, Beschreibung, Maintainer, Katalogtexte, Versionsquellen. |
| `logo.svg` / `logo.png` | für Partner ja | Kachel im Katalog und AI Hub. Ohne Logo sehen Partner die App nicht. |
| `config.domains.hcl.genai` | für Web-Apps | Öffentliche Adresse. Ohne sie keine Kachel im AI Hub. |
| `config.hosts.hcl.genai` | empfohlen | Interne Adresse, damit andere Apps dich erreichen. |
| `config.secrets.hcl.genai` | bei Bedarf | Secrets, die die Plattform erzeugen soll (z. B. Admin-Passwort). |
| `config.litellm.hcl.genai` | wenn die App ein LLM nutzt | Eigener LiteLLM-Schlüssel. |
| `config.databases.hcl.genai` | wenn die App Postgres braucht | Verbindungsdaten der verwalteten Datenbank. |
| `config.s3_buckets.hcl.genai` | wenn die App S3 braucht | Verbindungsdaten des Buckets. |
| `config.versions.hcl.genai` | empfohlen | App- und Chart-Version an einer Stelle. |

Jede `.genai`-Datei darf auch ohne Endung heißen (`terragrunt.hcl`); die Plattform sucht zuerst die Variante mit `.genai`.

## Schnellstart mit der Vorlage {#schnellstart}

Schnellster Weg: im [Baukasten](#baukasten) Schlüssel und Bausteine wählen und das fertige Repo als ZIP laden. Von Hand geht es so:

1. Den Ordner [vorlage/](vorlage/) in ein neues Repo kopieren.
2. Überall `meine-app` und `meine_app` durch deinen Schlüssel ersetzen ([Regeln](#schluessel)).
3. Nicht benötigte `config.*`-Dateien löschen und die passenden Zeilen in `terragrunt.hcl.genai` entfernen.
4. `main.tf` auf deine App anpassen, Logo austauschen, `metadata.json` ausfüllen.
5. Lokal prüfen ([Lokal prüfen](#lokal)), SemVer-Tag setzen, an das Plattform-Team übergeben ([Übergabe](#uebergabe)).

```bash title="Vorlage übernehmen"
cp -R docs/app-entwicklung/vorlage ../meine-wissensdatenbank
cd ../meine-wissensdatenbank
grep -rl 'meine[-_]app' . | xargs sed -i '' -e 's/meine-app/wissensdatenbank/g' -e 's/meine_app/wissensdatenbank/g'
./pruefen.sh
```

## Der Schlüssel der App {#schluessel}

Der Schlüssel ist der feste Name der App, zum Beispiel `open-webui`. Er lässt sich nach dem Import nicht mehr ändern.

- Nur Kleinbuchstaben, Ziffern und Bindestrich, höchstens 40 Zeichen, nicht mit `-` beginnen oder enden.
- Reserviert: `apps`, `import`, `new`.
- Der Import nimmt den einzigen Schlüssel aus `config.hosts`/`config.domains`, sonst den Repo-Namen ohne `terraform-`/`-terraform`.

Die Plattform schreibt den Schlüssel in zwei Formen. Das ist die häufigste Fehlerquelle:

| Wo | Schreibweise | Beispiel |
|---|---|---|
| Katalog, Ordner in der Umgebung, `dependencies` | mit Bindestrich | `open-webui` |
| Schlüssel in allen `config.*`-Dateien und in `inputs.*.<key>` | mit Unterstrich | `open_webui` |
| Abschnitt in `config.secrets.hcl.genai` und `secrets.<key>` | mit Unterstrich | `secrets.open_webui.admin_password` |

## `terragrunt.hcl.genai` {#terragrunt}

Die Datei wird pro Umgebung in zwei Schritten verarbeitet:

1. **Jinja** (`{{ … }}`) – beim Erzeugen der Umgebung. Verfügbar sind `source` (die Modulquelle mit Tag) und jeder Wert aus den Katalog-Standardwerten (`defaultValues`). Immer mit `default(…)` schreiben.
2. **Terragrunt/HCL** (`${ … }`, `try(…)`) – beim Ausrollen. Hier liest du alles, was die Umgebung bereitstellt, aus `local.common_vars.inputs`.

```hcl title="genai-cli/terragrunt.hcl.genai"
include "root" {
  path = find_in_parent_folders("root.hcl")
}

# Provider kommen von der Plattform. kubernetes.hcl ignoriert die Pflicht-Labels.
include "kubernetes" {
  path = "${get_terragrunt_dir()}/../providers/kubernetes.hcl"
}

include "helm" {
  path = "${get_terragrunt_dir()}/../providers/helm.hcl"
}

terraform {
  source = "{{ source | default('../../../../../terraform-meine-app') }}"
}

# Was vor dieser App angewendet sein muss. Daraus wird im Katalog "dependsOn".
dependencies {
  paths = ["../redis", "../../applications/litellm"]
}

locals {
  common_vars = read_terragrunt_config(find_in_parent_folders("terragrunt.hcl"))
}

inputs = merge(
  local.common_vars.inputs,
  {
    release_name = "meine-app"
    domain       = try(local.common_vars.inputs.domains.meine_app, "")
    replicas     = {{ replicas | default(1) }}

    # Redis – vom Redis-Modul der Umgebung
    redis_host     = try(local.common_vars.inputs.databases.redis.host, "")
    redis_port     = try(local.common_vars.inputs.databases.redis.port, "6379")
    redis_password = try(local.common_vars.inputs.databases.redis.password, "")

    # LiteLLM – OpenAI-kompatibel, eigener Schlüssel aus config.litellm.hcl.genai
    openai_base_url = "http://${try(local.common_vars.inputs.hosts.litellm, "localhost")}:4000/v1"
    openai_api_key  = try(local.common_vars.inputs.litellm.meine_app.key, "")

    # Admin – der Admin der Umgebung
    admin_email    = try(local.common_vars.inputs.default_user_email, "")
    admin_password = try(local.common_vars.inputs.default_user_password, "")
  }
)
```

> [!IMPORTANT] Immer `try(…, default)`
> Zugangsdaten für Datenbank und S3 stehen erst nach dem ersten Secret-Abgleich in der Umgebung. Ein nackter Zugriff wie `inputs.databases.meine_app.password` bricht dann schon den Plan ab. `try()` hält ihn lauffähig.

### Was die Umgebung bereitstellt {#inputs}

Alles unter `local.common_vars.inputs`. Weil `inputs = merge(local.common_vars.inputs, {...})` alles weiterreicht, kann dein Modul diese Namen auch direkt als Terraform-Variable deklarieren. Was es nicht deklariert, ignoriert Terraform.

| Eingabe | Inhalt |
|---|---|
| `namespace`, `release_name_prefix` | Kubernetes-Namespace der Umgebung und Präfix für Release-Namen |
| `domain`, `environment`, `organisation` | Basis-Domain, Umgebungsname, Organisation |
| `ingress_class_name`, `cluster_issuer_name`, `certificates` | Ingress-Klasse, cert-manager-Issuer, Zertifikate |
| `storage_class` | Storage-Klasse für Volumes |
| `image_pull_secrets`, `registry_credentials` | Namen der Pull-Secrets, Registry-Zugänge |
| `domains.<key>`, `hosts.<key>` | öffentliche und interne Adressen aller Apps der Umgebung |
| `databases.<key>`, `s3_buckets.<key>` | Verbindungsdaten (auch `databases.redis`) |
| `litellm.<key>.key` | LiteLLM-Schlüssel je App |
| `secrets.<key>.<name>` | eigene Secrets aus `config.secrets.hcl.genai` |
| `versions.<key>`, `helm_chart_versions.<key>` | Versionen aus `config.versions.hcl.genai` |
| `default_user_email`, `default_user_first_name`, `default_user_password` | Admin der Umgebung |
| `smtp_host`, `smtp_port`, `smtp_from`, `smtp_from_name`, `smtp_username`, `smtp_password` | Mailversand, leer wenn die Umgebung keinen hat |
| `http_proxy`, `https_proxy`, `no_proxy` | Proxy, meist leer |
| `models` | Modell-Liste der Umgebung |

### Regeln für das Terraform-Modul {#modul}

- **Keine `provider`-Blöcke und kein `backend`.** Beides erzeugt die Plattform. Eine Datei `providers.tf` wird beim Ausrollen leer überschrieben.
- **Helm-Provider `~> 2.0`.** Die erzeugte Provider-Konfiguration nutzt die Syntax von Version 2.
- **`k8s_config_path` und `k8s_context` nicht deklarieren** – die Plattform deklariert sie selbst.
- **Nichts außerhalb des Namespace** `var.namespace` anlegen; Cluster-Ressourcen gehören nicht in ein App-Modul.
- **Keine eigenen `genai.govdigital.de/*`-Labels** und nie Selektoren oder Pod-Template-Labels dafür ändern.
- **Release- und Workload-Namen enthalten den Schlüssel** (`${release_name_prefix}meine-app`). Daran ordnet das Monitoring Pods der App zu.

<!-- seite: dienste | Dienste anbinden | Redis, LiteLLM, Datenbank und Secrets | Du sagst, was deine App braucht. Die Plattform rollt es aus, erzeugt die Zugangsdaten und reicht sie an dein Modul weiter. -->

## Abhängigkeiten (`dependsOn`) {#abhaengigkeiten}

Du erklärst eine Abhängigkeit an **einer** Stelle: im `dependencies`-Block von `terragrunt.hcl.genai`. Daraus leitet der Import das Katalogfeld `dependsOn` ab.

```hcl title="Abhängigkeit auf Redis und LiteLLM"
dependencies {
  paths = ["../redis", "../../applications/litellm"]
}
```

Was dann passiert:

1. **Beim Bestellen** wählt die Plattform jede Abhängigkeit automatisch mit, auch über mehrere Stufen (deine App → LiteLLM → Redis, Presidio).
2. **Beim Erzeugen** bekommt die Abhängigkeit ihre Secrets (z. B. das Redis-Passwort) und schreibt ihre Verbindungsdaten in die Umgebung.
3. **Beim Ausrollen** wendet Terragrunt die Abhängigkeit vor deiner App an.
4. **Deine App** liest die Verbindungsdaten über `local.common_vars.inputs` – nicht über Terragrunt-Outputs.

Regeln:

- Der letzte Pfadteil ist der **Katalogschlüssel** der Abhängigkeit (`redis`, `litellm`). Ist er nicht im Katalog, blockiert der Import. Eine eigene Abhängigkeit (z. B. eine zweite App von dir) muss deshalb zuerst importiert werden.
- `../name` heißt „gleiche Stufe“, `../../applications/name` „andere Stufe“. Liegt die Abhängigkeit woanders, korrigiert die Plattform den Pfad selbst.
- Verweist deine Datei auf `../../…`, landet die App in der Stufe `ai-applications` (nach `applications`). Das ist richtig für Apps, die LiteLLM nutzen.
- Postgres ist **keine** Abhängigkeit, sondern eine verwaltete Datenbank ([Datenbank und S3](#datenbank)).

| Abhängigkeit | Pfad | Was deine App bekommt |
|---|---|---|
| Redis | `../redis` | `inputs.databases.redis.{host,port,password}` |
| LiteLLM | `../../applications/litellm` | `inputs.hosts.litellm`, `inputs.domains.litellm`, eigener Schlüssel über `config.litellm.hcl.genai` |
| Presidio | `../presidio` | `inputs.hosts.presidio_analyzer`, `inputs.hosts.presidio_anonymizer` |
| eine andere App | `../<key>` | was diese App in `config.hosts`/`config.domains` veröffentlicht |

> [!WARNING] Nachinstallieren in eine laufende Umgebung
> Bestellung und Assistent ziehen Abhängigkeiten automatisch mit. Fügt ein Operator eine App einzeln einer bestehenden Umgebung hinzu, passiert das heute nicht – die Abhängigkeit muss dort schon laufen.

## Redis anbinden {#redis}

1. Abhängigkeit eintragen: `"../redis"` im `dependencies`-Block.
2. Verbindungsdaten lesen. Das Redis-Modul der Umgebung veröffentlicht sie unter `databases.redis`:

```hcl title="terragrunt.hcl.genai – Redis"
redis_host     = try(local.common_vars.inputs.databases.redis.host, "")
redis_port     = try(local.common_vars.inputs.databases.redis.port, "6379")
redis_password = try(local.common_vars.inputs.databases.redis.password, "")
```

3. Im Modul daraus die URL bauen, die deine App erwartet:

```hcl title="main.tf – Redis-URL für die App"
locals {
  redis_url = "redis://:${var.redis_password}@${var.redis_host}:${var.redis_port}/0"
}
```

- `host` ist der Service im Namespace (`<präfix>redis-master.<namespace>`); wer einen voll qualifizierten Namen braucht, hängt `.svc.cluster.local` an.
- Das Passwort erzeugt die Plattform, sobald Redis in der Umgebung ist. Du musst nichts dafür deklarieren.
- Teile dir Redis mit anderen Apps: nimm eine eigene Datenbanknummer oder ein Schlüsselpräfix.

> [!NOTE] Ältere Schreibweise
> Ältere Module lesen `inputs.hosts.redis` und `inputs.redis_password`. Beides funktioniert noch; für neue Apps gilt `inputs.databases.redis.*`.

## LiteLLM anbinden {#litellm}

Deine App spricht mit LiteLLM wie mit der OpenAI-API. Sie bekommt einen eigenen Schlüssel mit eigenem Team, damit Nutzung und Kosten getrennt sichtbar sind.

1. Abhängigkeit eintragen: `"../../applications/litellm"`.
2. Schlüssel anmelden mit `config.litellm.hcl.genai`:

```hcl title="genai-cli/config.litellm.hcl.genai"
include "global" {
  path   = find_in_parent_folders("global.hcl")
  expose = true
}

locals {
  litellm = {
    meine_app = {
      team_alias     = "meine-app-team"
      key_alias      = "meine-app-api-key"
      create_api_key = true
      models         = []   # leer = alle Modelle der Umgebung
      metadata       = { service = "meine-app" }
      key            = try(include.global.locals.secrets.litellm.keys.meine_app, "")
    }
  }
}
```

3. Schlüssel und Adresse übergeben:

```hcl title="terragrunt.hcl.genai – LiteLLM"
openai_base_url = "http://${try(local.common_vars.inputs.hosts.litellm, "localhost")}:4000/v1"
openai_api_key  = try(local.common_vars.inputs.litellm.meine_app.key, "")
```

- Die Zeile `key = try(include.global.locals.secrets.litellm.keys.<key>, "")` ist Pflicht und muss genau so heißen: an ihr erkennt die Plattform, dass sie einen `sk-…`-Schlüssel erzeugen und in LiteLLM anlegen soll.
- Nimm die interne Adresse (`hosts.litellm`, Port 4000). Die öffentliche (`https://${inputs.domains.litellm}`) geht auch, läuft aber über den Ingress.
- Welche Modelle es gibt, steht in `inputs.models`. Modellnamen besser als Katalog-Standardwert (`{{ model_chat | default('…') }}`) statt fest im Code.

## Datenbank und S3 {#datenbank}

Postgres und S3 sind **verwaltet**: die Plattform legt Datenbank bzw. Bucket in der Infrastruktur-Stufe an und schreibt die Zugangsdaten in die Secrets der Umgebung. Deine App bekommt sie über zwei Dateien.

```hcl title="genai-cli/config.databases.hcl.genai"
locals {
  databases = {
    meine_app = {
      host     = try(include.global.locals.secrets.database.meine_app.host, "localhost")
      port     = try(include.global.locals.secrets.database.meine_app.port, "5432")
      name     = try(include.global.locals.secrets.database.meine_app.name, "${include.global.locals.environment_name}-meine-app")
      username = try(include.global.locals.secrets.database.meine_app.username, "${include.global.locals.environment_name}_meine_app")
      password = try(include.global.locals.secrets.database.meine_app.password, "")
    }
  }
}
```

```hcl title="genai-cli/config.s3_buckets.hcl.genai"
locals {
  s3_buckets = {
    meine_app = {
      bucket           = try(include.global.locals.secrets.s3_buckets.meine_app.bucket, "meine-app")
      endpoint         = try(include.global.locals.secrets.s3_buckets.meine_app.endpoint, "")
      region           = try(include.global.locals.secrets.s3_buckets.meine_app.region, "eu01")
      force_path_style = false
      username         = try(include.global.locals.secrets.s3_buckets.meine_app.access_key, "")
      secret_key       = try(include.global.locals.secrets.s3_buckets.meine_app.secret_key, "")
    }
  }
}
```

In `terragrunt.hcl.genai` liest du dann `inputs.databases.meine_app.{host,port,name,username,password}` und `inputs.s3_buckets.meine_app.{bucket,endpoint,region,username,secret_key}`.

- Der Import erkennt die Datenbank nur, wenn `config.databases` auf `secrets.database.<key>` verweist. Dann trägt er `requires.databases` im Katalog ein.
- Im S3-Abschnitt heißt der Access-Key **`username`** – so erwartet es die Bucket-Bereitstellung. Lies ihn als `inputs.s3_buckets.<key>.username`.
- Eine App, die Postgres selbst mitbringt (eigener StatefulSet), braucht beides nicht – dann ist das Passwort ein eigenes Secret ([Eigene Secrets](#secrets)).

## Admin-Zugang und eigene Secrets {#secrets}

### Der Admin der Umgebung

Jede Umgebung hat einen Admin: E-Mail, Vorname, Passwort. Der Partner gibt die E-Mail bei der Bestellung an, das Passwort erzeugt die Plattform. Übernimm diesen Admin, statt einen eigenen zu erfinden – dann meldet sich der Partner überall gleich an.

```hcl title="terragrunt.hcl.genai – Admin übernehmen"
admin_email      = try(local.common_vars.inputs.default_user_email, "")
admin_first_name = try(local.common_vars.inputs.default_user_first_name, "Administrator")
admin_password   = try(local.common_vars.inputs.default_user_password, "")
```

Dein Modul legt damit beim ersten Start den Admin an (Bootstrap-Variablen, Init-Job oder Helm-Hook – je nach App).

### Eigene Secrets erzeugen lassen

Braucht deine App weitere Secrets (Signaturschlüssel, Admin-Benutzername, interne Passwörter), meldest du sie in `config.secrets.hcl.genai` an. Die Plattform erzeugt fehlende Werte beim Anlegen der Umgebung und überschreibt nie einen vorhandenen.

```hcl title="genai-cli/config.secrets.hcl.genai"
locals {
  required_secrets = {
    meine_app = {
      admin_username = {
        type        = "static"
        default     = "admin"
        description = "Login-Name des Admins"
      }
      admin_password = {
        type        = "password"
        length      = 32
        description = "Passwort des Admins"
      }
      session_secret = {
        type        = "hex"
        length      = 32
        description = "Signiert Sitzungen"
      }
    }
  }
}
```

Lesen in `terragrunt.hcl.genai`:

```hcl title="terragrunt.hcl.genai – eigene Secrets"
admin_username = try(local.common_vars.inputs.secrets.meine_app.admin_username, "admin")
admin_password = try(local.common_vars.inputs.secrets.meine_app.admin_password, "")
session_secret = try(local.common_vars.inputs.secrets.meine_app.session_secret, "")
```

| `type` | erzeugt | Felder |
|---|---|---|
| `password` | Buchstaben und Ziffern | `length` (Standard 32) |
| `hex` | Hex-Zeichenkette, 2 Zeichen je Byte | `length` in Bytes (Standard 32) |
| `fernet` | Fernet-Schlüssel (44 Zeichen) | – |
| `prefixed` | `<prefix>-<zufall>` | `prefix`, `length` (Standard 24) |
| `static` | genau `default` | `default` – ohne `default` bleibt der Wert leer |

> [!WARNING] `admin_password` erbt das Admin-Passwort
> Heißt ein Secret `admin_password`, bekommt es das Passwort des Admins der Umgebung statt eines Zufallswerts. Das ist gewollt (ein Login für alle Apps) und **vorläufig**: es entfällt, sobald Konten zentral über den AI Hub vergeben werden. Willst du ein unabhängiges Passwort, nenne es anders.

- Zugangsdaten nie in `metadata.json`, Katalog-Standardwerte oder Klartext-Dateien schreiben. Secrets gehören in `config.secrets.hcl.genai`.
- Ein Secret, das der Partner selbst setzen muss (z. B. ein externer API-Schlüssel), meldest du als `static` ohne `default` an und beschreibst es in `description`. Das Plattform-Team trägt es dann ein.

## Adressen: Domain und Host {#adressen}

```hcl title="genai-cli/config.domains.hcl.genai"
locals {
  domains = {
    meine_app = "meine-app-${include.global.locals.domain}"
  }
}
```

```hcl title="genai-cli/config.hosts.hcl.genai"
locals {
  hosts = {
    meine_app = "${include.global.locals.release_name_prefix}meine-app.${include.global.locals.k8s_namespace}"
  }
}
```

- `domains.<key>` ist die öffentliche Adresse. Dein Ingress nutzt sie zusammen mit `ingress_class_name` und dem Issuer `cluster_issuer_name`.
- `hosts.<key>` muss zum Namen deines Kubernetes-Service passen. Andere Apps erreichen dich darüber.
- `include.global.locals.*` darfst du in allen `config.*`-Dateien nutzen; fehlt der `include "global"`-Block, ergänzt ihn die Plattform.

<!-- seite: katalog | Katalog | Im Katalog und im AI Hub erscheinen | Name, Texte, Logo und Versionen: was Partner sehen und was die Konsole beim Import ausliest. -->

## `metadata.json` und Katalogtexte {#metadata}

```json title="genai-cli/metadata.json"
{
  "name": "Meine App",
  "description": "Ein Satz, was die App tut.",
  "maintainers": ["team-meine-app"],
  "catalog": {
    "label": "Meine App",
    "summary": "Ein Satz für die Katalog-Kachel, ohne Zeilenumbruch.",
    "details": "Ein bis drei Absätze für die Detailseite.\n\nNur Klartext, kein Markdown.",
    "vendor": "Hersteller (Open Source)",
    "category": "ui",
    "role": "application",
    "defaultValues": {
      "replicas": 1,
      "model_chat": "stackit-openai-gpt-oss-120b"
    }
  },
  "versions": {
    "meine_app": {
      "description": "Image der App",
      "source": { "type": "registry", "host": "registry.onstackit.cloud", "repo": "govdigital/meine-app", "tagPrefix": "v", "limit": 50 }
    }
  }
}
```

| Feld | Bedeutung |
|---|---|
| `name`, `description`, `maintainers` | Grunddaten; `description` ohne `catalog.summary` wird zur Kurzbeschreibung |
| `catalog.label` | Anzeigename |
| `catalog.summary` | ein Satz, eine Zeile – Pflicht für Partner |
| `catalog.details` | Klartext-Absätze; keine Zeichen `<` `>` `*` `#` und kein Backtick – Pflicht für Partner |
| `catalog.vendor` | Hersteller – Pflicht für Partner |
| `catalog.category` | `core`, `observability`, `ui`, `tooling` oder `data` – Pflicht, ohne Kategorie lehnt der Katalog den Eintrag ab |
| `catalog.role` | `application` (Nutzer sehen sie) oder `service` (Baustein für andere Apps, z. B. Redis) |
| `catalog.tier` | `applications` oder `ai-applications`; sonst aus den Abhängigkeitspfaden abgeleitet |
| `catalog.defaultValues` | Jinja-Werte für `terragrunt.hcl.genai`; Platzhalter `${env}`, `${org}`, `${envName}` werden ersetzt |
| `versions.<name>.source` | woher die Konsole verfügbare Versionen liest: `registry`, `github-release` oder `gitlab-release` mit `host`, `repo`, `tagPrefix`, `stripPrefix`, `limit` |
| `helmChartVersions.<name>` | dasselbe für die Chart-Version |

## Logo {#logo}

Lege das Logo in `genai-cli/` ab. Die Plattform sucht in dieser Reihenfolge: `logo.svg`, `logo.png`, `logo.jpg`, `logo.jpeg`.

| Regel | Wert |
|---|---|
| Formate | SVG (bevorzugt), PNG, JPEG |
| Größe | höchstens 1 MiB im Repo |
| Rasterbilder | quadratisch, am besten 256 × 256 px; größere werden auf 256 px verkleinert |
| SVG | höchstens 128 KiB, kein `<script>`, keine `on…`-Attribute, kein `foreignObject`, keine externen Verweise, keine DTD |
| Darstellung | auf hellem Grund, ohne Rand, Motiv füllt die Fläche |
| nicht angenommen | `logo.webp`, `icon.ico` |

Ohne Logo bleibt die App für Partner unsichtbar.

## Im AI Hub erscheinen {#ai-hub}

Eine App bekommt automatisch eine Kachel im AI Hub der Umgebung, wenn

- `catalog.role` `application` ist und
- `config.domains.hcl.genai` eine Adresse unter genau dem Schlüssel liefert, mit Unterstrich: Katalog `meine-app` → `domains.meine_app`.

Nach jedem Ausrollen erneuert die Plattform den Hub selbst. Logo und Texte kommen aus dem Katalog.

## Versionen und Tags {#versionen}

- **Modul-Version:** setze SemVer-Tags (`v1.0.0`, `v1.1.0`). Beim Import legt die Konsole den neuesten Tag als Version fest; das Plattform-Team kann stattdessen „immer den neuesten Tag“ wählen. Ohne Tag läuft der unversionierte Stand – nur zum Testen.
- **Neue Tags** erreichen neue Bestellungen, sobald die Version im Katalog umgestellt ist (oder „neuester Tag“ gilt). Laufende Umgebungen aktualisieren sich nicht selbst.
- **App-Version:** steht in `config.versions.hcl.genai` und lässt sich je Umgebung umstellen.

```hcl title="genai-cli/config.versions.hcl.genai"
locals {
  versions = {
    meine_app = "{{ meine_app_version | default('v1.0.0') }}"
  }
  helm_chart_versions = {
    meine_app = "1.0.0"
  }
}
```

Jede Änderung, die eine Umgebung betrifft, ist ein neuer Tag. Einen veröffentlichten Tag nie verschieben.

## Images und Registry {#images}

- Images gehören in die STACKIT-Registry unter `registry.onstackit.cloud/govdigital/…`. Eine Cluster-Richtlinie meldet Images aus anderen Registries; heute nur als Prüfbefund, später als Sperre.
- Pull-Secrets nicht selbst anlegen: `image_pull_secrets = try(local.common_vars.inputs.image_pull_secrets, [])` übergeben und im Chart nutzen.
- Immer einen festen Tag verwenden, nie `latest`.
- Container ohne Root-Rechte, mit Ressourcen-Limits und Health-Checks (`readinessProbe`, `livenessProbe`).

<!-- seite: pruefen | Prüfen & übergeben | Prüfen und übergeben | Lokal testen, Checkliste abhaken, an das Plattform-Team geben – und was tun, wenn etwas hakt. -->

## Lokal prüfen {#lokal}

Eine Testumgebung zum Selbstbedienen gibt es noch nicht. Lokal prüfst du drei Dinge:

**1. Paket-Check** – die Vorlage bringt `pruefen.sh` mit. Es prüft Pflichtdateien, Schlüssel-Schreibweisen, `metadata.json`, Logo und Abhängigkeitspfade.

```bash title="Paket prüfen"
./pruefen.sh
```

**2. Modul** – das Terraform-Modul gegen einen lokalen Cluster (kind, k3d, Docker Desktop) mit Werten, die sonst die Plattform liefert:

```bash title="Modul lokal ausrollen"
kind create cluster --name app-test
kubectl run redis --image=redis:7-alpine -- redis-server --requirepass lokal-test
kubectl expose pod redis --port 6379
export KUBE_CONFIG_PATH=~/.kube/config
terraform init
terraform apply -var-file=beispiel/lokal.tfvars
kubectl port-forward svc/meine-app 8080:80
```

`beispiel/lokal.tfvars` in der Vorlage setzt Namespace, Image, Redis, LiteLLM-Ersatz und Admin mit Testwerten. Als LiteLLM-Ersatz taugt jeder OpenAI-kompatible Dienst (z. B. Ollama unter `http://host.docker.internal:11434/v1`). Ein `provider`-Block ist dafür nicht nötig: der Helm-Provider liest `KUBE_CONFIG_PATH`.

**3. Chart** – `helm lint chart/` und `helm template chart/` mit deinen Werten.

> [!NOTE] Was lokal nicht prüfbar ist
> Die Jinja-Werte, die Secret-Erzeugung und das Zusammenspiel der Umgebung prüft heute nur das Plattform-Team beim Import und in einer Dev-Umgebung.

## Übergabe an das Plattform-Team {#uebergabe}

1. Repo in der GitLab-Gruppe `genai-plattform/applications` anlegen (lassen). Nur von dort importiert die Konsole, und nur Repos mit `genai-cli/terragrunt.hcl.genai` auf dem Standard-Branch.
2. SemVer-Tag setzen.
3. Dem Plattform-Team Bescheid geben: Repo, Tag, Ansprechpartner.
4. Das Plattform-Team importiert unter **App-Katalog → Importieren**. Der Import zeigt einen Entwurf (Schlüssel, Stufe, Abhängigkeiten, Datenbanken, Buckets, Secrets, Logo, Texte) und blockiert, wenn eine Abhängigkeit nicht im Katalog ist oder die Vorlage am Tag fehlt.
5. Danach: Test in einer Dev-Umgebung, Version festlegen, für Partner freischalten. Neue Einträge sind angeboten, aber für Partner erst sichtbar, wenn das Plattform-Team es einschaltet.

| Was der Import liest | Woraus |
|---|---|
| Schlüssel | einziger Schlüssel in `config.hosts`/`config.domains`, sonst Repo-Name |
| Stufe | `catalog.tier`, sonst aus den Abhängigkeitspfaden |
| Abhängigkeiten | `dependencies`-Block, nur Einträge, die im Katalog sind |
| Datenbanken, Buckets | `config.databases` / `config.s3_buckets` mit Verweis auf `secrets.database.<key>` / `secrets.s3_buckets.<key>` |
| Texte, Kategorie, Rolle, Standardwerte | `metadata.json` → `catalog` |
| Logo | `logo.svg` / `logo.png` |
| Version | neuester SemVer-Tag |

## Checkliste {#checkliste}

Hake ab, was erledigt ist. Der Stand bleibt in diesem Browser gespeichert.

- [ ] Repo enthält ein Terraform-Modul und den Ordner `genai-cli/`
- [ ] `genai-cli/terragrunt.hcl.genai` vorhanden, mit `include "root"`, `include "kubernetes"` und `include "helm"`
- [ ] `terraform { source = "{{ source | default('…') }}" }` gesetzt
- [ ] Schlüssel gewählt: Kleinbuchstaben, Ziffern, Bindestrich, höchstens 40 Zeichen
- [ ] In allen `config.*`-Dateien und `inputs.*` den Schlüssel mit Unterstrich verwendet
- [ ] Jede Abhängigkeit im `dependencies`-Block, letzter Pfadteil ist ein Katalogschlüssel
- [ ] Redis über `inputs.databases.redis.{host,port,password}` angebunden (falls benötigt)
- [ ] LiteLLM: `config.litellm.hcl.genai` mit `key = try(include.global.locals.secrets.litellm.keys.<key>, "")`, Adresse über `hosts.litellm:4000/v1` (falls benötigt)
- [ ] Datenbank/S3: `config.databases`/`config.s3_buckets` auf `secrets.database.<key>` bzw. `secrets.s3_buckets.<key>`, S3-Access-Key als `username` (falls benötigt)
- [ ] Admin über `inputs.default_user_*` übernommen
- [ ] Eigene Secrets in `config.secrets.hcl.genai`, nirgends Klartext-Passwörter
- [ ] Jeder Zugriff auf `inputs.*` mit `try(…, default)`
- [ ] Jeder Jinja-Wert mit `| default(…)`
- [ ] `config.domains.hcl.genai` und `config.hosts.hcl.genai` passen zu Ingress und Service
- [ ] Modul ohne `provider`- und `backend`-Blöcke, Helm-Provider `~> 2.0`, kein `k8s_config_path`
- [ ] Images in `registry.onstackit.cloud/govdigital/…`, fester Tag, Pull-Secrets aus `inputs.image_pull_secrets`
- [ ] Container ohne Root, mit Limits und Health-Checks
- [ ] Release-Name enthält den Schlüssel
- [ ] Logo `logo.svg` oder `logo.png` nach den Regeln
- [ ] `metadata.json` mit `summary`, `details` (Klartext), `vendor`, `category`, `role`
- [ ] `config.versions.hcl.genai` mit App-Version
- [ ] `./pruefen.sh` läuft ohne Fehler
- [ ] Modul lokal ausgerollt, App erreichbar, Admin-Login funktioniert
- [ ] SemVer-Tag gesetzt
- [ ] Plattform-Team informiert: Repo, Tag, Ansprechpartner

## Bekannte Stolperstellen {#stolperstellen}

| Symptom | Ursache | Lösung |
|---|---|---|
| Plan bricht mit „Unsupported attribute“ ab | Zugriff ohne `try()` auf Daten, die erst später kommen | `try(…, "")` |
| App findet Redis nicht | `hosts.redis` statt `databases.redis` oder Service-Name falsch | `inputs.databases.redis.host` nutzen |
| LiteLLM-Schlüssel leer | `key`-Zeile fehlt oder anders geschrieben | genau `try(include.global.locals.secrets.litellm.keys.<key>, "")` |
| S3-Zugriff verweigert | Access-Key als `access_key` geschrieben, als `username` gelesen | im S3-Abschnitt `username` verwenden |
| Admin-Passwort unbekannt | Secret `admin_password` erbt das Admin-Passwort | gewollt; sonst anders benennen |
| Statisches Secret leer | `type = "static"` ohne `default` | `default` setzen oder Plattform-Team trägt den Wert ein |
| Import blockiert: „unknown dependency“ | Abhängigkeit ist nicht im Katalog | erst die Abhängigkeit in den Katalog bringen |
| App für Partner unsichtbar | `summary`, `details`, `vendor` oder Logo fehlen, oder `details` enthält `<>*#` | Texte und Logo ergänzen |
| Keine Kachel im AI Hub | `role` ist `service` oder keine Domain | `role: application`, `config.domains` |
| Doppelter Provider beim Init | Modul bringt eigenen `provider "helm"` mit | Provider-Block entfernen |
| Logo fehlt trotz Datei | `logo.webp` oder `icon.ico` | als SVG oder PNG ablegen |

<!-- seite: ki | Für KI | Für KI-Assistenten | Dieselbe Anleitung als harte Regeln, dazu Markdown, llms.txt und ein fertiger Auftrag zum Kopieren. -->

## Regeln für KI-Assistenten {#ki-regeln}

Kompakt für Agenten, die ein App-Paket erzeugen oder prüfen. Jede Regel ist oben begründet.

1. Ein App-Paket ist ein Git-Repo: Terraform-Modul im Wurzelordner, Plattform-Dateien in `genai-cli/`.
2. Pflicht ist `genai-cli/terragrunt.hcl.genai` und in `metadata.json` `catalog.category` (`core|observability|ui|tooling|data`). Für Partner zusätzlich `catalog.summary` (eine Zeile), `catalog.details` (Klartext ohne `<>*#` und Backtick), `catalog.vendor` und ein Logo `logo.svg`/`logo.png`.
3. Schlüssel: `^[a-z0-9]([a-z0-9-]{0,38}[a-z0-9])?$`. In `config.*`, `inputs.*` und `secrets.*` mit `_` statt `-`.
4. `.genai`-Dateien sind Jinja-Vorlagen. Jinja-Variablen: `source` und die Schlüssel aus `catalog.defaultValues`. Immer `{{ x | default(…) }}`.
5. Zur Laufzeit liest das Modul alles aus `local.common_vars.inputs`, wobei `common_vars = read_terragrunt_config(find_in_parent_folders("terragrunt.hcl"))`. Jeder Zugriff in `try(…, default)`.
6. Abhängigkeiten nur im Block `dependencies { paths = [...] }`. Letzter Pfadteil = Katalogschlüssel. Verbindungsdaten nie über `dependency`-Outputs.
7. Redis: Pfad `../redis`; lesen `inputs.databases.redis.host|port|password`.
8. LiteLLM: Pfad `../../applications/litellm`; `config.litellm.hcl.genai` mit `locals.litellm.<key>.{team_alias,key_alias,create_api_key=true,models=[],metadata,key=try(include.global.locals.secrets.litellm.keys.<key>,"")}`; lesen `inputs.litellm.<key>.key`; Basis-URL `http://${inputs.hosts.litellm}:4000/v1`.
9. Postgres/S3 nie als Abhängigkeit: `config.databases.hcl.genai` mit `secrets.database.<key>.{host,port,name,username,password}`, `config.s3_buckets.hcl.genai` mit `secrets.s3_buckets.<key>.{bucket,endpoint,region,access_key→username,secret_key}`.
10. Admin: `inputs.default_user_email|default_user_first_name|default_user_password`. Eigene Secrets in `config.secrets.hcl.genai` unter `locals.required_secrets.<key>.<name> = { type = password|hex|fernet|prefixed|static, length, default, prefix, description }`; lesen `inputs.secrets.<key>.<name>`. `admin_password` erbt das Admin-Passwort.
11. Modul: keine `provider`-/`backend`-Blöcke, keine Variablen `k8s_config_path`/`k8s_context`, Helm-Provider `~> 2.0`, nur Ressourcen im Namespace `var.namespace`, keine `genai.govdigital.de/*`-Labels, Release-Name `${release_name_prefix}<key>`.
12. Images aus `registry.onstackit.cloud/govdigital/…` mit festem Tag; `image_pull_secrets` aus `inputs`.
13. Nie Zugangsdaten in `metadata.json`, `defaultValues` oder Klartext-Dateien.
14. Vor der Übergabe `pruefen.sh` aus der Vorlage ausführen; Ergebnis muss fehlerfrei sein.

## Begriffe {#begriffe}

| Begriff | Bedeutung |
|---|---|
| Umgebung | eine Installation der Plattform für einen Kunden, mit eigenem Namespace und eigenen Secrets |
| Stufe (Tier) | Ordner einer Umgebung, die nacheinander ausgerollt werden: `infrastructure`, `applications`, `ai-applications` |
| Katalog | Liste aller bestellbaren Apps in der Konsole, gepflegt vom Plattform-Team |
| Schlüssel | fester Name einer App im Katalog, z. B. `open-webui` |
| Sidecar | eine der `config.*`-Dateien; die Plattform legt sie in der Umgebung ab und führt sie zu `inputs` zusammen |
| `secrets.yaml` | mit SOPS verschlüsselte Secrets der Umgebung |
| Secret-Abgleich | Schritt, der Zugangsdaten verwalteter Datenbanken und Buckets in `secrets.yaml` schreibt |
| AI Hub | Startseite einer Umgebung mit Kacheln aller Apps |
| Partner | Organisation, die Umgebungen bestellt (z. B. AKDB, Dataport) |