Observação: este é um tópico um pouco mais avançado sobre Serviços de Entrega de Borda e Criação de Documentos. Para uma introdução ao EDS e à autoria de documentos, consulte primeiro este link para obter contexto.

Informações básicas sobre configurações de entrega do AEM Edge baseadas em arquivos e serviço de configuração.

Quando a Adobe lançou o Edge Delivery Services (ou Helix, como é conhecido internamente), toda a configuração principal do site era feita usando arquivos de configuração armazenados no repositório do site. A implantação de uma nova configuração foi feita enviando uma atualização para o branch main do repositório, o que colocou essa configuração em funcionamento no site. Uma desvantagem disso era que qualquer repositório específico precisava estar diretamente vinculado a um site e a um repositório de documentos. Nesse caso, não seria possível ter um único repositório de código gerenciando vários sites - ou mesmo várias versões de um único site (como ambientes no estilo dev/stg/prd para preparação de conteúdo ou configuração).

Como resultado disso e de outras questões técnicas, a Adobe vem migrando para um novo projeto de arquitetura baseado no Serviço de Configuração. Nesse paradigma, as configurações são armazenadas e versionadas centralmente pela Adobe em seu Serviço de Configuração baseado em API e, uma vez migrados para esse serviço, os arquivos do seu projeto Edge Delivery não terão mais efeito no site.

Pré-requisitos para migrar para o Serviço de Configuração

Conforme observado em https://www.aem.live/docs/config-service-setup#prerequisites, antes de iniciar a migração para o Config Service, você precisa primeiro garantir que seu usuário da Adobe esteja mapeado como administrador da sua organização do Github, para que você tenha autoridade no Config Service para fazer alterações. Seu contato técnico da Adobe, com quem você geralmente lida, deve conseguir te ajudar com isso.

Pontos de extremidade e superfícies de configuração afetados pela migração para o serviço de configuração.

Isso afeta as seguintes superfícies de configuração em um projeto de Entrega de Borda:

• Mapeamento do Content Bus: A configuração em /fstab.yaml onde o projeto mapeia para um local no DA (ou em outro lugar, como AEM/Universal Editor ou SharePoint) agora está no Config Service. Este é o ponto crucial que permite que um único repositório controle vários sites (anteriormente conhecido como configuração "sem repositório", pois significava que o repositório de código e o repositório de conteúdo não estavam inextricavelmente ligados).

• Índices de consulta: A configuração de índice para todos os idiomas foi previamente armazenada no projeto em /helix-query.yaml

• Configuração do sitemap: A configuração do sitemap anteriormente feita em /helix-sitemap.yaml agora estará no Serviço de Configuração.

• Configuração do Sidekick: Existem dois tipos diferentes de configurações do Sidekick que antes eram mantidas no projeto git, mas agora estão em outro local.

  • Plugins DA: Antigamente, nos primórdios do DA, mantínhamos os plugins DA no arquivo /tools/sidekick/config.json no repositório de código. Isso seria para coisas como as diversas melhorias na interface do usuário do DA, como nosso seletor de datas, o plugin de tags do AEM, etc. Agora, isso é mantido na planilha Library na configuração do DA no próprio DA, em vez de no código-fonte.
  • Plugins/Configurações do Sidekick: Outras configurações do AEM Sidekick, como a configuração para Edição Rápida ou para Experimentação do AEM, agora são mantidas diretamente no serviço de configuração, em vez de no DA. A configuração do Sidekick no projeto git do EDS não terá mais efeito.

• Configuração de cabeçalhos HTTP: Anteriormente, isso era mantido na folha headers do DA, mas agora será movido para o serviço de configuração. Isso serve para configuração CORS, como adicionar um cabeçalho access-control-allow-origin em determinados hosts.

• Autenticação de Pré-visualização/Publicação do Helix: Para o controle de acesso autenticado de Pré-visualização/Publicação, temos usado um modelo de autenticação baseado em planilhas, onde você teria uma planilha data em https://da.live/sheet#/[orgname]/[sitename]/.helix/config, na qual listamos as funções admin.role.author ou admin.role.publish para IDs de entidade Adobe individuais que mapeiam para usuários/perfis. Isso foi substituído pelo Config Service, e os usuários agora são gerenciados diretamente no Config Service para essas funções de pré-visualização/publicação, bem como para solicitações de acesso. Além disso, anteriormente, a publicação autenticada exigia que você usasse um perfil/ID de usuário da Adobe ilegível, como "[email protected]", que seria mapeado para o login de um usuário em uma organização específica. Agora, no Config Service, o Helix permitirá que você use seu endereço de e-mail em vez do ID de entidade ininteligível e até mesmo permitirá que os usuários "solicitem acesso" quando encontrarem problemas de visualização/publicação, o que será então exibido em um aplicativo de interface administrativa no DA para aprovar/negar as solicitações de acesso.

