在 Azure Red Hat OpenShift 群集上使用 JBoss EAP 手动部署 Java 应用程序

本文介绍如何将 Red Hat JBoss Enterprise 应用程序平台(EAP)应用程序部署到 Azure Red Hat OpenShift 群集。 此示例是由 SQL 数据库支持的 Java 应用程序。 该应用使用 JBoss EAP Helm 图表进行部署。

本指南介绍如何:

  • 为 OpenShift 准备 JBoss EAP 应用程序。
  • 创建Azure SQL 数据库的单个数据库实例。
  • 使用 JBoss Helm 图表和 OpenShift Web 控制台在 Azure Red Hat OpenShift 群集上部署应用程序

示例应用程序是一个有状态应用程序,用于在 HTTP 会话中存储信息。 它利用 JBoss EAP 群集功能,并使用以下 Jakarta EE 和 MicroProfile 技术:

  • Jakarta Server Faces
  • Jakarta Enterprise Beans
  • Jakarta Persistence
  • MicroProfile Health

本文是有关在 Azure Red Hat OpenShift 群集上运行 JBoss EAP 应用的分步手动指南。 有关加速 Azure Red Hat OpenShift 群集之旅的更自动化解决方案,请参阅快速入门:使用 Azure 门户 在 Azure Red Hat OpenShift 上部署 JBoss EAP。

如果有兴趣在 Azure 解决方案上开发 JBoss EAP 的工程团队提供有关迁移方案的反馈或密切合作,请填写有关 JBoss EAP 迁移的简短调查,并包括联系信息。 项目经理、架构师和工程师团队会及时与你联系,以开展密切合作。

重要

本文使用 JBoss EAP Helm 图表部署应用程序。 在撰写本文时,此功能仍以技术预览版提供。 选择在生产环境中使用 JBoss EAP Helm 图表部署应用程序之前,请确保此功能是你的 JBoss EAP/XP 产品版本支持的功能。

重要

虽然 Azure Red Hat OpenShift 由 Red Hat 联合设计、运营和支持,Microsoft以提供集成支持体验,但运行在 Azure Red Hat OpenShift 之上的软件(包括本文中所述的软件)受其自己的支持和许可条款的约束。 有关 Azure Red Hat OpenShift 支持的详细信息,请参阅 Azure Red Hat OpenShift 4 的支持生命周期。 有关本文中所述软件支持的详细信息,请查看本文中列出的相应软件的主页。

先决条件

注意

Azure Red Hat OpenShift 至少需要 40 个核心才能创建和运行 OpenShift 群集。 新 Azure 订阅的默认 Azure 资源配额不满足此要求。 若要请求提高资源上限,请参阅标准配额:按 VM 系列提高上限中所述。 请注意,免费试用订阅无法增加配额,请升级到即用即付订阅再请求增加配额。

  1. 使用已安装的各种产品(如 Ubuntu、macOS 或 适用于 Linux 的 Windows 子系统)支持的类似 Unix 的操作系统准备本地计算机。

  2. 安装 Java 标准版 (SE) 实现。 本文中的本地开发步骤在 OpenJDK 的 Microsoft 版本中使用 Java 开发工具包 (JDK) 17 进行测试。

  3. 安装 Maven 3.8.6 或更高版本。

  4. 安装 Azure CLI 2.40 或更高版本。

  5. 将此演示应用程序(待办事项列表)的代码克隆到本地系统。 该演示应用程序已在 GitHub 上提供。

  6. 按照创建 Azure Red Hat OpenShift 4 群集中的说明进行操作。

    尽管“获取 Red Hat 请求机密”这一步标记为可选步骤,但本文仍需要此步骤。 拉取机密使 Azure Red Hat OpenShift 群集能够查找 JBoss EAP 应用程序映像。

    如果你打算在群集上运行内存密集型应用程序,请使用 --worker-vm-size 参数为工作器节点指定适当的虚拟机大小。 有关详细信息,请参阅:

  7. 按照连接到 Azure Red Hat OpenShift 4 群集中的步骤连接到该群集。

    • 执行“安装 OpenShift CLI”中的步骤
    • kubeadmin 用户的身份使用 OpenShift CLI 连接到 Azure Red Hat OpenShift 群集
  8. 执行以下命令,为此演示应用程序创建 OpenShift 项目:

    oc new-project eap-demo
    
  9. 执行以下命令,将视图角色添加到默认服务帐户。 需要此角色,以便应用程序可以发现其他 Pod,并使用它们设置群集:

    oc policy add-role-to-user view system:serviceaccount:$(oc project -q):default -n $(oc project -q)
    

