Debug delle build e implementazioni di AEM as a Cloud Service

Adobe Cloud Manager facilita la creazione e l’implementazione del codice in AEM as a Cloud Service. Possono verificarsi errori durante i passaggi del processo di compilazione, che richiedono un’azione per risolverli. Questa guida illustra gli errori comuni nell’implementazione e le modalità per affrontarli al meglio.

Pipe di generazione gestisci cloud

Convalida

Il passaggio di convalida assicura semplicemente la validità delle configurazioni di base di Cloud Manager. Gli errori di convalida comuni includono:

Lo stato dell'ambiente non è valido

  • Messaggio di errore: lo stato dell'ambiente non è valido.
    Lo stato dell'ambiente non è valido
  • Causa: l’ambiente di destinazione della pipeline è in uno stato di transizione in cui non può accettare nuove build.
  • Risoluzione: attendi che lo stato venga risolto in uno stato di esecuzione (o di aggiornamento disponibile). Se l’ambiente viene eliminato, ricrea l’ambiente o scegli un ambiente diverso in cui generare la build.

Impossibile trovare l’ambiente associato alla pipeline

  • Messaggio di errore: l’ambiente è contrassegnato come eliminato.
    L’ambiente viene contrassegnato come eliminato
  • Causa: l’ambiente configurato per l’utilizzo della pipeline è stato eliminato.
    Anche se viene ricreato un nuovo ambiente con lo stesso nome, Cloud Manager non riassocia automaticamente la pipeline a tale ambiente con lo stesso nome.
  • Risoluzione: modifica la configurazione della pipeline e seleziona nuovamente l’ambiente in cui distribuire.

Impossibile trovare il ramo Git associato alla pipeline

  • Messaggio di errore: pipeline non valida: XXXXXX Reason=Branch=xxxx non trovato nell'archivio.
    pipeline non valida: XXXXXX Reason=Branch=xxxx non trovato nel repository
  • Causa: il ramo Git configurato per l’utilizzo della pipeline è stato eliminato.
  • Risoluzione: ricrea il ramo Git mancante utilizzando lo stesso nome o riconfigura la pipeline in modo da creare da un ramo diverso esistente.

Build & Unit Testing

Test di build e unità

La fase Build and Unit Testing (Generazione e test di unità) esegue una build Maven (mvn clean package) del progetto estratto dal ramo Git configurato della pipeline.

Gli errori individuati in questa fase devono essere riproducibili nella creazione locale del progetto, con le seguenti eccezioni:

  • Viene utilizzata una dipendenza Maven non disponibile su Maven Central e l'archivio Maven contenente la dipendenza è:
    • Non raggiungibile da Cloud Manager, ad esempio un archivio Maven interno privato, oppure l’archivio Maven richiede l’autenticazione e sono state fornite le credenziali errate.
    • Non è stato registrato esplicitamente nel pom.xml del progetto. Tieni presente che, l’inclusione degli archivi Maven è scoraggiata in quanto aumenta i tempi di creazione.
  • I test di unità non riescono a causa di problemi di temporizzazione. Ciò può verificarsi quando le prove di unità sono sensibili alla tempistica. Un indicatore forte si basa su .sleep(..) nel codice di test.
  • L’utilizzo di plug-in Maven non supportati.

Scansione del codice

Scansione del codice

La scansione del codice esegue l’analisi del codice statico utilizzando una combinazione di best practice specifiche per Java e AEM.

La scansione del codice causa un errore di compilazione se nel codice sono presenti vulnerabilità di sicurezza critica. Le violazioni minori possono essere ignorate, ma si consiglia di correggerle. La scansione del codice è imperfetta e può causare falsi positivi.

Per risolvere i problemi di scansione del codice, scarica il rapporto in formato CSV fornito da Cloud Manager tramite il pulsante Download Details e controlla tutte le voci.

Per ulteriori dettagli, consulta le regole specifiche di AEM, consulta la documentazione di Cloud Manager regole di scansione del codice specifiche per AEM personalizzate.

