OSGi configureren voor Adobe Experience Manager as a Cloud Service configuring-osgi-for-aem-as-a-cloud-service

OSGiis een fundamenteel element in de technologiestapel van Adobe Experience Manager (AEM). Het wordt gebruikt om de samengestelde bundels van AEM en zijn configuraties te controleren.

OSGi verstrekt de gestandaardiseerde primitieven die toepassingen toestaan om van kleine, herbruikbare, en samenwerkingscomponenten worden geconstrueerd. Deze componenten kunnen in een toepassing worden samengesteld en worden opgesteld. Dit staat gemakkelijk beheer van bundels OSGi toe aangezien zij kunnen worden tegengehouden, geïnstalleerd, individueel begonnen. De onderlinge afhankelijkheden worden automatisch verwerkt. Elke component OSGi is bevat in één van de diverse bundels. Voor meer informatie, zie de specificatie OSGi.

U kunt de configuratiemontages voor componenten OSGi door configuratiedossiers beheren die deel van een AEM codeproject uitmaken.

OSGi-configuratiebestanden osgi-configuration-files

De veranderingen van de configuratie worden bepaald in de de codepakketten van het Project van het AEM (ui.config) als configuratiedossiers (.cfg.json) onder runtime specifieke config omslagen:

/apps/example/config.<runmode>

De indeling van OSGi-configuratiebestanden is gebaseerd op JSON met de .cfg.json -indeling die is gedefinieerd door het Apache Sling-project.

OSGi-configuraties richten OSGi-componenten via hun Persistent Identity (PID), die standaard de Java™-klassenaam van de OSGi-component krijgt. Bijvoorbeeld, om configuratie OSGi voor een dienst te verstrekken OSGi die door wordt uitgevoerd:

com.example.workflow.impl.ApprovalWorkflow.java

een OSGi-configuratiebestand wordt gedefinieerd op:

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

in de volgende cfg.json OSGi-configuratie-indeling.

Resolutie van de uitvoermodus runmode-resolution

De specifieke configuraties OSGi kunnen aan specifieke AEM instanties worden gericht door runmodes te gebruiken. Om runmode te gebruiken, creeer config omslagen onder /apps/example (waar voorbeeld uw projectnaam is), in het formaat:

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

Om het even welke configuraties OSGi in dergelijke omslagen worden gebruikt als de runmodes die in de config omslagnaam worden bepaald de runmodes aanpassen die door AEM worden gebruikt.

Als AEM bijvoorbeeld de auteur en dev van de runmodi gebruikt, worden de configuratieknooppunten in /apps/example/config.author/ en /apps/example/config.author.dev/ toegepast, terwijl de configuratieknooppunten in /apps/example/config.publish/ en /apps/example/config.author.stage/ niet worden toegepast.

Als meerdere configuraties voor dezelfde PID van toepassing zijn, wordt de configuratie met het hoogste aantal overeenkomende uitvoeringsmodi toegepast.

De granulariteit van deze regel staat op een PID-niveau. Dit betekent dat u bepaalde eigenschappen voor dezelfde PID niet kunt definiëren in /apps/example/config.author/ en meer specifieke eigenschappen in /apps/example/config.author.dev/ voor dezelfde PID. De configuratie met het hoogste aantal passende runmodes is effectief voor volledige PID.

Wanneer plaatselijk het ontwikkelen, wordt een loopmode startparameter, -r, gebruikt om de runmode configuratie te specificeren OSGI.

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

Runmodi controleren

AEM as a Cloud Service-runmodi zijn goed gedefinieerd op basis van het omgevingstype en de service. Herzie de volledige lijst van beschikbare runmodes van AEM as a Cloud Service.

De OSGi-configuratiewaarden die door de runmode worden gespecificeerd, kunnen worden geverifieerd door:

In de resulterende weergave worden alle configuraties van OSGi-componenten voor de geselecteerde laag of lagen weergegeven met hun toepasselijke OSGi-configuratiewaarden. Deze waarden kunnen met de OSGi configuratiewaarden in de broncode van het AEM project onder /apps/example/osgiconfig/config.<runmode(s)> worden van verwijzingen voorzien.

Om te verifiëren worden de aangewezen OSGi configuratiewaarden toegepast:

Typen OSGi-configuratiewaarden types-of-osgi-configuration-values

Er zijn drie soorten OSGi configuratiewaarden die met Adobe Experience Manager as a Cloud Service kunnen worden gebruikt.

Hoe te om het aangewezen Type van Waarde van de Configuratie te kiezen OSGi how-to-choose-the-appropriate-osgi-configuration-value-type

