Kubernetes in Eigenverwaltung - ABBYY Documentation

In diesem Leitfaden wird Vantage 3.0 selbstgehostet auf einem Kubernetes-Cluster bereitgestellt, den Sie selbst bereitstellen und betreiben. Er definiert die Schnittstellen, die Vantage vom Cluster benötigt, und verwendet Linkerd, Traefik und External Secrets mit HashiCorp Vault als Beispiele. Sie können auch gleichwertige Komponenten verwenden, die dieselben Anforderungen erfüllen. Dieser Leitfaden setzt einen betriebsbereiten Kubernetes-Cluster voraus. Kubernetes, das Service Mesh, den Ingress-Controller, das Secret-Management-System, Datenbanken, Speicher oder Registries installiert er nicht für Sie.

Die Charts vantage-operator und vantage-selfhosted müssen dieselbe Version verwenden. Die Beispiele auf dieser Seite verwenden für beide Charts die Version 0.70.13.

Referenzarchitektur

Aspekt	Vantage-Anforderung	Beispielimplementierung
Kubernetes	Eine unterstützte Kubernetes-Version mit funktionierendem DNS, Netzwerk und persistenten Volumes.	Ein von Ihnen betriebenes Kubernetes.
Deployment-Orchestrierung	ArgoCD mit aktivierten ApplicationSet Progressive Syncs.	ArgoCD 3.4.3.
Service Mesh	mTLS zwischen Workloads im Vantage-Namespace.	Linkerd.
Ingress	HTTPS-Ingress, das den Vantage-Pfad und die Rewrite-Vorgaben umsetzt und das ursprüngliche Anfrageprotokoll beibehält.	Traefik mit cert-manager.
Secrets	Native Kubernetes-`Secret`-Ressourcen im Vantage-Namespace.	External Secrets Operator, der Secrets aus HashiCorp Vault bereitstellt.
Datenbank	SQL Server oder PostgreSQL, jeweils mit einer separaten logischen Datenbank für jeden Vantage-Service.	PostgreSQL.
Cache	Redis.	Redis 7.4.
E-Mail	Standardmäßig SendGrid oder ein SMTP-Server.	SendGrid.
Speicher	Eine bereits vorhandene Kubernetes-`StorageClass`, die für Ihre Anforderungen an Verfügbarkeit und Beständigkeit geeignet ist.	Eine kundenseitig bereitgestellte persistente `StorageClass`.
Registries	Eine für Vantage-Artefakte bereitgestellte Quell-Registry und eine Ziel-Registry, die Sie betreiben.	Jede OCI-konforme private Registry.
Automatische Skalierung und Metriken	KEDA plus Prometheus, wenn die KEDA-Unterstützung aktiviert ist.	KEDA 2.17.3 und Prometheus Operator.

Unterstützte und getestete Komponentenversionen finden Sie unter Kompatibilität. Das vollständige Infrastrukturinventar und die Dimensionierungsgrundlage finden Sie unter Voraussetzungen.

Bevor Sie beginnen

Halten Sie die folgenden Werte und Ressourcen bereit:

Variable	Beschreibung
`$operator_namespace`	Namespace für den Vantage-Operator.
`$install_namespace`	Namespace für Vantage-Workloads.
`$operator_version`	Version des `vantage-operator`-Charts. Verwenden Sie `0.70.13` für diese Anleitung.
`$selfhosted_version`	Version des `vantage-selfhosted`-Charts. Verwenden Sie `0.70.13` für diese Anleitung.
`$charts_uri`	OCI-URI, die ABBYY für das Chart des Vantage-Operators bereitstellt.
`$chart_uri`	OCI-URI, die ABBYY für das Chart `vantage-selfhosted` bereitstellt.
`$release_name`	Helm-Release-Name für Vantage.
`$your_vantage_hostname`	DNS-Hostname für Vantage.
`$your_mailfrom`	Absenderadresse für ausgehende E-Mails.
`$your_platformadmin_email`	E-Mail-Adresse des anfänglichen Plattformadministrators.
`$your_oci_host`	Ziel-OCI-Registry, die Sie betreiben.
`$abbyy_oci_source_host`, `$abbyy_oci_source_repository`	Quell-Registry und -Repository, die für Vantage-Artefakte bereitgestellt werden.

