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

OSGi is 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. Zie de klasse OSGi-specificatie.

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 codepakketten van het AEM Project (ui.apps) als configuratiebestanden (.cfg.json) onder specifieke configuratiemappen voor de runmode:

/apps/example/config.<runmode>

De indeling van OSGi-configuratiebestanden is gebaseerd op JSON met behulp van 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

na de cfg.json OSGi-configuratieformaat.

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 het voorbeeld uw projectnaam is), in de volgende notatie:

/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 configuratieknooppunten in /apps/example/config.author/ en /apps/example/config.author.dev/ worden toegepast, terwijl 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 geen eigenschappen voor dezelfde PID kunt definiëren in /apps/example/config.author/ en meer specifieke /apps/example/config.author.dev/ voor dezelfde PID. De configuratie met het hoogste aantal passende runmodes is effectief voor volledige PID.

Bij lokale ontwikkeling, een runtime startparameter -r, wordt gebruikt om de configuratie op te geven van de runmode OSGI.

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

Runmodi controleren

AEM as a Cloud Service runmodes worden duidelijk bepaald gebaseerd op het milieutype en de dienst. Controleer de volledige lijst van beschikbare AEM as a Cloud Service runmodi.

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 worden van verwijzingen voorzien /apps/example/osgiconfig/config.<runmode(s)>.

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 de Manager API van de Wolk 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 alleen omgevingspecifieke configuraties ($[env:ENV_VAR_NAME]) voor niet-geheime configuratiewaarden wanneer de waarden variëren voor de voorproefrij 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 omgevingspecifieke configuraties ($[secret:SECRET_VAR_NAME]) voor om het even welke geheime OSGi configuratiewaarden, zoals wachtwoorden, privé API sleutels, of om het even welke 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. Gereedschappen zoals https://direnv.net/ helpen bij het vereenvoudigen van deze aanpak. 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.

Als $[secret:server_password] wordt gebruikt, een tekstbestand genaamd server_password moet worden gemaakt. Al deze geheime dossiers moeten in de zelfde folder en het kader bezit worden opgeslagen org.apache.felix.configadmin.plugin.interpolation.secretsdir moet met die lokale folder worden gevormd.

De 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

Auteur versus configuratie publiceren 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 intent is voor de waarde van de eigenschap OSGi my_var1 hetzelfde zijn voor het werkgebied en de pod, maar verschillen 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 intent is voor de waarde van de eigenschap OSGi my_var1 verschillen voor het werkgebied, de prod en voor elk van de drie ontwikkelomgevingen. De API voor Cloud Manager moet dus worden aangeroepen om de waarde in te stellen voor my_var1 voor elke 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 }

Voorbeeld 3

De intent is voor de waarde van de eigenschap OSGi my_var1 hetzelfde moet zijn voor werkgebied, productie en slechts een van de ontwikkelomgevingen, maar anders voor de andere twee ontwikkelomgevingen. In dit geval moet de API voor Cloud Manager worden aangeroepen om de waarde in te stellen van my_var1 voor elk van de ontwikkelomgevingen, inclusief voor de ontwikkelomgeving, die dezelfde waarde moet hebben als fase en productie. De waarde die in de map is ingesteld, wordt niet overgenomen 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 zijn een standaardwaarde voor het vervangingsteken in config.dev omslag dusdanig te plaatsen dat het de zelfde waarde zoals in in config map.

{ "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 pagina over 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 pagina voor 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 pagina voor 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 worden uitgevoerd door Cloud Manager 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 is gebaseerd in Cloud Manager. 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.