Implantar manualmente um aplicativo Java com o JBoss EAP em um cluster do Azure Red Hat OpenShift

Artigo
01/08/2025

Este artigo mostra como implantar um aplicativo Red Hat JBoss Enterprise Application Platform (EAP) em um cluster do Azure Red Hat OpenShift. O exemplo é um aplicativo Java apoiado por um banco de dados SQL. O aplicativo é implantado usando JBoss EAP Helm Charts.

Neste guia, você aprenderá a:

Prepare um aplicativo JBoss EAP para OpenShift.
Crie uma única instância de banco de dados do Banco de Dados SQL do Azure.
- Como a Identidade de Carga de Trabalho do Azure ainda não é suportada pelo Azure OpenShift, este artigo ainda usa nome de usuário e senha para autenticação de banco de dados em vez de usar conexões de banco de dados sem senha.
Implantar o aplicativo em um cluster do Azure Red Hat OpenShift usando JBoss Helm Charts e OpenShift Web Console

O aplicativo de exemplo é um aplicativo com monitoração de estado que armazena informações em uma sessão HTTP. Ele faz uso dos recursos de clustering do JBoss EAP e usa as seguintes tecnologias Jakarta EE e MicroProfile:

Jacarta Server Faces
Jacarta Enterprise Beans
Persistência em Jacarta
Estado de funcionamento do microperfil

Este artigo é uma orientação manual passo a passo para executar o aplicativo JBoss EAP em um cluster do Azure Red Hat OpenShift. Para obter uma solução mais automatizada que acelera sua jornada para o cluster do Azure Red Hat OpenShift, consulte Guia de início rápido: implantar o JBoss EAP no Red Hat OpenShift do Azure usando o portal do Azure.

Se você estiver interessado em fornecer comentários ou trabalhar em estreita colaboração em seu cenário de migração com a equipe de engenharia que desenvolve o JBoss EAP em soluções do Azure, preencha esta breve pesquisa sobre a migração do JBoss EAP e inclua suas informações de contato. A equipe de gerentes de programa, arquitetos e engenheiros entrará prontamente em contato com você para iniciar uma estreita colaboração.

Importante

Este artigo implanta um aplicativo usando JBoss EAP Helm Charts. No momento em que este artigo foi escrito, esse recurso ainda é oferecido como uma visualização de tecnologia. Antes de optar por implantar aplicativos com JBoss EAP Helm Charts em ambientes de produção, verifique se esse recurso é um recurso suportado para sua versão do produto JBoss EAP/XP.

Importante

Embora a Red Hat e o Microsoft Azure projetem, operem e ofereçam suporte ao Azure Red Hat OpenShift para fornecer uma experiência de suporte integrada, o software executado sobre o Azure Red Hat OpenShift, incluindo o descrito neste artigo, está sujeito aos seus próprios termos de suporte e licença. Para obter detalhes sobre o suporte do Azure Red Hat OpenShift, consulte Ciclo de vida do suporte para o Azure Red Hat OpenShift 4. Para obter detalhes sobre o suporte do software descrito neste artigo, consulte as páginas principais desse software, conforme listado no artigo.

Pré-requisitos

Nota

O Azure Red Hat OpenShift requer, pelo menos, 40 núcleos para criar e executar um cluster do OpenShift. A cota de recursos padrão do Azure para uma nova assinatura do Azure não atende a esse requisito. Para solicitar um aumento no limite de recursos, consulte Cota padrão: aumentar limites por série de VMs. A subscrição de avaliação gratuita não é elegível para um aumento de quota atualize para uma subscrição Pay-As-You-Go antes de solicitar um aumento de quota.

Prepare uma máquina local com um sistema operacional Unix-like suportado pelos vários produtos instalados - como Ubuntu, macOS ou Windows Subsystem para Linux.
Instale uma implementação Java Standard Edition (SE). As etapas de desenvolvimento local neste artigo foram testadas com o Java Development Kit (JDK) 17 da compilação Microsoft do OpenJDK.
Instale o Maven 3.8.6 ou posterior.
Instale a CLI do Azure 2.40 ou posterior.
Clone o código para este aplicativo de demonstração (todo-list) para o seu sistema local. O aplicativo de demonstração está no GitHub.
Siga as instruções em Criar um cluster do Azure Red Hat OpenShift 4.

