Show Menu
TÓPICOS×

Configuração do OSGi para o AEM as a Cloud Service

O OSGi é um elemento fundamental na pilha de tecnologia do Adobe Experience Manager (AEM). É usado para controlar os pacotes compostos do AEM e suas configurações.
O OSGi fornece as primitivas padronizadas que permitem que aplicativos sejam construídos a partir de componentes pequenos, reutilizáveis e colaborativos. Esses componentes podem ser compostos em um aplicativo e implantados. Isso permite o gerenciamento fácil de pacotes OSGi, pois eles podem ser interrompidos, instalados e iniciados individualmente. As interdependências são tratadas automaticamente. Cada componente OSGi está contido em um dos vários pacotes. Para obter mais informações, consulte a especificação do OSGi.
Você pode gerenciar as configurações de componentes OSGi por meio de arquivos de configuração que fazem parte de um projeto de código AEM.

Arquivos de configuração do OSGi

As alterações de configuração são definidas nos pacotes de código do AEM Project ( ui.apps ) como arquivos de configuração ( .cfg.json ) em pastas de configuração específicas do modo de execução:
/apps/example/config.<runmode>
O formato dos arquivos de configuração OSGi é baseado em JSON, usando o .cfg.json formato definido pelo projeto Apache Sling.
As configurações OSGi públicos alvos componentes OSGi por meio de sua identificação persistente (PID), que assume o nome padrão da classe Java do componente OSGi. Por exemplo, para fornecer configuração OSGi para um serviço OSGi implementado por:
com.example.workflow.impl.ApprovalWorkflow.java
um arquivo de configuração OSGi é definido em:
/apps/example/config/com.example.workflow.impl.ApprovalWorkflow.cfg.json
seguindo o formato de configuração cfg.json OSGi.
Versões anteriores de arquivos de configuração OSGi com suporte do AEM usando diferentes formatos de arquivo, como .cfg., .config e como definições de recurso XML sling:OsgiConfig. Esses formatos são substituídos pelo formato de configuração cfg.json OSGi.

Resolução do modo de execução

Configurações específicas de OSGi podem ser direcionadas a instâncias específicas de AEM usando modos de execução. Para usar o modo de execução, crie pastas de configuração em /apps/example (onde exemplo é o nome do projeto), no formato:
/apps/example/config.<author|publish>.<dev|stage|prod>/
Quaisquer configurações OSGi nessas pastas serão usadas se os modos de execução definidos no nome da pasta de configuração corresponderem aos modos de execução usados pelo AEM.
Por exemplo, se o AEM estiver usando o autor e o dev do runmode, nós de configuração em /apps/example/config.author/ e /apps/example/config.author.dev/ serão aplicados, enquanto nós de configuração em /apps/example/config.publish/ e não /apps/example/config.author.stage/ serão aplicados.
Se várias configurações para o mesmo PID forem aplicáveis, a configuração com o maior número de modos de execução correspondentes será aplicada.
A granularidade desta regra está em um nível PID. Isso significa que não é possível definir algumas propriedades para o mesmo PID em /apps/example/config.author/ e mais específicas em /apps/example/config.author.dev/ para o mesmo PID. A configuração com o maior número de modos de execução correspondentes será eficaz para todo o PID.
Ao desenvolver localmente, um parâmetro de inicialização do modo de execução pode ser passado para ditar qual configuração do modo de execução OSGI será usada.

Tipos de valores de configuração OSGi

Há três variedades de valores de configuração OSGi que podem ser usadas com o AEM como Cloud Service.
  1. Valores em linha, que são valores codificados permanentemente na configuração OSGi e armazenados em Git. Por exemplo:
    {
       "connection.timeout": 1000
    }
    
    
  2. Valores secretos, que são valores que não devem ser armazenados em Git por motivos de segurança. Por exemplo:
    {
    "api-key": "$[secret:server-api-key]"
    } 
    
    
  3. Valores específicos do Ambiente, que são valores que variam entre ambientes de desenvolvimento e, portanto, não podem ser direcionados com precisão pelo modo de execução (já que há um único dev modo de execução no AEM como Cloud Service). Por exemplo:
    {
     "url": "$[env:server-url]"
    }
    
    
    Observe que um único arquivo de configuração OSGi pode usar qualquer combinação desses tipos de valor de configuração em conjunto. Por exemplo:
    {
    "connection.timeout": 1000,
    "api-key": "$[secret:server-api-key]",
    "url": "$[env:server-url]"
    }
    
    