Sie benötigen außerdem:

Einen DNS-Eintrag für $your_vantage_hostname, der auf Ihren Ingress-Einstiegspunkt verweist.
Ein gültiges TLS-Zertifikat für diesen Hostnamen.
Kubernetes-Registry-Pull-Secrets, wenn Ihre Registry eine Authentifizierung erfordert.
Jedes Anwendungs-Secret, das unter Secret aliases aufgeführt ist.
Einen eindeutigen logischen Datenbanknamen für jeden Datenbankalias. Der Migrator jedes Service erstellt seine Datenbank beim ersten Ausführen.
Knoten mit Labels für TechCore-Worker.

Cluster vorbereiten

ArgoCD konfigurieren

Installieren Sie ArgoCD und aktivieren Sie ApplicationSet Progressive Syncs. ArgoCD benötigt außerdem eine OCI-Repository-Verbindung, die die Vantage-Komponenten-Charts aus Ihrer Ziel-Registry abrufen kann. Registrieren Sie die Ziel-Registry als OCI-Helm-Repository, indem Sie die ArgoCD-Dokumentation zu privaten Repositories befolgen. Bewahren Sie die Registry-Zugangsdaten in Ihrem vorhandenen Secret-Management-System auf, anstatt die Zugangsdaten direkt in einem ArgoCD-Application-Manifest abzulegen.

Service Mesh konfigurieren

Vantage erfordert mTLS zwischen seinen Workloads. Installieren und betreiben Sie ein unterstütztes Service Mesh und aktivieren Sie anschließend die Mesh-Injektion für $install_namespace, bevor Sie Vantage installieren. Zum Beispiel mit Linkerd:

kubectl create namespace $install_namespace --dry-run=client -o yaml | kubectl apply -f -
kubectl label namespace $install_namespace linkerd.io/inject=enabled --overwrite

Vergewissern Sie sich, dass neu erstellte Test-Pods im Namespace den Mesh-Sidecar erhalten, bevor Sie fortfahren. Wenn Sie ein anderes Mesh verwenden, folgen Sie dem jeweiligen Injektionsverfahren auf Namespace- oder Workload-Ebene.

TechCore-Worker-Knoten konfigurieren

Für TechCore-Worker-Workloads werden Knoten mit dem folgenden Label ausgewählt:

kubectl label node <node-name> k8s.abbyy.com/techcore=true

Ohne mindestens einen geeigneten Knoten bleiben TechCore-Pods im Status Pending. Informationen zur Isolierung von Training-Workern und zur Dimensionierungsgrundlage finden Sie unter Kubernetes-Knotenanforderungen.

Persistenten Speicher konfigurieren

Erstellen oder wählen Sie eine StorageClass, bevor Sie Vantage installieren. Die Speicherimplementierung muss Ihre Anforderungen an Produktionsverfügbarkeit, Datenbeständigkeit, Kapazität, Erweiterbarkeit, Backup und Wiederherstellung erfüllen. Geben Sie sie in den Vantage-Werten an:

vantage:
  storage:
    custom:
      storageClass: <storage-class-name>
      size: 300Gi

Der Name StorageClass ist unabhängig von der Kubernetes-Distribution. Übernehmen Sie die lokale StorageClass eines Entwicklungsclusters nicht in die Produktion, ohne zuvor die Ausfall- und Failover-Eigenschaften zu bewerten.

Datenbanken vorbereiten

Vantage unterstützt SQL Server und PostgreSQL. Legen Sie den Provider genau wie gezeigt fest; der Wert berücksichtigt die Groß- und Kleinschreibung:

vantage:
  databaseProvider: PostgreSQL

Gültige Werte sind SqlServer und PostgreSQL. Ein Wert wie Postgresql oder PostgreSql kann zur Laufzeit fehlschlagen, weil er nicht mit dem Data-Provider-Namen der Anwendung übereinstimmt. Jeder Vantage-Service muss eine eigene logische Datenbank verwenden. Services führen ihre eigenen Migrationen aus, und wenn mehrere Services auf dieselbe Datenbank verweisen, geraten ihre Migrationszustände in Konflikt. Verwenden Sie die Datenbankübersicht unter Datenbankaliasen, um Datenbanknamen und Verbindungszeichenfolgen zu planen. Sie müssen die Datenbanken nicht manuell erstellen: Der Migrator des jeweiligen Service erstellt seine Datenbank beim ersten Start.