Embora a etapa "Obter um segredo de pull da Red Hat" esteja rotulada como opcional, ela é necessária para este artigo. O segredo de pull permite que seu cluster Azure Red Hat OpenShift localize as imagens do aplicativo JBoss EAP.

Se você planeja executar aplicativos que consomem muita memória no cluster, especifique o tamanho adequado da máquina virtual para os nós de trabalho usando o --worker-vm-size parâmetro. Para obter mais informações, consulte:
- CLI do Azure para criar um cluster
- Tamanhos de máquinas virtuais suportados para memória otimizada
Conecte-se ao cluster seguindo as etapas em Conectar-se a um cluster do Azure Red Hat OpenShift 4.
- Siga as etapas em "Instalar a CLI do OpenShift"
- Conectar-se a um cluster do Azure Red Hat OpenShift usando a CLI do OpenShift com o usuário kubeadmin
Execute o seguinte comando para criar o projeto OpenShift para este aplicativo de demonstração:
```
oc new-project eap-demo
```
Execute o seguinte comando para adicionar a função de exibição à conta de serviço padrão. Essa função é necessária para que o aplicativo possa descobrir outros pods e configurar um cluster com eles:
```
oc policy add-role-to-user view system:serviceaccount:$(oc project -q):default -n $(oc project -q)
```

Preparar a candidatura

Clone o aplicativo de exemplo usando o seguinte comando:

git clone https://github.com/Azure-Samples/jboss-on-aro-jakartaee

Você clonou o aplicativo de demonstração Todo-list e seu repositório local está na ramificação principal . O aplicativo de demonstração é um aplicativo Java simples que cria, lê, atualiza e exclui registros no Azure SQL. Você pode implantar este aplicativo como ele está em um servidor JBoss EAP instalado em sua máquina local. Você só precisa configurar o servidor com o driver de banco de dados e a fonte de dados necessários. Você também precisa de um servidor de banco de dados acessível a partir do seu ambiente local.

No entanto, ao direcionar o OpenShift, convém cortar os recursos do servidor JBoss EAP. Por exemplo, talvez você queira reduzir a exposição à segurança do servidor provisionado e reduzir o espaço ocupado em geral. Você também pode querer incluir algumas especificações do MicroProfile para tornar seu aplicativo mais adequado para execução em um ambiente OpenShift. Quando você usa o JBoss EAP, uma maneira de realizar essa tarefa é empacotando seu aplicativo e seu servidor em uma única unidade de implementação conhecida como JAR inicializável. Vamos fazer isso adicionando as alterações necessárias ao nosso aplicativo de demonstração.

Navegue até ao repositório local da sua aplicação de demonstração e altere o ramo para o jar inicializável :

## cd jboss-on-aro-jakartaee
git checkout bootable-jar

Vamos fazer uma breve revisão do que mudamos neste ramo:

Adicionamos o wildfly-jar-maven plugin para provisionar o servidor e o aplicativo em um único arquivo JAR executável. A unidade de implementação OpenShift é o nosso servidor com a nossa aplicação.
No plug-in Maven, especificamos um conjunto de camadas do Galeão. Esta configuração permite-nos reduzir as capacidades do servidor apenas para o que precisamos. Para obter a documentação completa sobre o Galeão, consulte a documentação do WildFly.
Nosso aplicativo usa Jakarta Faces com solicitações Ajax, o que significa que há informações armazenadas na sessão HTTP. Não queremos perder essas informações se um pod for removido. Poderíamos guardar esta informação no cliente e devolvê-la em cada pedido. No entanto, há casos em que você pode decidir não distribuir determinadas informações aos clientes. Para esta demonstração, optamos por replicar a sessão em todas as réplicas de pod. Para isso, adicionámos <distributable /> ao web.xml. Isso, juntamente com os recursos de clustering de servidor, torna a sessão HTTP distribuível em todos os pods.
Adicionamos duas verificações de integridade do MicroProfile que permitem identificar quando o aplicativo está ativo e pronto para receber solicitações.

Executar a aplicação localmente