准备应用程序

使用以下命令克隆示例应用程序:

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

你克隆了 Todo-list 演示应用程序,本地存储库位于分支上 main 。 演示应用程序是一个简单的 Java 应用,用于在 Azure SQL 上创建、读取、更新和删除记录。 可以在本地计算机上安装的 JBoss EAP 服务器上部署此应用程序。 只需使用所需的数据库驱动程序和数据源配置该服务器。 还需要可从本地环境访问的数据库服务器。

但是,当你面向 OpenShift 时,可能需要剪裁 JBoss EAP 服务器的功能。 例如,你可能希望减少预配服务器的安全暴露,并减少总体占用情况。 可能还需要包含某些 MicroProfile 规范,使应用程序更适合在 OpenShift 环境中运行。 使用 JBoss EAP 时,完成此任务的一种方法是将应用程序和服务器打包到称为可启动 JAR 的单个部署单元中。 为此,让我们添加需要对演示应用程序所做的更改。

导航到演示应用程序的本地存储库,并将分支更改为 bootable-jar

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

让我们快速回顾一下我们在此分支中所做的更改:

  • 我们添加了插件 wildfly-jar-maven ,用于在单个可执行 JAR 文件中预配服务器和应用程序。 OpenShift 部署单元是包含我们应用程序的服务器。
  • 在 Maven 插件上,我们指定了一组 Galleon 层。 通过此配置,我们只能将服务器功能剪裁为所需的功能。 有关 Galleon 的完整文档,请参阅 WildFly 文档
  • 我们的应用程序将 Jakarta Face 与 Ajax 请求一起使用,这意味着 HTTP 会话中存储了信息。 如果删除了某个 pod,我们不希望丢失此类信息。 可将此信息保存在客户端上,并在每个请求中将其发回。 但是,在某些情况下,你可能不想要向客户分发某些信息。 对于此演示,我们选择跨所有 Pod 副本复制会话。 为此,我们添加到<distributable />了 .web.xml 这与服务器群集功能一起使 HTTP 会话可跨所有 Pod 分布。
  • 我们添加了两个 MicroProfile 运行状况检查,使你能够识别应用程序何时实时并准备好接收请求。

在本地运行应用程序

在 OpenShift 上部署应用程序之前,我们将在本地运行该应用程序,以验证其工作原理。 以下步骤假定你在本地环境中运行并提供了 Azure SQL。

若要创建数据库,请按照快速入门:创建 Azure SQL 数据库单一数据库中的步骤操作,但使用以下替换项。

  • 对于 资源组 ,请使用之前创建的资源组。
  • 对于“数据库名称”,请使用 todos_db
  • 对于“服务器管理员登录名”,请使用 azureuser
  • 对于“密码”,请使用 Passw0rd!
  • 在“防火墙规则”部分,将“允许 Azure 服务和资源访问此服务器”切换为“是”

可以放心使用链接的文章中的所有其他设置。

在“其他设置”页上,无需选择使用示例数据预填充数据库的选项,但这样做不会造成任何损害。

创建数据库后,从概述页获取服务器名称的值。 将鼠标悬停在“服务器名称”字段的值上方,然后选择该值旁边出现的复制图标。 将此值保存为稍后使用(我们设置了一个名为 MSSQLSERVER_HOST 此值的变量)。

