Secrets und Key Vault - ABBYY Documentation

Vantage 3.0 selbstgehostet liest beim Start jedes Pods alle Datenbank-Verbindungszeichenfolgen, API-Schlüssel und TLS-Zertifikate von einem Secrets-Provider; keiner dieser Werte ist in values.yaml-Dateien gespeichert. Zwei Provider werden unterstützt; pro Installation ist genau einer über vantage.secrets konfiguriert.

Unterstützte Provider

Provider	Helm-Wert	Beschreibung
Azure Key Vault	`vantage.secrets.azure`	Verwendet den Secrets Store CSI Driver mit dem Azure Key Vault-Provider. Der Operator erstellt pro Chart eine `SecretProviderClass`, und der Treiber bindet Secrets als Dateien in Pods ein.
Kubernetes Secrets	`vantage.secrets.kubernetes`	Verwendet vorhandene Kubernetes-`Secret`-Ressourcen direkt. Keine externe Secrets-Infrastruktur erforderlich.

Die beiden Provider verwenden dieselbe Secret-Alias-Konvention. Vantage-Workloads suchen Secrets anhand von Aliasen, unabhängig davon, woher die Werte stammen. Verwenden Sie das Alias-Inventar unten, um die Bereitstellung zu planen.

Azure Key Vault-Provider

vantage:
  secrets:
    azure:
      keyVaultName: mykeyvault
      tenantId: 00000000-0000-0000-0000-000000000000
      clientId: 00000000-0000-0000-0000-000000000000  # Client ID der UAMI mit Key Vault-Lesezugriff
      identityMode: workloadIdentity                   # workloadIdentity (Standard) | podIdentity | vmManagedIdentity

Identitätsmodi

Modus	Wie sich der CSI-Treiber authentifiziert
`workloadIdentity` (Standard)	Azure Workload Identity. Das ServiceAccount jedes Charts ist mit einer benutzerzugewiesenen verwalteten Identität (UAMI) föderiert, deren `clientId` hier angegeben wird. Diese UAMI muss Lesezugriff auf die Key-Vault-Objekte haben, die den von diesem Chart verwendeten Aliasen zugrunde liegen.
`podIdentity`	Legacy-AAD-Pod-Identity-Bindung. Dieser Modus ist kein getestetes Szenario; wenden Sie sich an Ihr ABBYY-Account-Team, bevor Sie sich darauf verlassen.
`vmManagedIdentity`	Eine VM-zugewiesene verwaltete Identität. Die Client ID der UAMI wird über `vantage.secrets.azure.userAssignedIdentityID` angegeben. Diese Identität muss Lesezugriff auf den Key Vault haben.

So funktioniert es

Vantage verwendet den Secrets Store CSI Driver mit dem Azure Key Vault Provider. Die SecretProviderClass jedes Charts wird als CSI-Volume in den verwendenden pod eingebunden, und dieses Mount veranlasst den Driver, die Werte in ein Kubernetes-Secret pro Chart zu synchronisieren (die secretObjects-Funktion der SPC), das der pod über envFrom und Volume-Mounts verwendet. Die Kette ist:

┌──────────────────────┐
│  Azure Key Vault     │  Vom Kunden bereitgestellte Secret-/Zertifikatsobjekte
└──────────┬───────────┘
           │ ① Lesen über konfigurierte Identität
           ▼
┌──────────────────────────────────────────────────┐
│  SecretProviderClass  (one per chart)            │  Vom Operator erstellt
│  alias → Key Vault objectName                    │
│  alias → key in the per-chart Kubernetes Secret  │
└──────────┬───────────────────────────────────────┘
           │ ② Befüllung durch Secrets Store CSI-Treiber
           ▼
┌──────────────────────────────────────────────────┐
│  Kubernetes Secret  (one per chart)              │  z. B. mail-helm-secrets
└──────────┬───────────────────────────────────────┘
           │ ③ envFrom (Umgebungsvariablen) und/oder volumeMounts (Dateien)
           ▼
┌──────────────────────────────────────────────────┐
│  Vantage pod                                     │
└──────────────────────────────────────────────────┘