Reporting ist nur mit SQL Server verfügbar. Wenn Sie PostgreSQL verwenden, lassen Sie vantage.reportingEnabled auf false gesetzt.

PostgreSQL-Verbindungszeichenfolgen müssen einzeilig sein und dürfen weder führende noch nachgestellte oder eingebettete Zeilenumbruchzeichen enthalten.

Kubernetes Secrets vorbereiten

Der Provider für Kubernetes Secrets liest native Kubernetes-Secret-Ressourcen aus $install_namespace. Vantage stellt keine direkte Verbindung zu Vault oder einem anderen externen Speicher für Secrets her. Wenn Sie External Secrets Operator, einen CSI-Treiber oder ein anderes Synchronisierungstool verwenden, konfigurieren Sie es so, dass die erforderlichen Kubernetes Secrets vor der Installation von Vantage erstellt werden. Wählen Sie den Kubernetes-Provider aus:

vantage:
  secrets:
    kubernetes: {}

Standardmäßig verwendet Vantage die dokumentierten Secret-Namen. Verwenden Sie objects, um einem Alias ein anderes Secret zuzuordnen:

vantage:
  secrets:
    kubernetes:
      objects:
        authSigningTlsCrt:
          secretName: vantage-auth-signing
        authSigningTlsKey:
          secretName: vantage-auth-signing
        authDeactivatedTlsCrt:
          secretName: vantage-auth-deactivated
        authDeactivatedTlsKey:
          secretName: vantage-auth-deactivated
        subscriptionDatabaseConnectionString:
          secretName: vantage-db-subscriptions

Die beiden Authentifizierungsschlüsselpaare signieren Anwendungstoken. Sie sind getrennt von dem Zertifikat, das öffentliches HTTPS am Ingress-Controller terminiert. Unter Certificate aliases finden Sie die erforderlichen Schlüssel und Formate. Wenn mehrere Service den generischen Schlüssel Database__ConnectionString verwenden, erstellen Sie für jeden Service ein separates Secret und ordnen Sie jeden Datenbankalias über vantage.secrets.kubernetes.objects zu. Ihr Secret-Management-System kann diese Secrets aus einer gemeinsamen Connection-String-Vorlage ableiten, aber jede daraus erzeugte Connection-String muss eine andere Datenbank angeben.

Der Operator validiert die Secrets-Konfiguration bei der Vorabprüfung. Die aufeinander abgestimmten Charts vantage-operator und vantage-selfhosted gewähren dem Operator über eine ClusterRole Lesezugriff auf Secrets, die nur im Namespace des Vantage-Release gebunden ist. Wenn Sie den Operator-Namespace oder das Controller-ServiceAccount anpassen, achten Sie darauf, dass die entsprechenden operator-Werte im Vantage-Chart mit dieser Installation übereinstimmen. Eine benutzerdefinierte resourceNames-Einschränkung muss jedes Secret enthalten, auf das der Kubernetes-Provider verweist.

Registry-Zugriff konfigurieren

Der Registry-Zugriff hat drei getrennte Nutzer:

Consumer	Required access
Vantage operator	Das Operator-Image abrufen. Konfigurieren Sie `manager.imagePullSecrets` bei Bedarf.
OCI migration job	Das Job-Image abrufen, aus der Quell-Registry lesen und in die Ziel-Registry schreiben.
Vantage workloads and ArgoCD	Workload-Images und Komponenten-Charts aus der Ziel-Registry abrufen.

Erstellen Sie Registry-Secrets in dem Namespace, in dem der jeweilige Nutzer ausgeführt wird. Speichern Sie keine Registry-Kennwörter im Klartext in Ihrer Values-Datei. Geben Sie für die OCI-Migration die Secrets für die Anmeldedaten der Quell- und Ziel-Registry an:

vantage:
  ociMigration:
    enabled: true
    serviceAccountName: <vantage-service-account>
    imagePullSecrets:
      - name: <operator-image-pull-secret>
    sources:
      - host: <source-registry>
        repository: <source-repository>
        credentialsRef:
          name: <source-registry-credentials>
    destination:
      host: <destination-registry>
      credentialsRef:
        name: <destination-registry-credentials>