Como escolher o tipo de valor de configuração OSGi apropriado

O caso comum para OSGi usa valores de configuração OSGi em linha. As configurações específicas do Ambiente são usadas apenas para casos de uso específicos em que um valor é diferente entre ambientes dev.
As configurações específicas do Ambiente estendem as configurações OSGi tradicionais e definidas estaticamente que contêm valores em linha, proporcionando a capacidade de gerenciar os valores de configuração OSGi externamente por meio da API do Cloud Manager. É importante entender quando deve ser usada a abordagem comum e tradicional de definir valores em linha e armazená-los em Git, em vez de abstrair os valores em configurações específicas do ambiente.
As orientações a seguir abordam quando usar configurações não secretas e secretas específicas do ambiente:

Quando usar valores de configuração embutidos

Os valores de configurações em linha são considerados a abordagem padrão e devem ser usados quando possível. As configurações em linha oferecem os benefícios de:
  • Eles são mantidos, com governança e histórico de versões no Git
  • Os valores estão implicitamente vinculados às implantações de código
  • Eles não exigem considerações adicionais de implantação nem coordenação
Sempre que definir um valor de configuração OSGi, start com valores em linha, qualquer configuração secreta ou específica do ambiente só será selecionada se necessário para o caso de uso.

Quando usar valores de configuração não secretos específicos para Ambientes

Use apenas configurações específicas do ambiente ( $[env:ENV_VAR_NAME] ) para valores de configuração não secretos quando os valores variarem entre ambientes de desenvolvimento. Isso inclui instâncias de desenvolvimento local e qualquer AEM como ambientes de desenvolvimento de Cloud Service. Evite usar configurações não secretas específicas de ambientes para o AEM como um Cloud Service Stage ou ambientes de produção.
  • Use apenas configurações não secretas específicas do ambiente para valores de configuração que diferem entre ambientes de desenvolvimento, incluindo instâncias de desenvolvimento local.
  • Em vez disso, use os valores em linha padrão nas configurações OSGi para valores não secretos de Fase e Produção. Neste contexto, não é recomendável usar configurações específicas do ambiente para facilitar as alterações de configuração no tempo de execução para o Palco e ambientes de Produção; estas alterações devem ser introduzidas através da gestão do código fonte.

Quando usar valores de configuração secretos específicos do ambiente

O AEM como Cloud Service requer o uso de configurações específicas do ambiente ( $[secret:SECRET_VAR_NAME] ) para quaisquer valores secretos de configuração OSGi, como senhas, chaves de API privadas ou quaisquer outros valores que não possam ser armazenados no Git por motivos de segurança.
Use configurações secretas específicas ao ambiente para armazenar o valor dos segredos em todo o AEM como ambientes Cloud Service, incluindo o Palco e a Produção.

Criação de configurações OSGi

Há duas maneiras de criar novas configurações OSGi, conforme descrito abaixo. A primeira abordagem é normalmente usada para configurar componentes OSGi personalizados que têm propriedades e valores OSGi conhecidos pelo desenvolvedor, e a última para componentes OSGi fornecidos pelo AEM.

Gravando configurações OSGi

Os arquivos de configuração OSGi formatados JSON podem ser gravados manualmente diretamente no projeto AEM. Geralmente, essa é a maneira mais rápida de criar configurações OSGi para componentes OSGi conhecidos, e especialmente componentes OSGi personalizados que foram projetados e desenvolvidos pelo mesmo desenvolvedor que define as configurações. Essa abordagem também pode ser aproveitada para copiar/colar e atualizar configurações para o mesmo componente OSGi em várias pastas do modo de execução.
  1. No IDE, abra o ui.apps projeto, localize ou crie a pasta de configuração ( /apps/.../config.<runmode> ) que público alvo os modos de execução que a nova configuração do OSGi deve afetar
  2. Nesta pasta de configuração, crie um novo <PID>.cfg.json arquivo. O PID é a Identidade persistente do componente OSGi, geralmente é o nome de classe completo da implementação do componente OSGi. Por exemplo: /apps/.../config/com.example.workflow.impl.ApprovalWorkflow.cfg.json Observe que os nomes dos arquivos de fábrica de configuração do OSGi usam a convenção de <PID>-<factory-name>.cfg.json nomenclatura
  3. Abra o novo .cfg.json arquivo e defina as combinações de chave/valor para a propriedade OSGi e os pares de valores, seguindo o formato de configuração JSON OSGi.
  4. Salve as alterações no novo .cfg.json arquivo
  5. Adicione e confirme seu novo arquivo de configuração OSGi ao Git