Het algemene geval voor OSGi gebruikt inline OSGi configuratiewaarden. Milieu-specifieke configuraties worden gebruikt slechts voor specifieke gebruiksgevallen waar een waarde tussen dev milieu's verschilt.

De milieu-specifieke configuraties breiden de traditionele, statisch bepaalde configuraties OSGi uit die gealigneerde waarden bevatten, die de capaciteit verstrekken om de OSGi configuratiewaarden extern via Cloud Manager API te beheren. Het is belangrijk om te begrijpen wanneer de gemeenschappelijke en traditionele benadering van het bepalen van gealigneerde waarden en het opslaan van hen in Git, zou moeten worden gebruikt, tegenover het abstraheren van de waarden in milieu-specifieke configuraties.

De volgende richtlijnen richten wanneer om niet geheime en geheime milieu-specifieke configuraties te gebruiken:

Wanneer moet inline configuratiewaarden worden gebruikt? when-to-use-inline-configuration-values

Inline-configuratiewaarden worden als de standaardbenadering beschouwd en moeten waar mogelijk worden gebruikt. Inline configuraties bieden de voordelen van:

Wanneer het bepalen van een OSGi configuratiewaarde, begin met gealigneerde waarden, en selecteer slechts geheime of milieu-specifieke configuraties indien nodig voor het gebruiksgeval.

Wanneer te gebruiken de niet geheime milieu-specifieke configuratiewaarden when-to-use-non-secret-environment-specific-configuration-values

Gebruik slechts milieu-specifieke configuraties ($[env:ENV_VAR_NAME]) voor niet geheime configuratiewaarden wanneer de waarden voor de voorproefrij variëren of over ontwikkelomgevingen variëren. Dit omvat lokale ontwikkelingsinstanties en alle Adobe Experience Manager as a Cloud Service-ontwikkelomgevingen. Vermijd het gebruik van niet-geheime omgevingspecifieke configuraties voor Adobe Experience Manager as a Cloud Service Stage- of Production-omgevingen, anders dan voor het instellen van unieke waarden voor de voorvertoningslaag.

Wanneer gebruiken geheim milieu-specifieke configuratiewaarden when-to-use-secret-environment-specific-configuration-values

Adobe Experience Manager as a Cloud Service vereist het gebruik van milieu-specifieke configuraties ($[secret:SECRET_VAR_NAME]) voor om het even welke geheime OSGi configuratiewaarden, zoals wachtwoorden, privé API sleutels, of een andere waarden die niet in Git om veiligheidsredenen kunnen worden opgeslagen.

Gebruik geheime omgevingspecifieke configuraties om de waarde voor geheimen op te slaan in alle Adobe Experience Manager as a Cloud Service-omgevingen, inclusief werkgebied en productie.

OSGi-configuraties maken creating-osgi-configurations

Er zijn twee manieren om configuraties tot stand te brengen OSGi, zoals hieronder beschreven. De eerste benadering wordt typisch gebruikt voor het vormen van componenten van douaneOSGi die bekende eigenschappen OSGi en waarden door de ontwikkelaar, en laatstgenoemde voor AEM-verstrekte componenten OSGi hebben.

OSGi-configuraties schrijven writing-osgi-configurations

De JSON geformatteerde OSGi configuratiedossiers kunnen door hand in het AEM project worden geschreven. Dit is vaak de snelste manier om configuraties OSGi voor bekende componenten te creëren OSGi, en vooral de componenten van douane OSGi die door de zelfde ontwikkelaar die de configuraties bepalen zijn ontworpen en ontwikkeld. Deze benadering kan ook worden gebruikt om configuraties voor de zelfde component te kopiëren/te kleven en bij te werken OSGi over diverse runmode omslagen.

OSGi-configuraties genereren met de AEM SDK QuickStart generating-osgi-configurations-using-the-aem-sdk-quickstart

De AEM QuickStart Jar's AEM Web Console van SDK kan worden gebruikt vormt componenten OSGi, en de configuraties van export OSGi als JSON. Dit is nuttig om AEM-verstrekte componenten te vormen OSGi waarvan eigenschappen OSGi en hun waardeformaten niet goed kunnen worden begrepen door de ontwikkelaar die de configuraties OSGi in het AEM project bepaalt.

Indelingen van eigenschappen van OSGi-configuratie osgi-configuration-property-formats

Inline-waarden inline-values

Inline-waarden worden opgemaakt als standaard naam-waardeparen, volgens de standaard JSON-syntaxis. Bijvoorbeeld:

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

