Dokumentation

Vorbereitung für die Verwendung von InSpire-Snapshots in einer CI/CD-Umgebung

Einführung

Mithilfe von Mindbreeze InSpire Snapshots können Sie Änderungen an Ihrer Appliance vornehmen, ohne diese Änderungen direkt am Produktivsystem durchführen zu müssen:

1. Die Implementierung der Änderungen erfolgt ausschließlich am Entwicklungssystem
2. Nach der Erstellung eines Development-Snapshots lässt sich dieser mithilfe Ihrer CI/CD-Pipeline automatisiert auf die Testumgebung anwenden und testen
3. Nach erfolgreichen Tests, erfolgt das Deployment des Snapshots am Produktivsystem.

Sie haben dabei folgende Vorteile:

• Einfache Einbindung in eine externe CI/CD-Pipeline mithilfe der Mindbreeze InSpire SnapshotService API
• Kein manueller Eingriff mehr am Test- und Produktivsystem notwendig
• Änderungen können in einem Repository als Datei (Snapshot-Archiv) abgelegt und versioniert werden. Diese Änderungen sind somit
  • reproduzierbar
  • nachvollziehbar
  • revisionssicher

In dieser Dokumentation finden Sie Informationen zu den Snapshots im Allgemeinen und darüber, welche Voraussetzungen für die Nutzung der API erfüllt sein müssen. Danach wird unser Java SDK-Beispiel kurz vorgestellt. Anschließend lernen Sie den Unterschied zwischen "Migration-Snapshots" und "Development-Snapshots" kennen und erfahren, wie Sie diese korrekt verwenden.

Anwendungsbereiche und Einschränkungen

Authentifizierung

SAML-Authentifizierung wird derzeit unterstützt. Für weitere Einzelheiten siehe: Einstellungen für Client Service und SAML-Authentifizierung

Cluster-Umgebungen: Master- und Standby-Appliance

Importierte Snapshots auf der Master-Appliance werden gemäß dem Synchronisierungszeitplan mit der Standby-Appliance synchronisiert. Die External URL des Client-Service muss auf die Standby-Appliance zeigen. Für weitere Details siehe: Einstellungen für Client Service und SAML-Authentifizierung und Ändern der Einstellungen für Client Service und SAML-Authentifizierung.

Allgemeine Informationen, Anforderungen und Voraussetzungen

In Snapshots enthaltene Daten

Benutzerdefinierte Connector Plugins

Hinzugefügte oder aktualisierte Custom Connector Plugins auf der Development Appliance sind in exportierten Migration-Snapshots und Development-Snapshots enthalten und können auf der Development Appliance importiert werden. Für weitere Details siehe: Plugin via „Upload“ hinzufügen

Insight Apps

Hinzugefügte oder aktualisierte Insight Apps auf der Development Appliance sind in exportierten Migration-Snapshots und Development-Snapshots enthalten und können auf der Development Appliance importiert werden. Für weitere Details siehe: Hinzufügen einer benutzerdefinierten Insight App

Credentials und Endpoints

Credentials und Endpoints auf der Development Appliance sind nur in exportierten Migration-Snapshots enthalten und können auf der Development Appliance importiert werden. Development-Snapshots enthalten keine Credentials oder Endpoints.

InSpire Admin API OAuth Authentication

Der Zugriff auf die Mindbreeze InSpire Admin API auf /api/v3/admin und den Mindbreeze InSpire-Blob-Store zum Herunterladen exportierter Snapshot-Archive (/blobs/v3/snapshotarchives) erfordert eine OAuth Bearer Token Authentifizierung unter Verwendung eines Service-Benutzers mit der Rolle InSpire-Administrator.

Das OAuth-Token kann über den Token-Endpoint /auth/realms/master/protocol/openid-connect/token unter Verwendung der angegebenen OAuth-Client-ID und Secret zusammen mit den Anmeldedaten des Service-Benutzers bezogen werden.

Client ID und Client Secret

