Konfigurera OSGi för Adobe Experience Manager as a Cloud Service configuring-osgi-for-aem-as-a-cloud-service

OSGi är en grundläggande del i Adobe Experience Manager (AEM) teknikstack. Det används för att styra de sammansatta paketen av AEM och dess konfigurationer.

OSGi innehåller standardmallar som gör att applikationer kan byggas av små, återanvändbara och samverkansbaserade komponenter. Dessa komponenter kan sättas samman till ett program och distribueras. Detta gör det enkelt att hantera OSGi-paket eftersom de kan stoppas, installeras och startas individuellt. De inbördes beroendena hanteras automatiskt. Varje OSGi-komponent finns i ett av de olika paketen. Mer information finns i OSGi-specifikation.

Du kan hantera konfigurationsinställningarna för OSGi-komponenter genom konfigurationsfiler som ingår i ett AEM kodprojekt.

OSGi-konfigurationsfiler osgi-configuration-files

Konfigurationsändringar definieras i AEM Project-kodpaket (ui.apps) som konfigurationsfiler (.cfg.json) under körningslägesspecifika konfigurationsmappar:

/apps/example/config.<runmode>

Formatet för OSGi-konfigurationsfiler är JSON-baserat med .cfg.json format som definieras av Apache Sling-projektet.

OSGi-konfigurationer har OSGi-komponenter som mål via deras PID (Persistent Identity), som är standard med OSGi-komponentens Java™-klassnamn. Om du till exempel vill tillhandahålla OSGi-konfiguration för en OSGi-tjänst som implementeras av:

com.example.workflow.impl.ApprovalWorkflow.java

en OSGi-konfigurationsfil definieras på:

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

följer cfg.json Konfigurationsformat för OSGi.

Upplösning för körningsläge runmode-resolution

Specifika OSGi-konfigurationer kan riktas mot specifika AEM genom att använda runmodes. Om du vill använda körningsläget skapar du konfigurationsmappar under /apps/example (där till exempel är ditt projektnamn), i formatet:

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

Alla OSGi-konfigurationer i sådana mappar används om de körningslägen som definieras i konfigurationsmappens namn matchar de körningslägen som används av AEM.

Om AEM t.ex. använder författaren och utvecklaren av runmodes, kommer konfigurationsnoderna i /apps/example/config.author/ och /apps/example/config.author.dev/ används, medan konfigurationsnoder i /apps/example/config.publish/ och /apps/example/config.author.stage/ används inte.

Om flera konfigurationer för samma PID kan användas, används konfigurationen med det högsta antalet matchande körningslägen.

Regelns granularitet är på PID-nivå. Det innebär att du inte kan definiera vissa egenskaper för samma PID i /apps/example/config.author/ och mer specifika /apps/example/config.author.dev/ för samma PID. Konfigurationen med det högsta antalet matchande körningslägen gäller för hela PID.

Vid lokal utveckling, en startparameter för körningsläge, -r, används för att ange OSGI-konfigurationen för runmode.

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

Verifiera körningslägen

AEM as a Cloud Service runmodes är väl definierade baserat på miljötyp och tjänst. Granska fullständig lista över tillgängliga AEM as a Cloud Service körningslägen.

OSGi-konfigurationsvärden som anges av körningsläget kan verifieras av:

I den resulterande vyn visas alla OSGi-komponentkonfigurationer för de valda nivåerna med de tillämpliga OSGi-konfigurationsvärdena. Dessa värden kan korsrefereras med OSGi-konfigurationsvärdena i AEM källkod under /apps/example/osgiconfig/config.<runmode(s)>.

Så här kontrollerar du att rätt OSGi-konfigurationsvärden används:

Typer av OSGi-konfigurationsvärden types-of-osgi-configuration-values

Det finns tre sorters OSGi-konfigurationsvärden som kan användas med Adobe Experience Manager as a Cloud Service.