Der Operator erstellt pro Chart eine SecretProviderClass (SPC), in der festgelegt wird, welche Key-Vault-Aliase das jeweilige Chart benötigt und wie jeder Alias einem Schlüssel in einem Kubernetes-Secret pro Chart zugeordnet wird.
Wenn ein Pod das Volume der SPC einhängt, authentifiziert sich der Secrets Store CSI driver mit der durch identityMode ausgewählten identity, ruft die benannten objects aus Key Vault ab und synchronisiert sie über die secretObjects-Funktion der SPC in ein Kubernetes-Secret pro Chart.
Der Pod des Charts verwendet das Secret pro Chart:
- Die meisten secrets werden über envFrom als environment variables geladen.
- Zertifikate (authSigningTlsCrt usw.) werden über volumeMounts zusätzlich als Dateien eingehängt (in der Regel unter /var/run/certs/).

Secret-Werte erscheinen im Kubernetes-Secret pro Chart und zur Runtime in der Umgebung des Pods; für kubectl get secret sind sie also nicht unsichtbar. Sie erscheinen jedoch nie in values.yaml, ArgoCD-Diffs oder Git, da der CSI driver sie beim Start des Pods befüllt. Der Secrets Store CSI driver und das Azure Key Vault provider plugin müssen vor Vantage im cluster installiert werden. Siehe Voraussetzungen.

Ressourcen pro Chart

Jedes Vantage-Chart, das Secrets verwendet, erhält einen eigenen Satz von Ressourcen:

Ressource	Namensmuster	Zweck
`SecretProviderClass`	`{chart}-secret-provider` (und `{chart}-migr-secret-provider` für Migrationsjobs)	Listet die Key Vault-Aliasse auf, die das Chart benötigt, und zeigt, wie sie dem Kubernetes-`Secret` des jeweiligen Charts zugeordnet werden.
`Secret`	`{chart}-secrets` (und `{chart}-migr-secrets`)	Wird vom CSI-Treiber befüllt und über `envFrom` in den Pod des Charts eingebunden.
Volume `Secret`s	`{chart}-secrets-volume-N`	Zusätzliche `Secret`s pro Chart für Inhalte, die als Dateien eingebunden werden müssen (z. B. Zertifikate).

Diese Aufteilung nach Charts sorgt dafür, dass der Zugriff auf Key Vault auf das notwendige Minimum beschränkt bleibt: Die SPC eines Charts verweist nur auf die Aliasse, die dieses Chart tatsächlich benötigt.

ServiceAccounts und Identitätsbereich

Der Operator erstellt oder annotiert keine ServiceAccount-Ressourcen. Jedes Chart bringt über die standardmäßigen Helm-Werte sein eigenes SA mit; der Kunde ist dafür verantwortlich, die ServiceAccounts der einzelnen Charts, die die SPCs einbinden, mit der benutzerzugewiesenen verwalteten Identität (UAMI) zu föderieren, deren clientId in vantage.secrets.azure.clientId angegeben ist. Diese Identität muss Lesezugriff auf die Key-Vault-Objekte haben, die den Aliasen der Charts zugrunde liegen.

Der Key-Vault-Zugriff und der Zugriff für Image-Pulls sind getrennte Themen, die denselben ServiceAccounts zugewiesen sein können. Die UAMI-Föderierung (auf dieser Seite) gewährt Leserechte für Secrets; sie authentifiziert keine Image-Pulls. Fügen Sie für Pulls den imagePullSecrets des ServiceAccount, der in vantage.serviceAccountName angegeben ist, ein Registry-Pull-Secret hinzu, oder gewähren Sie stattdessen AcrPull für die AKS-Kubelet-Identität. Siehe Zugriff für Image-Pulls.

Kubernetes-Secrets-Provider

vantage:
  secrets:
    kubernetes:
      # objects:                           # optional: Standard-Secret-Namen überschreiben
      #   sendgridApiKey:
      #     secretName: my-sendgrid-secret

