Konfigurera OSGi för Adobe Experience Manager 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

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

Specifika OSGi-konfigurationer kan riktas mot specifika AEM genom att använda runmodes. Skapa 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:

1. Öppna AEM som en Cloud Services-miljöns Developer Console
2. Välja vilka tjänstenivåer som ska inspekteras med Pod listruta
3. Markera Status tab
4. Markera Konfigurationer från Statusdump listruta
5. Markera Hämta status knapp

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:

1. I Developer Console's Configuration output
2. Leta reda på pid som representerar OSGi-konfigurationen som ska kontrolleras, Detta är namnet på OSGi-konfigurationsfilen i AEM källkod.
3. Inspect properties listan för pid och verifiera att nyckeln och värdena matchar OSGi-konfigurationsfilen i AEM projektkällkod för det körläge som verifieras.=

Typer av OSGi-konfigurationsvärden

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

1. Textbundna värden, som är värden som är hårdkodade i OSGi-konfigurationen och lagrade i Git. Till exempel:

   {
      "connection.timeout": 1000
   }
   

2. Hemliga värden, som är värden som inte får lagras i Git av säkerhetsskäl. Till exempel:

   {
   "api-key": "$[secret:server-api-key]"
   }
   

3. Miljöspecifika värden, som är värden som varierar mellan utvecklingsmiljöer och därför inte kan anges korrekt i körningsläge (eftersom det finns en enda dev runmode i Adobe Experience Manager as a Cloud Service). Till exempel:

   {
    "url": "$[env:server-url]"
   }
   

   En enskild OSGi-konfigurationsfil kan använda vilken kombination som helst av dessa konfigurationsvärdetyper tillsammans. Till exempel:

   {
   "connection.timeout": 1000,
   "api-key": "$[secret:server-api-key]",
   "url": "$[env:server-url]"
   }
   

Så här väljer du lämplig OSGi-konfigurationsvärdetyp

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:

När infogade konfigurationsvärden ska användas

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:

• De bevaras, med styrning och versionshistorik i Git
• Värdena är implicit knutna till koddistributioner
• De kräver inga ytterligare distributionsöverväganden eller samordning

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

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.

• Använd bara icke-hemliga miljöspecifika konfigurationer för konfigurationsvärden som skiljer sig mellan publicerings- och förhandsgranskningsskikt, eller för värden som skiljer sig åt mellan utvecklingsmiljöer, inklusive lokala utvecklingsinstanser.
• Förutom scenariot när förhandsvisningsnivån behöver variera från publiceringsnivån, använder du standardvärdena för intern visning i OSGi-konfigurationerna för icke-hemliga värden för scenen och produktionen. Det rekommenderas inte att man använder miljöspecifika konfigurationer för att underlätta konfigurationsändringar under körning till scen- och produktionsmiljöer. dessa ändringar bör införas via källkodshantering.

När hemliga miljöspecifika konfigurationsvärden ska användas

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

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

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.

1. Öppna ui.apps , leta upp eller skapa konfigurationsmappen (/apps/.../config.<runmode>) som är avsedd för de runmodes som den nya OSGi-konfigurationen måste ha
2. Skapa en <PID>.cfg.json -fil. PID är den beständiga identiteten för OSGi-komponenten. Det är vanligtvis det fullständiga klassnamnet för OSGi-komponentimplementeringen. Till exempel:
   /apps/.../config/com.example.workflow.impl.ApprovalWorkflow.cfg.json
   Observera att namnet på OSGi-konfigurationsfabriksfilen använder <factoryPID>-<name>.cfg.json namnkonvention
3. Öppna den nya .cfg.json och definiera nyckel/värde-kombinationerna för OSGi-egenskapen och värdepar, enligt följande Konfigurationsformat för JSON OSGi.
4. Spara ändringarna i den nya .cfg.json fil
5. Lägg till och implementera din nya OSGi-konfigurationsfil i Git

Generera OSGi-konfigurationer med 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 det AEM projektet.

1. Logga in på AEM SDK Quickstart Jars AEM Web console på https://<host>:<port>/system/console som admin-användare
2. Navigera till OSGi > Konfiguration
3. Om du vill konfigurera letar du reda på OSGi-komponenten och trycker på dess titel för att redigera
   
4. Redigera OSGi-konfigurationens egenskapsvärden via webbgränssnittet efter behov
5. Registrera beständig identitet (PID) på en säker plats. Detta används senare för att generera OSGi-konfigurationens JSON
6. Tryck på Spara
7. Navigera till OSGi > OSGi Installer Configuration Printer
8. Klistra in den PID som kopierats i steg 5, kontrollera att Serialization Format är inställt på OSGi Configurator JSON
9. Tryck på Skriv ut
10. OSGi-konfigurationen i JSON-format visas i avsnittet Serialiserade konfigurationsegenskaper
    
11. Öppna ui.apps , leta upp eller skapa konfigurationsmappen (/apps/.../config.<runmode>) som är avsett för de runmodes som den nya OSGi-konfigurationen måste ha.
12. Skapa en <PID>.cfg.json -fil. PID är samma värde från steg 5.
13. Klistra in serialiserade konfigurationsegenskaper från steg 10 i dialogrutan .cfg.json -fil.
14. Spara ändringarna i den nya .cfg.json -fil.
15. Lägg till och implementera den nya OSGi-konfigurationsfilen i Git.

Egenskapsformat för OSGi-konfiguration

Textbundna värden

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

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 den Adobe-definierade OSGi-konfigurationen.

Värden för hemlig konfiguration

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

use $[secret:SECRET_VAR_NAME]

Variabelnamn

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

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

• Minsta längd: 2
• Maximal längd: 100
• Måste matcha regex: [a-zA-Z_][a-zA-Z_0-9]*

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

Standardvärden

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

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. Exempel: 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-ramverksegenskap, så den här egenskapen ställs inte in i felix-konsolen (/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

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

• Separat config.author och config.publish OSGi-mappar måste användas enligt beskrivningen i Avsnittet Upplösning i körläge.
• Det finns två alternativ för att skapa de oberoende variabelnamnen som ska användas:

  • det första alternativet som rekommenderas: i alla OSGi-mappar (som config.author och config.publish) som deklarerats för att definiera olika värden, använd samma variabelnamn. Till exempel

    $[env:ENV_VAR_NAME;default=<value>], där standardvärdet motsvarar standardvärdet för den nivån (författare eller publicering). När miljövariabeln ställs in via API för Cloud Manager eller via en klient, differentiera mellan nivåerna med hjälp av parametern "service" som beskrivs i detta API-referensdokumentation. Parametern service binder variabelns värde till rätt OSGi-nivå. Det kan vara"författare","publicera" eller"förhandsgranska".

  • det andra alternativet, som är att deklarera distinkta variabler med ett prefix som author_<samevariablename> och publish_<samevariablename>

Konfigurationsexempel

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

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

Ange värden 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

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

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

Ta bort värden 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

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

Ange värden via kommandoraden

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

Ta bort värden via kommandoraden

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

Antal variabler

Upp till 200 variabler per miljö kan deklareras.

Distributionsöverväganden för Hemliga och miljöspecifika konfigurationsvärden

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. Observera att de kvalitetsportar och tester som körs av Cloud Manager under en vanlig koddistribution inte utförs 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.

Resurser för Business.Adobe.com