Geração de configurações OSGi usando o Início rápido do SDK do AEM

O console da Web do AEM SDK Quickstart Jar pode ser usado para configurar componentes OSGi e exportar configurações OSGi como JSON. Isso é útil para configurar componentes OSGi fornecidos pelo AEM cujas propriedades OSGi e seus formatos de valor podem não ser bem entendidos pelo desenvolvedor que define as configurações OSGi no projeto do AEM. Observe que usar a interface de usuário de configuração do console da Web do AEM grava .cfg.json arquivos no repositório, portanto, esteja ciente disso para evitar um comportamento inesperado durante o desenvolvimento local, quando as configurações de OSGi definidas pelo projeto do AEM podem diferir das configurações geradas.
  1. Faça logon no console da Web do AEM SDK Quickstart Jar como o usuário administrador
  2. Navegue até OSGi > Configuração
  3. Localize o componente OSGi a ser configurado e toque em seu título para editar
  4. Edite os valores de propriedade de configuração do OSGi por meio da interface do usuário da Web, conforme necessário
  5. Registrar a Identidade Persistente (PID) em local seguro, isso será usado posteriormente para gerar a configuração JSON da configuração OSGi
  6. Toque em Salvar
  7. Navegue até OSGi > Impressora de configuração do instalador OSGi
  8. Colar no PID copiado na Etapa 5, certifique-se de que o Formato de serialização esteja definido como "OSGi Configurator JSON"
  9. Toque em Imprimir,
  10. A configuração OSGi no formato JSON será exibida na seção Propriedades de configuração serializadas
  11. No IDE, abra o ui.apps projeto, localize ou crie a pasta de configuração ( /apps/.../config.<runmode> ) que público alvo os modos de execução que a nova configuração do OSGi deve afetar.
  12. Nesta pasta de configuração, crie um novo <PID>.cfg.json arquivo. O PID tem o mesmo valor da Etapa 5.
  13. Cole as Propriedades de configuração serializadas da Etapa 10 no .cfg.json arquivo.
  14. Salve as alterações no novo .cfg.json arquivo.
  15. Adicione e confirme seu novo arquivo de configuração OSGi ao Git.

Formatos de propriedade de configuração OSGi

Valores em linha

Como seria de esperar, os valores em linha são formatados como pares padrão de nome-valor, seguindo a sintaxe JSON padrão. Por exemplo:
{
   "my_var1": "val",
   "my_var2": [ "abc", "def" ],
   "my_var3": 500
}

Valores de Configuração Específicos do Ambiente

A configuração do OSGi deve atribuir um espaço reservado para a variável que deve ser definida por ambiente:
use $[env:ENV_VAR_NAME]

Os clientes só devem utilizar esta técnica para as propriedades de configuração OSGI relacionadas com o respectivo código personalizado; ele não deve ser usado para substituir a configuração OSGI definida pela Adobe.

Valores de configuração secretos

A configuração do OSGi deve atribuir um espaço reservado para o segredo que deve ser definido por ambiente:
use $[secret:SECRET_VAR_NAME]

Nomeação de variável

O seguinte se aplica aos valores de configuração específicos e secretos do ambiente.
Os nomes das variáveis devem seguir as seguintes regras:
  • Comprimento mínimo: 2
  • Comprimento máximo: 100
  • deve corresponder a regex: [a-zA-Z_][a-zA-Z_0-9]*
Os valores das variáveis não devem exceder 2048 caracteres.

Valores padrão