Erstellen Sie die Secret-Ressourcen im Installations-Namespace, bevor Sie das Chart ausführen. Wenn objects nicht definiert ist, werden die Standardnamen für Secrets verwendet. Geben Sie eine objects-Zuordnung (secretName pro Alias) an, um auf Secrets mit abweichenden Namen zu verweisen. Dieser Provider erfordert weder den Secrets Store CSI driver noch einen Cloud-Schlüsseltresor. Die Werte werden direkt aus den Secret-Objekten im Cluster gelesen. Während der Vorabprüfung validiert der Operator die Secrets-Konfiguration. Die zugehörigen Operator- und Vantage-Charts installieren eine Secret-Reader-ClusterRole und binden sie ausschließlich im Vantage-Release-Namespace an das ServiceAccount des Operators. Wenn Sie den Zugriff auf Secrets über resourceNames einschränken, schließen Sie jeden Standardnamen und jeden überschriebenen Secret-Namen ein. Ein externes Secret-Management-System kann weiterhin Ihre maßgebliche Quelle bleiben. So kann External Secrets Operator beispielsweise Kubernetes-Secrets aus HashiCorp Vault materialisieren. Vantage verwendet nur die daraus entstehenden Kubernetes-Secrets und stellt keine direkte Verbindung zu External Secrets oder Vault her.

PostgreSQL und dienstspezifische Secrets

Setzen Sie vantage.databaseProvider: PostgreSQL, um PostgreSQL zu verwenden. Jeder Service muss eine Verbindungszeichenfolge erhalten, die eine eigene logische Datenbank angibt; bei gemeinsamer Nutzung derselben Datenbank kommt es zu Konflikten beim Migrationsstatus der Services. Einige Workloads lesen eindeutig benannte Schlüssel für Verbindungszeichenfolgen und können sich ein Secret teilen. Andere Workloads lesen den generischen Schlüssel Database__ConnectionString; erstellen Sie für jeden dieser Services ein separates Secret und ordnen Sie dessen Alias über vantage.secrets.kubernetes.objects zu:

vantage:
  databaseProvider: PostgreSQL
  reportingEnabled: false
  secrets:
    kubernetes:
      objects:
        subscriptionDatabaseConnectionString:
          secretName: vantage-db-subscriptions
        workspaceDatabaseConnectionString:
          secretName: vantage-db-workspace

Jedes zugeordnete Secret enthält denselben Schlüssel, aber eine andere Datenbankverbindungszeichenfolge:

apiVersion: v1
kind: Secret
metadata:
  name: vantage-db-subscriptions
  namespace: <install-namespace>
type: Opaque
stringData:
  Database__ConnectionString: "Host=<host>;Port=5432;Database=subscriptions;Username=<user>;Password=<password>;Ssl Mode=Require"

Verwenden Sie Ihr Secret-Management-System, um diese Secrets zu erstellen, ohne Anmeldedaten in die Versionsverwaltung einzuchecken. Verbindungszeichenfolgen müssen einzeilig sein und dürfen keine führenden, nachgestellten oder eingebetteten Zeilenumbrüche enthalten. Reporting ist nur mit SQL Server verfügbar. Lassen Sie reportingEnabled: false, wenn Sie PostgreSQL verwenden.

Secret-Aliasse

Die folgenden Aliasse bilden die verbindliche Schnittstelle zwischen Vantage-Workloads und Ihrem Secrets-Provider. Mit dem Azure-Provider ist es am einfachsten, Ihre Key Vault-Secrets so zu benennen, dass sie dem Alias entsprechen. Bei beiden Providern können Sie Namen jedoch über ein objects-Mapping in Ihrer Secrets-Konfiguration neu zuordnen.

Plattform

Alias	Beschreibung
`sendgridApiKey`†	API-Schlüssel für SendGrid. Erforderlich, sofern Sie nicht `spec.smtp` konfigurieren.
`redisConnectionString`	Verbindungszeichenfolge für Redis.
`redisCacheConnectionString`	Verbindungszeichenfolge für Redis-Cache / Sperren / client-Cache. `redisConnectionString` kann wiederverwendet werden.
`secretStorageUserKeyVaultUri`	URI des Azure Key Vaults, der zum Speichern von Secrets verwendet wird. Kann derselbe Vault oder ein separater sein (ein separater wird empfohlen).

Speicher

Nur erforderlich, wenn das Standard-Backend für Azure Blob Storage verwendet wird. Wenn spec.storage.custom für ein Backend konfiguriert ist, das auf einer Kubernetes-StorageClass basiert (zum Beispiel NFS), werden diese Aliasse nicht verwendet. Jeder Alias ist eine Verbindungszeichenfolge für ein Speicherkonto; Informationen dazu, wofür die einzelnen Speichertypen verwendet werden, finden Sie in der grundlegenden Vantage-Systemdokumentation.