Fügen Sie das Pull-Secret der Ziel-Registry zu den imagePullSecrets des ServiceAccount hinzu, der durch vantage.serviceAccountName angegeben ist und als Standard-ServiceAccount für Vantage-Workloads dient.

Wenn ein Komponenten-Pod unter einem anderen ServiceAccount ausgeführt wird, benötigt auch dieser ServiceAccount Pull-Zugriff auf die Registry. Prüfen Sie den spec.serviceAccountName des Pods, bevor Sie den default-ServiceAccount des Namespace ändern.

Autoskalierung und Metriken konfigurieren

Die Unterstützung für KEDA ist optional, wird jedoch empfohlen. Verwenden Sie KEDA 2.17.3: In KEDA 2.18 und späteren Versionen wurde ein scaler-Feld entfernt, das von den aktuellen Vantage-Workload-Charts verwendet wird; daher können die erforderlichen HPAs nicht erstellt werden. Einige Vantage-ScaledObject-Ressourcen fragen Prometheus unter dieser festen Adresse ab:

http://prometheus-operated.observability.svc.cluster.local:9090

Bevor Sie KEDA aktivieren:

Installieren Sie KEDA 2.17.3.
Installieren Sie Prometheus Operator und eine Prometheus-Instanz im Namespace observability.
Vergewissern Sie sich, dass der zugehörige Service prometheus-operated heißt und Port 9090 verfügbar macht.
Konfigurieren Sie Prometheus so, dass es den ServiceMonitor von Vantage erkennt.

Aktivieren Sie KEDA für die Vantage-Ressource und aktivieren Sie den ServiceMonitor des Charts über den separaten observability-Abschnitt auf oberster Ebene:

vantage:
  keda:
    enabled: true

observability:
  prometheus:
    namespace: observability
    serviceMonitor:
      create: true

observability ist ein Top-Level-Schlüssel; verschachteln Sie ihn nicht unter vantage. Informationen zu Trigger-Strategien, Verifizierung und Kapazitätsplanung finden Sie unter Automatische Skalierung mit KEDA. Informationen zur mesh-spezifischen Scraping-Konfiguration finden Sie unter Überwachung mit Prometheus.

Ingress und TLS konfigurieren

Der im Chart integrierte Ingress ist für Istio gedacht. Wenn Sie Traefik oder einen anderen Ingress-Controller verwenden, deaktivieren Sie ihn:

ingress:
  enabled: false

Ihre Ingress-Konfiguration muss:

HTTPS für vantage.dnsRecord mit einem vertrauenswürdigen Zertifikat terminieren.
die Pfade für Vantage-UI, API, Authentifizierung, Hilfe, SCIM, URL-Shortener, Workspace, Verifizierung und Try Any Skill an die entsprechenden Services weiterleiten.
die von Vantage verwendeten Rewrites für /api/vN/ nach /publicapi/vN/, /api/, SCIM und Heartbeat anwenden.
spezifischere Routen vor der Catch-all-Route der UI abgleichen.
den ursprünglichen Host und das ursprüngliche Schema weiterleiten, einschließlich X-Forwarded-Proto: https, wenn TLS am Ingress-Controller terminiert wird.

Traefik setzt diese Anforderungen mit einer IngressRoute und geordneten Middleware-Ressourcen um. Behandeln Sie das Routenmanifest als versionierte Vantage-Konfiguration: Parametrisieren Sie den Hostnamen, den Namespace, das Zertifikats-Secret und die generierten Service-Namen für Ihr Release, anstatt Werte aus einer anderen Umgebung zu übernehmen.

Routing-Kontrakt

Ermitteln Sie die generierten Kubernetes-Service-Namen in $install_namespace und implementieren Sie dann diese Routen in der aufgeführten Reihenfolge. Regex- und exakte Routen müssen Vorrang vor Präfix- und Catch-all-Routen haben.

