AEM har introducerat möjligheten att använda användargränssnittet i Cloud Manager för att konfigurera standardmiljövariabler med version 2021.12.0. Mer information finns i dokumentationen här.
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.
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.
Tidigare versioner AEM OSGi-konfigurationsfiler som stöds med olika filformat, som .cfg
, .config
och som XML sling:OsgiConfig
resursdefinitioner. Dessa format har ersatts av .cfg.json
Konfigurationsformat för OSGi.
AEM 6.x stöder anpassade runmodes, men det gör AEM as a Cloud Service inte. AEM as a Cloud Service stöd och exakt uppsättning av körningslägen. Alla variationer i OSGi-konfigurationer mellan AEM as a Cloud Service miljöer måste hanteras med OSGi-konfigurationsmiljövariabler.
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.
A config.preview
Konfigurationsmapp för OSGi inte deklareras på samma sätt som config.publish
kan deklareras som en mapp. I stället ärver förhandsgranskningsnivån sin OSGi-konfiguration från publiceringsskiktets värden.
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
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:
pid
som representerar OSGi-konfigurationen som ska kontrolleras, Detta är namnet på OSGi-konfigurationsfilen i AEM källkod.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.=Det finns tre sorters OSGi-konfigurationsvärden som kan användas med Adobe Experience Manager as a Cloud Service.
Textbundna värden, som är värden som är hårdkodade i OSGi-konfigurationen och lagrade i Git. Till exempel:
{
"connection.timeout": 1000
}
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]"
}
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]"
}
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:
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.
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.
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.
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.
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.
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<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
<factoryPID>-<name>.cfg.json
namnkonvention.cfg.json
och definiera nyckel/värde-kombinationerna för OSGi-egenskapen och värdepar, enligt följande Konfigurationsformat för JSON OSGi..cfg.json
filAEM 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.
Konfigurationsgränssnittet för AEM-webbkonsolen skriver .cfg.json
till databasen. Därför bör du vara medveten om det här arbetsflödet för att undvika oväntade beteenden under lokal utveckling när de AEM projektdefinierade OSGi-konfigurationerna kan skilja sig från de genererade konfigurationerna.
https://<host>:<port>/system/console
som admin-användareui.apps
, leta upp eller skapa konfigurationsmappen (/apps/.../config.<runmode>
) som är avsett för de runmodes som den nya OSGi-konfigurationen måste ha.<PID>.cfg.json
-fil. PID är samma värde från steg 5..cfg.json
-fil..cfg.json
-fil.Textbundna värden formateras som namnvärdespar enligt JSON-standardsyntaxen. Till exempel:
{
"my_var1": "val",
"my_var2": [ "abc", "def" ],
"my_var3": 500
}
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.
Platshållare kan inte användas i repoinit-programsatser.
OSGi-konfigurationen ska tilldela en platshållare för hemligheten som ska definieras per miljö:
use $[secret:SECRET_VAR_NAME]
Följande gäller för både miljöspecifika och hemliga konfigurationsvärden.
Variabelnamn måste följa följande regler:
[a-zA-Z_][a-zA-Z_0-9]*
Värdena för variablerna får inte överstiga 2 048 tecken.
Det finns regler för användning av vissa prefix för variabelnamn:
Variabelnamn med prefix INTERNAL_
, ADOBE_
, eller CONST_
reserveras av Adobe. Alla kundinställda variabler som börjar med dessa prefix ignoreras.
Kunderna får inte referera till variabler som är prefix med INTERNAL_
eller ADOBE_
antingen.
Miljövariabler med prefix AEM_
definieras av produkten som publikt API som ska användas och anges av kunderna.
När kunderna kan använda och ange miljövariabler som börjar med prefixet AEM_
de ska inte definiera sina egna variabler med det här prefixet.
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.
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.
Filtillägg tillåts inte för textfilen.
Därför måste textfilen namnges i ovanstående exempel server_password - utan filtillägg.
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
Om en OSGi-egenskap kräver olika värden för författare jämfört med publicering:
config.author
och config.publish
OSGi-mappar måste användas enligt beskrivningen i Avsnittet Upplösning i körläge.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>
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.
Mapp | Innehåll i myfile.cfg.json |
config |
{ "my_var1": "val", "my_var2": "abc", "my_var3": 500 } |
config.dev |
{ "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.
Mapp | Innehåll i myfile.cfg.json |
config.stage |
{ "my_var1": "val1", "my_var2": "abc", "my_var3": 500 } |
config.prod |
{ "my_var1": "val2", "my_var2": "abc", "my_var3": 500 } |
config.dev |
{ "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.
Mapp | Innehåll i myfile.cfg.json |
config |
{ "my_var1": "val1", "my_var2": "abc", "my_var3": 500 } |
config.dev |
{ "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.
Mapp | Innehåll i myfile.cfg.json |
config |
{ "my_var1": "val1", "my_var2": "abc", "my_var3": 500 } |
config.dev |
{ "my_var1": "$[env:my_var1;default=val1]" "my_var2": "abc", "my_var3": 500 } |
Se den här sidan om hur API:t måste konfigureras.
Kontrollera att det använda Cloud Manager-API:t har tilldelats rollen "Deployment Manager - Cloud Service". Andra roller kan inte köra alla kommandon nedan.
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"
}
]
Standardvariabler anges inte via API, utan i själva OSGi-egenskapen.
Se den här sidan för mer information.
GET /program/{programId}/environment/{environmentId}/variables
Se den här sidan för mer information.
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.
$ aio cloudmanager:list-environment-variables ENVIRONMENT_ID
Name Type Value
MY_VAR1 string plaintext value
MY_VAR2 secretString ****
$ aio cloudmanager:set-environment-variables ENVIRONMENT_ID --variable MY_VAR1 "plaintext value" --secret MY_VAR2 "some secret value"
$ aio cloudmanager:set-environment-variables ENVIRONMENT_ID --delete MY_VAR1 MY_VAR2
Se den här sidan om du vill ha mer information om hur du konfigurerar värden med plugin-programmet Cloud Manager för Adobe I/O CLI.
Upp till 200 variabler per miljö kan deklareras.
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.
API:t kanske inte fungerar när en pipeline används, antingen en AEM eller en kunddistribution, beroende på vilken del av slutpipeline som körs vid den tidpunkten. Felsvaret kommer att ange att begäran inte lyckades, men det kommer inte att ange den specifika orsaken.
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.