注意

为了保持较低的成本,本快速入门将指导读者选择无服务器计算层。 没有活动时,此层将缩减为零。 发生这种情况时,数据库不会立即做出响应。 如果在执行本文中的步骤期间发现数据库问题,请考虑禁用“自动暂停”。 若要了解如何操作,请在 Azure SQL 数据库无服务器中搜索“自动暂停”。 编写时,以下 AZ CLI 命令将禁用本文中配置的数据库的自动暂停。 az sql db update --resource-group $RESOURCEGROUP --server <Server name, without the .database.windows.net part> --name todos_db --auto-pause-delay -1

按照后续步骤在本地生成并运行应用程序。

  1. 生成可启动 JAR。 由于我们正在与 eap-datasources-galleon-pack MS SQL Server 数据库一起使用,因此必须指定要用于此特定环境变量的数据库驱动程序版本。 有关和 MS SQL Server 的详细信息 eap-datasources-galleon-pack ,请参阅 Red Hat 中的文档

    export MSSQLSERVER_DRIVER_VERSION=7.4.1.jre11
    mvn clean package
    
  2. 使用以下命令启动可启动 JAR。

    必须确保 Azure SQL 数据库允许来自运行此服务器的主机的网络流量。 因为你在执行快速入门:创建 Azure SQL 数据库单一数据库中的步骤时选择了“添加当前客户端 IP 地址”,如果运行服务器的主机是浏览器从中连接到 Azure 门户的同一台主机,则应允许网络流量。 如果运行服务器的主机是其他一些主机,则需要参考“使用Azure 门户来管理服务器级 IP 防火墙规则

    启动应用程序时,需要传递所需的环境变量来配置数据源:

    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
    

    如果你想要详细了解本演示使用的基础运行时,用于集成数据源的 Galleon 功能包文档提供了可用环境变量的完整列表。 有关功能包概念的详细信息,请参阅 WildFly 文档

    如果收到类似于以下示例的文本的错误:

    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.
    

    此消息指示确保允许网络流量无法正常工作的步骤。 确保错误消息中的 IP 地址包含在防火墙规则中。

    如果收到一条消息,其文本类似于以下示例:

    Caused by: com.microsoft.sqlserver.jdbc.SQLServerException: There is already an object named 'TODOS' in the database.
    

    此消息表明示例数据已在数据库中。 可以忽略此消息。

  3. (可选)若要验证群集功能,还可以通过将 jboss.node.name 参数传递给可启动 JAR 来启动同一应用程序的更多实例;为避免端口号冲突,请使用 jboss.socket.binding.port-offset 来偏移端口号。 例如,若要启动表示 OpenShift 上的新 Pod 的第二个实例,可以在新的终端窗口中执行以下命令:

    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"
    

    如果群集正常工作,可以在服务器控制台上看到类似于以下跟踪的跟踪:

    INFO  [org.infinispan.CLUSTER] (thread-6,ejb,node) ISPN000094: Received new cluster view for channel ejb
    

    注意

    默认情况下,可启动 JAR 会将 JGroups 子系统配置为使用 UDP 协议,并向 230.0.0.4 多播地址发送消息以发现其他群集成员。 若要正确验证本地计算机上的群集功能,操作系统应该能够发送和接收多播数据报,并通过以太网接口将其路由到 IP 230.0.0.4。 如果在服务器日志中看到与群集相关的警告,请检查网络配置并验证它是否支持该地址上的多播。

  4. 在浏览器中打开 http://localhost:8080/ 以访问应用程序主页。 如果创建了更多实例,可以通过移动端口号来访问它们,例如 http://localhost:9080/。 应用程序应如下图所示:

    ToDo EAP 演示应用程序的屏幕截图。

  5. 检查应用程序的运行情况和就绪情况探测。 OpenShift 使用这些终结点来验证 Pod 是否实时并准备好接收用户请求。

    若要检查运行情况状态,请运行:

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

    你应该会看到以下输出:

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

    若要检查就绪状态,请运行:

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

    你应该会看到以下输出:

     {"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"}]}
    
  6. 按 Ctrl-C 停止应用程序