Creare immagini

Creare immagini

L’immagine di generazione è responsabile della combinazione degli artefatti di codice generati nel passaggio Build & Unit Testing (Generazione e test di unità) con la versione di AEM, per formare un singolo artefatto distribuibile.

Sebbene durante la generazione e il testing di unità siano stati rilevati problemi di compilazione e compilazione del codice, durante il tentativo di combinare l’artefatto di build personalizzato con la versione di AEM potrebbero essere stati identificati problemi di configurazione o di struttura.

Configurazioni OSGi duplicate

Quando più configurazioni OSGi vengono risolte tramite la modalità runmode per l’ambiente AEM di destinazione, il passaggio Genera immagine non riesce e viene restituito l’errore:

[ERROR] Unable to convert content-package [/tmp/packages/enduser.all-1.0-SNAPSHOT.zip]: 
Configuration ‘com.example.ExampleComponent’ already defined in Feature Model ‘com.example.groupId:example.all:slingosgifeature:xxxxx:X.X’, 
set the ‘mergeConfigurations’ flag to ‘true’ if you want to merge multiple configurations with same PID

Causa 1

  • Causa: il pacchetto all del progetto AEM contiene più pacchetti di codice e la stessa configurazione OSGi viene fornita da più pacchetti di codice, dando luogo a un conflitto e il passaggio Build Image non è in grado di decidere quale deve essere utilizzato, generando in tal modo un errore nella build. Questo non si applica alle configurazioni di fabbrica OSGi, purché abbiano nomi univoci.
  • Risoluzione: esamina tutti i pacchetti di codice (compresi eventuali pacchetti di codice di terze parti inclusi) che vengono distribuiti come parte dell'applicazione AEM, alla ricerca di configurazioni OSGi duplicate che risolvono, tramite modalità runmode, l'ambiente di destinazione. La guida del messaggio di errore "set the mergeConfigurations flag to true" (Imposta il flag mergeConfigurations su true) non è possibile in AEM as a Cloud Service e deve essere ignorata.

Causa 2

  • Causa: il progetto AEM include erroneamente lo stesso pacchetto di codice due volte, con conseguente duplicazione di qualsiasi configurazione OSGi contenuta in tale pacchetto.
  • Risoluzione: esamina tutti i pacchetti pom.xml di incorporati in tutto il progetto e assicurati che la filevault-package-maven-plugin 🔗 configurazione sia impostata su <cloudManagerTarget>none</cloudManagerTarget>.

Script di reindirizzamento non valido

Gli script di reindirizzamento definiscono il contenuto di base, gli utenti, le ACL, ecc. In AEM as a Cloud Service, gli script di reindirizzamento vengono applicati durante la generazione dell’immagine, ma sul quickstart locale dell’SDK AEM vengono applicati quando viene attivata la configurazione di fabbrica del repoinit OSGi. Per questo motivo, gli script di Repoinit potrebbero silenziosamente non riuscire (con la registrazione) nell’avvio rapido locale dell’SDK AEM e causare un errore nel passaggio Genera immagine, arrestando la distribuzione.

  • Causa: uno script di repoinit non è valido. Questo potrebbe lasciare il tuo archivio in uno stato incompleto come qualsiasi script di reindirizzamento dopo che lo script non riuscito verrà eseguito contro il repository.
  • Risoluzione: esamina l’avvio rapido locale dell’SDK AEM quando la configurazione OSGi dello script di reindirizzamento viene distribuita per determinare se e quali sono gli errori.

Dipendenza contenuto reindirizzamento non soddisfatta