Öffentlicher Pfad	Vantage-Komponente	Umschreibung oder Verhalten
`^/api/v[0-9]+(/\|$)`	API-Gateway	`/api/vN/...` in `/publicapi/vN/...` umschreiben.
`^/verification/(markup\|manualreview)/<id>/notifications`	Verifizierung	Keine Umschreibung.
`^/workspace/(v1/files\|skilloperations/notifications\|projects/<id>/notifications\|skills/<id>/notifications\|catalogoperations/notifications)`	Workspace	Keine Umschreibung.
`/api/heartbeat/scenarios`	Heartbeat	In `/api/scenarios` umschreiben.
Exakt `/try-any-skill`	Try Any Skill	Dauerhaft nach `/try-any-skill/` umleiten.
`/try-any-skill/`	Try Any Skill	Keine Umschreibung.
`/ad/` und `/ss/`	AD-Frontend	Keine Umschreibung; verwenden Sie den Service-Port, der vom generierten Workload bereitgestellt wird.
`/auth2`	Auth Identity	Keine Umschreibung.
`/help`	Dokumentation	Keine Umschreibung.
`/scim/`	SCIM-Adapter	Das Präfix `/scim` entfernen.
`/surl`	URL-Verkürzer	Keine Umschreibung.
`/api` und `/api/`	API-Gateway	Das Präfix `/api` entfernen.
`/`	Vantage-Frontend	Catch-all-Route; zuletzt auswerten.

Der integrierte Istio-Ingress des Charts blockiert außerdem /api/status und /api/status/config, die interne Statusinformationen offenlegen, die Clients nicht benötigen. Das Blockieren dieser Pfade wird empfohlen, ist aber für den Betrieb von Vantage nicht erforderlich. Wenn Ihr Ingress-Controller keine direkte Ablehnungsantwort zurückgeben kann, können Sie diese Pfade vor der allgemeinen /api-Regel an ein dediziertes Deny-Backend weiterleiten.

Weitergeleitetes HTTPS-Schema

Wenn TLS an einem Ingress-Controller endet und die Backend-Verbindung über HTTP erfolgt, müssen die Vantage-Authentifizierungs-Services X-Forwarded-Proto auswerten. Stellen Sie sicher, dass die folgende Umgebungsvariable in den Anwendungs-Containern für auth-identity, auth-adminapi2, api-gateway und api-registry vorhanden ist:

ASPNETCORE_FORWARDEDHEADERS_ENABLED=true

Wenn die aktuellen Workload-Charts keine Überschreibung über eine Umgebungsvariable unterstützen, verwenden Sie Ihren üblichen Admission-Mutationsmechanismus, z. B. Kyverno oder einen vergleichbaren mutierenden Webhook. Wenden Sie die Mutation an, bevor Sie die Vantage-Pods erstellen. Andernfalls kann das OIDC-Discovery-Dokument http://-Endpoints ausweisen, und die Browser-Anmeldung schlägt fehl.

Installieren Sie den Operator

Installieren Sie eine Operator-Instanz im Cluster:

helm upgrade --install vantage-operator $charts_uri/vantage-operator \
  --version 0.70.13 \
  --namespace $operator_namespace \
  --create-namespace \
  --wait

Wenn für die Operator-Registry ein Pull-Secret erforderlich ist, fügen Sie diese Option vor --wait zum Befehl hinzu:

  --set "manager.imagePullSecrets[0].name=<operator-image-pull-secret>"

Vantage installieren

Erstellen Sie eine Datei mit den Werten, die die oben vorbereitete Konfiguration zusammenführt. Dieses gekürzte Beispiel zeigt die für Self-Managed spezifischen Werte; fügen Sie die vollständigen Secret-Zuordnungen und die Registry-Zugangsdaten für Ihre Umgebung hinzu:

operator:
  namespace: <operator-namespace>

ingress:
  enabled: false

vantage:
  dnsRecord: <vantage-hostname>
  mailFrom: <sender-email>
  platformAdminEmail: <platform-admin-email>
  serviceAccountName: <vantage-service-account>
  databaseProvider: PostgreSQL
  reportingEnabled: false
  updatePolicy:
    manual: {}

  secrets:
    # Fügen Sie ein objects-Mapping hinzu, wenn Ihre Secret-Namen von den Standardnamen abweichen.
    kubernetes: {}

  storage:
    custom:
      storageClass: <storage-class-name>
      size: 300Gi

  keda:
    enabled: true

  ociMigration:
    enabled: true
    serviceAccountName: <vantage-service-account>
    imagePullSecrets:
      - name: <operator-image-pull-secret>
    sources:
      - host: <source-registry>
        repository: <source-repository>
        credentialsRef:
          name: <source-registry-credentials>
    destination:
      host: <destination-registry>
      credentialsRef:
        name: <destination-registry-credentials>