Omgevingsspecifieke configuratiewaarden environment-specific-configuration-values

De configuratie OSGi zou placeholder voor de variabele moeten toewijzen die bestemd is om per milieu te worden bepaald:

use $[env:ENV_VAR_NAME]

De klanten zouden deze techniek voor OSGi configuratieeigenschappen met betrekking tot hun douanecode slechts moeten gebruiken; het moet niet worden gebruikt om Adobe-bepaalde configuratie met voeten te treden OSGi.

Geheime configuratiewaarden secret-configuration-values

De configuratie OSGi zou placeholder voor het geheim moeten toewijzen dat bestemd is om per milieu te worden bepaald:

use $[secret:SECRET_VAR_NAME]

Naam variabele variable-naming

Het volgende is op zowel milieu-specifieke als geheime configuratiewaarden van toepassing.

De namen van variabelen moeten de volgende regels volgen:

Waarden voor de variabelen mogen niet meer dan 2048 tekens bevatten.

Standaardwaarden default-values

Het volgende is op zowel milieu-specifieke als geheime configuratiewaarden van toepassing.

Als er geen waarde per omgeving is ingesteld, wordt de tijdelijke aanduiding tijdens runtime niet vervangen en blijft deze op zijn plaats omdat er geen interpolatie heeft plaatsgevonden. Om dit te voorkomen, kan een standaardwaarde als deel van placeholder met de volgende syntaxis worden verstrekt:

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

Als er een standaardwaarde is opgegeven, wordt de tijdelijke aanduiding vervangen door de waarde voor de afzonderlijke omgeving, indien opgegeven, of door de opgegeven standaardwaarde.

Lokale ontwikkeling local-development

Het volgende is op zowel milieu-specifieke als geheime configuratiewaarden van toepassing.

Variabelen kunnen in de lokale omgeving worden gedefinieerd, zodat ze tijdens runtime door de lokale AEM worden opgehaald. Bijvoorbeeld op Linux®:

export ENV_VAR_NAME=my_value

Men adviseert dat een eenvoudig bash manuscript wordt geschreven dat de milieuvariabelen plaatst die in de configuraties worden gebruikt en het uitvoeren alvorens AEM te beginnen. Hulpmiddelen zoals https://direnv.net/hulp met het vereenvoudigen van deze benadering. Afhankelijk van het type van de waarden, zouden zij in broncodebeheer kunnen worden gecontroleerd, als zij tussen iedereen kunnen worden gedeeld.

De waarden voor geheimen worden gelezen uit bestanden. Daarom moet voor elke plaatsaanduiding die een geheim gebruikt, een tekstbestand met de geheime waarde worden gemaakt.

Bijvoorbeeld, als $[secret:server_password] wordt gebruikt, moet een tekstdossier genoemd server_password worden gecreeerd. Al deze geheime dossiers moeten in de zelfde folder worden opgeslagen en het kaderbezit org.apache.felix.configadmin.plugin.interpolation.secretsdir moet met die lokale folder worden gevormd.