• Configuração do robots.txt: Anteriormente, isso era mantido em /robots.txt no projeto git, mas agora é configurado no Config Service.

• Configuração de CDN: Anteriormente, isso era mantido na planilha .helix/config no DA, mas agora é enviado para o Serviço de Configuração. Isso serviria para definir valores como:

  • cdn.prod.host
  • cdn.prod.type
  • cdn.prod.serviceId
  • cdn.prod.authToken

Etapas para migrar um site de entrega de borda baseado em arquivos existente para o Config Service.

Existe um comando migrate na API do AEM Admin (Helix) que permite migrar automaticamente uma configuração de entrega de borda baseada em arquivo para o Config Service. No entanto, existem algumas ressalvas, então aqui está o que você precisa saber sobre isso.

Primeiro, vamos supor que você já tenha um site criado no DA usando configuração baseada em arquivos (sei que tenho alguns sites assim, posso estar na minoria, mas este é o meu post no blog - você precisará reavaliar os passos para o seu caso específico).

Passos:

1. Certifique-se de ser administrador da sua organização: Conforme mencionado acima, trabalhe com a Adobe para garantir que você tenha admin na sua organização do Github. Valide isso acessando https://tools.aem.live/tools/site-admin/index.html e depois faça login. Se tudo funcionar corretamente, você deverá ver uma solicitação 200 bem-sucedida para https://admin.hlx.page/config/[orgname]/sites.json

2. Obtenha seu token de autenticação: Pressione shift+ctrl+I ou shift+cmd+I para abrir as ferramentas de desenvolvedor e observe a solicitação sites.json mencionada acima. Se você abrir a aba de rede e olhar os cabeçalhos, você verá um valor x-auth-token . Copie esse valor, pois esse é o token de portador que você precisará usar nas próximas solicitações de API para interagir com o Serviço de Configuração do AEM.

3. Faça uma cópia do seu site: É uma boa ideia fazer um teste no seu site (aquele com configurações baseadas em arquivos) para que você possa testar esse processo antes de executá-lo em produção. Crie um novo repositório e site EDS e preencha-o com a mesma base de código do seu site atual (caso ainda não possua um repositório de desenvolvimento). Idealmente, também, crie uma fonte de conteúdo de desenvolvimento para que você tenha um ambiente de testes totalmente equipado e operacional para experimentar.

4. Execute o comando Migrate em modo de teste: Execute o seguinte comando, que fará uma simulação da migração do serviço baseado em arquivos para o serviço de configuração:
   
   curl --request GET --url 'https://admin.hlx.page/config/{my-org}/sites/{my-site}.json?migrate=true&validate=true' -H "Authorization: token $MY_AUTH_TOKEN_NOTED_ABOVE"
   
   Se isso funcionar, exibirá um texto de validação como o seguinte, que indicará se a migração funcionará ou não. No meu caso, significa que NÃO estou pronto para migrar e tenho coisas a resolver:
   
   "error": "validation failed.", "message": "/sidekick/plugins/0/environments/0 must be equal to one of the allowed values; /sidekick/plugins/2/environments/0 must be equal to one of the allowed values",
   
   Além disso, se você receber um erro 400 (Bad Request) na sua invocação, também poderá usar o cabeçalho x-error na resposta HTTP, que também informará sobre quaisquer problemas na solicitação de simulação de migração:

   

   Neste caso, o erro está me dizendo que na minha lista de plugins do AEM Sidekick, o primeiro plugin em /tools/sidekick/config.json é inválido, pois configurar um plugin desta forma não é mais suportado no Config Service. Neste exemplo, preciso migrar este plugin para a planilha da Biblioteca DA para plugins do DA.

   

