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

OSGi är ett grundläggande element 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-specifikationen.

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-projektets kodpaket (ui.config) som konfigurationsfiler (.cfg.json) under körningsspecifika konfigurationsmappar:

/apps/example/config.<runmode>

Formatet på OSGi-konfigurationsfilerna är JSON-baserat med formatet .cfg.json 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 konfigurationsformatet cfg.json 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äge skapar du konfigurationsmappar under /apps/example (där exemplet ä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örfattare och dev för körningslägena används konfigurationsnoderna i /apps/example/config.author/ och /apps/example/config.author.dev/, medan konfigurationsnoderna i /apps/example/config.publish/ och /apps/example/config.author.stage/ inte tillämpas.

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 i /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 används en startparameter för körningsläge, -r, för att ange OSGI-konfigurationen för körningsläget.

$ 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äldefinierade baserat på miljötyp och tjänst. Granska den fullständiga listan ö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 gör det möjligt 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 bara miljöspecifika konfigurationer ($[env:ENV_VAR_NAME]) för icke-hemliga konfigurationsvärden när värdena varierar för förhandsgranskningsnivå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 att miljöspecifika konfigurationer ($[secret:SECRET_VAR_NAME]) används för alla hemliga OSGi-konfigurationsvärden, till exempel 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 dig att förenkla det här arbetssä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 till exempel $[secret:server_password] används måste en textfil med namnet server_password 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.

org.apache.felix.configadmin.plugin.interpolation.secretsdir är en Sling-ramverksegenskap, så den här egenskapen har inte angetts i felix-konsolen (https://experienceleague.adobe.com/system/console?lang=sv), men har angetts i filen sling.properties 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

Skapa jämfört med Publish Configuration 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 att OSGi-egenskapen my_var1 ska vara samma för stage och prod, men olika 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 att OSGi-egenskapen my_var1 ska ha olika värden för stage, prod 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 för varje dev-miljö.

{
 "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 att OSGi-egenskapen my_var1 ska vara samma för scenen, produktionen och bara en av utvecklingsmiljöerna, men att den ska vara annorlunda för de två andra utvecklingsmiljöerna. I det här fallet måste Cloud Manager API anropas för att ange värdet my_var1 för var och en av utvecklingsmiljöerna, inklusive för utvecklingsmiljön som ska ha samma värde som fas 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 mappen config .

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

Mer information finns på den här sidan.

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.

Mer information finns på den här sidan.

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. De kvalitetsportar och tester som körs av Cloud Manager under en vanlig koddistribution utförs inte under den här processen.

Normalt anropas API:t för att ange miljövariabler innan kod som är beroende av dem distribueras 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.