Antes de implantar o aplicativo no OpenShift, vamos executá-lo localmente para verificar como ele funciona. As etapas a seguir pressupõem que você tenha o SQL do Azure em execução e disponível em seu ambiente local.

Para criar o banco de dados, siga as etapas em Guia de início rápido: criar um banco de dados único do Banco de Dados SQL do Azure, mas use as substituições a seguir.

Para Grupo de recursos , use o grupo de recursos criado anteriormente.
Para Nome do banco de dados, use todos_db.
Para login de administrador do servidor, use azureuser.
Para Passw0rd! .
Na seção Regras de firewall, alterne a opção Permitir que os serviços e recursos do Azure acessem este servidor para Sim.

Todas as outras configurações podem ser usadas com segurança a partir do artigo vinculado.

Na página Configurações adicionais, você não precisa escolher a opção para pré-preencher o banco de dados com dados de exemplo, mas não há nenhum dano em fazer isso.

Depois de criar o banco de dados, obtenha o valor para o nome do servidor na página de visão geral. Passe o mouse sobre o valor do campo Nome do servidor e selecione o ícone de cópia que aparece ao lado do valor. Salve esse valor de lado para uso posterior (definimos uma variável chamada MSSQLSERVER_HOST para esse valor).

Nota

Para manter os custos monetários baixos, o Guia de início rápido direciona o leitor para selecionar a camada de computação sem servidor. Essa camada é dimensionada para zero quando não há atividade. Quando isso acontece, o banco de dados não responde imediatamente. Se, em algum momento ao executar as etapas neste artigo, você observar problemas no banco de dados, considere desativar a pausa automática. Para saber como, pesquise Pausa automática no Banco de Dados SQL do Azure sem servidor. No momento da escrita, o seguinte comando da CLI do Azure desabilita a pausa automática para o banco de dados configurado neste artigo: az sql db update --resource-group $RESOURCEGROUP --server <Server name, without the .database.windows.net part> --name todos_db --auto-pause-delay -1

Siga as próximas etapas para criar e executar o aplicativo localmente.

Crie o JAR inicializável. Como estamos usando o banco de dados com o eap-datasources-galleon-pack MS SQL Server, devemos especificar a versão do driver de banco de dados que queremos usar com essa variável de ambiente específica. Para obter mais informações sobre o e o eap-datasources-galleon-pack MS SQL Server, consulte a documentação da Red Hat
```
export MSSQLSERVER_DRIVER_VERSION=7.4.1.jre11
mvn clean package
```
Inicie o JAR inicializável usando os seguintes comandos.

Você deve garantir que o banco de dados SQL do Azure permita o tráfego de rede do host no qual esse servidor está sendo executado. Como você selecionou Adicionar endereço IP do cliente atual ao executar as etapas em Guia de início rápido: criar um banco de dados único do Banco de Dados SQL do Azure, se o host no qual o servidor está sendo executado for o mesmo host do qual seu navegador está se conectando ao portal do Azure, o tráfego de rede deverá ser permitido. Se o host no qual o servidor está sendo executado for algum outro host, você precisará consultar Usar o portal do Azure para gerenciar regras de firewall IP no nível do servidor.

Quando estamos iniciando o aplicativo, precisamos passar as variáveis de ambiente necessárias para configurar a fonte de dados:
```
export MSSQLSERVER_USER=azureuser
export MSSQLSERVER_PASSWORD='Passw0rd!'
export MSSQLSERVER_JNDI=java:/comp/env/jdbc/mssqlds
export MSSQLSERVER_DATABASE=todos_db
export MSSQLSERVER_HOST=<server name saved aside earlier>
export MSSQLSERVER_PORT=1433
mvn wildfly-jar:run
```
Se você quiser saber mais sobre o tempo de execução subjacente usado por esta demonstração, o Galleon Feature Pack para integrar a documentação de fontes de dados tem uma lista completa de variáveis de ambiente disponíveis. Para obter detalhes sobre o conceito de pacote de recursos, consulte a documentação do WildFly.

Se você receber um erro com texto semelhante ao exemplo a seguir:
```
Cannot open server '<your prefix>mysqlserver' requested by the login. Client with IP address 'XXX.XXX.XXX.XXX' is not allowed to access the server.
```
Esta mensagem indica que os passos para garantir que o tráfego de rede é permitido não funcionaram. Verifique se o endereço IP da mensagem de erro está incluído nas regras de firewall.