Wir empfehlen, einen eigenen OAuth Client für dieses Service zu schaffen. Dieser kann über das Mindbreeze InSpire Management Center konfiguriert werden. Hinweis: Die vorhandenen Mindbreeze Inspire Clients sollten nicht verwendet werden, da sie bei jedem Update überschrieben werden.

Navigieren Sie zu Setup/Credentials und wählen Sie den Abschnitt „Clients“. Fügen Sie einen neuen OAuth Client mit den folgenden Parametern hinzu:

• Client Protocol: openid-connect
• Access Type: confidential
• Valid Redirect URIs: /openidc/*

Fügen Sie nach dem Speichern des Clients die folgende Mapper-Konfiguration für die Bereitstellung der Benutzerrollen im Authentifizierungstoken hinzu:

• Name: role
• Mapper Type: User Realm Role
• Token Claim Name: roles

Erforderliche Service-Benutzerrollen

Der Service-Benutzer für Snapshot-Operationen benötigt die Rolle des InSpire-Administrators. Sie können einen dedizierten Service-Benutzer im Abschnitt „Users“ der Credentials-Konfiguration im Mindbreeze InSpire Management Center erstellen:

Stellen Sie im Abschnitt „Role Mappings“ der Benutzerkonfiguration sicher, dass die Rolle „InSpire Administrator“ dem erstellten Service-Benutzer zugeordnet ist.

Verwendung des Java SDK Beispiels

Das Java SDK-Beispielprojekt „SnapshotClient“ bietet ein einfaches Werkzeug für den folgenden Anwendungsfall:

• Erstellen eines Snapshots auf einer Mindbreeze InSpire-Appliance
• Exportieren des erstellten Snapshots als Snapshot-Archiv
• Herunterladen des Snapshot-Archivs
• Hochladen des Snapshot-Archivs auf eine Ziel-Appliance
• Das hochgeladene Archiv importieren und anwenden

Die aktuellste SDK kann auf www.mindbreeze.com/developer#quick-start herunterladen werden. Diese enthält unter anderem auch das Java SDK-Beispielprojekt „SnapshotClient“.

Projektstruktur

Das SDK-Beispielprojekt hat die folgende Struktur:

src

Ordner mit dem Java-Quellcode eines Command-Line-Tools zur Ausführung der erforderlichen API-Aufrufe:

• InSpireHTTPChannel.java: Implementierung des Netzwerkkommunikationskanals;
• Main.java: Main Klasse (Command Line Parameter Parsing und Ausführung der Befehle);
• OAuthManager.java: OAuth Login Manager;
• SnapshotClient.java: Wrapper für API Aufrufe;

lib

Ordner für die referenzierten Bibliotheken:

• messdk-generated.jar: ein dünner Wrapper, der generierte Klassen für die Zusammenarbeit mit der Snapshot-API verwendet.
• protobuf-java-3.0.jar: Google Protobuf-Bibliothek
• protobuf-java-util-3.12.3.jar: Google Protobuf-Bibliothek
• json-20200518.jar: JSON-Parsing-Tools für die OAuth-Authentifizierung (https://mvnrepository.com/artifact/org.json/json)

Bauen des Projekts

Das Bauen des Projekts erfordert Java JDK 8+ und Apache ANT 1.9.7+.

Das Beispielprojekt kann mit Apache Ant mit dem mitgelieferten build.xml gebaut werden. Führen Sie im Projektordner (in dem sich die build.xml befindet) den folgenden Befehl aus:

ant install

Dadurch wird das Projekt aufgebaut. Zusätzlich wird das JAR und die referenzierten JARs, die sich im Installationsordner befinden, in ein ZIP-Archiv verpackt.

Dieses ZIP-Archiv kann extrahiert werden. Anschließend kann das Tool ausgeführt werden und zeigt standardmäßig die Nutzungsinformationen an:

java -jar snapshot-client.jar

Initiales Deployment (Migration-Snapshot)

Ziel

Für den Aufbau der Infrastruktur (z.B. für Webserver-Zertifikate, Credentials, Frontend-Authentifizierung) ist ein auf der Development-Appliance erstellter Migration-Snapshot erforderlich. Mit dieser Dokumentation stellen wir Beispiele für die Verwendung des Confluence Connectors (Crawler und Principal Cache) und eines Client Service mit SAML zur Verfügung.

Einrichtung der Produktivumgebung

Stellen Sie auf der Production-Appliance sicher, dass die Mindbreeze InSpire-Lizenz installiert ist.

Konfiguration der Services für die Entwicklungsumgebung

Konfiguration der Confluence-Datenquelle

Überprüfen Sie, ob die folgenden Eigenschaften entsprechend der Entwicklungsumgebung korrekt konfiguriert sind:

• Crawling Root
• Login URL
• Form Elements

Denken Sie daran, dass dies die Konnektoreigenschaften sind, die entsprechend der Produktivumgebung geändert werden sollten, bevor ein erster Snapshot für die Produktivumgebung erstellt wird. (Siehe Anpassung der Version der Development-Appliance für Production).

Konfiguration des Confluence Principal Resolution Cache

Stellen Sie sicher, dass die „Confluence Server URL“ auf den Confluence-Server der Entwicklungsumgebung zeigt und im Tab „Network“ als „Endpoint“ konfiguriert ist. Das ausgewählte Credential sollte aus der Entwicklungsumgebung stammen. Wir werden diese Cache-Eigenschaften ändern, bevor wir einen Snapshot für die Produktivumgebung erstellen. (Siehe Anpassung der Version der Development-Appliance für Production).

Einstellungen für den Client Service und SAML-Authentifizierung

Laden Sie die SAML-IdP-Metadatendatei im Tab „Authentication“ aus der Entwicklungsumgebung zusammen mit dem bereits hochgeladenen SSL-Zertifikat in der Registerkarte „Certificates“ hoch.

Nach dem Hochladen wählen Sie „Use SAML Authentication“ für den konfigurierten Client Service.

Wie im Abschnitt Anpassung der Version der Development-Appliance für Production beschrieben, werden wir diesen Authentifikator und das SSL-Zertifikat entfernen und die IdP-Metadatendatei und das SSL-Zertifikat später aus der Produktivumgebung hochladen.

Konfigurieren Sie im Tab „Client Services“ die „External URL“ der Entwicklungsumgebung, die später auch geändert wird.

Jetzt kann ein SAML-Entitätsdeskriptor von https://inspire-dev.mycompany.com:8443/saml20/sp/entitiesdescriptor heruntergeladen und für die Konfiguration der vertrauenden Partei auf dem SAML-IdP-Server verwendet werden (weitere Einzelheiten zur SAML-Authentifizierung finden Sie in der folgenden Dokumentation: https://help.mindbreeze.com/de/index.php?topic=doc/SAML-Authentifizierung/index.htm).

Der obige Schritt wird nach Änderung des SSL-Zertifikats, der IdP-Metadaten und der external URL wiederholt, um den SAML-Entitätsdeskriptor für den IdP-Server der Produktionsumgebung zu erstellen.

Testen der Services der Entwicklungsumgebung

Nachdem Sie die Entwicklungsumgebung konfiguriert haben, stellen Sie bitte sicher, dass die Daten vom Confluence-Server der Entwicklungsumgebung indiziert sind und durchsucht werden können.

Erstellen des "Migration"-Snapshots der Development Appliance

Bevor wir die Konfiguration ändern, um einen Migration-Snapshot für die Production-Appliance zu erstellen, sollten wir einen Migration-Snapshot der Arbeitskonfiguration für die Development-Appliance als Backup mit dem mitgelieferten Snapshot-Tool erstellen. Die Development-Appliance sollte später mit diesem Snapshot wiederhergestellt werden.

java -jar snapshot-client.jar \

         --inspire-url="https://inspire-dev.mycompany.com:8443" \

         --client-id="" \

         --client-secret="" \

         --service-username="" \

         --service-user-password="" \

         --request-type=EXPORT \

         --json-request-file=create.json \

         --output-file=inspire-dev-appliance.snapshot

Die Datei create.json sollte ein vollständiges Migrationsprofil haben (APPLIANCE_MIGRATION):

{

  "name": "Dev Appliance Snapshot",

  "description": "Description",

  "options": {

    "profile": "APPLIANCE_MIGRATION"

  }

}

Anpassung der Version der Development-Appliance für Production

Ändern der Konfiguration der Confluence-Datenquelle

Die folgenden Eigenschaften sollten je nach Produktivumgebung geändert werden:

• Crawling Root
• Login URL
• Form Elements

Ändern der Konfiguration des Confluence Principal Resolution Cache

Das Feld „Confluence Server URL“ zeigt nun auf den Confluence-Server der Produktivumgebung und dieser wird im Tab „Network“ als „Endpoint“ konfiguriert. Der Endpoint und die Credentials aus der Entwicklungsumgebung sollten durch den Endpoint und den Credentials aus der Produktivumgebung ersetzt werden.

Ändern der Einstellungen für den Client Service und SAML-Authentifizierung

Deaktivieren Sie unter „Authentication“ das Kontrollkästchen „Use SAML Authentication“ und entfernen Sie den SAML Authenticator. Entfernen Sie anschließend im Tab „Certificates“ das SSL-Zertifikat.

Laden Sie im Tab „Certificates“ das SSL-Zertifikat der Produktivumgebung hoch; laden Sie dann im Tab „Authentication“ die SAML-IdP-Metadatendatei der Produktivumgebung zusammen mit diesem SSL-Zertifikat hoch.

Wählen Sie nach dem Hochladen „Use SAML Authentication“ mit dem neuen Authenticator für den Client Service aus.

Konfigurieren Sie am Tab „Client Services“ die „External URL“ der Produktivumgebung (in einer Cluster-Umgebung sollte es die Standby-Appliance-URL sein).

Der SAML-Entity-Descriptor für die Produktivumgebung kann unter https://inspire-dev.mycompany.com:8443/saml20/sp/entitiesdescriptor heruntergeladen und zur Konfiguration der vertrauenden Partei des SAML-IdP-Servers der Produktivumgebung verwendet werden (weitere Einzelheiten zur SAML-Authentifizierung finden Sie unter: https://help.mindbreeze.com/de/index.php?topic=doc/SAML-Authentifizierung/index.htm).

Erstellen des “Migration”-Snapshots für die Production-Appliance

Mit dem mitgelieferten Snapshot-Tool erstellen wir einen Snapshot der Development-Appliance für die Production-Appliance:

java -jar snapshot-client.jar \

         --inspire-url="https://inspire-dev.mycompany.com:8443" \

         --client-id="" \

         --client-secret="" \

         --service-username="" \

         --service-user-password="" \

         --request-type=EXPORT \

         --json-request-file=create.json \

         --output-file=inspire-prod-appliance.snapshot

Die Datei create.json sollte das vollständige Migrationsprofil haben (APPLIANCE_MIGRATION)

{

  "name": "Prod Appliance Snapshot",

  "description": "Description",

  "options": {

    "profile": "APPLIANCE_MIGRATION"

  }

}

Wiederherstellung der Development-Appliance

Nachdem wir den Migrations-Snapshot für die Production-Appliance erstellt haben, stellen wir die Development-Appliance wieder her, indem wir den Migrations-Snapshot importieren, der vor der Durchführung der Änderungen erstellt wurde.

java -jar snapshot-client.jar \

         --inspire-url="https://inspire-dev.mycompany.com:8443" \

         --client-id="" \

         --client-secret="" \

         --service-username="" \

         --service-user-password="" \

         --request-type=IMPORT \

         --input-file=inspire-dev-appliance.snapshot

Importieren des Snapshots auf die Production-Appliance

Die Anwendung des Migrations-Snapshots auf die Production-Appliance sollte durch Aufruf des Snapshot-Tools wie folgt durchgeführt werden:

java -jar snapshot-client.jar \

         --inspire-url="https://inspire-prod.mycompany.com:8443" \

         --client-id="" \

         --client-secret="" \

         --service-username="" \

         --service-user-password="" \

         --request-type=IMPORT \

         --input-file=inspire-prod-appliance.snapshot

Optional kann man mit dem Parameter disable-sync-tasks am Zielsystem, auf dem der Snapshot importiert wird, die Index- und Konfiguration-Synchronisation-Tasks deaktivieren. Nach erfolgreichen Tests können die Tasks manuell reaktiviert werden.

         --disable-sync-tasks

Parametrisierung der Konfiguration für den Development-Snapshot

Bevor wir die Development-Snapshots auf die Production-Appliance anwenden, ist es notwendig sicherzustellen, dass die Konfigurationseinstellungen, die sich auf die Produktivumgebung beziehen, nicht durch die Development-Snapshots überschrieben werden. Das bedeutet, dass beide Appliances den gleichen Satz von Environment Parameters mit unterschiedlichen Werten haben sollten. Neu eingeführte Environment Parameter in der Development-Appliance sollten beim Import von Development-Snapshots auf der Production-Appliance explizit definiert werden.

Beispielsweise sollten die folgenden Optionen als Environment Parameter konfiguriert werden:

• Confluence Data Source
  • Crawling Root
  • Login URL
  • Form Elements

• Confluence Principal Resolution Cache
  • Credentials Endpoint

• Client Service
  • External URL

Um die Environment Parameter verwenden zu können, muss das Feature zuerst aktiviert werden. Die Dokumentation dazu finden Sie hier: Konfiguration Mindbreeze InSpire – Parametrisierung Aktivieren/Deaktivieren.

Die Parametrisierung der Crawling Root kann wie folgt vorgenommen werden:

Die Login URL, die Form Elements (Confluence Datasource), der Credential Endpoint (Network Tab) und die External URL (Client Service) sollten mithilfe des obigen Parametrisierungsdialogs parametrisiert werden. Nach der Konfiguration der Environment Parameter sollte ein Migrations-Snapshot aus der Development-Appliance wie folgt exportiert werden.

java -jar snapshot-client.jar \

         --inspire-url="https://inspire-dev.mycompany.com:8443" \

         --client-id="" \

         --client-secret="" \

         --service-username="" \

         --service-user-password="" \

         --request-type=EXPORT \

         --json-request-file=create.json \

         --output-file=inspire-prod-appliance.snapshot

Die Datei create.json sollte das Migrationsprofil haben (APPLIANCE_MIGRATION):

{

  "name": "Prod Appliance Snapshot",

  "description": "Description",

  "options": {

    "profile": "APPLIANCE_MIGRATION"

  }

}

Der erstellte Migrations-Snapshot sollte auf die Production-Appliance importiert werden. Beim Importieren sollten die Snapshot-Parameter dem Snapshot-Tool in einer separaten import.json-Datei zur Verfügung gestellt werden:

java -jar snapshot-client.jar \

         --inspire-url="https://inspire-prod.mycompany.com:8443" \

         --client-id="" \

         --client-secret="" \

         --service-username="" \

         --service-user-password="" \

         --request-type=IMPORT \

         --json-request-file=import.json \

         --output-file=inspire-prod-appliance.snapshot

Die Datei import.json sollte entsprechend der Produktivumgebung für jeden Parameter einen Wert enthalten (z.B.: confluence_crawling_root):

{

   "importOptions": {

     "configurationParameters": {

        "confluence_crawling_root": "<prod_url>",

        "<other param name>": "<other param value>"     

      }

   }

}

Nach dem initialen Deployment können neu hinzugefügte Parameter nur über die import.json zur Production-Appliance hinzugefügt werden. Siehe: Hinzufügen von Funktionen zu Production (Development-Snapshot)

Das Hinzufügen von Crendentials, Endpoint und Zertifikaten auf der Production-Appliance nach dem initialen Deployment sollte in folgenden Schritten erfolgen:

1. Es sollte ein Migrations-Snapshot der Development-Appliance erstellt werden, um die Einstellungen der Development-Appliance zu sichern.
2. Auf der Production-Appliance sollte ein Migrations-Snapshot erstellt und auf der Development-Appliance importiert werden.
3. Konfigurationsänderungen an Credentials, Endpoints und Zertifikaten sollten an der Development-Appliance vorgenommen und getestet werden.
4. Auf der Development-Appliance sollte ein Migrations-Snapshot erstellt werden.
5. Der erstellte Migrations-Snapshot sollte wieder auf die Production-Appliance importiert werden.
6. Die Development-Appliance sollte aus dem anfänglichen Backup-Snapshot wiederhergestellt werden.

Hinzufügen von Funktionen zu Production (Development-Snapshot)

Hinzufügen von Metadaten, diese aggregierbar machen und Hinzufügen eines Filters zur Insight Apps

Konfigurieren Sie in der Development-Appliance folgendes:

• Konfigurieren Sie im Index Service die Precomputed Synthesized Metadata wie folgt:
  

• Konfigurieren Sie im Atlassian Confluence-Connector Extract Metadata wie unten dargestellt:
• 
  

• Machen Sie es aggregierbar
  

• Stellen Sie sicher, dass Sie die folgende Crawler-Konfigurationsoption deaktivieren:
  

• Im Client Service sollten Sie nun die folgenden Filter sehen:
  

• Fügen Sie die gefilterte Facette der Insight App im index.html hinzu:
  

• Im Client Service sollten Sie den folgenden Filter sehen (Breadcrumbs 2):
  

Erstellen Sie einen neuen Snapshot (Profile: DEVELOPMENT).

Importieren Sie den Development-Snapshot in die Production-Appliance, und starten Sie eine Re-Indizierung.

Öffnen Sie dann den Search-Client und Sie sollten den gleichen Filter (Breadcrumb2) sehen, wenn Sie nach ALL suchen.

Hinzufügen einer benutzerdefinierten Insight App

Fügen Sie in der Development-Appliance eine neue Insight App hinzu:

Konfigurieren Sie diese dann als „Additional Context“ im Client-Service:

Erstellen Sie einen neuen Snapshot (Profile: DEVELOPMENT) und wenden Sie ihn auf Production an. Die neue Insight App wird auch auf Production angewendet.

Lokale Dateien zurücksetzen

Fügen Sie zunächst eine Datei zu einer vorhandenen Insight App auf der Development-Appliance hinzu:

Fügen Sie außerdem eine weitere Datei zu einer vorhandenen Insight App auf der Production-Appliance hinzu:

Erstellen Sie einen neuen Snapshot (mit Profile: DEVELOPMENT) auf der Development-Appliance.

Importieren Sie den Development-Snapshot. Wenn die Option -reset im Befehl NICHT angegeben ist, sollten sowohl die in der Development als auch die in Production erstellte Dateien in der Insight App bei Produktion vorhanden sein:

Wenn jedoch die Option -reset im Befehl angegeben ist, wird nur die in der Development-Appliance erstellte Datei auf die Produktion angewendet.

Plugin via „Upload“ hinzufügen

Laden Sie auf der Development-Appliance ein benutzerdefiniertes oder ein Built-In Plugin hoch, z.B. MyCustomPlugin-20.4.1.243.zip):

Erstellen Sie einen neuen Snapshot (mit Profil: DEVELOPMENT) der Development Appliance.

Importieren Sie den Development-Snapshot in die Production-Appliance und Sie sollten dasselbe Plugin in der Auflistung sehen:

Production Credentials bleiben erhalten

Beim Anwenden eines Development-Snapshots, der Änderungen der Anmeldeinformationen (z. B. Benutzername oder Kennwort) enthält, werden die Anmeldeinformationen auf Production nicht geändert.

Production-Zertifikate bleiben erhalten

Das Anwenden eines Development-Snapshots, der Zertifikatsänderungen in der Produktivumgebung enthält, ändert die Zertifikate in Production nicht.

Resourcen in Production bleiben erhalten, mit Ausnahme von Query Relevance Boosting und Search Relevance Optionen

Änderungen von Ressourcen in Development Snapshots (z.B. Hinzufügen oder Löschen von Dateien unter /data/resources) werden nicht auf die Production-Ressourcen angewendet.

Auf die Produktivumgebung werden jedoch nur Änderungen von Query Relevance Boosting und Search Relevance Optionen angewendet (data/resources/relevance).