5. Corrija quaisquer problemas de validação conforme mencionado acima: você precisará revisar e corrigir quaisquer problemas que surgirem e, em seguida, executar novamente sua solicitação de validação.
   
   Pegue todos os plugins existentes definidos como plugins Sidekick no projeto e coloque-os no DA. No caso de problemas com o plugin Sidekick como este, os plugins DA seriam configurados em https://da.live/config#/[orgname]/[sitename]/ na aba "biblioteca" da planilha.

   

   Ou outro problema como este:

   

   Isso indica que tínhamos algumas propriedades ilegais em nossos cabeçalhos que não são mais suportadas (ou talvez nunca tenham sido suportadas e simplesmente não causavam problemas, então foram deixadas lá por engano).
   
   Assim que esses problemas forem resolvidos, você estará pronto para executar a migração propriamente dita.

6. Envie/Migre a configuração limpa e validada para o serviço de configuração: Para enviar a configuração, use o seguinte comando:
   
   curl --request POST --url 'https://admin.hlx.page/config/{my-org}/sites/{my-site}.json?migrate=true' -H "Authorization: token $MY_AUTH_TOKEN_NOTED_ABOVE"
   
   Essencialmente o mesmo comando que acima, mas com um POST em vez de um GET. Isso irá migrar você para o serviço de configuração.

7. Validação: Há algumas coisas que você precisa validar imediatamente após a migração.

   1. Validar índices: Acesse https://tools.aem.live/tools/index-admin/index.html e verifique se seus índices foram importados corretamente.
   2. Validar Sitemaps: Acesse https://tools.aem.live/tools/sitemap-admin/index.html e verifique se todos os sitemaps foram enviados corretamente.
   3. Validar usuários: Vá para https://tools.aem.live/tools/user-admin/index.html?org={orgname}&site={sitename} e verifique se seus usuários de Visualização/Publicação estão aparecendo lá.
   4. Validar usuários no DA: Vá para https://da.live/apps/aem-permissions#/{orgname}/{sitename} , que permitirá que você veja uma lista amigável das permissões de visualização/publicação conforme elas são expostas ao DA. É também aqui que você agora poderá
   5. Validar Pré-visualização/Publicação: Ao iniciar sessão como um utilizador com permissões de pré-visualização/publicação, certifique-se de que ainda consegue pré-visualizar/publicar corretamente. Obtenha um usuário que NÃO tenha acesso à pré-visualização ou publicação e certifique-se de que esse acesso esteja devidamente restrito.
   6. Qualquer outra validação diversa que você julgue necessária para o seu site.

8. Teste de estabilidade: Realize testes de qualidade e integração com a equipe, corrija quaisquer outros problemas de pré-visualização/publicação que surgirem e deixe a nova configuração em funcionamento por pelo menos uma semana para identificar quaisquer outros problemas que possam aparecer.

9. Limpeza dos arquivos de configuração: Após a conclusão do período de testes (burn-in), você não precisará mais das configurações internas do repositório e poderá começar a removê-las uma a uma. Recomendo manter cópias limpas das suas configurações atuais no Git para controle de versão, apenas para fins de recuperação de desastres, caso alguém faça uma requisição de API incorreta que, por algum motivo, não possa ser desfeita.

Notas sobre as implicações de CI/CD do Config Service

Uma observação sobre CI/CD: agora que você tem a flexibilidade inerente de um serviço de configuração baseado em API, você também tem a desvantagem de que seu CI/CD baseado em Git não terá mais efeito.

A boa notícia é que existem ferramentas como o Version Admin para acompanhar as alterações de configuração e quem fez cada alteração:

A má notícia é que isso remove a estrutura de CI/CD integrada e centrada em pull requests que todos conhecemos e adoramos no Edge Delivery. Portanto, se você tiver situações em que deseja que um engenheiro júnior proponha alterações, será significativamente mais difícil para ele fornecer uma solicitação de pull request que demonstre que a alteração de configuração proposta pode ser implementada com segurança.

A situação se complica ainda mais pelo fato de a autorização da API ser baseada no usuário atualmente conectado, o que torna um pouco difícil a integração de um conjunto persistente de chaves em um pipeline de CI/CD. Tenho certeza de que é possível, só vai exigir alguns ajustes.

Portanto, para isso (até o momento da redação deste texto), você precisará implementar seu próprio processo de CI/CD com o qual se sinta confortável, levando em consideração o tamanho e a estrutura da sua organização.

Espero que isso ajude, e por favor, entre em contato se tiver algum problema com alguma dessas etapas!

Sobre o autor

Gostou do que ouviu? Tem dúvidas sobre o que é certo para você? Adoraríamos conversar! Entre em contato conosco.

Mais artigos que você pode gostar