Konfigurieren von OSGi für Adobe Experience Manager as a Cloud Service configuring-osgi-for-aem-as-a-cloud-service

OSGi ist ein wesentlicher Bestandteil der Technologien von Adobe Experience Manager (AEM). OSGi wird zur Steuerung der AEM-Bundles und ihrer Konfigurationen verwendet.

OSGi bietet standardisierte Grundbausteine – kleine, wiederverwendbare, gemeinsame genutzte Komponenten. Diese Komponenten können zu einem Programm zusammengefügt und bereitgestellt werden. Dies ermöglicht die einfache Verwaltung von OSGi-Bundles, da diese einzeln angehalten, installiert und gestartet werden können. Die gegenseitigen Abhängigkeiten werden automatisch verwaltet. Jede OSGi-Komponente ist in einem der verschiedenen Bundles enthalten. Weitere Informationen finden Sie in der OSGi-Spezifikation.

Sie können die Konfigurationseinstellungen für OSGi-Komponenten mithilfe von Konfigurationsdateien verwalten, die Teil eines AEM-Code-Projekts sind.

OSGi-Konfigurationsdateien osgi-configuration-files

Konfigurationsänderungen werden in den Code-Paketen (ui.config) des AEM-Projekts als Konfigurationsdateien (.cfg.json) unter Ausführungsmodus-spezifischen Konfigurationsordnern definiert:

/apps/example/config.<runmode>

Das Format der OSGi-Konfigurationsdateien ist JSON-basiert und verwendet das im Apache Sling-Projekt definierte .cfg.json-Format.

OSGi-Konfigurationen zielen auf OSGi-Komponenten über ihre PID (Persistent Identity) ab, die standardmäßig den Java-Klassennamen der OSGi-Komponente verwendet. Um zum Beispiel eine OSGi-Konfiguration für einen von

com.example.workflow.impl.ApprovalWorkflow.java

implementierten OSGi-Service bereitzustellen, wird eine OSGi-Konfigurationsdatei unter

/apps/example/config/com.example.workflow.impl.ApprovalWorkflow.cfg.json

nach dem cfg.json OSGi-Konfigurationsformat definiert.

Ausführungsmodus-Auflösung runmode-resolution

Spezifische OSGi-Konfigurationen können mithilfe von Ausführungsmodi auf bestimmte AEM-Instanzen ausgerichtet werden. Um den Ausführungsmodus zu verwenden, erstellen Sie unter /apps/example (wobei „example“ Ihr Projektname ist) Konfigurationsordner im folgenden Format:

/apps/example/config.<author|publish>.<dev|stage|prod>/

Alle OSGi-Konfigurationen in diesen Ordnern werden verwendet, wenn die im config-Ordnernamen definierten Ausführungsmodi mit den von AEM verwendeten Ausführungsmodi übereinstimmen.

Wenn AEM beispielsweise die Ausführungsmodi „author“ und „dev“ verwendet, werden Konfigurationsknoten in /apps/example/config.author/ und /apps/example/config.author.dev/ angewendet, während Konfigurationsknoten in /apps/example/config.publish/ und /apps/example/config.author.stage/ nicht angewendet werden.

Wenn mehrere Konfigurationen für dieselbe PID anwendbar sind, wird die Konfiguration mit der höchsten Anzahl an passenden Ausführungsmodi angewendet.

Die Granularität dieser Regel liegt auf PID-Ebene. Es ist daher nicht möglich, für dieselbe PID einige Eigenschaften in /apps/example/config.author/ und spezifischere in /apps/example/config.author.dev/ zu definieren. Die Konfiguration mit der höchsten Anzahl von übereinstimmenden Ausführungsmodi ist für die gesamte PID wirksam.

Bei der lokalen Entwicklung wird ein Ausführungsmodus-Startparameter -r verwendet, um die OSGi-Konfiguration für den Ausführungsmodus anzugeben.

$ java -jar aem-sdk-quickstart-xxxx.x.xxx.xxxx-xxxx.jar -r publish,dev

Überprüfen der Ausführungsmodi

Ausführungsmodi von AEM as a Cloud Service sind basierend auf dem Umgebungstyp und Service klar definiert. Überprüfen Sie die vollständige Liste der verfügbaren Ausführungsmodi von AEM as a Cloud Service.

Die vom Ausführungsmodus bestimmten OSGi-Konfigurationswerte können wie folgt überprüft werden:

In der resultierenden Ansicht werden alle OSGi-Komponentenkonfigurationen für die ausgewählte(n) Ebene(n) mit den entsprechenden OSGi-Konfigurationswerten angezeigt. Diese Werte können mit den OSGi-Konfigurationswerten im Quellcode des AEM-Projekts unter /apps/example/osgiconfig/config.<runmode(s)> abgeglichen werden.

So überprüfen Sie, ob die entsprechenden OSGi-Konfigurationswerte angewendet werden:

Typen von OSGi-Konfigurationswerten types-of-osgi-configuration-values

Es gibt drei verschiedene OSGi-Konfigurationswerte, die mit Adobe Experience Manager as a Cloud Service verwendet werden können.

Auswählen des entsprechenden OSGi-Konfigurationswerttyps how-to-choose-the-appropriate-osgi-configuration-value-type

Normalerweise werden für OSGi Inline-OSGi-Konfigurationswerte verwendet. Umgebungsspezifische Konfigurationen werden nur für bestimmte Anwendungsfälle verwendet, in denen sich ein Wert zwischen Entwicklungsumgebungen unterscheidet.

Umgebungsspezifische Konfigurationen erweitern die traditionellen, statisch definierten OSGi-Konfigurationen, die Inline-Werte enthalten, und bieten die Möglichkeit, die OSGi-Konfigurationswerte extern über die Cloud Manager-API zu verwalten. Es ist wichtig zu verstehen, wann der übliche und traditionelle Ansatz zum Definieren und Speichern von Inline-Werten in Git verwendet werden sollte, anstatt die Werte in umgebungsspezifischen Konfigurationen zu abstrahieren.

In den folgenden Anleitungen wird beschrieben, wann nicht geheime und geheime umgebungsspezifische Konfigurationen verwendet werden müssen:

Verwendung von Inline-Konfigurationswerten when-to-use-inline-configuration-values

Inline-Konfigurationswerte werden als Standardansatz betrachtet und sollten nach Möglichkeit verwendet werden. Inline-Konfigurationen bieten folgende Vorteile:

Beginnen Sie bei der Definition eines OSGi-Konfigurationswerts mit Inline-Werten und wählen Sie nur geheime oder umgebungsspezifische Konfigurationen aus, wenn dies für den Anwendungsfall erforderlich ist.

Verwendung nicht geheimer umgebungsspezifischer Konfigurationswerte when-to-use-non-secret-environment-specific-configuration-values

Verwenden Sie nur umgebungsspezifische Konfigurationen ($[env:ENV_VAR_NAME]) für nicht geheime Konfigurationswerte, wenn die Werte für die Vorschauebene variieren oder in den Entwicklungsumgebungen variieren. Dazu gehören lokale Entwicklungsinstanzen und alle Entwicklungsumgebungen von Adobe Experience Manager as a Cloud Service. Vermeiden Sie außer zum Festlegen eindeutiger Werte für die Vorschauebene die Verwendung nicht geheimer umgebungsspezifischer Konfigurationen für Adobe Experience Manager as a Cloud Service-Staging- oder -Produktionsumgebungen.

Verwendung geheimer umgebungsspezifischer Konfigurationswerte when-to-use-secret-environment-specific-configuration-values

Adobe Experience Manager as a Cloud Service erfordert die Verwendung umgebungsspezifischer Konfigurationen ($[secret:SECRET_VAR_NAME]) für geheime OSGi-Konfigurationswerte wie Passwörter, private API-Schlüssel oder andere Werte, die aus Sicherheitsgründen nicht in Git gespeichert werden können.

Verwenden Sie geheime umgebungsspezifische Konfigurationen, um den Wert für Geheimnisse in allen Adobe Experience Manager as a Cloud Service-Umgebungen zu speichern, einschließlich Staging- und Produktionsumgebungen.

Erstellen von OSGi-Konfigurationen creating-osgi-configurations

Es gibt zwei Möglichkeiten, OSGi-Konfigurationen zu erstellen, wie unten beschrieben. Der erste Ansatz wird typischerweise für die Konfiguration von benutzerdefinierten OSGi-Komponenten verwendet, die dem Entwickler bekannte OSGi-Eigenschaften und -Werte haben, und der zweite für von AEM bereitgestellte OSGi-Komponenten.

Schreiben von OSGi-Konfigurationen writing-osgi-configurations