O seguinte se aplica aos valores de configuração específicos e secretos do ambiente.
Se nenhum valor por ambiente for definido, no tempo de execução o espaço reservado não será substituído e mantido no lugar, pois nenhuma interpolação ocorreu. Para evitar isso, um valor padrão pode ser fornecido como parte do espaço reservado com a seguinte sintaxe:
$[env:ENV_VAR_NAME;default=<value>]

Com um valor padrão fornecido, o espaço reservado será substituído pelo valor por ambiente, se fornecido, ou pelo valor padrão fornecido.

Desenvolvimento local

O seguinte se aplica aos valores de configuração específicos e secretos do ambiente.
As variáveis podem ser definidas no ambiente local para que sejam coletadas pelo AEM local no tempo de execução. Por exemplo, no Linux:
export ENV_VAR_NAME=my_value

É recomendável que um script bash simples seja gravado, que defina as variáveis de ambiente usadas nas configurações e execute-o antes de iniciar o AEM. Ferramentas como https://direnv.net/ ajudam a simplificar essa abordagem. Dependendo do tipo de valores, eles podem ser verificados no gerenciamento de código-fonte, se puderem ser compartilhados entre todos.
Os valores para segredos são lidos de arquivos. Portanto, para cada espaço reservado que usa um segredo, é necessário criar um arquivo de texto contendo o valor secreto.
Por exemplo, se $[secret:server_password] for usado, um arquivo de texto chamado server_password precisa ser criado. Todos esses arquivos secretos precisam ser armazenados no mesmo diretório e a propriedade framework org.apache.felix.configadmin.plugin.interpolation.secretsdir precisa ser configurada com esse diretório local.

Configuração de autor versus publicação

Se uma propriedade OSGI exigir valores diferentes para autor versus publicação:
  • pastas separadas config.author e config.publish OSGi devem ser usadas, conforme descrito na seção Resolução Runmode.
  • devem ser usados nomes de variáveis independentes. É recomendável usar um prefixo como author_<variablename> e publish_<variablename> onde os nomes das variáveis sejam os mesmos

Exemplos de configuração

Nos exemplos abaixo, suponha que haja 3 ambientes dev, além dos ambientes stage e prod.
Exemplo 1
O objetivo é que o valor da propriedade OSGI seja igual my_var1 para stage e prod, mas diferente para cada um dos três ambientes dev.
Pasta Conteúdo de myfile.cfg.json
configuração
{ "my_var1": "val", "my_var2": "abc", "my_var3": 500}


config.dev
{ "my_var1" : "$[env:my_var1]" "my_var2": "abc", "my_var3": 500}


Exemplo 2
O objetivo é que o valor da propriedade OSGI seja diferente my_var1 para stage, prod e para cada um dos 3 ambientes dev. Assim, a API do Gerenciador de nuvem precisará ser chamada para definir o valor para my_var1 cada adenv dev.
Pasta Conteúdo de myfile.cfg.json
config.stage
{ "my_var1": "val1", "my_var2": "abc", "my_var3": 500}


config.prod
{ "my_var1": "val2", "my_var2": "abc", "my_var3": 500}


config.dev
{ "my_var1" : "$[env:my_var1]" "my_var2": "abc", "my_var3": 500}


Exemplo 3
A intenção é que o valor da propriedade OSGi seja o mesmo para o palco, produção e apenas um dos ambientes dev, mas que seja diferente para os outros dois ambientes dev. my_var1 Nesse caso, a API do Gerenciador de nuvem precisará ser chamada para definir o valor de my_var1 cada um dos ambientes dev, incluindo o ambiente dev que deve ter o mesmo valor que stage e production. Ele não herdará o valor definido na configuração da pasta.
Pasta Conteúdo de myfile.cfg.json
configuração
{ "my_var1": "val1", "my_var2": "abc", "my_var3": 500}


config.dev
{ "my_var1" : "$[env:my_var1]" "my_var2": "abc", "my_var3": 500}


Outra maneira de fazer isso seria definir um valor padrão para o token de substituição na pasta config.dev de modo que ele tenha o mesmo valor que na pasta config .
Pasta Conteúdo de myfile.cfg.json
configuração
{ "my_var1": "val1", "my_var2": "abc", "my_var3": 500}


config.dev
{ "my_var1": "$[env:my_var1;default=val1]" "my_var2": "abc", "my_var3": 500}


Formato da API do Cloud Manager para a definição de propriedades