Alias	Beschreibung
`storageArchiveConnectionString`	Verbindungszeichenfolge für das Speicherkonto (“Archiv”).
`storageLegacyTemporaryConnectionString`	Verbindungszeichenfolge für das Speicherkonto (“temporär (alt)”).
`storageTemporaryConnectionString`	Verbindungszeichenfolge für das Speicherkonto (“temporär”).
`storagePermanentConnectionString`	Verbindungszeichenfolge für das Speicherkonto (“permanent”).
`storageStandardConnectionString`	Verbindungszeichenfolge für das Speicherkonto (“Standard”).

Datenbanken

Verbindungszeichenfolgen, je eine pro separater Datenbank. Die Datenbanknamen dienen nur zur Veranschaulichung; jeder Name, den Ihr Bereitstellungsprozess erzeugt, ist zulässig, solange die Verbindungszeichenfolge auf die richtige Datenbank verweist.

Alias	Datenbank
`apiRegistryDatabaseConnectionString`	`apiregistry`
`auth2DatabaseConnectionString`	`auth`
`authIdentityDatabaseConnectionString`	`auth-identity`
`cronServiceDatabaseConnectionString`	`cron`
`documentSetStorageDatabaseConnectionString`	`documentset`
`mailDatabaseConnectionString`	`mail`
`securityAuditDatabaseConnectionString`	`security-audit`
`storageDatabaseConnectionString`	`storage`
`workflowDatabaseConnectionString`	`workflows`
`catalogStorageDatabaseConnectionString`	`catalogstorage`
`folderImportDatabaseConnectionString`	`folderimport`
`interactiveJobsDatabaseConnectionString`	`interactive-jobs`
`mailImportDatabaseConnectionString`	`mailimport`
`permissionsDatabaseConnectionString`	`permissions`
`reportingDatabaseConnectionString`	`reporting` (muss Columnstore-Indizierung unterstützen).
`secretStorageDatabaseConnectionString`	`secretstorage`
`skillInfoDatabaseConnectionString`	`skillinfo`
`skillMonitorDatabaseConnectionString`	`skillmonitor`
`subscriptionDatabaseConnectionString`	`subscriptions`
`tokenManagementDatabaseConnectionString`	`tokenmanagement`
`transactionsDatabaseConnectionString`	`transactions`
`urlShortenerDatabaseConnectionString`	`urlshortener`
`workspaceDatabaseConnectionString`	`workspace`

OAuth

Alias	Beschreibung
`oAuthGoogleClientId`	Google-Client-ID für OAuth.
`oAuthGoogleClientSecret`	Google-Client-Secret für OAuth.
`oAuthMicrosoftClientId`	Microsoft-Client-ID für OAuth.
`oAuthMicrosoftClientSecret`	Microsoft-Client-Secret für OAuth.

† sendgridApiKey ist nur erforderlich, wenn kein SMTP verwendet wird. Siehe Bekannte Einschränkungen.

Zertifikataliasse

Vier PEM-kodierte TLS-Artefakte sind erforderlich, die als zwei Paare von Secret-Aliasen bereitgestellt werden (Zertifikat + privater Schlüssel). Beim Azure-Provider speichern Sie sie als Key Vault-Secrets, nicht als Key Vault-Zertifikatobjekte:

Alias	Beschreibung
`authSigningTlsCrt`	PEM-kodiertes Zertifikat für die Auth-Signierung (aus dem Key Vault-Zertifikat `auth-signing`).
`authSigningTlsKey`	PEM-kodierter privater Schlüssel für die Auth-Signierung.
`authDeactivatedTlsCrt`	PEM-kodiertes Zertifikat für deaktivierte Auth-Token (aus dem Key Vault-Zertifikat `auth-deactivated`).
`authDeactivatedTlsKey`	PEM-kodierter privater Schlüssel für deaktivierte Auth-Token.

Beim Azure-Provider ist es am einfachsten, zwei selbstsignierte Zertifikate in Key Vault mit den Namen auth-signing und auth-deactivated zu erstellen (Common Name = Ihr Vantage-dnsRecord-Wert) und anschließend vier Key Vault-Secrets anzulegen, deren Namen den obigen Aliasen entsprechen. Beim Kubernetes-Provider erstellen Sie die Secret-Ressourcen mit dem PEM-Material vorab. Die Standard-Datenschlüssel sind auth-signing-tls-crt, auth-signing-tls-key, auth-deactivated-tls-crt und auth-deactivated-tls-key. Verwenden Sie ein objects-Mapping, um Secret-Namen neu zuzuordnen.