observability:
  prometheus:
    namespace: observability
    serviceMonitor:
      create: true

Installieren Sie das passende vantage-selfhosted-Chart:

helm upgrade --install $release_name $chart_uri/vantage-selfhosted \
  --version 0.70.13 \
  --namespace $install_namespace \
  --create-namespace \
  --values values-self-managed.yaml \
  --wait

Nachdem der Operator die Workload-Services erstellt hat, wenden Sie Ihre Ingress-Controller-Konfiguration an und prüfen Sie, ob das TLS-Zertifikat bereit ist.

Installation überwachen

Warten Sie, bis die Custom-Resource den Status Ready meldet:

kubectl -n $install_namespace wait \
  --for=condition=Ready vantages.vantage.abbyy.com/$release_name \
  --timeout=30m

Prüfen Sie anschließend die generierten ArgoCD-Anwendungen und Workloads. Verlassen Sie sich nicht nur auf Ready:

argocd app list -l vantage.abbyy.com/managed-by=vantage-operator
kubectl -n $install_namespace get pods
kubectl -n $install_namespace get scaledobjects,hpa

Wenn die OCI-Migration aktiviert ist, überwachen Sie sie gesondert:

kubectl -n $install_namespace wait --for=create job/$release_name-oci-migration --timeout=2m
kubectl -n $install_namespace wait --for=condition=Complete job/$release_name-oci-migration --timeout=20m

Die Skill-Installation wird in einem separaten Job ausgeführt und kann auch dann noch weiterlaufen, nachdem Vantage Ready meldet:

kubectl -n $install_namespace wait --for=create job/$install_namespace-skill-installer-job
kubectl -n $install_namespace wait --for=condition=Complete job/$install_namespace-skill-installer-job

Bestätigen Sie abschließend Folgendes:

Jede generierte ArgoCD-Anwendung ist Synced und Healthy.
Die Vantage-Pods laufen und sind mesh-injiziert.
Prometheus meldet die Vantage-/metrics-text-Targets als UP.
KEDA-ScaledObject-Ressourcen sind Ready, und die HPA-Metrikwerte sind nicht <unknown>.
Das OIDC-Discovery-Dokument und die Browser-Weiterleitungen verwenden https://-URLs.
Vantage ist unter https://$your_vantage_hostname verfügbar.

Wie geht es weiter

Secrets

Kubernetes-Secret-Aliase, Schlüsselpaare für die Authentifizierung und Datenbank-Verbindungsstrings.

Überwachung

Konfigurieren Sie Prometheus so, dass Metriken von Vantage über das Service Mesh abgerufen werden.

Fehlerbehebung

Diagnostizieren Sie Ausfälle von Operator, Datenbank, Registry, Ingress und Autoskalierung.

Upgrade

Aktualisieren Sie den Operator und die Vantage Charts gemeinsam.

​Referenzarchitektur

​Bevor Sie beginnen

​Cluster vorbereiten

​ArgoCD konfigurieren

​Service Mesh konfigurieren

​TechCore-Worker-Knoten konfigurieren

​Persistenten Speicher konfigurieren

​Datenbanken vorbereiten

​Kubernetes Secrets vorbereiten

​Registry-Zugriff konfigurieren

​Autoskalierung und Metriken konfigurieren

​Ingress und TLS konfigurieren

​Routing-Kontrakt

​Weitergeleitetes HTTPS-Schema

​Installieren Sie den Operator

​Vantage installieren

​Installation überwachen

​Wie geht es weiter

Secrets

Überwachung

Fehlerbehebung

Upgrade

Referenzarchitektur

Bevor Sie beginnen

Cluster vorbereiten

ArgoCD konfigurieren

Service Mesh konfigurieren

TechCore-Worker-Knoten konfigurieren

Persistenten Speicher konfigurieren

Datenbanken vorbereiten

Kubernetes Secrets vorbereiten

Registry-Zugriff konfigurieren

Autoskalierung und Metriken konfigurieren

Ingress und TLS konfigurieren

Routing-Kontrakt

Weitergeleitetes HTTPS-Schema

Installieren Sie den Operator

Vantage installieren

Installation überwachen

Wie geht es weiter