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 do Java e da 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, consulte as regras de verificação de código personalizadas 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 build 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: todos os pacotes do projeto do 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 Criar Imagem não poder decidir qual deve ser usado, desta forma falhando na compilação. 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 projeto do 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 AEM SDK 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 AEM SDK e, mas causar falha na etapa Criar imagem, interromper 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 AEM SDK 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. Na inicialização rápida local do AEM SDK, 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 incorrido em 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 à pasta de instalação, e iniciando o AEM. O erro se apresentará no error.log do AEM SDK local quickstart.
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, ou seja, 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 contém 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 que originalmente estava falhando.
- Para reproduzir esse problema localmente, verifique se a versão do AEM SDK é a mesma versão 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 do Adobe, via:
-
Adobe Admin Console > Guia Suporte > Criar caso
Se você for membro de várias organizações da Adobe, verifique se a organização da Adobe que tem pipeline com falha está selecionada no alternador de organizações da Adobe antes de criar o caso.
Implantar em
A etapa Implantar em é responsável por obter o artefato de código gerado na Imagem de compilação, iniciar os novos serviços de Autor e Publicação do AEM usando-o e, após o sucesso, remover todos os serviços antigos de Autor e Publicação 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 do AEM
-
Causa: um pipeline do Cloud Manager contém uma versão do 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 ao verificar se a versão do AEM do ambiente é superior à 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 passagens 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 logs
aemerrordos serviços de Autor e Publicação do AEM 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 Publicação do AEM por volta da 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 qualquer ERRO relatado por aspectos do AEM que você está estendendo/interagindo com 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 de Publicação do AEM.
- A 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:
-
Autor do AEM > Ferramentas > Implantação > Distribuição
-
-
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 da AEM usado para implantar pacotes de conteúdo no serviço de Publicação do AEM não pode gravar em
/varno AEM Publish. Isso resulta na falha da implantação do pacote de conteúdo no serviço de Publicação do AEM. -
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 Autor do AEM, Publicação do AEM ou ambos, por meio dos modos de execução OSGi. - Se os recursos
/varforem necessários apenas no autor do AEM e não puderem ser modelados razoavelmente usando repoinit, mova-os para um pacote de conteúdo distinto, 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 nesta Base de Dados de Conhecimento do Adobe.
- 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 do Adobe, via:
-
Adobe Admin Console > Guia Suporte > Criar caso
Se você for membro de várias organizações da Adobe, verifique se a organização da Adobe que tem pipeline com falha está selecionada no alternador de organizações da Adobe antes de criar o caso.