Configuração de valores por API

A chamada da API implantará as novas variáveis e valores em um ambiente da Cloud, de modo semelhante a um pipeline de implantação de código de cliente típico. Os serviços de autor e publicação serão reiniciados e farão referência aos novos valores, normalmente demorando alguns minutos.
PATCH /program/{programId}/environment/{environmentId}/variables

]
        {
                "name" : "MY_VAR1",
                "value" : "plaintext value",
                "type" : "string"  <---default
        },
        {
                "name" : "MY_VAR2",
                "value" : "<secret value>",
                "type" : "secretString"
        }
]

Observe que as variáveis padrão não são definidas por API, mas na própria propriedade OSGi.
Consulte esta página para obter mais informações.

Obter valores por meio da API

GET /program/{programId}/environment/{environmentId}/variables

Consulte esta página para obter mais informações.

Excluindo valores por meio da API

PATCH /program/{programId}/environment/{environmentId}/variables

Para excluir uma variável, inclua-a com um valor vazio.
Consulte esta página para obter mais informações.

Obtendo valores pela linha de comando

$ aio cloudmanager:list-environment-variables ENVIRONMENT_ID
Name     Type         Value
MY_VAR1  string       plaintext value 
MY_VAR2  secretString ****

Configuração de valores pela Linha de Comando

$ aio cloudmanager:set-environment-variables ENVIRONMENT_ID --variable MY_VAR1 "plaintext value" --secret MY_VAR2 "some secret value"

Exclusão de valores pela linha de comando

$ aio cloudmanager:set-environment-variables ENVIRONMENT_ID --delete MY_VAR1 MY_VAR2

Consulte esta página para obter mais informações sobre como configurar valores usando o plug-in do Gerenciador de nuvem para a CLI de E/S da Adobe.

Número de variáveis

Até 200 variáveis por ambiente podem ser declaradas.

Considerações de implantação para valores de configuração secretos e específicos do Ambiente

Como os valores de configuração secretos e específicos do ambiente vivem fora do Git e, portanto, não fazem parte do AEM formal como um mecanismo de implantação do Cloud Service, o cliente deve gerenciar, administrar e integrar o AEM como um processo de implantação do Cloud Service.
Como mencionado acima, chamar a API implantará as novas variáveis e valores em ambientes da Cloud, de modo semelhante a um pipeline de implantação de código do cliente típico. Os serviços de autor e publicação serão reiniciados e farão referência aos novos valores, normalmente demorando alguns minutos. Observe que as portas de qualidade e os testes executados pelo Gerenciador de nuvem durante uma implantação regular de código não são executados durante esse processo.
Normalmente, os clientes ligam para a API para definir variáveis de ambiente antes de implantar um código que depende deles no Cloud Manager. Em algumas situações, é possível modificar uma variável existente após a implantação do código.
Observe que a API pode não ter êxito quando um pipeline está em uso, seja uma atualização do AEM ou implantação do cliente, dependendo de qual parte do pipeline de fim a fim está sendo executada no momento. A resposta ao erro indicará que a solicitação não foi bem-sucedida, embora não indique o motivo específico.
Pode haver situações em que uma implantação programada de código de cliente dependa de variáveis existentes para ter novos valores, o que não seria apropriado com o código atual. Se isso for uma preocupação, é recomendável fazer modificações variáveis de uma forma aditiva. Para fazer isso, crie novos nomes de variáveis em vez de apenas alterar o valor de variáveis antigas para que o código antigo nunca faça referência ao novo valor. Em seguida, quando a nova versão do cliente parecer estável, é possível optar por remover os valores mais antigos.
Da mesma forma, como os valores de uma variável não têm controle de versão, uma reversão do código pode fazer com que ele faça referência a valores mais recentes que causam problemas. A estratégia de variáveis aditivas acima mencionada também ajudaria neste caso.
Essa estratégia de variável aditiva também é útil para cenários de recuperação de desastres em que, se o código de vários dias antes precisar ser implantado novamente, os nomes e os valores de variável aos quais ele faz referência permanecerão intactos. Isso depende de uma estratégia em que um cliente espera alguns dias antes de remover essas variáveis mais antigas, caso contrário, o código mais antigo não teria variáveis apropriadas para fazer referência.