OSGi-Konfigurationsdateien im JSON-Format können manuell direkt im AEM-Projekt geschrieben werden. Dies ist häufig die schnellste Möglichkeit, OSGi-Konfigurationen für bekannte OSGi-Komponenten und insbesondere benutzerdefinierte OSGi-Komponenten zu erstellen, die von demselben Entwickler entworfen und entwickelt wurden, der die Konfigurationen definiert. Dieser Ansatz kann auch genutzt werden, um Konfigurationen für dieselbe OSGi-Komponente in verschiedenen Ausführungsmodus-Ordnern zu kopieren, einzufügen und zu aktualisieren.

Generieren von OSGi-Konfigurationen mit AEM SDK QuickStart generating-osgi-configurations-using-the-aem-sdk-quickstart

Die AEM Web-Konsole von AEM SDK QuickStart Jar kann verwendet werden, um OSGi-Komponenten zu konfigurieren und OSGi-Konfigurationen als JSON zu exportieren. Dies ist nützlich, um von AEM bereitgestellte OSGi-Komponenten zu konfigurieren, deren OSGi-Eigenschaften und deren Werteformate vom Entwickler, der die OSGi-Konfigurationen im AEM-Projekt definiert, möglicherweise nicht gut verstanden werden.

OSGi-Konfigurationseigenschaftsformate osgi-configuration-property-formats

Inline-Werte inline-values

Inline-Werte werden gemäß der standardmäßigen JSON-Syntax als Name-Wert-Paare formatiert. Zum Beispiel:

{
   "my_var1": "val",
   "my_var2": [ "abc", "def" ],
   "my_var3": 500
}

Umgebungsspezifische Konfigurationswerte environment-specific-configuration-values

Die OSGi-Konfiguration sollte einen Platzhalter für die Variable zuweisen, die pro Umgebung definiert werden soll:

use $[env:ENV_VAR_NAME]

Kundinnen und Kunden sollten diese Technik nur für OSGI-Konfigurationseigenschaften im Zusammenhang mit ihrem benutzerdefinierten Code verwenden. Sie darf nicht verwendet werden, um die von Adobe definierte OSGI-Konfiguration zu überschreiben.

Geheime Konfigurationswerte secret-configuration-values

Die OSGi-Konfiguration sollte einen Platzhalter für das Geheimnis zuweisen, das pro Umgebung definiert werden soll:

use $[secret:SECRET_VAR_NAME]

Variablenbenennung variable-naming

Folgendes gilt sowohl für umgebungsspezifische als auch für geheime Konfigurationswerte.

Variablennamen müssen die folgenden Regeln befolgen:

Die Variablenwerte dürfen 2048 Zeichen nicht überschreiten.

Standardwerte default-values

Folgendes gilt sowohl für umgebungsspezifische als auch für geheime Konfigurationswerte.

Wenn kein Wert pro Umgebung festgelegt ist, wird der Platzhalter zur Laufzeit nicht ersetzt und an Ort und Stelle belassen, da keine Interpolation stattgefunden hat. Um dies zu vermeiden, kann ein Standardwert als Teil des Platzhalters mit der folgenden Syntax bereitgestellt werden:

$[env:ENV_VAR_NAME;default=<value>]

Wenn ein Standardwert angegeben ist, wird der Platzhalter entweder durch den pro Umgebung angegebenen Wert oder durch den bereitgestellten Standardwert ersetzt.

Lokale Entwicklung local-development

Folgendes gilt sowohl für umgebungsspezifische als auch für geheime Konfigurationswerte.

Variablen können in der lokalen Umgebung definiert werden, damit sie zur Laufzeit von der lokalen AEM-Instanz abgerufen werden. Zum Beispiel unter Linux®:

export ENV_VAR_NAME=my_value

Es wird empfohlen, ein einfaches Bash-Skript zu schreiben, das die in den Konfigurationen verwendeten Umgebungsvariablen festlegt, und dieses Skript vor dem Starten von AEM auszuführen. Tools wie https://direnv.net/ helfen bei der Vereinfachung dieses Ansatzes. Abhängig vom Typ der Werte können sie in die Quell-Code-Verwaltung eingecheckt werden, wenn sie von allen gemeinsam genutzt werden können.

Die Werte für Geheimnisse werden aus Dateien gelesen. Daher muss für jeden Platzhalter, der einen geheimen Schlüssel verwendet, eine Textdatei mit dem geheimen Wert erstellt werden.