Gli script di reindirizzamento definiscono il contenuto di base, gli utenti, le ACL, ecc. Nell’avvio rapido locale dell’SDK di AEM, gli script di reindirizzamento vengono applicati quando viene attivata la configurazione di fabbrica OSGi del reindirizzamento, o in altre parole, dopo che l’archivio è attivo e possono aver subito modifiche di contenuto direttamente o tramite pacchetti di contenuto. In AEM as a Cloud Service, gli script di reindirizzamento vengono applicati durante la generazione di immagini rispetto a un archivio che potrebbe non contenere il contenuto da cui dipende lo script di reindirizzamento.

  • Causa: uno script di reindirizzamento dipende dal contenuto inesistente.
  • Risoluzione: verifica che esista il contenuto da cui dipende lo script di reindirizzamento. Spesso, questo indica un script di reindirizzamento non adeguatamente definito che non contiene direttive che definiscono queste strutture di contenuto mancanti, ma necessarie. Questo può essere riprodotto localmente eliminando AEM, decomprimendo il Jar e aggiungendo alla cartella di installazione la configurazione OSGi del repoinit contenente lo script di reindirizzamento e avviando AEM. L’errore si presenterà nel file error.log locale di quickstart dell’SDK di AEM.

La versione dei componenti core dell'applicazione è maggiore della versione distribuita

Questo problema riguarda solo gli ambienti non di produzione che NON eseguono l'aggiornamento automatico all'ultima versione di AEM.

AEM as a Cloud Service include automaticamente la versione più recente dei componenti core in ogni versione di AEM, il che significa che dopo l’aggiornamento automatico o manuale di un ambiente AEM as a Cloud Service la versione più recente dei componenti core è stata implementata.

È possibile che il passaggio Genera immagine non riesca quando:

  • L’applicazione di distribuzione aggiorna la versione della dipendenza Maven dei componenti core nel progetto core (bundle OSGi)
  • L’applicazione di distribuzione viene quindi distribuita in un ambiente sandbox (non di produzione) AEM as a Cloud Service che non è stato aggiornato per utilizzare una versione di AEM che contiene la nuova versione dei componenti core.

Per evitare questo errore, ogni volta che è disponibile un aggiornamento dell’ambiente AEM as a Cloud Service , includi l’aggiornamento come parte della build/distribuzione successiva e assicurati che gli aggiornamenti siano inclusi sempre dopo aver incrementato la versione dei componenti core nella base di codice dell’applicazione.

  • Sintomi:
    il passaggio Genera immagine non riesce con un messaggio di errore che segnala che
    com.adobe.cq.wcm.core.components... Impossibile importare i pacchetti in intervalli di versioni specifici dal core progetto.

    [ERROR] Bundle com.example.core:0.0.3-SNAPSHOT is importing package(s) Package com.adobe.cq.wcm.core.components.models;version=[12.13,13) in start level 20 but no bundle is exporting these for that start level in the required version range.
    [ERROR] Analyser detected errors on feature 'com.adobe.granite:aem-ethos-app-image:slingosgifeature:aem-runtime-application-publish-dev:1.0.0-SNAPSHOT'. See log output for error messages.
    [INFO] ------------------------------------------------------------------------
    [INFO] BUILD FAILURE
    [INFO] ------------------------------------------------------------------------
    
  • Causa: il bundle OSGi dell'applicazione (definito nel core progetto) importa le classi Java dalla dipendenza core Components, a un livello di versione diverso da quello distribuito in AEM as a Cloud Service.

  • Risoluzione:

    • Utilizzando Git, ripristina un commit di lavoro esistente prima dell’incremento della versione del componente core. Invia questo commit a un ramo Git di Cloud Manager ed esegui un aggiornamento dell’ambiente da questo ramo. Questo aggiornerà AEM as a Cloud Service all’ultima versione di AEM, che includerà la versione più recente dei componenti core. Una volta che AEM as a Cloud Service è stato aggiornato alla versione più recente di AEM, che avrà la versione più recente dei componenti core, ridistribuisci il codice originariamente non riuscito.
    • Per riprodurre questo problema localmente, assicurati che la versione dell’SDK AEM sia la stessa versione di AEM rilasciata dall’ambiente AEM as a Cloud Service.

Creare un caso di supporto Adobe