Så här väljer du lämplig OSGi-konfigurationsvärdetyp how-to-choose-the-appropriate-osgi-configuration-value-type

I det vanliga fallet för OSGi används inline OSGi-konfigurationsvärden. Miljöspecifika konfigurationer används endast för specifika användningsområden där värdet skiljer sig mellan olika utvecklingsmiljöer.

Miljöspecifika konfigurationer utökar de traditionella, statiskt definierade OSGi-konfigurationer som innehåller infogade värden, vilket ger möjlighet att hantera OSGi-konfigurationsvärden externt via Cloud Manager API. Det är viktigt att förstå när den vanliga och traditionella metoden för att definiera textbundna värden och lagra dem i Git ska användas, jämfört med att abstrahera värdena till miljöspecifika konfigurationer.

Följande riktlinjer beskriver när icke-hemliga och hemliga miljöspecifika konfigurationer ska användas:

Använda interna konfigurationsvärden when-to-use-inline-configuration-values

Värden för infogade konfigurationer anses vara standardmetoden och bör användas när det är möjligt. Textbundna konfigurationer ger fördelar med:

När du definierar ett OSGi-konfigurationsvärde börjar du med infogade värden och väljer bara hemliga eller miljöspecifika konfigurationer om det behövs för användningsfallet.

När icke-hemliga miljöspecifika konfigurationsvärden ska användas when-to-use-non-secret-environment-specific-configuration-values

Använd endast miljöspecifika konfigurationer ($[env:ENV_VAR_NAME]) för icke-hemliga konfigurationsvärden när värdena varierar för förhandsvisningsnivån eller varierar mellan olika utvecklingsmiljöer. Detta omfattar lokala utvecklingsinstanser och alla Adobe Experience Manager as a Cloud Service utvecklingsmiljöer. Förutom för att ange unika värden för förhandsvisningsnivån bör du undvika att använda icke-hemliga miljöspecifika konfigurationer för Adobe Experience Manager as a Cloud Service Stage- eller Production-miljöer.

När hemliga miljöspecifika konfigurationsvärden ska användas when-to-use-secret-environment-specific-configuration-values

Adobe Experience Manager as a Cloud Service kräver användning av miljöspecifika konfigurationer ($[secret:SECRET_VAR_NAME]) för eventuella hemliga OSGi-konfigurationsvärden, som lösenord, privata API-nycklar eller andra värden som inte kan lagras i Git av säkerhetsskäl.

Använd hemliga miljöspecifika konfigurationer för att lagra värdet för hemligheter i alla Adobe Experience Manager as a Cloud Service-miljöer, inklusive Stage och Production.

Skapa OSGi-konfigurationer creating-osgi-configurations

Det finns två sätt att skapa OSGi-konfigurationer enligt beskrivningen nedan. Den tidigare metoden används vanligtvis för att konfigurera anpassade OSGi-komponenter som har välkända OSGi-egenskaper och -värden av utvecklaren, och den senare för AEM OSGi-komponenter.

Skriver OSGi-konfigurationer writing-osgi-configurations

JSON-formaterade OSGi-konfigurationsfiler kan skrivas för hand direkt i AEM. Detta är ofta det snabbaste sättet att skapa OSGi-konfigurationer för välkända OSGi-komponenter, och särskilt anpassade OSGi-komponenter som har utformats och utvecklats av samma utvecklare som definierar konfigurationerna. Den här metoden kan också användas för att kopiera/klistra in och uppdatera konfigurationer för samma OSGi-komponent i olika körningslägemappar.

Generera OSGi-konfigurationer med AEM SDK QuickStart generating-osgi-configurations-using-the-aem-sdk-quickstart

AEM SDK Quickstart Jars AEM Web Console kan användas för att konfigurera OSGi-komponenter och exportera OSGi-konfigurationer som JSON. Detta är användbart för att konfigurera AEM OSGi-komponenter vars OSGi-egenskaper och deras värdeformat kanske inte är väl förstådda av den utvecklare som definierar OSGi-konfigurationerna i AEM.

