Quick Start

Diese Anleitung bringt eine vollständige Plattform zum Laufen – Datenspeicher, ein LiteLLM Gateway, Langfuse-Observability und die LibreChat-Chat-App – auf einem Cluster, auf dem der Operator bereits installiert ist. Sie läuft ohne Lizenz (die Community-Edition); mit einer Lizenz verdrahten sich die Chat-App und das Tracing selbst.

Alles kann auf einmal angewendet werden: Jede Ressource wird Ready, sobald die von ihr referenzierten Ressourcen es sind, und der Operator stellt die Verarbeitung zurück, während er wartet.

Verwenden Sie den mitgelieferten funktionierenden Satz

Das Repository liefert genau diese Manifeste unter config/samples/quickstart/. Ersetzen Sie jedes REPLACE_ME in secrets.yaml und führen Sie dann aus:

bash

kubectl apply -k config/samples/quickstart/

config/samples/*.yaml enthält ein Referenzbeispiel pro Ressourcenart mit weiteren Optionen (Vault, Wäg, Guardrails, Stacks, …); diese sind Beispiele zum Kopieren, kein Satz, der als Ganzes angewendet wird.

0. Namespaces

yaml

apiVersion: v1
kind: Namespace
metadata: { name: forge-data }
---
apiVersion: v1
kind: Namespace
metadata: { name: forge-gateway }
---
apiVersion: v1
kind: Namespace
metadata: { name: forge-langfuse }
---
apiVersion: v1
kind: Namespace
metadata: { name: forge-ui }

1. (Optional) Eine Lizenz anwenden

Ohne Lizenz läuft die Plattform als die Community-Edition (eine Instanz pro Typ, manuelles Wiring). Um Multi-Instance und auto-wiring zu aktivieren, laden Sie Ihre Lizenz aus dem Kundenportal unter portal.navique.dev herunter (oder starten Sie eine Testversion) und erstellen Sie anschließend das Lizenz-Secret und eine License:

bash

kubectl -n navique-system create secret generic navique-license \
  --from-file=license=./license.lic

yaml

apiVersion: core.navique.com/v1alpha1
kind: License
metadata:
  name: cluster            # singleton — must be named "cluster"
spec:
  secretRef:
    name: navique-license
    key: license
    namespace: navique-system

Siehe Lizenz verwalten.

2. Anmeldedaten

Die Workloads lesen einfache Kubernetes-Secrets – es muss nichts weiter installiert werden. Ersetzen Sie jedes REPLACE_ME:

yaml

# Plain Kubernetes Secrets: nothing else to install. Replace every REPLACE_ME.
# In production, have a SecretsManagement (Vault, Azure Key Vault, …) produce
# these instead and set the workloads' secretsRef.

# The model provider key(s) the gateway uses (models[].refSecretKey).
apiVersion: v1
kind: Secret
metadata: { name: model-credentials, namespace: forge-gateway }
stringData:
  OPENAI_API_KEY: REPLACE_ME
---
# Credentials for Langfuse's object storage. object-storage.yaml starts a small
# MinIO with these; with your own S3, put its access keys here.
apiVersion: v1
kind: Secret
metadata: { name: langfuse-s3, namespace: forge-langfuse }
stringData:
  access-key-id: forge-langfuse
  secret-access-key: REPLACE_ME_min_8_chars
---
# Only used WITHOUT a licence: the key the chat app sends to the gateway.
# Create a key in the gateway's LiteLLM admin UI and paste it here. With the
# auto-wiring licence the operator mints and injects a key itself and ignores
# this Secret.
apiVersion: v1
kind: Secret
metadata: { name: chat-gateway-key, namespace: forge-ui }
stringData:
  LITELLM_API_KEY: REPLACE_ME

Anmeldedaten aus einem Vault

Lassen Sie in Produktion eine SecretsManagement diese Secrets aus HashiCorp Vault, Azure Key Vault oder einem beliebigen External-Secrets-Provider erzeugen, und setzen Sie die optionale secretsRef der Workloads darauf.

3. Object Storage für Langfuse

Langfuse v3 benötigt Object Storage. Zur Evaluierung genügt ein MinIO mit einer Replica:

yaml

# EVALUATION ONLY: a single-replica MinIO (no redundancy, ephemeral storage) so
# Langfuse v3 has the object storage it requires. In production, use your own
# S3 / Azure Blob / GCS and drop this file (see observability.yaml).
apiVersion: apps/v1
kind: Deployment
metadata: { name: minio, namespace: forge-langfuse }
spec:
  replicas: 1
  selector: { matchLabels: { app: minio } }
  template:
    metadata: { labels: { app: minio } }
    spec:
      containers:
        - name: minio
          image: quay.io/minio/minio:latest
          args: ["server", "/data"]
          env:
            - { name: MINIO_ROOT_USER, valueFrom: { secretKeyRef: { name: langfuse-s3, key: access-key-id } } }
            - { name: MINIO_ROOT_PASSWORD, valueFrom: { secretKeyRef: { name: langfuse-s3, key: secret-access-key } } }
          ports: [ { containerPort: 9000 } ]
          volumeMounts: [ { name: data, mountPath: /data } ]
      volumes: [ { name: data, emptyDir: {} } ]
---
apiVersion: v1
kind: Service
metadata: { name: minio, namespace: forge-langfuse }
spec:
  selector: { app: minio }
  ports: [ { port: 9000, targetPort: 9000 } ]
---
# Creates the bucket Langfuse writes to.
apiVersion: batch/v1
kind: Job
metadata: { name: minio-bucket, namespace: forge-langfuse }
spec:
  backoffLimit: 20
  template:
    spec:
      restartPolicy: OnFailure
      containers:
        - name: mc
          image: quay.io/minio/mc:latest
          env:
            - { name: AK, valueFrom: { secretKeyRef: { name: langfuse-s3, key: access-key-id } } }
            - { name: SK, valueFrom: { secretKeyRef: { name: langfuse-s3, key: secret-access-key } } }
          command: ["sh", "-c", "mc alias set local http://minio.forge-langfuse.svc:9000 \"$AK\" \"$SK\" && mc mb --ignore-existing local/langfuse"]

Entfernen Sie dies in Produktion und lassen Sie blob (Schritt 6) auf Ihren eigenen S3, Azure Blob Storage oder Google Cloud Storage zeigen – siehe Observability.

4. Datenspeicher

yaml

# The shared datastores, sized for evaluation (one replica each). Each consumer
# gets its own logical database. Without the auto-wiring licence the databases
# must be declared here; with it, a datastore also creates the databases its
# referencing workloads ask for.
apiVersion: core.navique.com/v1alpha1
kind: PostgresCluster
metadata: { name: forge-pg, namespace: forge-data }
spec:
  type: cnpg
  mode: managed
  managed: { instances: 1, storageSize: 5Gi }
  databases:
    - { name: litellm }
    - { name: langfuse }
---
apiVersion: core.navique.com/v1alpha1
kind: ClickHouseCluster
metadata: { name: forge-ch, namespace: forge-data }
spec:
  type: clickhouse
  mode: managed
  databases:
    - { name: langfuse }
---
apiVersion: core.navique.com/v1alpha1
kind: RedisInstance
metadata: { name: forge-redis, namespace: forge-data }
spec:
  type: ot-container-kit
  mode: managed
  managed: { topology: standalone, storageSize: 1Gi }
---
# The chat app's conversation store and search index live next to it.
apiVersion: core.navique.com/v1alpha1
kind: MongoCluster
metadata: { name: forge-mongo, namespace: forge-ui }
spec:
  type: mck
  mode: managed
  managed: { members: 1, version: "8.0.4", storageSize: 5Gi }
  databases:
    - { name: LibreChat }
---
apiVersion: core.navique.com/v1alpha1
kind: MeilisearchInstance
metadata: { name: forge-meili, namespace: forge-ui }
spec:
  type: meilisearch
  mode: managed
  managed: { storageSize: 1Gi }

Kein Block-Storage vorhanden oder möchten Sie Ihren eigenen mitbringen?

Setzen Sie mode: external und geben Sie eine connectionSecretRef an, oder verwenden Sie mode: adopt, um auf einen bereits von Ihnen betriebenen Datenspeicher zu verweisen. Siehe die Referenzseite der jeweiligen Ressource.

5. Das Gateway

yaml

# The LiteLLM gateway. Model keys come from the model-credentials Secret.
apiVersion: core.navique.com/v1alpha1
kind: Gateway
metadata: { name: gateway, namespace: forge-gateway }
spec:
  database:
    mode: postgresCluster
    postgresClusterRef: { name: forge-pg, namespace: forge-data }
    databaseName: litellm
  instance:
    replicas: 1
    masterKey: { autoGenerate: true }
    saltKey: { autoGenerate: true }
  # Traces to Langfuse — wired automatically with the auto-wiring licence.
  observabilityRef: { name: observability, namespace: forge-langfuse }
  models:
    - name: gpt-4o-mini
      modelName: gpt-4o-mini
      model: openai/gpt-4o-mini
      refSecretKey: OPENAI_API_KEY

6. Observability (Langfuse)

yaml

# Langfuse v3 on the shared datastores. The first person to sign up becomes its
# administrator (set langfuse.bootstrap to seed an admin, org and API keys).
apiVersion: core.navique.com/v1alpha1
kind: Observability
metadata: { name: observability, namespace: forge-langfuse }
spec:
  type: langfuse
  langfuse:
    postgres: { mode: ref, ref: { name: forge-pg, namespace: forge-data }, databaseName: langfuse }
    clickhouse: { mode: ref, ref: { name: forge-ch, namespace: forge-data }, databaseName: langfuse }
    redis: { mode: ref, ref: { name: forge-redis, namespace: forge-data } }
    blob:
      provider: s3
      s3:
        bucket: langfuse
        region: us-east-1
        endpoint: http://minio.forge-langfuse.svc:9000
        forcePathStyle: true
        credentialsSecretRef: { name: langfuse-s3 }

7. Die Chat-App (LibreChat)

yaml

# LibreChat. With the auto-wiring licence, gatewayRef is enough: the operator
# mints a gateway key and fills the model list. Without it, the chat app uses the
# gateway address and key below (secrets.yaml: chat-gateway-key).
apiVersion: core.navique.com/v1alpha1
kind: ChatUI
metadata: { name: forge-ui, namespace: forge-ui }
spec:
  gatewayRef: { name: gateway, namespace: forge-gateway }
  gateway:
    url: http://gateway.forge-gateway.svc.cluster.local:4000/v1
    apiKeySecretRef: { name: chat-gateway-key, key: LITELLM_API_KEY }
  models: [ gpt-4o-mini ]
  mongo: { mode: ref, ref: { name: forge-mongo }, databaseName: LibreChat }
  meilisearch: { mode: ref, ref: { name: forge-meili } }

Mit einer Lizenz und gatewayRef erzeugt der Operator einen Gateway-Key für die Chat-App und injiziert die Gateway-Adresse selbst. Ohne Lizenz verwendet die Chat-App gateway.{url, apiKeySecretRef} – siehe Auto-Wiring.

8. Die Konvergenz beobachten

bash

# Datastores
kubectl -n forge-data get postgrescluster,clickhousecluster.core.navique.com,redisinstance
kubectl -n forge-ui   get mongocluster,meilisearchinstance

# Workloads
kubectl -n forge-gateway  get gateway
kubectl -n forge-langfuse get observability
kubectl -n forge-ui       get chatui

# Drill into a resource's conditions if something is pending
kubectl -n forge-gateway describe gateway gateway

Jede Ressource meldet Ready, sobald ihre Abhängigkeiten verfügbar sind; ihre Conditions geben genau an, worauf sie wartet.

9. Die Plattform erreichen

In diesem Satz wird nichts außerhalb des Clusters bereitgestellt; leiten Sie einen Port weiter, um es auszuprobieren:

bash

kubectl -n forge-ui port-forward svc/forge-ui-librechat 3080:3080         # chat app → http://localhost:3080
kubectl -n forge-langfuse port-forward svc/observability-web 3000:3000   # Langfuse → http://localhost:3000

Wählen Sie das Modell in der Chat-App aus und chatten Sie – Anfragen fließen durch das Gateway, und (mit einer Lizenz) erscheinen Traces in Langfuse. Um sie zu veröffentlichen, setzen Sie ingress auf den Ressourcen – siehe die Referenzseite der jeweiligen Ressource.

Aufräumen

Das Löschen einer Ressource löst ihren Finalizer aus: emittierte Upstream-CRs und eigene Helm- Releases werden entfernt, und jeder vom Operator installierte Capability-Operator wird deinstalliert, sobald nichts anderes ihn mehr benötigt. Adoptierte und externe Ressourcen werden nie angetastet. Siehe Provenance & Lebenszyklus.

bash

kubectl delete -k config/samples/quickstart/

Quick Start ​

0. Namespaces ​

1. (Optional) Eine Lizenz anwenden ​

2. Anmeldedaten ​

3. Object Storage für Langfuse ​

4. Datenspeicher ​

5. Das Gateway ​

6. Observability (Langfuse) ​

7. Die Chat-App (LibreChat) ​

8. Die Konvergenz beobachten ​

9. Die Plattform erreichen ​

Aufräumen ​

Quick Start

0. Namespaces

1. (Optional) Eine Lizenz anwenden

2. Anmeldedaten

3. Object Storage für Langfuse

4. Datenspeicher

5. Das Gateway

6. Observability (Langfuse)

7. Die Chat-App (LibreChat)

8. Die Konvergenz beobachten

9. Die Plattform erreichen

Aufräumen