Wenn beispielsweise $[secret:server_password] verwendet wird, muss eine Textdatei mit dem Namen server_password erstellt werden. Alle diese geheimen Dateien müssen im selben Ordner gespeichert werden, und die Framework-Eigenschaft org.apache.felix.configadmin.plugin.interpolation.secretsdir muss mit diesem lokalen Ordner konfiguriert werden.

org.apache.felix.configadmin.plugin.interpolation.secretsdir ist eine Sling-Framework-Eigenschaft. Diese Eigenschaft wird nicht in der Felix-Konsole (https://experienceleague.adobe.com/system/console?lang=de) festgelegt, sondern in der Datei „sling.properties“, die beim Starten des Systems verwendet wird. Diese Datei finden Sie im Unterverzeichnis „/conf“ des extrahierten Ordners „Jar/install“ (crx-quickstart/conf).

Beispiel: Fügen Sie diese Zeile am Ende der Datei „crx-quickstart/conf/sling.properties“ hinzu, um „crx-quickstart/secretsdir“ als geheimen Ordner zu konfigurieren:

org.apache.felix.configadmin.plugin.interpolation.secretsdir=${sling.home}/secretsdir

Vergleich von Autoren- und Veröffentlichungskonfiguration author-vs-publish-configuration

Wenn eine OSGi-Eigenschaft unterschiedliche Werte für Autoren- und Veröffentlichungsumgebung erfordert:

Konfigurationsbeispiele configuration-examples

Gehen Sie in den folgenden Beispielen davon aus, dass es neben der Staging- und der Produktionsumgebung drei Entwicklungsumgebungen gibt.

Beispiel 1

Der Wert der OSGi-Eigenschaft my_var1 soll für die Staging- und die Produktionsumgebung gleich und für jede der drei Entwicklungsumgebungen unterschiedlich sein.

{
 "my_var1": "val",
 "my_var2": "abc",
 "my_var3": 500
}

{
 "my_var1" : "$[env:my_var1]"
 "my_var2": "abc",
 "my_var3": 500
}

Beispiel 2

Der Wert der OSGi-Eigenschaft my_var1 soll für die Staging-, Produktions- und für jede der drei Entwicklungsumgebungen unterschiedlich sein. Daher muss die Cloud Manager-API aufgerufen werden, um den Wert für my_var1 für jede Entwicklungsumgebung festzulegen.

{
 "my_var1": "val1",
 "my_var2": "abc",
 "my_var3": 500
}

{
 "my_var1": "val2",
 "my_var2": "abc",
 "my_var3": 500
}

{
 "my_var1" : "$[env:my_var1]"
 "my_var2": "abc",
 "my_var3": 500
}

Beispiel 3

Der Wert der OSGi-Eigenschaft my_var1 soll für die Staging-, Produktions- und eine der Entwicklungsumgebungen gleich und für die anderen zwei Entwicklungsumgebungen unterschiedlich sein. In diesem Fall muss die Cloud Manager-API aufgerufen werden, um den Wert von my_var1 für jede Entwicklungsumgebung festzulegen, einschließlich der Entwicklungsumgebung, die denselben Wert wie die Staging- und die Produktionsumgebung haben soll. Der im Ordner config festgelegte Wert wird nicht vererbt.

{
 "my_var1": "val1",
 "my_var2": "abc",
 "my_var3": 500
}

{
 "my_var1" : "$[env:my_var1]"
 "my_var2": "abc",
 "my_var3": 500
}

Eine andere Möglichkeit, dies zu erreichen, besteht darin, einen Standardwert für das Ersatz-Token im Ordner „config.dev“ so festzulegen, dass er denselben Wert wie im Ordner config hat.

{
 "my_var1": "val1",
 "my_var2": "abc",
 "my_var3": 500
}

{
 "my_var1": "$[env:my_var1;default=val1]"
 "my_var2": "abc",
 "my_var3": 500
}

Cloud Manager-API-Format zum Festlegen von Eigenschaften cloud-manager-api-format-for-setting-properties

Informationen zur Cloud Manager-API und deren Konfiguration finden Sie unter Adobe Cloud Manager auf der Adobe Developer-Website.

Festlegen von Werten über API setting-values-via-api

Durch den Aufruf der API werden die neuen Variablen und Werte in einer Cloud-Umgebung bereitgestellt, ähnlich wie bei einer typischen Bereitstellungs-Pipeline für Kunden-Code. Die Authoring- und Publishing-Services werden neu gestartet und verweisen auf die neuen Werte. Dies dauert normalerweise einige Minuten.

PATCH /program/{programId}/environment/{environmentId}/variables

[
        {
                "name" : "MY_VAR1",
                "value" : "plaintext value",
                "type" : "string"  <---default
        },
        {
                "name" : "MY_VAR2",
                "value" : "<secret value>",
                "type" : "secretString"
        }
]

Abrufen von Werten über API getting-values-via-api

GET /program/{programId}/environment/{environmentId}/variables

Weitere Informationen finden Sie unter Cloud Manager-API.

Löschen von Werten über API deleting-values-via-api

PATCH /program/{programId}/environment/{environmentId}/variables

Um eine Variable zu löschen, fügen Sie sie mit einem leeren Wert ein.

Weitere Informationen finden Sie unter Cloud Manager-API.

Abrufen von Werten über die Befehlszeile getting-values-via-cli

$ aio cloudmanager:list-environment-variables ENVIRONMENT_ID
Name     Type         Value
MY_VAR1  string       plaintext value
MY_VAR2  secretString ****

Festlegen von Werten über die Befehlszeile setting-values-via-cli

$ aio cloudmanager:set-environment-variables ENVIRONMENT_ID --variable MY_VAR1 "plaintext value" --secret MY_VAR2 "some secret value"

Löschen von Werten über die Befehlszeile deleting-values-via-cli

$ aio cloudmanager:set-environment-variables ENVIRONMENT_ID --delete MY_VAR1 MY_VAR2

Anzahl der Variablen number-of-variables

Pro Umgebung können bis zu 200 Variablen deklariert werden.

Bereitstellungsaspekte für geheime und umgebungsspezifische Konfigurationswerte deployment-considerations-for-secret-and-environment-specific-configuration-values

Da die geheimen und umgebungsspezifischen Konfigurationswerte außerhalb von Git bestehen und daher nicht Teil der formellen Adobe Experience Manager as a Cloud Service-Bereitstellungsmechanismen sind, sollte der Kunde sie verwalten, steuern und in den Adobe Experience Manager as a Cloud Service-Bereitstellungsprozess integrieren.

Wie oben erwähnt, werden durch den Aufruf der API die neuen Variablen und Werte in Cloud-Umgebungen bereitgestellt, ähnlich wie bei einer typischen Bereitstellungs-Pipeline für Kunden-Code. Die Authoring- und Publishing-Services werden neu gestartet und verweisen auf die neuen Werte. Dies dauert normalerweise einige Minuten. Die Qualitäts-Gates und Tests, die von Cloud Manager während einer regulären Code-Bereitstellung ausgeführt werden, werden während dieses Prozesses nicht ausgeführt.

Normalerweise würden Kunden die API aufrufen, um Umgebungsvariablen zu setzen, bevor sie Code bereitstellen, der sich in Cloud Manager auf diese Variablen verlässt. In einigen Situationen kann es sinnvoll sein, eine vorhandene Variable zu ändern, nachdem der Code bereits bereitgestellt wurde.

Es kann Situationen geben, in denen sich eine geplante Bereitstellung von Kunden-Code darauf verlässt, dass vorhandene Variablen neue Werte haben, die mit dem aktuellen Code nicht übereinstimmen würden. Wenn dies ein Problem darstellt, wird empfohlen, variable Änderungen auf additive Weise vorzunehmen. Erstellen Sie dazu neue Variablennamen, anstatt nur den Wert alter Variablen zu ändern, sodass der alte Code nie auf den neuen Wert verweist. Wenn die neue Kundenversion dann stabil aussieht, können Sie die älteren Werte entfernen.

Da die Werte einer Variablen nicht versioniert sind, kann ein Rollback des Codes dazu führen, dass sie auf neuere Werte verweisen, die Probleme verursachen. Auch hier würde die zuvor erwähnte additive Variablenstrategie helfen.

Diese additive Variablenstrategie ist auch für Disaster-Recovery-Szenarien nützlich, bei denen die Variablennamen und -werte, auf die sie verweisen, auch dann noch intakt sind, wenn Code von mehreren Tagen zuvor erneut bereitgestellt werden musste. Dies beruht auf einer Strategie, bei der ein Kunde einige Tage wartet, bevor er diese älteren Variablen entfernt. Andernfalls hätte der ältere Code keine geeigneten Variablen, auf die er verweisen könnte.