部署到 OpenShift

若要部署应用程序,我们将使用 Azure Red Hat OpenShift 中已提供的 JBoss EAP Helm 图表。 此外,需要提供所需的配置,例如,数据库用户、数据库密码、要使用的驱动程序版本,以及数据源使用的连接信息。 以下步骤假定你在 OpenShift 群集中运行并可访问 Azure SQL,并将数据库用户名、密码、主机名、端口和数据库名称存储在名为 mssqlserver-secretOpenShift OpenShift Secret 对象的数据库中。

导航到演示应用程序的本地存储库,并将当前分支更改为 bootable-jar-openshift

git checkout bootable-jar-openshift

让我们快速回顾一下我们在此分支中更改的内容:

  • 我们添加了一个新的 Maven 配置文件,该配置文件使用 bootable-jar-openshift 特定的配置来准备可启动 JAR,以便在云上运行服务器。 例如,它使 JGroups 子系统能够使用网络请求通过 KUBE_PING 协议发现其他 Pod。
  • 我们在 jboss-on-aro-jakartaee/deployment 目录中添加了一组配置文件。 在此目录中,可以找到用于部署应用程序的配置文件。

在 OpenShift 上部署应用程序

后续步骤将说明如何使用 OpenShift Web 控制台通过 Helm 图表部署应用程序。 使用名为“机密”的功能,避免将敏感值硬编码到 Helm 图表中。 机密只是 name=value 对的集合,其中值在需要之前在一些已知位置指定。 在本例中,Helm 图表使用两个机密,其中每个机密包含以下“名称=值”对。

  • mssqlserver-secret

    • db-host 传递 MSSQLSERVER_HOST 值。
    • db-name 传递 MSSQLSERVER_DATABASE
    • db-password 传递 MSSQLSERVER_PASSWORD
    • db-port 传递 MSSQLSERVER_PORT 值。
    • db-user 传递 MSSQLSERVER_USER 值。
  • todo-list-secret

    • app-cluster-password 传递用户指定的任意密码,以便可以更安全地构成群集节点。
    • app-driver-version 传递 MSSQLSERVER_DRIVER_VERSION 值。
    • app-ds-jndi 传递 MSSQLSERVER_JNDI 值。
  1. 创建 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}
    
  2. 创建 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}
    
  3. 打开 OpenShift 控制台并导航到开发人员视图。 可以通过运行以下命令来发现 OpenShift 群集的控制台 URL。 使用从上一步获取的 kubeadmin userid 和密码登录。

    az aro show \
        --name $CLUSTER \
        --resource-group $RESOURCEGROUP \
        --query "consoleProfile.url" \
        --output tsv
    

    <从导航窗格顶部的下拉菜单中选择/>开发人员透视。

    OpenShift 控制台开发人员视图的屏幕截图。

  4. /开发人员的角度来看,从“项目”下拉菜单中选择 eap-demo 项目。><

    OpenShift 控制台项目组合框的屏幕截图。

  5. 选择“+添加” 。 在“开发人员目录”部分,选择“Helm 图表”。 到达 Azure Red Hat OpenShift 群集上可用的 Helm 图表目录。 在“按关键字筛选”框中,键入“eap”。 应会看到多个选项,如下所示:

    OpenShift 控制台 EAP Helm 图表的屏幕截图。

    由于应用程序使用 MicroProfile 功能,因此我们选择了 EAP Xp 的 Helm 图表。 Xp 是“扩展包”的英文缩写。 借助 JBoss Enterprise Application Platform 扩展包,开发人员可以使用 Eclipse MicroProfile 应用程序编程接口 (API) 来生成和部署基于微服务的应用程序。

  6. 选择 JBoss EAP XP 4 Helm 图表,然后选择“ 安装 Helm 图表”。

