Depuração da build e de implantações do AEM as a Cloud Service
O Adobe Cloud Manager facilita a criação de código e as implantações no AEM as a Cloud Service. Podem ocorrer falhas durante as etapas no processo de criação, exigindo uma ação para resolvê-las. Este guia aborda as falhas comuns no na implantação e a melhor maneira de abordá-las.
Validação
A etapa de validação simplesmente garante a validade das configurações básicas do Cloud Manager. Falhas comuns de validação incluem:
O ambiente está em um estado inválido
- Mensagem de erro: o ambiente está em um estado inválido.
- Causa: o ambiente de destino do pipeline está em um estado de transição e, nesse momento, não pode aceitar novas compilações.
- Solução: aguarde até que o estado seja resolvido para um estado em execução (ou atualização disponível). Se o ambiente estiver sendo excluído, recrie-o ou escolha outro ambiente para o qual criar.
Não foi possível encontrar o ambiente associado ao pipeline
- Mensagem de erro: o ambiente está marcado como excluído.
- Causa: O ambiente que o pipeline está configurado para usar foi excluído.
Mesmo que um novo ambiente com o mesmo nome seja recriado, o Cloud Manager não reassociará automaticamente o pipeline a esse ambiente com o mesmo nome. - Solução: edite a configuração do pipeline e selecione novamente o ambiente no qual implantar.
Não foi possível encontrar a ramificação Git associada ao pipeline
- Mensagem de erro: Pipeline inválido: XXXXXX. Motivo=Branch=xxxx não encontrado no repositório.
- Causa: A ramificação Git que o pipeline está configurado para usar foi excluída.
- Solução: recrie a ramificação Git ausente usando exatamente o mesmo nome ou reconfigure o pipeline para compilar a partir de uma ramificação diferente existente.
Teste de build e unidade
A fase de Teste de compilação e unidade executa uma compilação Maven (mvn clean package) do projeto retirado da ramificação Git configurada do pipeline.
Os erros identificados nesta fase devem ser reproduzíveis na criação do projeto localmente, com as seguintes exceções:
-
Uma dependência maven não disponível em Maven Central é usada, e o repositório Maven que contém a dependência é:
- Inacessível do Cloud Manager, como um repositório Maven interno privado ou o repositório Maven requer autenticação e as credenciais incorretas foram fornecidas.
- Não registrado explicitamente no
pom.xmldo projeto. Observe que a inclusão de repositórios Maven não é incentivada, pois aumenta os tempos de compilação.
-
Falha nos testes de unidade devido a problemas de tempo. Isso pode ocorrer quando os testes de unidade são sensíveis ao tempo. Um indicador forte depende de
.sleep(..)no código de teste. -
O uso de plug-ins Maven não compatíveis.
Varredura de código
A varredura de código executa análise de código estático usando uma combinação de práticas recomendadas específicas para Java e AEM.
A varredura de código resulta em falha na build se houver vulnerabilidades críticas de segurança no código. Violações menores podem ser substituídas, mas é recomendável que sejam corrigidas. Observe que a verificação de código é imperfeita e pode resultar em falsos positivos.
Para resolver problemas de verificação de código, baixe o relatório em formato CSV fornecido pela Cloud Manager por meio do botão Detalhes do Download e revise todas as entradas.
Para obter mais detalhes, consulte as regras específicas do AEM nas regras personalizadas de verificação de código específicas do AEM das documentações do Cloud Manager.
Imagens de build
A imagem de build é responsável por combinar os artefatos de código criados na etapa de Teste de compilação e unidade com a versão do AEM, para formar um único artefato implantável.
Embora qualquer problema de compilação e criação de código seja encontrado durante o Teste de compilação e unidade, pode haver problemas estruturais ou de configuração identificados ao tentar combinar o artefato de compilação personalizado com a versão do AEM.
Duplicar configurações de OSGi
Quando várias configurações de OSGi são resolvidas por meio do modo de execução para o ambiente AEM de destino, a etapa Criar imagem falha com o erro:
[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: o pacote inteiro do projeto AEM, contém vários pacotes de código e a mesma configuração OSGi é fornecida por mais de um dos pacotes de código, resultando em um conflito, o que resulta na etapa Compilar Imagem não poder decidir qual deve ser usado, portanto, a compilação falha. Observe que isso não se aplica às configurações de fábrica OSGi, desde que tenham nomes exclusivos.
- Solução: revise todos os pacotes de código (incluindo todos os pacotes de código de terceiros incluídos) que estão sendo implantados como parte do aplicativo AEM, procurando configurações OSGi duplicadas que resolvem, via modo de execução, para o ambiente de destino. A orientação da mensagem de erro de "definir o sinalizador mergeConfigurations como true" não é possível no AEM as a Cloud Service e deve ser ignorada.
Causa 2
- Causa: o AEM inclui incorretamente o mesmo pacote de código duas vezes, resultando na duplicação de qualquer configuração OSGi contida nesse pacote.
- Solução: revise todos os pom.xmls de pacotes inseridos no projeto all e verifique se eles têm a
filevault-package-maven-pluginconfiguração definida como<cloudManagerTarget>none</cloudManagerTarget>.
Script de repoinit malformado
Os scripts de repoinit definem o conteúdo básico, os usuários, as ACLs, etc. No AEM as a Cloud Service, os scripts de repoinit são aplicados durante a imagem da build, no entanto, na inicialização rápida local do SDK AEM eles são aplicados quando a configuração de fábrica de repoinit do OSGi é ativada. Por causa disso, os scripts de Repoinit podem falhar silenciosamente (com o registro) na inicialização rápida local do SDK do AEM e, mas causar falha na etapa Criar imagem, interrompendo a implantação.
- Causa: um script de repoinit está malformado. Isso pode deixar o repositório em um estado incompleto, pois qualquer script de repoinit após o script com falha não é executado no repositório.
- Solução: revise o quickstart local do SDK do AEM quando a configuração OSGi do script de repoinit for implantada para determinar se e quais são os erros.
Dependência de conteúdo de repoinit não satisfeita
Os scripts de repoinit definem o conteúdo básico, os usuários, as ACLs, etc. No quickstart local do SDK do AEM, os scripts de repoinit são aplicados quando a configuração de fábrica OSGi de repoinit é ativada ou, em outras palavras, depois que o repositório está ativo e pode ter ocorrido alterações de conteúdo diretamente ou por meio de pacotes de conteúdo. No AEM as a Cloud Service, os scripts de repoinit são aplicados durante a criação de imagem em um repositório que pode não conter conteúdo do qual o script de repoinit depende.
- Causa: um script de repoinit depende de um conteúdo que não existe.
- Solução: verifique se o conteúdo do qual o script repoinit depende existe. Geralmente, isso indica uma definição inadequada de scripts de repoinit que faltam diretivas que definem essas estruturas de conteúdo ausentes, mas necessárias. Isso pode ser reproduzido localmente excluindo o AEM, descompactando o Jar e adicionando a configuração OSGi de repoinit contendo o script de repoinit para a pasta de instalação, e iniciando o AEM. O erro se apresenta no error.log de quickstart local do SDK do AEM.
A versão dos Componentes principais do aplicativo é superior à versão implantada
Esse problema afeta apenas ambientes não relacionados à produção que NÃO são atualizados automaticamente para a versão mais recente do AEM.
O AEM as a Cloud Service inclui automaticamente a versão mais recente dos Componentes principais em cada versão do AEM, o que significa que depois que um ambiente do AEM as a Cloud Service é atualizado, automática ou manualmente, ele recebe a versão mais recente dos Componentes principais implantada.
É possível para a etapa Criar imagem que falhará quando:
- O aplicativo de implantação atualiza a versão de dependência do Maven dos Componentes principais no projeto
core(pacote OSGi) - O aplicativo de implantação é então implantado em um ambiente de sandbox (não produção) do AEM as a Cloud Service que não foi atualizado para usar uma versão do AEM que contenha essa nova versão dos Componentes principais.
Para evitar essa falha, sempre que uma Atualização do ambiente do AEM as a Cloud Service estiver disponível, inclua a atualização como parte da próxima build/implantação e sempre verifique se as atualizações estão incluídas após incrementar a versão dos Componentes principais na base de código do aplicativo.
-
Sintomas:
A etapa Criar Imagem falha com um ERRO informando que o(s) pacote(s)com.adobe.cq.wcm.core.components...em intervalos de versões específicos não puderam ser importados pelo projetocore.code language-none [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: o pacote OSGi do aplicativo (definido no projeto
core) importa classes Java da dependência principal dos Componentes Principais, em um nível de versão diferente do que está implantado no AEM as a Cloud Service. -
Resolução:
- Usando o Git, reverta para uma confirmação de trabalho que existe antes do incremento de versão do Componente principal. Envie essa confirmação para uma ramificação Git do Cloud Manager e execute uma Atualização do ambiente a partir dessa ramificação. Isso atualizará o AEM as a Cloud Service para a versão mais recente do AEM, que incluirá a versão mais recente dos Componentes principais. Depois que o AEM as a Cloud Service for atualizado para a versão mais recente do AEM, que terá a versão mais recente dos Componentes principais, reimplante o código com falha original.
- Para reproduzir esse problema localmente, verifique se a versão do SDK do AEM é a mesma versão de lançamento do AEM que o ambiente do AEM as a Cloud Service está usando.
Criar um caso de suporte do Adobe
Se as abordagens de solução de problemas acima não resolverem o problema, crie um caso de suporte de Adobe, via:
-
Adobe Admin Console > Guia Suporte > Criar caso
Se você for membro de várias organizações de Adobe, verifique se a organização de Adobe que tem pipeline com falha está selecionada no alternador de organizações de Adobe antes de criar o caso.
Implantar em
A etapa Implantar em é responsável por pegar o artefato de código gerado na Imagem de compilação, iniciar novos serviços de Autor e Publish do AEM usando-o e, após o sucesso, remover qualquer serviço antigo de Autor e Publish do AEM. Os pacotes e índices de conteúdo mutável também são instalados e atualizados nesta etapa.
Familiarize-se com logs do AEM as a Cloud Service antes de depurar a etapa Implantar em. O log aemerror contém informações sobre a inicialização e o desligamento de pods que podem ser pertinentes à Implantação para problemas. Observe que o log disponível por meio do botão Baixar log na etapa Implantar em do Cloud Manager não é o log aemerror e não contém informações detalhadas relacionadas à inicialização dos aplicativos.
Os três principais motivos pelos quais a etapa Implantar em podem falhar:
O pipeline do Cloud Manager contém uma versão antiga de AEM
-
Causa: um pipeline do Cloud Manager contém uma versão de AEM mais antiga do que a implantada no ambiente de destino. Isso pode acontecer quando um pipeline é reutilizado e apontado para um novo ambiente que está executando uma versão posterior do AEM. Isso pode ser identificado verificando se a versão do AEM do ambiente é maior do que a versão do AEM do pipeline.
-
Resolução:
- Se o ambiente de destino tiver uma Atualização disponível, selecione Atualizar nas ações do ambiente e execute o build novamente.
- Se o ambiente de destino não tiver uma Atualização disponível, significa que ele está executando a versão mais recente do AEM. Para resolver isso, exclua o pipeline e recrie-o.
O Cloud Manager atinge o limite
O código em execução durante a inicialização do serviço AEM recém-implantado leva tanto tempo que o Cloud Manager atinge o tempo limite antes que a implantação possa ser concluída. Nesses casos, a implantação pode ser bem-sucedida, mesmo que o status do Cloud Manager seja considerado como Falha.
- Causa: o código personalizado pode executar operações, como consultas grandes ou percursos de conteúdo, acionadas antecipadamente no pacote OSGi ou ciclos de vida de Componente que atrasam significativamente o tempo de inicialização do AEM.
- Solução: revise a implementação do código que é executado antecipadamente no ciclo de vida do Pacote OSGi e revise os
aemerrorlogs dos serviços AEM Author e Publish no momento da falha (tempo de log em GMT), conforme mostrado pela Cloud Manager, e procure mensagens de log indicando quaisquer processos de execução de log personalizados.
Código ou configuração incompatível
A maioria das violações de código e configuração é capturada anteriormente na build. No entanto, é possível que o código ou a configuração personalizada seja incompatível com o AEM as a Cloud Service e não seja detectada até que seja executada no container.
-
Causa: o código personalizado pode invocar operações demoradas, como consultas grandes ou percursos de conteúdo, acionadas antecipadamente no pacote OSGi ou ciclos de vida de Componente que atrasam significativamente o tempo de inicialização do AEM.
-
Solução: revise os
aemerrorlogs dos serviços de Autor e Publish do AEM na hora (hora do log em GMT) da falha, conforme mostrado pela Cloud Manager.- Revise os logs para qualquer ERRO lançado pelas classes Java fornecidas pelo aplicativo personalizado. Se algum problema for encontrado, resolva, envie o código corrigido e recrie o pipeline.
- Revise os logs para quaisquer ERROS relatados por aspectos do AEM com os quais você está estendendo/interagindo no aplicativo personalizado e investigue-os; esses ERROS podem não ser diretamente atribuídos a classes Java. Se algum problema for encontrado, resolva, envie o código corrigido e recrie o pipeline.
Inclusão de /var no pacote de conteúdo
/var é mutável e contém uma variedade de conteúdos transitórios, de tempo de execução. Incluindo /var em pacotes de conteúdo (por exemplo, ui.content) implantado via Cloud Manager pode causar falha na etapa Implantar.
Esse problema é difícil de identificar, pois não resulta em falha na implantação inicial, somente em implantações subsequentes. Os sintomas perceptíveis incluem:
- A implantação inicial é bem-sucedida, no entanto, o conteúdo mutável novo ou alterado, que faz parte da implantação, parece não existir no serviço AEM Publish.
- Ativação/desativação de conteúdo no AEM Author está bloqueada
- As implantações subsequentes falham na etapa Implantar em, com a etapa Implantar em falhando após aproximadamente 60 minutos.
Para validar esse problema, é a causa do comportamento com falha:
-
Determinando que pelo menos um pacote de conteúdo faça parte da implantação, grava em
/var. -
Verifique se a fila de distribuição primária (em negrito) está bloqueada em:
-
AEM Author > Tools > Deployment > Distribution
-
-
Ao falhar na implantação subsequente, baixe os logs "Implantar em" da Cloud Manager usando o botão Baixar log:
… e verifique se há aproximadamente 60 minutos entre as instruções de registro:
code language-none 2020-01-01T01:01:02+0000 Begin deployment in aem-program-x-env-y-dev [CorrelationId: 1234]… e …
code language-none 2020-01-01T02:04:10+0000 Failed deployment in aem-program-x-env-y-devObserve que esse log não conterá esses indicadores nas implantações iniciais que relatam como bem-sucedido, apenas em implantações subsequentes com falha.
-
Causa: o usuário do serviço de replicação do AEM usado para implantar pacotes de conteúdo no serviço AEM Publish AEM não pode gravar em
/varno Publish. Isso resulta na falha da implantação do pacote de conteúdo no serviço AEM Publish. -
Solução: as seguintes maneiras de resolver esses problemas são listadas na ordem de preferência:
- Se os recursos
/varnão forem necessários, remova todos os recursos em/vardos pacotes de conteúdo que são implantados como parte do aplicativo. - Se os recursos
/varforem necessários, defina as estruturas de nó usando repoinit. Os scripts de repoinit podem ser direcionados para o AEM Author, AEM Publish ou ambos, por meio dos modos de execução OSGi. - Se os recursos
/varforem necessários apenas para o autor do AEM e não puderem ser modelados razoavelmente usando repoinit, mova-os para um pacote de conteúdo discreto, que só seja instalado no AEM Author por incorporação no pacoteallem uma pasta de modo de execução do AEM Author (<target>/apps/example-packages/content/install.author</target>). - Forneça ACLs apropriadas ao usuário do serviço
sling-distribution-importer, conforme descrito neste Adobe KB.
- Se os recursos
Criar um caso de suporte do Adobe
Se as abordagens de solução de problemas acima não resolverem o problema, crie um caso de suporte de Adobe, via:
-
Adobe Admin Console > Guia Suporte > Criar caso
Se você for membro de várias organizações de Adobe, verifique se a organização de Adobe que tem pipeline com falha está selecionada no alternador de organizações de Adobe antes de criar o caso.