Se receber uma mensagem com texto semelhante ao exemplo seguinte:
```
Caused by: com.microsoft.sqlserver.jdbc.SQLServerException: There is already an object named 'TODOS' in the database.
```
Esta mensagem indica que os dados de exemplo já estão no banco de dados. Pode ignorar esta mensagem.
(Opcional) Se quiser verificar os recursos de clustering, você também pode executar mais instâncias do mesmo aplicativo passando para o JAR inicializável o jboss.node.name argumento e, para evitar conflitos com os números de porta, alterando os números de porta usando jboss.socket.binding.port-offset. Por exemplo, para iniciar uma segunda instância que representa um novo pod no OpenShift, você pode executar o seguinte comando em uma nova janela do terminal:
```
export MSSQLSERVER_USER=azureuser
export MSSQLSERVER_PASSWORD='Passw0rd!'
export MSSQLSERVER_JNDI=java:/comp/env/jdbc/mssqlds
export MSSQLSERVER_DATABASE=todos_db
export MSSQLSERVER_HOST=<server name saved aside earlier>
export MSSQLSERVER_PORT=1433
mvn wildfly-jar:run -Dwildfly.bootable.arguments="-Djboss.node.name=node2 -Djboss.socket.binding.port-offset=1000"
```
Se o cluster estiver funcionando, você poderá ver no log do console do servidor um rastreamento semelhante ao seguinte:
```
INFO  [org.infinispan.CLUSTER] (thread-6,ejb,node) ISPN000094: Received new cluster view for channel ejb
```
Nota

Por padrão, o JAR inicializável configura o subsistema JGroups para usar o protocolo UDP e envia mensagens para descobrir outros membros do cluster para o endereço de multicast 230.0.0.4. Para verificar corretamente os recursos de clustering em sua máquina local, seu sistema operacional deve ser capaz de enviar e receber datagramas multicast e roteá-los para o IP 230.0.0.4 através de sua interface ethernet. Se vir avisos relacionados com o cluster nos registos do servidor, verifique a configuração da rede e verifique se suporta multicast nesse endereço.
Abra http://localhost:8080/ no seu navegador para visitar a página inicial do aplicativo. Se você criou mais instâncias, poderá acessá-las alterando o número da porta, por exemplo, http://localhost:9080/. O aplicativo deve ser semelhante à seguinte imagem:

Verifique as sondas de vivacidade e prontidão para a aplicação. O OpenShift usa esses endpoints para verificar quando seu pod está ativo e pronto para receber solicitações do usuário.

Para verificar o estado de vivacidade, execute:

curl http://localhost:9990/health/live

Deverá ver este resultado:

{"status":"UP","checks":[{"name":"SuccessfulCheck","status":"UP"}]}

Para verificar o estado de prontidão, execute:

curl http://localhost:9990/health/ready

Deverá ver este resultado:

 {"status":"UP","checks":[{"name":"deployments-status","status":"UP","data":{"todo-list.war":"OK"}},{"name":"server-state","status":"UP","data":{"value":"running"}},{"name":"boot-errors","status":"UP"},{"name":"DBConnectionHealthCheck","status":"UP"}]}

Pressione Ctrl+C para parar o aplicativo.

Implantar no OpenShift

Para implantar o aplicativo, usaremos os JBoss EAP Helm Charts já disponíveis no Azure Red Hat OpenShift. Também precisamos fornecer a configuração desejada, por exemplo, o usuário do banco de dados, a senha do banco de dados, a versão do driver que queremos usar e as informações de conexão usadas pela fonte de dados. As etapas a seguir pressupõem que você tenha o SQL do Azure em execução e acessível a partir do cluster OpenShift e tenha armazenado o nome de usuário, a senha, o nome do host, a porta e o nome do banco de dados em um objeto OpenShift OpenShift Secret chamado mssqlserver-secret.

Navegue até o repositório local do aplicativo de demonstração e altere a ramificação atual para bootable-jar-openshift :

git checkout bootable-jar-openshift