Egenskapsformat för OSGi-konfiguration osgi-configuration-property-formats

Textbundna värden inline-values

Textbundna värden formateras som namnvärdespar enligt JSON-standardsyntaxen. Till exempel:

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

Miljöspecifika konfigurationsvärden environment-specific-configuration-values

OSGi-konfigurationen ska tilldela en platshållare för variabeln som ska definieras per miljö:

use $[env:ENV_VAR_NAME]

Kunder bör endast använda den här tekniken för OSGi-konfigurationsegenskaper som är relaterade till deras anpassade kod. Den får inte användas för att åsidosätta Adobe-definierad OSGi-konfiguration.

Värden för hemlig konfiguration secret-configuration-values

OSGi-konfigurationen ska tilldela en platshållare för hemligheten som ska definieras per miljö:

use $[secret:SECRET_VAR_NAME]

Variabelnamn variable-naming

Följande gäller för både miljöspecifika och hemliga konfigurationsvärden.

Variabelnamn måste följa följande regler:

Värdena för variablerna får inte överstiga 2 048 tecken.

Standardvärden default-values

Följande gäller för både miljöspecifika och hemliga konfigurationsvärden.

Om inget värde har angetts per miljö ersätts inte platshållaren vid körning och den lämnas kvar på plats eftersom ingen interpolering har gjorts. Du kan undvika detta genom att ange ett standardvärde som en del av platshållaren med följande syntax:

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

När ett standardvärde anges ersätts platshållaren antingen med det angivna värdet per-environment eller med det angivna standardvärdet.

Lokal utveckling local-development

Följande gäller för både miljöspecifika och hemliga konfigurationsvärden.

Variabler kan definieras i den lokala miljön så att de hämtas av den lokala AEM vid körning. I Linux®:

export ENV_VAR_NAME=my_value

Vi rekommenderar att du skriver ett enkelt basskript som anger de systemvariabler som används i konfigurationerna och kör det innan du startar AEM. verktyg som https://direnv.net/ hjälper till med att förenkla det här tillvägagångssättet. Beroende på vilken typ av värden det är kan de checkas in i källkodshanteringen om de kan delas mellan alla.

Värdena för hemligheter läses från filer. Därför måste en textfil med det hemliga värdet skapas för varje platshållare som använder en hemlighet.

Om $[secret:server_password] används, en textfil med namnet server_password måste skapas. Alla dessa hemliga filer måste lagras i samma katalog och ramverksegenskapen org.apache.felix.configadmin.plugin.interpolation.secretsdir måste konfigureras med den lokala katalogen.