Se i suddetti approcci di risoluzione dei problemi non risolvono il problema, crea un caso di assistenza Adobe, tramite:

  • Adobe Admin Console > Scheda Supporto > Crea caso

    Se sei membro di più organizzazioni Adobe, assicurati che l’organizzazione Adobe che ha una pipeline non riuscita sia selezionata nel commutatore Adobe Orgs prima di creare il caso.

Distribuisci su

Il passaggio Distribuisci a è responsabile dell’artefatto di codice generato in Genera immagine, avvia i nuovi servizi di authoring e pubblicazione AEM che lo utilizzano e, dopo il successo, rimuove tutti i vecchi servizi di authoring e pubblicazione AEM. Anche in questo passaggio vengono installati e aggiornati pacchetti di contenuto variabile e indici.

Acquisisci familiarità con i registri di AEM as a Cloud Service prima di eseguire il debug della distribuzione al passaggio . Il registro aemerror contiene informazioni sull'avvio e lo spegnimento dei pod che possono essere pertinenti per distribuire i problemi. Il registro disponibile tramite il pulsante Download Log nel passaggio Distribuzione a di Cloud Manager non è il registro aemerror e non contiene informazioni dettagliate relative all’avvio delle applicazioni.

Distribuisci su

I tre motivi principali per cui il passaggio Distribuisci a potrebbe non riuscire:

La pipeline di Cloud Manager contiene una vecchia versione di AEM

  • Causa: una pipeline di Cloud Manager contiene una versione di AEM precedente a quella distribuita nell’ambiente di destinazione. Questo può accadere quando una pipeline viene riutilizzata e indirizzata a un nuovo ambiente che esegue una versione successiva di AEM. Questo può essere identificato controllando se la versione AEM dell’ambiente è maggiore della versione AEM della pipeline.
    La pipeline di Cloud Manager contiene una vecchia versione di AEM
  • Risoluzione:
    • Se nell’ambiente di destinazione è disponibile un aggiornamento, seleziona Aggiorna dalle azioni dell’ambiente, quindi esegui nuovamente la build.
    • Se nell’ambiente di destinazione non è disponibile un aggiornamento, significa che è in esecuzione la versione più recente di AEM. Per risolvere il problema, elimina la pipeline e ricreala.

Timeout di Cloud Manager

Il codice in esecuzione durante l’avvio del nuovo servizio AEM implementato richiede talmente tempo che Cloud Manager riceve un timeout prima del completamento della distribuzione. In questi casi, l’implementazione potrebbe avere successo, anche se lo stato di Cloud Manager segnalava Non riuscito.

  • Causa: il codice personalizzato può eseguire operazioni, come query di grandi dimensioni o traversate di contenuti, attivate all’inizio nel bundle OSGi o nei cicli di vita dei componenti, ritardando significativamente il tempo di avvio di AEM.
  • Risoluzione: esamina l'implementazione del codice in esecuzione all'inizio del ciclo di vita del bundle di OSGi, esamina i aemerror registri dei servizi Author e Publish di AEM al momento dell'errore (ora di accesso GMT) come mostrato dal Cloud Manager e cerca i messaggi di registro che indicano eventuali processi di log in esecuzione personalizzati.

Codice o configurazione non compatibili

La maggior parte delle violazioni del codice e della configurazione viene rilevata in precedenza nella build, tuttavia è possibile che il codice personalizzato o la configurazione sia incompatibile con AEM as a Cloud Service e non venga rilevato finché non viene eseguito nel contenitore .

  • Causa: il codice personalizzato può richiamare operazioni lunghe, come query di grandi dimensioni o attraversamenti di contenuti, attivate all’inizio nel bundle OSGi o nei cicli di vita dei componenti, rallentando in modo significativo il tempo di avvio di AEM.
  • Risoluzione: esamina i aemerror registri dei servizi Author e Publish di AEM intorno all’ora (ora di accesso GMT) dell’errore, come mostrato da Cloud Manager.
    1. Controlla i registri per eventuali ERRORS generati dalle classi Java fornite dall'applicazione personalizzata. Se vengono rilevati problemi, risolvi, invia il push del codice fisso e ricompila la pipeline.
    2. Controlla i registri per eventuali ERRORI segnalati dagli aspetti di AEM con cui stai estendendo/interagendo nell’applicazione personalizzata e analizzali; questi ERRORI potrebbero non essere direttamente attribuiti alle classi Java. Se vengono rilevati problemi, risolvi, invia il push del codice fisso e ricompila la pipeline.