此时,我们需要配置该图表,以生成和部署应用程序:

  1. 将版本名称更改为“eap-todo-list-demo”

  2. 可以使用“表单视图”或“YAML 视图”来配置 Helm 图表。 在标有“配置方式”的部分,选择“YAML 视图”

  3. 通过复制并粘贴 deployment/application/todo-list-helm-helm.yaml 中提供的 Helm 图表文件内容(而不是现有内容)来更改 YAML 内容,以配置 Helm 图表

    OpenShift 控制台 EAP Helm 图表 YAML 内容

    此内容引用之前设置的机密。

  4. 最后,选择“安装”开始部署应用程序。 此操作将 打开拓扑 视图,其中包含 Helm 版本(名为 eap-todo-list-demo)及其关联的资源的图形表示形式。

    OpenShift 控制台拓扑的屏幕截图。

    Helm 版本(缩写为 HR)命名为 eap-todo-list-demo。 其中包含一个部署资源(缩写为 D),该资源也名为 eap-todo-list-demo

    如果在 D 框左下角的圆圈中选择带有两个箭头的图标,则转到“日志”窗格。 在此处可以观察生成进度。 若要返回拓扑视图,请在左侧导航窗格中选择“拓扑”

  5. 生成完成后,左下角图标将显示绿色检查

  6. 部署完成后,圆圈轮廓为深蓝色。 如果将鼠标悬停在深蓝色上,应会看到一条消息,指出类似 3 Running。 看到该消息时,可以从与部署关联的路由转到 URL(使用右上角图标)。

    OpenShift 控制台打开应用程序的屏幕截图。

  7. 该应用程序将在浏览器中打开(如下图所示)并可供使用:

    OpenShift 应用程序运行的屏幕截图。

  8. 应用程序显示提供信息的 Pod 的名称。 若要验证群集功能,可以添加一些待办事项。 然后,使用使用 <a0/> 在应用程序上显示的“服务器主机名”字段中指示的名称删除 Pod。 删除 Pod 后,在同一应用程序窗口中创建新的 Todo。 可以看到,新的 Todo 是通过 Ajax 请求添加的, “服务器主机名 ”字段现在显示不同的名称。 在后台,OpenShift 负载均衡器调度了新请求,并将其传送到可用的 Pod。 雅加达人脸视图是从处理请求的 Pod 中存储的 HTTP 会话副本还原的。 事实上,可以看到 “会话 ID ”字段未更改。 如果会话未跨 Pod 复制,则会收到 Jakarta Face ViewExpiredException,并且应用程序无法按预期工作。

清理资源

删除应用程序

如果你只想删除应用程序,可以打开 OpenShift 控制台,然后在开发人员视图中导航到“Helm”菜单选项。 在此菜单上,可以看到群集上安装的所有 Helm 图表版本。

OpenShift 卸载应用程序

找到“eap-todo-list-demo”Helm 图表,并在行尾选择树状垂直点以打开操作上下文菜单项

选择“卸载 Helm 版本”以删除应用程序。 请注意,用于提供应用程序配置的机密对象不是图表的一部分。 如果不再需要该对象,则需要单独删除它。

若要删除用于保存应用程序配置的机密,请执行以下命令:

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

删除 OpenShift 项目

还可以通过删除 eap-demo 项目来删除为本演示创建的所有配置。 为此,请执行以下命令:

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

删除 Azure Red Hat OpenShift 群集

按照教程中的 步骤删除 Azure Red Hat OpenShift 群集:删除 Azure Red Hat OpenShift 4 群集

删除资源组

如果要删除上述步骤创建的所有资源,请删除为 Azure Red Hat OpenShift 群集创建的资源组。

后续步骤

可以从本指南中使用的参考资料中了解到更多信息:

继续探索在 Azure 上运行 JBoss EAP 的选项。