Vamos fazer uma rápida revisão sobre o que mudamos neste ramo:

Adicionamos um novo perfil Maven chamado bootable-jar-openshift que prepara o JAR inicializável com uma configuração específica para executar o servidor na nuvem. Por exemplo, ele permite que o subsistema JGroups use solicitações de rede para descobrir outros pods usando o protocolo KUBE_PING.
Adicionamos um conjunto de arquivos de configuração no diretório jboss-on-aro-jakartaee/deployment . Neste diretório, você pode encontrar os arquivos de configuração para implantar o aplicativo.

Implantar o aplicativo no OpenShift

As próximas etapas explicam como você pode implantar o aplicativo com um gráfico Helm usando o console da Web OpenShift. Evite codificar valores sensíveis em seu gráfico Helm usando um recurso chamado "segredos". Um segredo é simplesmente uma coleção de pares nome-valor, onde os valores são especificados em algum lugar conhecido antes de serem necessários. No nosso caso, o gráfico Helm usa dois segredos, com os seguintes pares nome-valor de cada um.

mssqlserver-secret
- db-host transmite o valor de MSSQLSERVER_HOST.
- db-name transmite o valor de MSSQLSERVER_DATABASE
- db-password transmite o valor de MSSQLSERVER_PASSWORD
- db-port transmite o valor de MSSQLSERVER_PORT.
- db-user transmite o valor de MSSQLSERVER_USER.
todo-list-secret
- app-cluster-password transmite uma senha arbitrária especificada pelo usuário para que os nós do cluster possam se formar com mais segurança.
- app-driver-version transmite o valor de MSSQLSERVER_DRIVER_VERSION.
- app-ds-jndi transmite o valor de MSSQLSERVER_JNDI.

Crie mssqlserver-secret.

oc create secret generic mssqlserver-secret \
    --from-literal db-host=${MSSQLSERVER_HOST} \
    --from-literal db-name=${MSSQLSERVER_DATABASE} \
    --from-literal db-password=${MSSQLSERVER_PASSWORD} \
    --from-literal db-port=${MSSQLSERVER_PORT} \
    --from-literal db-user=${MSSQLSERVER_USER}

Crie todo-list-secret.

export MSSQLSERVER_DRIVER_VERSION=7.4.1.jre11
oc create secret generic todo-list-secret \
    --from-literal app-cluster-password=mut2UTG6gDwNDcVW \
    --from-literal app-driver-version=${MSSQLSERVER_DRIVER_VERSION} \
    --from-literal app-ds-jndi=${MSSQLSERVER_JNDI}

Abra o console OpenShift e navegue até a visualização do desenvolvedor. Você pode descobrir a URL do console para seu cluster OpenShift executando este comando. Inicie sessão com o kubeadmin userid e palavra-passe que obteve num passo anterior.
```
az aro show \
    --name $CLUSTER \
    --resource-group $RESOURCEGROUP \
    --query "consoleProfile.url" \
    --output tsv
```
Selecione a <perspetiva /> Desenvolvedor no menu suspenso na parte superior do painel de navegação.
<Na perspetiva /> Developer, selecione o projeto eap-demo no menu suspenso Project.
Selecione +Adicionar. Na seção Catálogo do desenvolvedor, selecione Gráfico de leme. Você chega ao catálogo do Helm Chart disponível no cluster do Azure Red Hat OpenShift. Na caixa Filtrar por palavra-chave, digite eap. Você deve ver várias opções, como mostrado aqui:

Como nosso aplicativo usa recursos MicroProfile, selecionamos o Helm Chart para EAP Xp. O "Xp" significa Expansion Pack. Com o pacote de expansão JBoss Enterprise Application Platform, os desenvolvedores podem usar interfaces de programação de aplicativos (APIs) Eclipse MicroProfile para criar e implantar aplicativos baseados em microsserviços.
Selecione o JBoss EAP XP 4 Helm Chart e, em seguida, selecione Install Helm Chart.

Neste ponto, precisamos configurar o gráfico para criar e implantar o aplicativo:

Altere o nome da versão para eap-todo-list-demo.
Podemos configurar o Gráfico de Leme usando um Modo de Exibição de Formulário ou um Modo de Exibição YAML. Na seção chamada Configurar via, selecione Visualização YAML.
Altere o conteúdo do YAML para configurar o gráfico de leme copiando e colando o conteúdo do arquivo de gráfico de leme disponível em deployment/application/todo-list-helm-chart.yaml em vez do conteúdo existente:

Este conteúdo faz referência aos segredos que você definiu anteriormente.
Por fim, selecione Instalar para iniciar a implantação do aplicativo. Esta ação abre a visualização Topologia com uma representação gráfica da versão Helm (chamada eap-todo-list-demo) e seus recursos associados.

O Helm Release (abreviado HR) é chamado eap-todo-list-demo. Ele inclui um recurso de implantação (abreviado D) também chamado eap-todo-list-demo.

Se você selecionar o ícone com duas setas em um círculo no canto inferior esquerdo da caixa D , será direcionado para o painel Logs . Aqui você pode observar o progresso da construção. Para retornar à exibição de topologia, selecione Topologia no painel de navegação esquerdo.
Quando a compilação estiver concluída, o ícone inferior esquerdo exibirá uma verificação verde.
Quando a implantação é concluída, o contorno do círculo é azul escuro. Se você passar o mouse sobre o azul escuro, verá uma mensagem informando algo semelhante a 3 Running. Quando você vir essa mensagem, poderá acessar a URL do aplicativo (usando o ícone no canto superior direito) da rota associada à implantação.
O aplicativo é aberto em seu navegador parecendo semelhante à seguinte imagem pronta para ser usada:
O aplicativo mostra o nome do pod que serve as informações. Para verificar os recursos de clustering, você pode adicionar alguns itens Todo. Em seguida, exclua o pod com o nome indicado no campo Nome do host do servidor que aparece no aplicativo usando oc delete pod <pod-name>. Depois de excluir o pod, crie um novo Todo na mesma janela do aplicativo. Você pode ver que o novo Todo é adicionado por meio de uma solicitação Ajax e o campo Nome do Host do Servidor agora mostra um nome diferente. Nos bastidores, o balanceador de carga OpenShift despachou a nova solicitação e a entregou em um pod disponível. A visualização Jakarta Faces é restaurada a partir da cópia da sessão HTTP armazenada no pod que está processando a solicitação. Na verdade, você pode ver que o campo ID da sessão não foi alterado. Se a sessão não for replicada em seus pods, você receberá um Jakarta Faces ViewExpiredExceptione seu aplicativo não funcionará como esperado.

Clean up resources (Limpar recursos)

Excluir o aplicativo

Se você quiser apenas excluir seu aplicativo, você pode abrir o console OpenShift e, na visualização do desenvolvedor, navegar até a opção de menu Helm . Neste menu, você pode ver todas as versões do Helm Chart instaladas no cluster.

Encontre o eap-todo-list-demo Helm Chart. No final da linha, selecione os pontos verticais da árvore para abrir a entrada do menu contextual da ação.

Selecione Desinstalar Helm Release para remover o aplicativo. Observe que o objeto secreto usado para fornecer a configuração do aplicativo não faz parte do gráfico. Você precisa removê-lo separadamente se não precisar mais dele.

Execute o seguinte comando se desejar excluir o segredo que contém a configuração do aplicativo:

$ oc delete secrets/todo-list-secret
# secret "todo-list-secret" deleted

Excluir o projeto OpenShift

Você também pode excluir toda a configuração criada para esta demonstração excluindo o eap-demo projeto. Para fazer isso, execute o seguinte comando:

$ oc delete project eap-demo
# project.project.openshift.io "eap-demo" deleted

Excluir o cluster do Azure Red Hat OpenShift

Exclua o cluster do Azure Red Hat OpenShift seguindo as etapas em Tutorial: Excluir um cluster do Azure Red Hat OpenShift 4.

Eliminar o grupo de recursos

Se quiser excluir todos os recursos criados pelas etapas anteriores, exclua o grupo de recursos criado para o cluster do Azure Red Hat OpenShift.

Próximos passos

Você pode aprender mais com as referências usadas neste guia:

Continue a explorar as opções para executar o JBoss EAP no Azure.

Saiba mais sobre o JBoss EAP no Azure

Partilhar via