The org.apache.felix.configadmin.plugin.interpolation.secretsdir är en Sling framework-egenskap. Den här egenskapen ställs inte in i felix-konsolen (https://experienceleague.adobe.com/system/console?lang=sv), men ställs in i den sling.properties-fil som används när systemet startas. Den här filen finns i /conf-undermappen i den extraherade JAR/install-mappen (crx-quickstart/conf).

exempel: lägg till den här raden i slutet av crx-quickstart/conf/sling.properties-filen för att konfigurera crx-quickstart/secretsdir som en hemlig mapp:

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

Författare jämfört med Publiceringskonfiguration author-vs-publish-configuration

Om en OSGi-egenskap kräver olika värden för författare jämfört med publicering:

Konfigurationsexempel configuration-examples

I exemplen nedan antar vi att det finns tre utvecklingsmiljöer förutom scen- och prodmiljöer.

Exempel 1

Avsikten är värdet på OSGi-egenskapen my_var1 vara densamma för scenen och produkten, men skiljer sig åt för var och en av de tre utvecklingsmiljöerna.

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

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

Exempel 2

Avsikten är värdet på OSGi-egenskapen my_var1 skiljer sig åt för scenen, produkten och för var och en av de tre utvecklingsmiljöerna. Därför måste Cloud Manager API anropas för att ange värdet för my_var1 for each dev env.

{ "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 }

Exempel 3

Avsikten är värdet på OSGi-egenskapen my_var1 vara densamma för scenen, produktionen och bara en av utvecklingsmiljöerna, men för att det ska skilja sig åt för de två andra utvecklingsmiljöerna. I det här fallet måste Cloud Manager API anropas för att ange värdet för my_var1 för var och en av utvecklingsmiljöerna, även för utvecklingsmiljön, som bör ha samma värde som stadium och produktion. Det ärver inte det värde som angetts i mappen config.

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

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

Ett annat sätt att uppnå detta är att ange ett standardvärde för ersättningstoken i mappen config.dev så att det är samma värde som i config mapp.

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

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

API-format för Cloud Manager för att ange egenskaper cloud-manager-api-format-for-setting-properties

Se den här sidan om hur API måste konfigureras.

Ange värden via API setting-values-via-api

Anrop av API:t distribuerar de nya variablerna och värdena till en molnmiljö, ungefär som en vanlig pipeline för kundkoddistribution. Tjänsterna för författare och publicering startas om och de nya värdena anges, vilket normalt tar några minuter.

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

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

Hämta värden via API getting-values-via-api

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

Se den här sidan för mer information.

Ta bort värden via API deleting-values-via-api

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

Om du vill ta bort en variabel inkluderar du den med ett tomt värde.

Se den här sidan för mer information.

Hämta värden via kommandoraden getting-values-via-cli

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

Ange värden via kommandoraden setting-values-via-cli

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

Ta bort värden via kommandoraden deleting-values-via-cli

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

Antal variabler number-of-variables

Upp till 200 variabler per miljö kan deklareras.

Distributionsöverväganden för Hemliga och miljöspecifika konfigurationsvärden deployment-considerations-for-secret-and-environment-specific-configuration-values

Eftersom de hemliga och miljöspecifika konfigurationsvärdena finns utanför Git, och därför inte ingår i de formella distributionsmekanismerna för Adobe Experience Manager as a Cloud Service, bör kunden hantera, styra och integrera dem i Adobe Experience Manager as a Cloud Service distributionsprocess.

Som nämnts ovan distribueras de nya variablerna och värdena till Cloud-miljöer när API anropas, på samma sätt som en vanlig pipeline för kundkoddistribution. Tjänsterna för författare och publicering startas om och de nya värdena anges, vilket normalt tar några minuter. Kvalitetsgates och tester som körs av Cloud Manager under en vanlig koddistribution utförs inte under den här processen.

Normalt anropar kunderna API för att ange miljövariabler innan de distribuerar kod som är beroende av dem i Cloud Manager. I vissa fall kanske du vill ändra en befintlig variabel efter att koden redan har distribuerats.

Det kan finnas scenarier där en schemalagd kundkoddistribution förlitar sig på befintliga variabler för att ha nya värden, vilket inte är lämpligt med den aktuella koden. Om detta är ett problem bör variabla ändringar göras på ett additivt sätt. Det gör du genom att skapa nya variabelnamn i stället för att bara ändra värdet för gamla variabler så att gammal kod aldrig refererar till det nya värdet. När den nya kundreleasen ser stabil ut kan man välja att ta bort de äldre värdena.

Eftersom variabelns värden inte är versionshanterade kan en återställning av koden få den att referera till nyare värden som orsakar problem. Här skulle även den tidigare nämnda additiva variabelstrategin vara till hjälp.

Den här additiva variabelstrategin är också användbar för scenarier där, om kod från flera dagar tidigare behövde omdistribueras, variabelnamnen och värdena som den refererar till fortfarande är intakta. Detta bygger på en strategi där kunden väntar några dagar innan de tar bort de äldre variablerna, annars har den äldre koden inte rätt variabler att referera till.