org.apache.felix.configadmin.plugin.interpolation.secretsdir is een Sling framework-eigenschap; deze eigenschap wordt dus niet ingesteld in de felix-console (https://experienceleague.adobe.com/system/console?lang=nl), maar wel in het sling.properties-bestand dat wordt gebruikt wanneer het systeem wordt opgestart. Dit bestand staat in de subdir /conf van de uitgepakte map Jar/install (crx-quickstart/conf).

voorbeeld: voeg deze regel toe aan het einde van het bestand 'crx-quickstart/conf/sling.properties' om 'crx-quickstart/secretsdir' te configureren als een geheime map:

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

Author versus Publish-configuratie author-vs-publish-configuration

Als een bezit OSGi verschillende waarden voor auteur tegenover publiceert vereist:

Configuratievoorbeelden configuration-examples

In de onderstaande voorbeelden wordt ervan uitgegaan dat er naast het werkgebied en de prod-omgevingen drie ontwikkelomgevingen zijn.

Voorbeeld 1

De bedoeling is dat de waarde van de eigenschap OSGi my_var1 hetzelfde is voor werkgebied en staaf, maar verschilt voor elk van de drie ontwikkelomgevingen.

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

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

Voorbeeld 2

De bedoeling is dat de waarde van de eigenschap OSGi my_var1 verschilt voor werkgebied, staaf en voor elk van de drie ontwikkelomgevingen. De Cloud Manager API moet dus worden aangeroepen om de waarde voor my_var1 voor elke dev-gebeurtenis in te stellen.

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

Voorbeeld 3

De bedoeling is dat de waarde van de eigenschap OSGi my_var1 gelijk is voor werkgebied, productie en slechts één van de ontwikkelomgevingen, maar dat deze verschilt voor de andere twee ontwikkelomgevingen. In dit geval moet de Cloud Manager API worden aangeroepen om de waarde my_var1 in te stellen voor elke ontwikkelomgeving, inclusief voor de ontwikkelomgeving die dezelfde waarde moet hebben als het werkgebied en de productie. Het zal niet de waarde erven die in de omslag wordt geplaatst config.

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

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

Een andere manier om dit te verwezenlijken zou een standaardwaarde voor het vervangingsteken in de omslag config.dev moeten plaatsen dusdanig dat het de zelfde waarde zoals in de config omslag is.

{
 "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-indeling voor het instellen van eigenschappen cloud-manager-api-format-for-setting-properties

Zie deze paginaover hoe API moet worden gevormd.

Waarden instellen via API setting-values-via-api

Het roepen van API stelt de nieuwe variabelen en de waarden aan een milieu van de Wolk op, gelijkend op een typische pijpleiding van de de plaatsing van de klantencode. De auteur- en publicatieservices worden opnieuw gestart en er wordt een verwijzing naar de nieuwe waarden gemaakt. Dit duurt meestal enkele minuten.

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

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

Waarden ophalen via API getting-values-via-api

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

Zie deze paginavoor meer informatie.

Waarden verwijderen via API deleting-values-via-api

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

Als u een variabele wilt verwijderen, neemt u deze op met een lege waarde.

Zie deze paginavoor meer informatie.

Waarden ophalen via de opdrachtregel getting-values-via-cli

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

Waarden instellen via de opdrachtregel setting-values-via-cli

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

Waarden verwijderen via de opdrachtregel deleting-values-via-cli

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

Aantal variabelen number-of-variables

Er kunnen maximaal 200 variabelen per omgeving worden gedeclareerd.

De Overwegingen van de plaatsing voor geheime en milieu-specifieke configuratiewaarden deployment-considerations-for-secret-and-environment-specific-configuration-values

Omdat de geheime en milieu-specifieke configuratiewaarden buiten Git leven, en daarom geen deel van de formele de plaatsingsmechanismen van Adobe Experience Manager as a Cloud Service uitmaken, zou de klant, in het plaatsingsproces van Adobe Experience Manager as a Cloud Service moeten leiden beheren en integreren.

Zoals hierboven vermeld, voert het roepen van API de nieuwe variabelen en waarden aan de milieu's van de Wolk, gelijkend op een typische pijpleiding van de de plaatsing van de klantencode op. De auteur- en publicatieservices worden opnieuw gestart en er wordt een verwijzing naar de nieuwe waarden gemaakt. Dit duurt meestal enkele minuten. De kwaliteitspoorten en -tests die door Cloud Manager worden uitgevoerd tijdens een reguliere code-implementatie, worden tijdens dit proces niet uitgevoerd.

Klanten bellen de API doorgaans om omgevingsvariabelen in te stellen voordat ze code implementeren die op hen in Cloud Manager vertrouwt. In sommige situaties, zou men een bestaande variabele kunnen willen wijzigen nadat de code reeds is opgesteld.

Er kunnen scenario's zijn waar een geplande plaatsing van de klantencode op bestaande variabelen baseert om nieuwe waarden te hebben, die niet met de huidige code aangewezen zouden zijn. Als dit een probleem is, wordt aanbevolen op additieve wijze variabele wijzigingen aan te brengen. Hiertoe maakt u nieuwe variabelenamen in plaats van alleen de waarde van oude variabelen te wijzigen zodat oude code nooit naar de nieuwe waarde verwijst. Wanneer de nieuwe versie van de klant stabiel lijkt, kunt u de oudere waarden verwijderen.

Op dezelfde manier aangezien de waarden van een variabele niet versioned zijn, zou een terugdraaiing van code het kunnen veroorzaken om nieuwere waarden te verwijzen die kwesties veroorzaken. De eerder genoemde additieve variabele-strategie zou hier ook toe bijdragen.

Deze additieve variabele strategie is ook nuttig voor scenario's van de rampenterugwinning waar als de code van verscheidene dagen vóór moest worden opnieuw opgesteld, de veranderlijke namen en de waarden het verwijzingen nog intact zal zijn. Dit is gebaseerd op een strategie waarbij een klant een paar dagen wacht voordat deze oudere variabelen worden verwijderd, anders zou de oudere code geen geschikte variabelen hebben om naar te verwijzen.