Benennung und Zuordnung

Beim Azure-Provider verwenden Aliase, die nicht in der objects-Zuordnung aufgeführt sind, den Alias selbst als Namen des Key Vault-Objekts (abgerufen als Typ secret). Wenn Ihre Key Vault-Objekte bereits so benannt sind, dass sie den Aliasen entsprechen, ist keine objects-Zuordnung erforderlich. Beim Kubernetes-Provider werden die Standardnamen der Secrets verwendet, wenn objects nicht definiert ist. Wenn Ihr Bereitstellungsprozess andere Namen verwendet, geben Sie in Ihrer Secrets-Konfiguration eine objects-Zuordnung an:

vantage:
  secrets:
    azure:
      # ...
      objects:
        sendgridApiKey:
          objectName: my-sendgrid-key            # Azure Key Vault-Objektname
        reportingDatabaseConnectionString:
          objectName: vantage-reporting-conn

vantage:
  secrets:
    kubernetes:
      objects:
        sendgridApiKey:
          secretName: my-sendgrid-secret         # Kubernetes Secret-Name
        reportingDatabaseConnectionString:
          secretName: my-reporting-secret

Der Alias ist durch den API-Vertrag festgelegt; den Objektnamen können Sie frei wählen.

Erforderliche Berechtigungen

Beim Azure Key Vault Provider muss die vom Secrets Store CSI driver verwendete Identität Lesezugriff auf jedes oben aufgeführte Secret und Zertifikat haben:

workloadIdentity (Standard): die benutzerzugewiesene verwaltete Identität, deren clientId in vantage.secrets.azure.clientId angegeben ist.
vmManagedIdentity: die Identität, deren Client ID in vantage.secrets.azure.userAssignedIdentityID angegeben ist.
podIdentity: kein getestetes Szenario; wenden Sie sich an Ihr ABBYY Account Team, bevor Sie diese Option verwenden.

Beim Kubernetes Secrets Provider sind keine Berechtigungen für Key Vault oder Cloud-Identitäten erforderlich. Erstellen Sie die Secret-Ressourcen vorab im Installations-Namespace; Vantage verwendet sie direkt.

Die Workload Identity für den CSI driver (hier) unterscheidet sich von der Workload Identity, die von anderen Workloads in Ihrem Cluster verwendet wird (zum Beispiel von einem In-mesh Prometheus, den Sie zur Überwachung bereitstellen; das Vantage-Installationsprogramm stellt Prometheus nicht bereit). Dabei kann dieselbe UAMI oder es können unterschiedliche UAMIs verwendet werden.

Nächste Schritte

Voraussetzungen

Anforderungen auf Cluster-Ebene und an externe Services für jede Installation.

Installation auf Azure

Azure Key Vault-Übersicht und die Schritt-für-Schritt-Installation.

Selbstverwaltetes Kubernetes

Native Kubernetes-Secrets und PostgreSQL-Konfiguration.

​Unterstützte Provider

​Azure Key Vault-Provider

​Identitätsmodi

​So funktioniert es

​Ressourcen pro Chart

​ServiceAccounts und Identitätsbereich

​Kubernetes-Secrets-Provider

​PostgreSQL und dienstspezifische Secrets

​Secret-Aliasse

​Plattform

​Speicher

​Datenbanken

​OAuth

​Zertifikataliasse

​Benennung und Zuordnung

​Erforderliche Berechtigungen

​Nächste Schritte

Voraussetzungen

Installation auf Azure

Selbstverwaltetes Kubernetes

Unterstützte Provider

Azure Key Vault-Provider

Identitätsmodi

So funktioniert es

Ressourcen pro Chart

ServiceAccounts und Identitätsbereich

Kubernetes-Secrets-Provider

PostgreSQL und dienstspezifische Secrets

Secret-Aliasse

Plattform

Speicher

Datenbanken

OAuth

Zertifikataliasse

Benennung und Zuordnung

Erforderliche Berechtigungen

Nächste Schritte