Inclusione di /var nel pacchetto di contenuti

/var è modificabile contenente una varietà di contenuti transitori e di runtime. Inclusione di /var in pacchetti di contenuti (ad esempio). ui.content) implementata tramite Cloud Manager potrebbe causare il mancato funzionamento del passaggio Distribuzione .

Questo problema è difficile da identificare in quanto non si traduce in un errore nella distribuzione iniziale, solo nelle distribuzioni successive. I sintomi noti includono:

  • La distribuzione iniziale ha esito positivo, indipendentemente dal fatto che il contenuto mutabile, nuovo o modificato, che fa parte della distribuzione, non esista nel servizio AEM Publish.
  • L’attivazione/disattivazione del contenuto in AEM Author è bloccata
  • Le implementazioni successive non riescono nel passaggio Distribuisci a e il passaggio Distribuisci a non riesce dopo circa 60 minuti.

Per convalidare questo problema è la causa del comportamento non riuscito:

  1. Determinando che almeno un pacchetto di contenuto fa parte della distribuzione, scrive in /var.

  2. Verifica che la coda di distribuzione primaria (in grassetto) sia bloccata in:

    • AEM Author > Strumenti > Implementazione > Distribuzione

      Coda di distribuzione bloccata

  3. In caso di errore nella distribuzione successiva, scarica i registri "Distribuisci a" di Cloud Manager utilizzando il pulsante Download Log (Scarica registro):

    Scarica la distribuzione nei registri

    … e verifica che ci siano circa 60 minuti tra le istruzioni di log:

    2020-01-01T01:01:02+0000 Begin deployment in aem-program-x-env-y-dev [CorrelationId: 1234]
    

    … e …

    2020-01-01T02:04:10+0000 Failed deployment in aem-program-x-env-y-dev
    

    Tieni presente che questo registro non conterrà questi indicatori sulle distribuzioni iniziali che hanno avuto esito positivo, ma solo sulle distribuzioni successive con errori.

  • Causa: l'utente del servizio di replica di AEM utilizzato per distribuire pacchetti di contenuto al servizio AEM Publish non può scrivere su /var AEM Publish. Questo causa un errore nella distribuzione del pacchetto di contenuti al servizio AEM Publish.
  • Risoluzione: i seguenti modi per risolvere questi problemi sono elencati in ordine di preferenza:
    1. Se le risorse /var non sono necessarie, rimuovi le risorse sotto /var dai pacchetti di contenuto distribuiti come parte dell'applicazione.
    2. Se le risorse /var sono necessarie, definisci le strutture dei nodi utilizzando repoinit. Gli script di reindirizzamento possono essere indirizzati a AEM Author, AEM Publish o a entrambi tramite le modalità di esecuzione OSGi.
    3. Se le risorse /var sono necessarie solo su AEM Author e non possono essere modellate in modo ragionevole utilizzando repoinit, spostale in un pacchetto di contenuti discreti, installato solo su AEM Author da incorporare nel pacchetto all in una cartella di modalità runmode di AEM Author (<target>/apps/example-packages/content/install.author</target>).
    4. Fornisci ACL appropriati all'utente del servizio sling-distribution-importer come descritto in questo Adobe KB.

Creare un caso di supporto Adobe

Se i suddetti approcci di risoluzione dei problemi non risolvono il problema, crea un caso di assistenza Adobe, tramite:

  • Adobe Admin Console > Scheda Supporto > Crea caso

    Se sei membro di più organizzazioni Adobe, assicurati che l’organizzazione Adobe che ha una pipeline non riuscita sia selezionata nel commutatore Adobe Orgs prima di creare il caso.

In questa pagina