Language:
Format:

适用于 OpenShift 的 JBoss EAP 在线版入门

Red Hat JBoss Enterprise Application Platform 7.3

用于 OpenShift 在线的红帽 JBoss 企业应用平台开发指南

摘要

将红帽 JBoss 企业应用平台用于 OpenShift Online 的指南

第 1 章简介

1.1. 什么是红帽 JBoss 企业应用平台(JBoss EAP)？

红帽 JBoss 企业应用平台 7(JBoss EAP)是基于开放标准构建并符合 Java 企业版 7 规格的中间件平台。它为高可用性群集、消息传递和分布式缓存等功能提供了预配置选项。它包含一个模块化结构，允许您仅在需要时启用服务，从而提高启动速度。

基于 Web 的管理控制台和管理命令行界面(CLI)无需编辑 XML 配置文件，还增加了编写脚本和自动执行任务的功能。此外，JBoss EAP 还包括 API 和开发框架，使您能够快速开发、部署和运行安全且可扩展的 Jakarta EE 应用。JBoss EAP 7 是一款适用于 Web 配置文件和完整平台规格的 Jakarta EE 8 兼容实施，也是 Java EE 8 完整平台和 Web 配置文件规范的认证实施。

1.2. JBoss EAP 如何在 OpenShift 上工作？

红帽为 JBoss EAP 提供容器化映像，专为与 OpenShift 配合使用而设计。开发人员可以利用此镜像快速轻松地构建、扩展和测试跨混合环境部署的应用程序。

1.3. 比较：用于 OpenShift 的 JBoss EAP 和 JBoss EAP

将 JBoss EAP 产品与用于 OpenShift 镜像的 JBoss EAP 进行比较时有一些显著的差异。下表描述了这些差异，并记录了适用于 OpenShift 的当前 JBoss EAP 版本中包含的或支持哪些功能。

表 1.1. 用于 OpenShift 的 JBoss EAP 和 JBoss EAP 之间的差异

JBoss EAP 功能	OpenShift 的 JBoss EAP 状态	描述
JBoss EAP 管理控制台	未包括	用于 OpenShift 的 JBoss EAP 管理控制台不包含 JBoss EAP 管理控制台。
JBoss EAP 管理 CLI	不推荐	不建议将 JBoss EAP 管理 CLI 用于容器化环境中运行的 JBoss EAP。当容器重启时，使用管理 CLI 在运行的容器中进行的任何配置更改都将丢失。管理 CLI 可以从容器集内访问，以满足故障排除需要。
受管域	不支持	虽然 JBoss EAP 受管域不受支持，但应用的创建和分发在 OpenShift 上的容器中进行管理。
默认根页面	Disabled	默认根页面已被禁用，但您可以将自己的应用部署至 root 上下文，即 `ROOT.war`。
远程消息传递	支持	支持用于 pod 间和远程消息传递的红帽 AMQ。ActiveMQ Artemis 仅支持具有 JBoss EAP 实例的单一 pod 中的消息传递，并且仅在缺少红帽 AMQ 时启用。
事务恢复	部分支持	某些不受支持的事务恢复场景，以及使用 JBoss EAP for OpenShift 镜像进行事务恢复时要注意的事项。 EAP 操作器是 OpenShift 4 中唯一经过测试且受支持的事务恢复选项。如需有关使用 EAP 操作器恢复事务的更多信息，请参阅 EAP Operator for Safe Transaction Recovery。
嵌入式消息传递代理	已弃用	在 OpenShift 容器中使用嵌入式消息传递代理已弃用。在以后的发行版本中将删除对嵌入式代理的支持。如果容器配置为使用嵌入式消息传递代理，如果没有配置远程代理，则会记录警告信息。如果容器配置不包括消息传递目的地，请将 `DISABLE_EMBEDDED_JMS_BROKER` 环境变量设置为 `true`，以禁用配置嵌入式消息传递代理的功能。

1.4. 版本兼容性和支持

用于 OpenShift 的 JBoss EAP 提供适用于 JDK 8、JDK 11 和 Eclipse OpenJ9 的镜像。

每个镜像有两种不同的版本：S2I 构建器镜像和运行时镜像。S2I 构建器镜像包含完整的 JBoss EAP 服务器，以及 S2I 构建期间所需的工具。运行时镜像包含运行 JBoss EAP 但不包含服务器所需的依赖项。服务器在连锁构建期间安装在运行时镜像中。

以下修改已应用于 JBoss EAP 中适用于 OpenShift 7.3 的镜像。

已删除默认驱动程序和模块。
已删除 MySQL 和 PostgreSQL 模板。您可以使用自定义层置备这些功能。
在这些镜像中，Hawkular 代理没有处于活动状态。如果配置，则忽略它。
容器启动时默认不再添加默认数据源 ExampleDS。如果您需要默认数据源，请使用环境变量 ENABLE_GENERATE_DEFAULT_DATASOURCE，其值为 true (ENABLE_GENERATE_DEFAULT_DATASOURCE=true)

注意

以下发现机制协议已弃用，并已被其他协议替代：

openshift.DNS_PING 协议已弃用，并替换为 dns.DNS_PING 协议。如果您在 自定义的 standalone-openshift .xml 文件中引用了 openshift. DNS_PING 协议，请将协议替换为 dns.DNS_PING 协议。
openshift.KUBE_PING 发现机制协议已弃用，并替换为 kubernetes.KUBE_PING 协议。

JDK 8 镜像

Red Hat Universal Base Image: 7
模板名称前缀：eap73-*
构建器镜像：https://access.redhat.com/containers/#/registry.access.redhat.com/jboss-eap-7/eap73-openjdk8-openshift-rhel7
运行时镜像：https://access.redhat.com/containers/#/registry.access.redhat.com/jboss-eap-7/eap73-openjdk8-runtime-openshift-rhel7

注意

IBM Z 和 IBM Power 系统不提供 JBoss EAP 的 JDK 8 镜像。

JDK 11 镜像

Red Hat Universal Base Image: 8
模板名称前缀：eap73-openjdk11-*
构建器镜像：https://access.redhat.com/containers/#/registry.access.redhat.com/jboss-eap-7/eap73-openjdk11-openshift-rhel8
运行时镜像：https://access.redhat.com/containers/#/registry.access.redhat.com/jboss-eap-7/eap73-openjdk11-runtime-openshift-rhel8

Eclipse OpenJ9 镜像

Red Hat Universal Base Image: 8
模板名称前缀：eap73-*
构建器镜像：https://access.redhat.com/containers/#/registry.access.redhat.com/jboss-eap-7/eap73-openj9-11-openshift-rhel8
运行时镜像：https://access.redhat.com/containers/#/registry.access.redhat.com/jboss-eap-7/eap73-openj9-11-runtime-openshift-rhel8

适用于 OpenShift 的 JBoss EAP 经常更新。因此，务必要了解哪些镜像版本与哪些版本的 OpenShift 兼容。有关版本兼容性和支持的更多信息，请参阅红帽客户门户网站中的 OpenShift 和 Atomic Platform 测试的集成。

其它资源

针对 OpenShift 的 JBoss EAP 的功能调试

1.4.1. OpenShift 4.x 支持

OpenShift 4.1 的更改会影响对 Jolokia 的访问，Open Java 控制台在 OpenShift 4.x Web 控制台中不再可用。

在以前的版本中，在 OpenShift 发行本中，某些 kube-apiserver 代理请求已经过身份验证，并传递给集群。现在，这种行为被视为不安全，因此不再支持以这种方式访问 Jolokia。

由于 OpenShift 控制台代码库更改，Open Java 控制台链接不再可用。

1.4.2. IBM Z 和 IBM Power 系统支持

libartemis-native 的 s390x 和 ppc64le 变体不包含在镜像中。因此，任何与 AIO 相关的设置都不会被考虑。

journal-type ： 将 journal-type 设置为 ASYNCIO 无效。此属性的值在运行时默认为 NIO。
journal-max-io ：此属性无效。
journal-store-enable-async-io ：此属性无效。

1.4.3. 在 OpenShift 中从 JBoss EAP 7.1 升级到 JBoss EAP 7.3

OpenShift 上的 JBoss EAP 7.1 安装的 standalone-openshift.xml 文件与 JBoss EAP 7.3 及更高版本不兼容。您必须修改随 JBoss EAP 7.1 安装的 standalone-openshift.xml 文件，然后使用该文件为 OpenShift 启动 JBoss EAP 7.3 或更高版本的容器。

其他资源

在 OpenShift 中将 JBoss EAP 7.1 升级到 JBoss EAP 7.3 时对 standalone-openshift.xml 的更新

1.5. 部署选项

您可以使用以下选项之一在 OpenShift 中部署 JBoss EAP Java 应用程序：

适用于 OpenShift 的 JBoss EAP 模板.如需更多信息，请参阅在 JBoss EAP CD 上为 OpenShift 镜像构建和运行 Java 应用。
EAP 操作器是特定于 JBoss EAP 的控制器，扩展 OpenShift API，以代表 OpenShift 用户创建、配置和管理复杂有状态应用的实例。如需更多信息，请参阅 OpenShift 上自动化应用程序部署的 EAP Operator。

注意

EAP 操作器仅支持 OpenShift 4 及更高版本。

第 2 章在用于 OpenShift 镜像的 JBoss EAP 上构建并运行 Java 应用

以下工作流演示了如何使用 Source-to-Image(S2I)流程在 JBoss EAP for OpenShift 镜像上构建和运行 Java 应用。

例如，这个过程 中使用了 Kitchensink faststart。它使用 JSF、CDI、EJB、JPA 和 Bean 验证来演示启用 Web 的 Jakarta EE 数据库应用。如需更多信息，请参阅 JBoss EAP 7 附带的 BIOSchen sink 快速入门。

2.1. 先决条件

此工作流假定您已拥有活跃的 OpenShift Online 订阅，并且已安装了 OpenShift CLI。

2.2. 为应用部署准备 OpenShift

使用 oc login 命令登录 您的 OpenShift 实例。
在 OpenShift 中创建新项目：
项目允许一组用户组织和管理与其他组不同的内容。您可以使用以下命令在 OpenShift 中创建项目：
```
$ oc new-project PROJECT_NAME
```
例如，对于 kitchensink quickstart，使用以下命令创建名为 eap-demo 的新项目：
```
$ oc new-project eap-demo
```
可选：创建密钥存储和 secret。
注意
如果您使用 OpenShift 项目中支持 HTTPS 的功能，则需要创建密钥存储和机密。例如，如果您使用 eap73-https-s2i 模板（用于 JDK 8）或 eap73-openjdk11-https-s2i 模板（用于 JDK 11），您必须创建一个密钥存储和 secret。
这个 toolschen sink quickstart 的工作流演示不使用 HTTPS 模板，因此不需要密钥存储和 secret。
1. 创建密钥存储.
  警告
  以下命令将生成自签名证书，但对于生产环境，红帽建议您使用从认证认证机构(CA)购买的 SSL 证书进行 SSL 加密连接(HTTPS)。
  您可以使用以下命令，使用 Java keytool 命令生成密钥存储：
```
$ keytool -genkey -keyalg RSA -alias ALIAS_NAME -keystore KEYSTORE_FILENAME.jks -validity 360 -keysize 2048
```
  例如，对于 Kitchensink quickstart，使用以下命令生成密钥存储：
```
$ keytool -genkey -keyalg RSA -alias eapdemo-selfsigned -keystore keystore.jks -validity 360 -keysize 2048
```
2. 从密钥存储创建机密。
  使用以下命令，从前面创建的密钥存储创建机密。
```
$ oc create secret SECRET_NAME KEYSTORE_FILENAME.jks
```
  例如，对于 Kitchensink quickstart，使用以下命令来创建 secret：
```
$ oc create secret eap7-app-secret keystore.jks
```

2.3. 导入适用于 OpenShift 镜像流和模板的最新 JBoss EAP

您必须将适用于 OpenShift 的最新 JBoss EAP 镜像流和模板导入到 OpenShift 项目的命名空间中。

注意

使用您的客户门户网站凭证登录红帽容器注册表，以导入 JBoss EAP 镜像流和模板。如需更多信息，请参阅 Red Hat Container Registry 身份验证。

为 JDK 8 导入命令

for resource in \
  eap73-amq-persistent-s2i.json \
  eap73-amq-s2i.json \
  eap73-basic-s2i.json \
  eap73-https-s2i.json \
  eap73-image-stream.json \
  eap73-sso-s2i.json \
  eap73-starter-s2i.json \
do
  oc replace --force -f \
https://raw.githubusercontent.com/jboss-container-images/jboss-eap-7-openshift-image/eap73/templates/${resource}
done

此命令导入以下镜像流和模板：

JDK 8 构建器镜像流： jboss-eap73-openshift
JDK 8 运行时镜像流： jboss-eap73-runtime-openshift
命令中指定的所有模板。

JDK 11 导入命令

for resource in \
  eap73-openjdk11-amq-persistent-s2i.json \
  eap73-openjdk11-amq-s2i.json \
  eap73-openjdk11-basic-s2i.json \
  eap73-openjdk11-https-s2i.json \
  eap73-openjdk11-image-stream.json \
  eap73-openjdk11-sso-s2i.json \
  eap73-openjdk11-starter-s2i.json \
do
  oc replace --force -f \
https://raw.githubusercontent.com/jboss-container-images/jboss-eap-7-openshift-image/eap73/templates/${resource}
done

此命令导入以下镜像流和模板：

JDK 11 构建器镜像流： jboss-eap73-openjdk11-openshift
JDK 11 运行时镜像流： jboss-eap73-openjdk11-runtime-openshift
命令中指定的所有模板。

在 IBM Z 和 IBM Power 系统上为 Eclipse OpenJ9 导入命令

oc replace --force -f \
https://raw.githubusercontent.com/jboss-container-images/jboss-eap-openshift-templates/eap73/eap73-openj9-image-stream.json

for resource in \
  eap73-amq-persistent-s2i.json \
  eap73-amq-s2i.json \
  eap73-basic-s2i.json \
  eap73-https-s2i.json \
  eap73-sso-s2i.json \
do
  oc replace --force -f \
https://raw.githubusercontent.com/jboss-container-images/jboss-eap-openshift-templates/eap73/templates/${resource}
done

此命令导入以下镜像流和模板：

Eclipse OpenJ9 构建器镜像流： jboss-eap-7-openj9-11-openshift
Eclipse OpenJ9 运行时镜像流： jboss-eap-7-openj9-11-runtime-openshift
命令中指定的所有模板。

注意

使用这些命令导入的 JBoss EAP 镜像流和模板仅在该 OpenShift 项目中可用。

如果要将镜像流和模板导入到其他项目中，请将 -n PROJECT_NAME 添加到 命令的 oc replace 行。例如：

...
oc replace -n PROJECT_NAME --force -f
...

如果使用 cluster-samples-operator，请参阅有关配置集群样本操作器的 OpenShift 文档。有关配置集群样本操作器的详情，请参阅配置 Samples Operator。

2.4. 将 JBoss EAP Source-to-Image(S2I)应用部署到 OpenShift

在导入镜像和模板后，您可以将应用部署到 OpenShift。

OpenJDK 8 和 Eclipse OpenJ9 模板名称使用前缀 eap73-* ；例如，eap73-https-s2i。OpenJDK 11 模板名称使用前缀 eap73-openjdk11-* ；例如，eap73-openjdk11-https-s2i。

先决条件

可选： 模板可以为许多模板参数指定默认值，您可能需要覆盖部分或全部默认值。要查看模板信息，包括参数列表和任何默认值，请使用命令 oc describe template TEMPLATE_NAME。

流程

创建一个新的 OpenShift 应用，它将 JBoss EAP 用于 OpenShift 镜像和您的 Java 应用的源代码。您可以将其中一个提供的 JBoss EAP 用于 OpenShift 模板，以进行 S2I 构建。您也可以选择调配修剪的服务器。
例如，若要使用 JDK 8 构建器镜像部署 kitchensink 快速启动，请输入以下命令在 eap- demo 项目中使用 eap73-basic-s2i 模板，在准备 OpenShift for 应用部署中创建的 eap chen sink 源代码在 GitHub 上：这个快速入门不支持修剪功能。
```
oc new-app --template=eap73-basic-s2i \1
 -p IMAGE_STREAM_NAMESPACE=eap-demo \2
 -p SOURCE_REPOSITORY_URL=https://github.com/jboss-developer/jboss-eap-quickstarts \3
 -p SOURCE_REPOSITORY_REF=7.3.x-openshift \4
 -p CONTEXT_DIR=kitchensink5
```
1
要使用的模板。eap73 前缀指定 JDK 8 模板。
2
最新的镜像流和模板导入到项目命名空间中，因此您必须指定要查找镜像流的命名空间。这通常是项目的名称
3
包含应用源代码的存储库的 URL。
4
用于源代码的 Git 存储库引用。这可以是 Git 分支或标签引用。
5
要构建的源存储库中的目录。
注意
将此命令的修改版本用于 IBM Z 和 IBM Power Systems 上的 Eclipse OpenJ9 构建器镜像。在命令中包含下列镜像名称参数：JDK 环境将这些参数使用默认值。
- EAP_IMAGE_NAME=jboss-eap-7-openj9-11-openshift \
- EAP_RUNTIME_IMAGE_NAME=jboss-eap-7-openj9-11-runtime-openshift \
再举一个例子，若要使用 JDK 11 运行时镜像部署 helloworld-html5 快速启动并修剪 JBoss EAP 以仅包含 jaxrs-server 层，请输入以下命令：命令使用 eap- demo 项目中的 eap73-openjdk11-basic-s2i 模板（ 在用于应用部署的准备 OpenShift 中创建）和 GitHub 上的 helloworld-html5 源代码。
```
oc new-app --template=eap73-openjdk11-basic-s2i \1
 -p IMAGE_STREAM_NAMESPACE=eap-demo \2
 -p SOURCE_REPOSITORY_URL=https://github.com/jboss-developer/jboss-eap-quickstarts \3
 -p SOURCE_REPOSITORY_REF=7.3.x-openshift \4
 -p GALLEON_PROVISION_LAYERS=jaxrs-server \5
 -p CONTEXT_DIR=helloworld-html56
```
1
要使用的模板。eap73-openjdk11 前缀指定 JDK 11 模板。
2
最新的镜像流和模板导入到项目命名空间中，因此您必须指定要查找镜像流的命名空间。这通常是项目的名称。
3
包含应用源代码的存储库的 URL。
4
用于源代码的 Git 存储库引用。这可以是 Git 分支或标签引用。
5
调配仅包含 jaxrs-server 层的修剪服务器。
6
要构建的源存储库中的目录。
注意
在创建新的 OpenShift 应用时，您可能还想配置环境变量。
例如，如果您使用 eap73-https-s2i 等 HTTPS 模板，您必须指定所需的 HTTPS 环境变量 HTTPS _NAME、HTTPS_ PASSWORD 和 HTTPS_ KEYSTORE，才能匹配您的密钥存储详细信息。
注意
如果模板使用 AMQ，则必须包含带有适当值的 AMQ_IMAGE_NAME 参数。
如果模板使用 SSO，您必须包含带有适当值的 SSO_IMAGE_NAME 参数。
检索构建配置的名称：
```
$ oc get bc -o name
```
使用上一步中的构建配置名称来查看构建的 Maven 进度。
```
$ oc logs -f buildconfig/BUILD_CONFIG_NAME
```
例如，对于 kitchensink quickstart，以下命令显示 Maven 构建的进度：
```
$ oc logs -f buildconfig/eap-app
```

其它资源

针对 OpenShift 的 JBoss EAP 的功能调试

2.5. 部署后的任务

根据您的应用，可能需要在构建和部署 OpenShift 应用后执行一些任务。这可能包括公开服务，以便可以从 OpenShift 外部查看应用，或者将应用扩展到特定数量的副本。

使用以下命令获取应用的服务名称：
```
$ oc get service
```
将主服务作为路由公开，以便您可以从 OpenShift 外部访问您的应用。例如，对于 Kitchensink quickstart，使用以下命令来公开所需的服务和端口：
```
$ oc expose service/eap-app --port=8080
```
注意
如果您使用模板来创建应用，则路由可能已存在。如果存在，请继续下一步。
获取路由的 URL。
```
$ oc get route
```
使用 URL 访问 Web 浏览器中的应用。URL 是上一命令输出中 HOST/PORT 字段的值。
如果您的应用不使用 JBoss EAP 根上下文，请将应用的上下文附加到 URL。例如，对于 kitchensink quickstart，URL 可以是 http://HOST_PORT_VALUE/kitchensink/。
此外，您还可以通过运行以下命令来扩展应用实例：这会将副本数量增加到 3。
```
$ oc scale deploymentconfig DEPLOYMENTCONFIG_NAME --replicas=3
```
例如，对于 Kitchensink quickstart，使用以下命令来扩展应用：
```
$ oc scale deploymentconfig eap-app --replicas=3
```

2.6. JBoss EAP 中针对 OpenShift 的连锁构建支持

用于 OpenShift 的 JBoss EAP 支持 OpenShift 中的连锁构建。

用于 OpenShift 模板的 JBoss EAP 采用连锁构建。当您使用这些模板时，两个构建结果：

名为 [application name]-build-artifacts的中间镜像
最终镜像 [应用程序名称]

有关连锁构建的详情，请参阅 OpenShift 文档。

其它资源

OpenShift Chained 构建文档

第 3 章为 Java 应用程序配置 JBoss EAP for OpenShift 镜像

用于 OpenShift 的 JBoss EAP 映像已预配置为 Java 应用的基本用途。不过，您可以在镜像内配置 JBoss EAP 实例。推荐的方法是使用 OpenShift S2I 流程，以及应用模板参数和环境变量。

重要

当容器重启或终止时，运行中的容器上所做的任何配置更改都将丢失。

这包括使用传统 JBoss EAP 安装中包含的脚本进行的任何配置更改，如 add-user.sh 或管理 CLI。

强烈建议您使用 OpenShift S2I 流程以及应用模板参数和环境变量，在 JBoss EAP for OpenShift 镜像内对 JBoss EAP 实例进行任何配置更改。

3.1. 用于 OpenShift S2I 流程的 JBoss EAP 如何工作

说明 JBoss EAP 的 S2I 进程的流程图：

如果源代码存储库中存在 pom.xml 文件，S2I 构建器镜像将启动 Maven 构建流程。Maven 构建使用 $MAVEN_ARGS 的内容。
如果源代码存储库中不存在 pom.xml 文件，S2I 构建器镜像将启动二进制类型构建。
要添加自定义 Maven 参数或选项，请使用 $MAVEN_ARGS_APPEND。$MAVEN_ARGS_APPEND 变量将选项附加到 $MAVEN_ARGS。
默认情况下，OpenShift 配置文件使用 Maven 软件包 目标，其中包括用于跳过测试的系统属性(-DskipTests)和启用红帽 GA 存储库(-Dcom.redhat.xpaas.repo)。
Maven 构建成功的结果复制到 OpenShift 镜像 JBoss EAP 中的 EAP_HOME/standalone/deployments/ 目录中。这包括 $ARTIFACT_DIR 环境变量指定的源存储库中的所有 JAR、WAR 和 EAR 文件。ARTIFACT_DIR 的默认值是 Maven 目标目录。
注意
要在 JBoss EAP 上的代理后面将 Maven 用于 OpenShift 镜像，请设置 $HTTP_PROXY_HOST 和 $HTTP_PROXY_PORT 环境变量。另外，您还可以设置 $HTTP_PROXY_USERNAME、$HTTP_PROXY_PASSWORD 和 $HTTP_PROXY_NONPROXYHOSTS 变量。
模块 源存储库目录中的所有文件复制到 JBoss EAP for OpenShift 镜像的 EAP_HOME/modules/ 目录中。
configuration 源存储库目录中的所有文件复制到 JBoss EAP for OpenShift 镜像中的 EAP_HOME/standalone/configuration/ 目录中。如果要使用自定义 JBoss EAP 配置文件，请将文件命名为 standalone-openshift.xml。

其它资源

如需有关二进制类型构建的更多信息，请参阅 OpenShift 4.2 文档上的 Binary（本地）源。
如需有关如何指示 S2I 进程使用自定义 Maven 工件存储库镜像的其他指导，请参阅 Artifact Repository Mirrors。

3.2. 使用环境变量为 OpenShift 配置 JBoss EAP

使用环境变量是为 OpenShift 镜像配置 JBoss EAP 的推荐方法。如需有关为应用容器和构建容器指定环境变量的说明，请参阅 OpenShift 文档。

例如，您可以在创建 OpenShift 应用程序时使用环境变量设置 JBoss EAP 实例的管理用户名和密码：

oc new-app --template=eap73-basic-s2i \
 -p IMAGE_STREAM_NAMESPACE=eap-demo \
 -p SOURCE_REPOSITORY_URL=https://github.com/jboss-developer/jboss-eap-quickstarts \
 -p SOURCE_REPOSITORY_REF=7.3.x-openshift \
 -p CONTEXT_DIR=kitchensink \
 -e ADMIN_USERNAME=myspecialuser \
 -e ADMIN_PASSWORD=myspecialp@ssw0rd

注意

这个示例使用 JDK 8 模板。对于 JDK 11，使用 eap73-openjdk11-basic-s2i 模板。

参考信息中列出了 JBoss EAP for OpenShift 镜像的可用环境变量。

3.2.1. JVM 内存配置

OpenShift EAP 镜像具有根据当前环境自动计算默认 JVM 内存设置的机制，但也可以使用环境变量配置 JVM 内存设置。

3.2.1.1. JVM 默认内存设置

如果为当前容器定义了内存限值，并且限制低于可用内存总量，则会自动计算默认 JVM 内存设置。否则，默认 JVM 内存设置是 EAP 版本的 standalone.conf 文件中定义的默认文件，用作镜像的基础服务器。

容器内存限值从文件 /sys/fs/cgroup/memory/memory.limit_in_bytes 中检索。使用 /proc/meminfo 命令检索可用内存总量。

当自动计算内存设置时，会使用以下公式：

最大堆大小(-Xmx)： 50% 的用户内存
初始堆大小(-Xms)：计算的最大堆大小的 2 5%(25%)

例如，定义的内存限值为 1 GB，这个限制低于 /proc/meminfo 报告的总可用内存，然后内存设置将为： -Xms128m -Xmx512

您可以使用以下环境变量来修改自动计算的 JVM 设置：请注意，这些变量仅在自动计算默认内存大小时才使用（换句话说，定义有效的容器内存限值）。

JAVA_MAX_MEM_RATIO
JAVA_INITIAL_MEM_RATIO
JAVA_MAX_INITIAL_MEM

您可以通过将以下两个环境变量的值设置为 0 来禁用自动内存计算。

JAVA_INITIAL_MEM_RATIO
JAVA_MAX_MEM_RATIO

3.2.1.2. JVM Garbage Collection Settings

OpenShift 的 EAP 镜像包含垃圾回收和垃圾回收日志记录的设置

垃圾收集器设置

-XX:+UseParallelOldGC -XX:MinHeapFreeRatio=10 -XX:MaxHeapFreeRatio=20 -XX:GCTimeRatio=4 -XX:AdaptiveSizePolicyWeight=90 -XX:+ExitOnOutOfMemoryError

Java 8 的垃圾收集日志记录设置（非模式 JVM）

-verbose:gc -Xloggc:/opt/eap/standalone/log/gc.log -XX:+PrintGCDetails -XX:+PrintGCDateStamps -XX:+UseGCLogFileRotation -XX:NumberOfGCLogFiles=5 -XX:GCLogFileSize=3M -XX:-TraceClassUnloading

Java 11 的垃圾收集日志记录设置（模态 JVM）

-Xlog:gc*:file=/opt/eap/standalone/log/gc.log:time,uptimemillis:filecount=5,filesize=3M

3.2.1.3. 默认设置中的资源限制

如果设置，镜像中会包含其他默认设置。

-XX:ParallelGCThreads={core-limit} -Djava.util.concurrent.ForkJoinPool.common.parallelism={core-limit} -XX:CICompilerCount=2

{core-limit} 的值使用 JAVA_CORE_LIMIT 环境变量或容器实施的 CPU 核心限制来定义。

CICompilerCount 的值始终固定为 2。

3.2.1.4. JVM 环境变量

使用这些环境变量，在 EAP 中为 OpenShift 镜像配置 JVM。

表 3.1. JVM 环境变量

变量名称	示例	默认值	JVM 设置	描述
JAVA_OPTS	-verbose:class	没有默认	多个	要传递给 `java` 命令的 JVM 选项。使用 `JAVA_OPTS_APPEND` 配置额外的 JVM 设置。如果使用 `JAVA_OPTS`，一些不可配置的默认值不会添加到服务器 JVM 设置中。您必须明确添加这些设置。使用 `JAVA_OPTS` 时，将禁用容器脚本默认添加的某些设置。禁用的设置包括 -XX:MetaspaceSize=96M -Djava.net.preferIPv4Stack=true -Djboss.modules.system.pkgs=org.jboss.logmanager,jdk.nashorn..api,com.sun.crypto.provider -Djava.awt.headless=true 此外，如果没有启用自动内存计算，则不定义初始 Java 内存(-Xms)和最大 Java 内存(-Xmx)。如果您使用 `JAVA_OPTS` 配置附加设置，请添加这些默认值。
JAVA_OPTS_APPEND	-Dsome.property=value	没有默认	多个	用户指定的 Java 选项，可附加到 `JAVA_OPTS` 中生成的选项.
JAVA_MAX_MEM_RATIO	50	50	-Xmx	如果未在 `JAVA_OPTS` 中指定 `-Xmx` 选项，则使用此变量。此变量的值用于根据容器的限制计算默认的最大堆内存大小。如果在没有内存约束的容器中使用此变量，则变量无效。如果在具有内存约束的容器中使用此变量，则 `-Xmx` 的值被设置为容器可用内存的指定比率。默认值为 50，表示可用内存的 50% 用作上限。要跳过最大内存计算，将此变量的值设置为 0。No `-Xmx` 选项将添加到 `JAVA_OPTS`。
JAVA_INITIAL_MEM_RATIO	25	25	-xms	如果未在 `JAVA_OPTS` 中指定 `-Xms` 选项，则使用此变量。此变量的值用于根据最大堆内存计算默认初始堆内存大小。如果在没有内存约束的容器中使用此变量，则变量无效。如果在具有内存约束的容器中使用此变量，则 `-Xms` 的值被设置为 `-Xmx` 内存的指定比率。默认值为 25，表示最大内存的 25% 用作初始堆大小。要跳过初始内存的计算，将此变量的值设置为 0。No `-Xms` 选项将添加到 `JAVA_OPTS`。
JAVA_MAX_INITIAL_MEM	4096	4096	-xms	如果未在 `JAVA_OPTS` 中指定 `-Xms` 选项，则使用此变量。此变量的值用于计算初始内存堆的最大大小。该值以兆字节(MB)为单位表示。如果在没有内存约束的容器中使用此变量，则变量无效。如果此变量在具有内存约束的容器中使用，则 `-Xms` 的值将设置为变量中指定的值。默认值为 4096MB，指定最大初始堆永远不会大于 4096MB。
JAVA_DIAGNOSTICS	true	false (disabled)	设置取决于容器使用的 JDK。 OpenJDK8: -XX:NativeMemoryTracking=summary -XX:+PrintGC -XX:+PrintGCDateStamps -XX:+PrintGCTimeStamps -XX:+UnlockDiagnosticVMOptions OpenJDK11: -Xlog:gc:utctime -XX:NativeMemoryTracking=summary	将此变量的值设为 true，以在发生事件时将诊断信息包含在标准输出中。如果在 `JAVA_DIAGNOSTICS` 已定义为 true 的环境中将此变量定义为 true，则仍会包含诊断。
DEBUG	true	false	-agentlib:jdwp=transport=dt_socket,address=$DEBUG_PORT,server=y,suspend=n	启用远程调试。
DEBUG_PORT	8787	8787	-agentlib:jdwp=transport=dt_socket,address=$DEBUG_PORT,server=y,suspend=n	指定用于调试的端口。
JAVA_CORE_LIMIT		未定义	-XX:parallelGCThreads -Djava.util.concurrent.ForkJoinPool.common.parallelism -XX:CICompilerCount	内核数的用户定义的限制。如果容器报告了限制约束，则 JVM 设置的值仅限于容器核心限值。-XXCICompilerCount 的值始终为 2。默认情况下，此变量未定义。在这种情况下，如果容器中没有定义限制，则不会设置 JVM 设置。
GC_MIN_HEAP_FREE_RATIO	20	10	-XX:MinHeapFreeRatio	垃圾回收后最少空闲堆的百分比以避免扩展。
GC_MAX_HEAP_FREE_RATIO	40	20	-XX:MaxHeapFreeRatio	垃圾回收后的最大堆百分比以避免收缩。
GC_TIME_RATIO	4	4	-XX:GCTimeRatio	指定垃圾回收之外所用时间（例如，应用程序执行时间）与垃圾回收所花费的时间比例。
GC_ADAPTIVE_SIZE_POLICY_WEIGHT	90	90	-XX:AdaptiveSizePolicyWeight	给予当前垃圾收集时间与之前的垃圾回收时间的权重。
GC_METASPACE_SIZE	20	96	-XX:MetaspaceSize	初始元空间大小。
GC_MAX_METASPACE_SIZE	100	256	-XX:MaxMetaspaceSize	最大元空间大小。
GC_CONTAINER_OPTIONS	-XX:+UserG1GC	-XX:-UseParallelOldGC	-XX:-UseParallelOldGC	指定要使用的 Java 垃圾回收。变量的值应当是 JRE 命令行选项，用于指定所需的垃圾回收。指定的 JRE 命令覆盖默认值。

以下环境变量已弃用：

JAVA_OPTIONS ：使用 JAVA_OPTS。
INITIAL_HEAP_PERCENT ：使用 JAVA_INITIAL_MEM_RATIO.
container_HEAP_PERCENT ：使用 JAVA_MAX_MEM_RATIO。

3.3. 构建扩展和项目工件

OpenShift 镜像的 JBoss EAP 使用各种构件扩展 OpenShift 中的数据库支持。这些工件通过不同的机制包含在构建的镜像中：

S2I 工件，这些工件在 S2I 过程中注入到镜像中。
通过 OpenShift 机密机制提供的环境文件的运行时构件。

重要

现在，弃用了对将红帽提供的内部数据源驱动程序与 JBoss EAP 搭配使用的支持。红帽建议您将数据库供应商获取的 JDBC 驱动程序用于 JBoss EAP 应用。

JBoss EAP for OpenShift 镜像不再提供以下内部数据源：

MySQL
PostgreSQL

有关安装驱动程序的更多信息，请参阅模块、驱动程序和通用部署。

有关使用 JBoss EAP 配置 JDBC 驱动程序的更多信息，请参阅 JBoss EAP 配置指南中的 JDBC 驱动程序。

请注意，如果您想将其添加到置备的服务器中，您也可以创建自定义层来安装这些驱动程序和数据源。

其它资源

针对 OpenShift 的 JBoss EAP 的功能调试

3.3.1. S2I 工件

S2I 工件包括模块、驱动程序和其他通用部署，它们提供了部署所需的必要配置基础架构。此配置在 S2I 过程中构建至镜像中，因此在运行时仅需要配置数据源和相关资源适配器。

如需有关如何指示 S2I 流程利用自定义 Maven 工件存储库镜像的其他指导，请参阅 Artifact Repository Mirrors。

3.3.1.1. 模块、驱动程序和通用部署

以下几个选项可用于将这些 S2I 构件包含在用于 OpenShift 镜像的 JBoss EAP 中：

将工件包含在应用源部署目录中。构建期间下载工件并注入到镜像中。这类似于在用于 OpenShift 镜像的 JBoss EAP 上部署应用。
包含 CUSTOM_INSTALL_DIRECTORIES 环境变量，这是在 S2I 过程中用于安装和配置镜像工件的目录列表。在 S2I 中包括此信息有两种方法：
- 指定的 安装目录中的 install.sh 脚本。安装脚本在 S2I 过程中执行，并以强制方式运行。
  install.sh 脚本示例
```
#!/bin/bash

injected_dir=$1
source /usr/local/s2i/install-common.sh
install_deployments ${injected_dir}/injected-deployments.war
install_modules ${injected_dir}/modules
configure_drivers ${injected_dir}/drivers.env
```
  install.sh 脚本负责使用 install-common.sh 提供的 API 来自定义基础镜像。install-common.sh 包含 install.sh 脚本用于安装和配置模块、驱动程序和通用部署的功能。
  install-common.sh 中包含的功能：
  - install_modules
  - configure_drivers
  - install_deployments
    模块
    模块是用于类加载和依赖关系管理的逻辑类分组。模块在应用服务器的 EAP_HOME/modules/ 目录中定义。每个模块都作为子目录存在，如 EAP_HOME/modules/org/。每个模块目录随后包含一个插槽子目录，默认为 main，它包含 module.xml 配置文件以及任何所需的 JAR 文件。
    有关为 MySQL 和 PostgreSQL JDBC 驱动程序配置 module.xml 文件的更多信息，请参阅 JBoss EAP 配置指南中的数据源配置示例。
    PostgreSQL Datasource 的 module.xml 文件示例
    
    <?xml version="1.0" encoding="UTF-8"?> <module xmlns="urn:jboss:module:1.0" name="org.postgresql"> <resources> <resource-root path="postgresql-jdbc.jar"/> </resources> <dependencies> <module name="javax.api"/> <module name="javax.transaction.api"/> </dependencies> </module>
    
    MySQL Connect/J 8 数据源的 module.xml 文件示例
    
    <?xml version="1.0" encoding="UTF-8"?> <module xmlns="urn:jboss:module:1.0" name="com.mysql"> <resources> <resource-root path="mysql-connector-java-8.0.Z.jar" /> </resources> <dependencies> <module name="javax.api"/> <module name="javax.transaction.api"/> </dependencies> </module>
    
    注意
    mysql-connector-java-8.0.Z.jar 中的 ".Z " 指示下载的 JAR 文件的版本。可以重命名文件，但名称必须与 module.xml 文件中的名称匹配。
    install .sh 中的 install _modules 功能将对应的 JAR 文件复制到 JBoss EAP 中的模块目录中，以及 module.xml。
    驱动程序
    驱动程序作为模块安装。该驱动程序随后由 configure_drivers 功能在 install.sh 中配置，其配置属性在运行时工件环境文件中定义。
    添加数据源驱动程序
    MySQL 和 PostgreSQL 数据源不再作为预配置的内部数据源提供。您仍可将这些驱动程序安装为模块；请参阅模块、驱动程序和通用部署中的描述。您可以从数据库供应商为 JBoss EAP 应用获取这些 JDBC 驱动程序。
    为 要安装的每个数据源创建一个 driver.env 文件。
    MySQL Datasource 的 Driver.env 文件示例
    
    #DRIVER DRIVERS=MYSQL MYSQL_DRIVER_NAME=mysql MYSQL_DRIVER_MODULE=org.mysql MYSQL_DRIVER_CLASS=com.mysql.cj.jdbc.Driver MYSQL_XA_DATASOURCE_CLASS=com.mysql.jdbc.jdbc2.optional.MysqlXADataSource
    
    PostgreSQL Datasource 的 driver.env 文件示例
    
    #DRIVER DRIVERS=POSTGRES POSTGRES_DRIVER_NAME=postgresql POSTGRES_DRIVER_MODULE=org.postgresql POSTGRES_DRIVER_CLASS=org.postgresql.Driver POSTGRES_XA_DATASOURCE_CLASS=org.postgresql.xa.PGXADataSource
    
    有关下载各种驱动程序的位置（如 MySQL 或 PostgreSQL）的详情，请参阅《配置指南》中的 JDBC 驱动程序下载位置。

通用部署

可以使用 install -common.sh 中的 API 提供的 install_deployments 功能，从注入的镜像部署 JAR、WAR、RAR 或 EAR 等可部署存档文件。

如果已声明 CUSTOM_INSTALL_DIRECTORIES 环境变量，但没有在自定义安装目录中找到 install.sh 脚本，则以下工件目录将复制到构建镜像中的对应目的地：
- modules/* 复制到 $JBOSS_HOME/modules/system/layers/openshift
- configuration/* 复制到 $JBOSS_HOME/standalone/configuration
- Deployment/* 复制到 $JBOSS_HOME/standalone/deployments
与 install.sh 替代方案相比，这是一种基本的配置方法，并且要求构件进行适当的结构。

3.3.2. Runtime Artifacts

3.3.2.1. datasources

数据源有两种类型：

内部数据源.这些数据源在 OpenShift 上运行，但通过 Red Hat Registry 默认不可用。这些数据源的配置由添加到 OpenShift Secret 的环境文件提供。
外部数据源.这些数据源不在 OpenShift 上运行。外部数据源的配置由添加到 OpenShift Secret 的环境文件提供。

示例：数据源环境文件

DB_SERVICE_PREFIX_MAPPING=PostgresXA-POSTGRES=DS1
DS1_JNDI=java:jboss/datasources/pgds
DS1_DRIVER=postgresql-42.2.5.jar
DS1_USERNAME=postgres
DS1_PASSWORD=postgres
DS1_MAX_POOL_SIZE=20
DS1_MIN_POOL_SIZE=20
DS1_CONNECTION_CHECKER=org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker
DS1_EXCEPTION_SORTER=org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter

DB_SERVICE_PREFIX_MAPPING 属性是一个以逗号分隔的数据源属性前缀列表。然后，这些前缀附加到该数据源的所有属性中。然后，可以将多个数据源包含在单个环境文件中。另外，每个数据源也可以在单独的环境文件中提供。

数据源包含两种类型的属性：连接池特定属性和数据库驱动程序特定属性。连接池相关的属性生成与数据源的连接。数据库驱动程序特定属性决定数据源的驱动程序，并配置为驱动程序 S2I 工件。

在上例中，DS1 是数据源前缀，CONNECTION_CHECKER 指定一个用于验证数据库连接的连接检查器类，EXCEPTION_SORTER 指定用于检测严重数据库连接异常的分类器类。

数据源环境文件添加到项目的 OpenShift Secret 中。然后，模板中使用 ENV_FILES environment 属性调用这些环境文件，其值是完全限定环境文件的逗号分隔列表，如下所示：

{
    “Name”: “ENV_FILES”,
    “Value”: “/etc/extensions/datasources1.env,/etc/extensions/datasources2.env”
}

3.3.2.2. 资源适配器

资源适配器配置由添加到 OpenShift Secret 的环境文件提供。

表 3.2. 资源适配器属性

属性	描述
PREFIX_ID	服务器配置文件中指定的资源适配器标识符。
前缀_ARCHIVE	资源适配器存档。
PREFIX_MODULE_SLOT	插槽子目录，其中包含 `module.xml` 配置文件和任何所需的 JAR 文件。
PREFIX_MODULE_ID	JBoss 模块 ID，可以从中加载对象工厂 Java 类。
前缀 _CONNECTION_CLASS	受管连接工厂或 admin 对象的完全限定类名称。
PREFIX_CONNECTION_JNDI	连接工厂的 JNDI 名称。
PREFIX_PROPERTY_ParentDirectory	存储数据文件的目录。
PREFIX_PROPERTY_AllowParentPaths	将 `AllowParentPaths` 设置为 `false` 以禁止 `。` 在路径中。这可以防止请求父目录中不包含的文件。
PREFIX_POOL_MAX_SIZE	池的最大连接数。不会在每个子池中创建更多连接。
PREFIX_POOL_MIN_SIZE	池的最小连接数。
PREFIX_POOL_PREFILL	指定是否应预先填充池。更改此值需要重新启动服务器。
前缀 _POOL_FLUSH_STRATEGY	出现错误时，应如何清空池。有效值为：Fa `ilingConnectionOnly` （默认）、`IdleConnections` 和 `EntirePool`。

RESOURCE_ADAPTERS 属性是一个以逗号分隔的资源适配器属性前缀列表。然后，这些前缀会附加到该资源适配器的所有属性中。然后，可将多个资源适配器包含在单个环境文件中。在以下示例中，MYRA 用作资源适配器的前缀。另外，每个资源适配器也可以在单独的环境文件中提供。

示例：资源适配器环境文件

#RESOURCE_ADAPTER
RESOURCE_ADAPTERS=MYRA
MYRA_ID=myra
MYRA_ARCHIVE=myra.rar
MYRA_CONNECTION_CLASS=org.javaee7.jca.connector.simple.connector.outbound.MyManagedConnectionFactory
MYRA_CONNECTION_JNDI=java:/eis/MySimpleMFC

资源适配器环境文件添加到项目命名空间的 OpenShift Secret 中。然后，模板中使用 ENV_FILES environment 属性调用这些环境文件，其值是完全限定环境文件的逗号分隔列表，如下所示：

{
    "Name": "ENV_FILES",
    "Value": "/etc/extensions/resourceadapter1.env,/etc/extensions/resourceadapter2.env"
}

3.4. 为 OpenShift 使用 JBoss EAP 模板的结果

当您使用 JBoss EAP 模板编译应用时，可能会生成两个镜像。

在创建最终镜像 [application name]-build-artifacts 之前，可能会生成名为 [application name] 的中间镜像。

您可以在部署应用程序后删除 [application name]-build-artifacts 镜像。

3.5. 用于 OpenShift 镜像的红帽 JBoss 企业应用平台的 SSO 配置

在适用于 OpenShift 镜像的红帽 JBoss 企业应用平台中，SSO 配置为使用传统 安全 子系统。

这些镜像中将 environmment 变量 SSO_FORCE_LEGACY_SECURITY 设置为 true。

如果要 将 elytron 子系统用于 SSO 安全，请将 SSO_FORCE_LEGACY_SECURITY 环境变量的值更新为 false。

3.6. 默认数据源

在 JBoss EAP 7.3 中，默认数据源 ExampleDS 已被删除。

有些快速入门需要这个数据源：

cmt
thread-racing

由客户开发的应用程序可能还需要默认的数据源。

如果您需要默认数据源，请使用 GENERATE_DEFAULT_DATASOURCE 环境变量在调配 JBoss EAP 服务器时包括它。

ENABLE_GENERATE_DEFAULT_DATASOURCE=true

3.7. 用于 OpenShift 镜像的 JBoss EAP 的部署注意事项

3.7.1. 扩展和持久性存储分区

使用持久存储部署 JBoss EAP 有两种方法：单节点分区和多节点分区。

单节点分区将 JBoss EAP 数据存储目录（包括事务数据）存储在存储卷中。

多节点分区创建额外的独立 分割 -n 目录以存储每个 JBoss EAP pod 的事务数据，其中 n 是一个增量整数。如果 JBoss EAP pod 更新、意外停机或重新部署，则不会更改此通信。当 JBoss EAP pod 再次正常运行时，它将重新连接到关联的拆分目录，并像以前一样继续。如果添加了新的 JBoss EAP pod，则会为该 pod 创建一个相应的 split-n 目录。

要启用多节点配置，您必须将 SPLIT_DATA 参数设置为 true。这会使服务器为用作数据存储的持久性卷中的每个实例创建独立的 split-n 目录。

警告

在使用 EAP 操作器时，使用 SPLIT_DATA 等环境变量可能会导致一致性问题。您必须使用 EAP 操作器来管理 OpenShift 4 及更高版本中的事务发现。

重要

由于单节点和多节点分区的不同存储方法，将部署从单节点更改为多节点会导致应用程序丢失以前存储在数据目录中的所有数据，包括消息、事务日志等。如果将部署从多节点更改为单节点，则也是如此，因为存储路径不匹配。

3.7.2. 扩展缩减和交易恢复

使用多节点配置部署用于 OpenShift 镜像的 JBoss EAP 时，如果群集缩减，则可能将意外终止的事务保留在终止容器集的数据目录中。

请参阅手动事务恢复以完成这些分支。

第 4 章针对 OpenShift 的 JBoss EAP 的功能调试

构建包含 JBoss EAP 的镜像时，您可以控制要包含在镜像中的 JBoss EAP 功能和子系统。

S2I 镜像中包含的默认 JBoss EAP 服务器包括完整的服务器和所有功能。您可能想要减少调配的服务器中包含的功能。例如，您可能要减少调配的服务器的安全暴露，或者您可能要减小内存占用空间，使其更适合微服务容器。

4.1. 调配自定义 JBoss EAP 服务器

要调配具有修剪功能的自定义服务器，请在 S2I 构建阶段传递 GALLEON_PROVISION_LAYERS 环境变量。

环境变量的值是用于置备以构建服务器的层的逗号分隔列表。

例如，如果您将环境变量指定为 GALLEON_PROVISION_LAYERS=jaxrs-server,sso，则会为 JBoss EAP 服务器置备以下功能：

Servlet 容器
配置数据源的功能
jaxrs、we ld 和 jpa 子系统
Red Hat SSO 集成

4.2. 可用的 JBoss EAP 层

红帽提供六个层来自定义 OpenShift 中的 JBoss EAP 服务器调配。

三个层是提供核心功能的基础层。有三个是增强基础层的 decorator 层。

任何调配层不支持以下 Jakarta EE 规格：

Jakarta Server Faces 2.3
Jakarta Enterprise Beans 3.2
Jakarta XML Web Services 2.3

4.2.1. base Layers

每个基础层都包含适用于典型服务器用户案例的核心功能。

datasources-web-server

此层包括一个 servlet 容器，以及配置数据源的功能。

此层不包括 MicroProfile 功能。

以下是 datasources-web-server 中默认包含的 JBoss EAP 子系统：

core-management
datasources
deployment-scanner
EE
elytron
io
jca
jmx
logging
naming
request-controller
security-manager
事务
undertow

此层支持以下 Jakarta EE 规格：

Jakarta JSON Processing 1.1
Jakarta JSON Binding 1.0
Jakarta Servlet 4.0
Jakarta Expression Language 3.0
Jakarta 服务器页面 2.3
Jakarta Standard Tag Library 1.2
jakarta Concurrency 1.1
Jakarta Annotations 1.3
Jakarta XML Binding 2.3
雅加达调试支持其他语言 1.0
Jakarta Transactions 1.3
Jakarta Connectors 1.7

jaxrs-server

该层通过以下 JBoss EAP 子系统 增强了数据源-web-server 层：

jaxrs
weld
jpa

此层还添加了基于 Infinispan 的第二级实体在容器中进行本地缓存。

此层中包含以下 MicroProfile 功能：

MicroProfile REST Client

除了 datasources-web-server 层所支持的以下 Jakarta EE 规格外，还支持以下 Jakarta EE 规格：

Jakarta 上下文和依赖注入 2.0
Jakarta Bean 验证 2.0
Jakarta Interceptors 1.2
Jakarta RESTful Web Services 2.1
Jakarta Persistence 2.2

cloud-server

该层使用以下 JBoss EAP 子系统增强了 jaxrs-server 层：

resource-adapters
messaging-activemq （远程代理消息传递，而非嵌入式消息传递）

此层还会在 jaxrs-server 层中添加以下可观察功能：

MicroProfile Health
MicroProfile Metrics
MicroProfile Config
MicroProfile OpenTracing

除了 jaxrs-server 层支持的以下 Jakarta EE 规格外，还支持以下 Jakarta EE 规格：

Jakarta 安全 1.0

4.2.2. decorator Layers

解码器层不单独使用。您可以使用基础层配置一个或多个 decorator 层，以提供额外的功能。

sso

这个解码器层将红帽单点登录集成添加到调配的服务器中。

Observability（可观察性）

这个 decorator 层在置备的服务器中添加以下可观察功能：

MicroProfile Health
MicroProfile Metrics
MicroProfile Config
MicroProfile OpenTracing

注意

此层内置到 cloud-server 层。您不需要将此层添加到 云服务器层。

web-clustering

此层将嵌入式 Infinispan 型 Web 会话集群添加到调配的服务器。

4.3. 在 JBoss EAP 中配置用户开发的层

除了红帽提供的调配层外，您还可以配置您开发的自定义层。

流程

使用 Galleon Maven 插件构建自定义层。
如需更多信息，请参阅为 JBoss EAP 构建自定义层。
将自定义层部署到可访问的 Maven 存储库。
创建自定义调配文件，以引用用户定义的层并支持的 JBoss EAP 层，并将它存储在您的应用目录中。
如需更多信息，请参阅 JBoss EAP 的自定义配置文件。
运行 S2I 流程以在 OpenShift 中调配 JBoss EAP 服务器。
如需更多信息，请参阅使用用户开发的层构建应用程序配置。

4.3.1. 为 JBoss EAP 构建自定义层

创建自定义层功能包作为 Maven 项目。

自定义层至少依赖于一个基础层。选择为您的自定义层提供所需功能的基础层。

在 Maven 项目中，在 src/main/resources 目录中创建您的层内容。

例如，要在 src/main/resources 目录中创建层来调配对 PostgreSQL 和 PostgreSQL 数据源的支持，以创建 tier /standalone 子目录。单机 子目录包含以下内容：

postgresql-driver

此目录包含包含以下内容的 layer-spec.xml 文件：

<?xml version="1.0" ?>
<layer-spec xmlns="urn:jboss:galleon:layer-spec:1.0" name="postgresql-driver">
    <feature spec="subsystem.datasources">
        <feature spec="subsystem.datasources.jdbc-driver">
            <param name="driver-name" value="postgresql"/>
            <param name="jdbc-driver" value="postgresql"/>
            <param name="driver-xa-datasource-class-name" value="org.postgresql.xa.PGXADataSource"/>
            <param name="driver-module-name" value="org.postgresql.jdbc"/>
        </feature>
    </feature>
    <packages>
        <package name="org.postgresql.jdbc"/>
    </packages>
</layer-spec>

postgresql-datasource

此目录包含包含以下内容的 layer-spec.xml 文件：

<?xml version="1.0" ?>
<layer-spec xmlns="urn:jboss:galleon:layer-spec:1.0" name="postgresql-datasource">
    <dependencies>
        <layer name="postgresql-driver"/>
    </dependencies>
    <feature spec="subsystem.datasources.data-source">
        <param name="use-ccm" value="true"/>
        <param name="data-source" value="PostgreSQLDS"/>
        <param name="enabled" value="true"/>
        <param name="use-java-context" value="true"/>
        <param name="jndi-name" value="java:jboss/datasources/${env.POSTGRESQL_DATASOURCE,env.OPENSHIFT_POSTGRESQL_DATASOURCE:PostgreSQLDS}"/>
        <param name="connection-url" value="jdbc:postgresql://${env.POSTGRESQL_SERVICE_HOST,\
env.OPENSHIFT_POSTGRESQL_DB_HOST}:${env.POSTGRESQL_SERVICE_PORT,\
env.OPENSHIFT_POSTGRESQL_DB_PORT}/${env.POSTGRESQL_DATABASE, env.OPENSHIFT_POSTGRESQL_DB_NAME}"/>
        <param name="driver-name" value="postgresql"/>
        <param name="user-name" value="${env.POSTGRESQL_USER, env.OPENSHIFT_POSTGRESQL_DB_USERNAME}"/>
        <param name="password" value="${env.POSTGRESQL_PASSWORD, env.OPENSHIFT_POSTGRESQL_DB_PASSWORD}"/>
        <param name="check-valid-connection-sql" value="SELECT 1"/>
        <param name="background-validation" value="true"/>
        <param name="background-validation-millis" value="60000"/>
        <param name="flush-strategy" value="IdleConnections"/>
        <param name="statistics-enabled" value="${wildfly.datasources.statistics-enabled:${wildfly.statistics-enabled:false}}" />
    </feature>

在用于构建自定义功能包的 pom.xml 文件中，请参阅 JBoss EAP 依赖项。
```
<dependency>
    <groupId>org.jboss.eap</groupId>
    <artifactId>wildfly-ee-galleon-pack</artifactId>1
    <version>7.3.0.GA-redhat-00004</version>
    <type>zip</type>
</dependency>
```
1
使用 JBoss EAP 扩展包(JBoss EAP XP)时，此元素的值应当是 wildfly-galleon-pack。
Red Hat Maven 存储库中提供了这些依赖项：https://maven.repository.redhat.com/ga/
使用 Galleon Maven 插件中的 build-user-feature-pack 目标来构建自定义层。

其它资源

base Layers

WildFly Galleon Maven 插件文档

将驱动程序和数据源打包作为 Galleon 层的示例

4.3.2. JBoss EAP 的自定义配置文件

自定义调配文件是文件名 provisioning.xml 的 XML 文件，存储在 galleon 子目录中。

以下代码演示了自定义调配文件。

<?xml version="1.0" ?>
<installation xmlns="urn:jboss:galleon:provisioning:3.0">
    <feature-pack location="eap-s2i@maven(org.jboss.universe:s2i-universe)">1
        <default-configs inherit="false"/>2
        <packages inherit="false"/>3
    </feature-pack>
    <feature-pack location="com.example.demo:my-galleon-feature-pack:1.0
">4
        <default-configs inherit="false"/>
        <packages inherit="false"/>
    </feature-pack>
    <config model="standalone" name="standalone.xml">5
        <layers>
            <include name="cloud-server"/>
            <include name="my-custom-driver"/>
            <include name="my-custom-datasource"/>
        </layers>
    </config>
    <options>6
        <option name="optional-packages" value="passive+"/>
    </options>
</installation>

1: 此元素指示调配流程调配当前的 eap-s2i 功能包。请注意，构建器镜像仅包含一个功能包。
2: 此元素指示调配流程排除默认配置。
3: 此元素指示调配流程排除默认软件包。
4: 此元素指示调配流程调配 com.example.demo:my-galleon-feature-pack:1.0 功能包。子元素指示进程排除默认配置和默认软件包。
5: 此元素指示调配流程创建自定义单机配置。该配置包括来自 com .example.demo:my -galleon-feature -pack:1.0 功能包的 cloud-server 基础层和 my-custom-driver 和 my-custom- datasource 自定义层。
6: 此元素指示调配流程以优化 JBoss EAP 模块的调配。

4.3.3. 使用用户开发的层构建应用程序

从包含自定义调配文件的目录构建应用时，S2I 构建流程会检测调配文件并按指示调配 JBoss EAP 服务器。

先决条件

用户开发的层必须存在于可访问的 Maven 存储库中。
应用程序目录必须包含有效的调配文件，该文件指向用户开发的层以及包含它们的功能包。

流程

输入标准 S2I build 命令以构建应用。

例如，假设您在应用目录中创建以下自定义调配文件：

<?xml version="1.0" ?>
<installation xmlns="urn:jboss:galleon:provisioning:3.0">
    <feature-pack location="eap-s2i@maven(org.jboss.universe:s2i-universe)">
        <default-configs inherit="false"/>
        <packages inherit="false"/>
    </feature-pack>
    <feature-pack location="com.example.demo:my-galleon-feature-pack:1.0">
        <default-configs inherit="false"/>
        <packages inherit="false"/>
    </feature-pack>
    <config model="standalone" name="standalone.xml">
        <layers>
            <include name="cloud-server"/>
            <include name="my-custom-driver"/>
            <include name="my-custom-datasource"/>
        </layers>
    </config>
    <options>
        <option name="optional-packages" value="passive+"/>
    </options>
</installation>

以下命令使用 com.example.demo:my-galleon-feature-pack:1.0 功能包构建应用，其中包括 my-custom-driver 和 my-custom-datasource 层。生成的应用命名为 eap-my-custom-db。与数据库的连接使用环境变量进行配置。

oc build my-app \
-e DEMO_DB=demo \
-e DEMO_PASSWORD=demo \
-e DEMO_HOST=127.0.0.1  \
-e DEMO_PORT=5432 \
-e DEMO_USER=demo \
eap-my-custom-db

您可以使用 demo 用户和密码 demo 在端口 5432 上登录数据库。

其它资源

JBoss EAP 的自定义配置文件

第 5 章将应用从 OpenShift 4 上的 JBoss EAP Imagestreams 迁移到 eap73 Imagestreams

为 eap71 和 eap 72 镜像流开发的应用需要更改，才能在 eap73 镜像流中正常工作。

5.1. eap73 镜像流的存活度和就绪度探测配置更新

从 OpenShift 3.11 上运行的 eap72 镜像迁移到任何 eap 73 镜像时，必须调整探测的 YAML 配置。

在 eap72 镜像中，存活度探测的默认 YAML 配置类似如下代码示例：

OpenShift 3.11 存活度探测上的 eap72 镜像的 YAML 配置示例

livenessProbe:
        exec:
          command:
            - /bin/bash
            - '-c'
            - /opt/eap/bin/livenessProbe.sh
        initialDelaySeconds: 60
        periodSeconds: 10
        successThreshold: 1
        failureThreshold: 3

在本例中，存活度探测位于 JBoss EAP 镜像中的 /opt/eap/bin/livenessProbe.sh。该探测会在 60 秒初始延迟后第一次触发，然后在 JBoss EAP 服务器上启动 pod 后每隔 10 秒触发一次。

三个失败的探测失败后，容器就被视为不健康，OpenShift 将在其容器集中重新启动容器。

在 eap72 镜像上，一个调用会持续 5 秒，然后返回为成功或失败。调用后跟 10 秒等待期。这意味着，如果 JBoss EAP 镜像不健康，则在 pod 内的容器重启前 3 次调用持续大约 35 秒。

在任何 eap73 镜像上，一个调用会持续不到 1 秒。三个调用持续大约 23 秒。在 YAML 配置中，应对 eap73 镜像的探测配置进行如下调整：

任何 eap73 镜像流存活度探测的 YAML 配置示例

livenessProbe:
        exec:
          command:
            - /bin/bash
            - '-c'
            - /opt/eap/bin/livenessProbe.sh
        initialDelaySeconds: 60
        periodSeconds: 16
        successThreshold: 1
        failureThreshold: 3

在这个示例中，periodSeconds 增加了 6 秒。现在，第一个调用持续 1 秒，后跟 16 秒等待期间。三个调用将持续大约 34 秒，这与探测的 eap72 镜像行为几乎等同。

在就绪度探测中，使用类似值在 YAML 配置中更新 periodSeconds。

任何 eap73 镜像流就绪度探测的 YAML 配置示例

readinessProbe:
        exec:
          command:
            - /bin/bash
            - '-c'
            - /opt/eap/bin/readinessProbe.sh
        initialDelaySeconds: 10
        periodSeconds: 16
        successThreshold: 1
        failureThreshold: 3

其它资源

监控 OpenShift 4 上的容器健康状况

OpenShift 3.11 上的存活度和就绪度探测

5.2. 默认数据源删除

在 JBoss EAP 7.3 中，默认数据源已从 JBoss EAP 镜像流中删除。

如果您开发了使用默认数据源的自定义应用程序，您可以在置备服务器时包括它。使用 ENABLE_GENERATE_DEFAULT_DATASOURCE 环境变量，值设为 true。

ENABLE_GENERATE_DEFAULT_DATASOURCE=true

5.3. 在 OpenShift 中将 JBoss EAP 7.1 升级到 JBoss EAP 7.3 时对 `standalone-openshift.xml` 的更新

JBoss EAP 7.1 安装的配置文件 standalone-openshift.xml 与 JBoss EAP 7.3 及更高版本不兼容。

如果要在从 JBoss EAP 7.1 升级到 JBoss EAP 7.3 后使用 standalone-openshift.xml 文件，您必须对文件进行以下更改：

更新 logging 子系统的版本。

替换

<subsystem xmlns="urn:jboss:domain:logging:3.0">

使用

<subsystem xmlns="urn:jboss:domain:logging:8.0">

更新 logging 子系统配置中的日志格式器：

替换

<custom-formatter module="org.jboss.logmanager.ext" class="org.jboss.logmanager.ext.formatters.LogstashFormatter">
    <properties>
        <property name="metaData" value="log-handler=CONSOLE"/>
    </properties>
</custom-formatter>

使用

<json-formatter>
    <exception-output-type value="formatted"/>
    <key-overrides timestamp="@timestamp"/>
    <meta-data>
        <property name="@version" value="1"/>
    </meta-data>
</json-formatter>

第 6 章故障排除

6.1. Pod 重启故障排除

由于多种原因，容器集可以重新启动，但 JBoss EAP pod 重新启动的常见原因可能包括 OpenShift 资源约束，特别是内存不足问题。如需有关 OpenShift 容器集驱除的更多信息，请参阅 OpenShift 文档。

默认情况下，用于 OpenShift 模板的 JBoss EAP 配置为在其遇到内存不足问题等情况时自动重新启动受影响的容器。以下步骤可以帮助您诊断内存不足和其他 pod 重启问题并进行故障排除。

获取遇到问题的 pod 的名称。
您可以看到容器集名称，以及每个容器集通过以下命令重启的次数。
```
$ oc get pods
```
若要诊断容器集重新启动的原因，您可以检查上一容器集的 JBoss EAP 日志或 OpenShift 事件。
1. 要查看上述 pod 的 JBoss EAP 日志，请使用以下命令：
```
oc logs --previous POD_NAME
```
2. 若要查看 OpenShift 事件，可使用以下命令：
```
$ oc get events
```
如果容器集因为资源问题而重启，您可以尝试修改 OpenShift 容器集配置，以增加其资源请求和限值。如需有关配置 pod 计算资源的更多信息，请参阅 OpenShift 文档。

6.2. 使用 JBoss EAP 管理 CLI 进行故障排除

JBoss EAP 管理 CLI EAP_HOME/bin/jboss-cli.sh 可以从容器内访问，以满足故障排除需要。

重要

不建议使用 JBoss EAP 管理 CLI 在运行的容器集中进行配置更改。当容器重启时，使用管理 CLI 在运行的容器中进行的任何配置更改都将丢失。

若要对 OpenShift 的 JBoss EAP 进行配置更改，请参阅为 Java 应用配置用于 OpenShift 镜像的 JBoss EAP。

首先，打开一个连接至正在运行的容器集的远程 shell 会话。
```
$ oc rsh POD_NAME
```
在远程 shell 会话中运行以下命令来启动 JBoss EAP 管理 CLI：
```
$ /opt/eap/bin/jboss-cli.sh
```

第 7 章用于在 OpenShift 上自动部署应用的 EAP Operator

EAP 操作器是特定于 JBoss EAP 的控制器，用于扩展 OpenShift API。您可以使用 EAP 操作器创建、配置、管理和无缝升级复杂有状态应用的实例。

EAP 操作器在集群中管理多个 JBoss EAP Java 应用实例。它还通过验证所有事务是否在缩减副本前完成，并将 pod 标记为 干净 以进行终止，以此确保应用集群中的安全交易恢复。EAP 操作器使用 StatefulSet 来适当处理 EJB 远程处理和事务恢复处理。StatefulSet 确保 持久性存储和网络主机名的稳定性，即使在 pod 重启后也是如此。

您必须使用 OperatorHub 安装 EAP 操作器，供 OpenShift 集群管理员用来发现、安装和升级操作器。

在 OpenShift Container Platform 4 中，您可以使用 Operator Lifecycle Manager(OLM)来安装、更新和管理所有操作器以及在多个集群中运行的关联服务的生命周期。

OLM 在 OpenShift Container Platform 4 中默认运行。它协助集群管理员对集群上运行的操作器进行安装、升级和授予访问权限。OpenShift Container Platform Web 控制台为集群管理员提供安装操作器的管理屏幕，以及授予特定项目的访问权限，以使用集群上可用的操作器目录。

如需有关操作器和 OLM 的更多信息，请参阅 OpenShift 文档。

7.1. 使用 Web 控制台安装 EAP Operator

作为 JBoss EAP 集群管理员，您可以使用 OpenShift Container Platform Web 控制台从红帽 OperatorHub 安装 EAP operator。然后，您可以将 EAP 操作器订阅到一个或多个命名空间，供集群上的开发人员使用。

以下是在使用 Web 控制台安装 EAP 操作器前必须注意的几个要点：

Installation Mode：选择 All namespaces on the cluster(default) 来在所有命名空间中安装 Operator，或选择单独的命名空间（如果可用），以仅在所选命名空间中安装 Operator。
更新频道：如果 EAP 操作器可以通过多个频道获得，您可以选择您要订阅的频道。例如，要通过 stable 频道部署（如果可用），则从列表中选择这个选项。
批准策略：您可以选择自动或手动更新。如果选择自动更新 EAP Operator，则当有新版本的 Operator 可用时，Operator Lifecycle Manager(OLM)会自动升级 EAP operator 的正在运行的实例。如果选择手动更新，则当有新版本的 Operator 可用时，OLM 会创建更新请求。然后，您必须手动批准更新请求，使 Operator 更新至新版本。

注意

以下流程可能会根据 OpenShift Container Platform Web 控制台中的修改而更改。有关最新和最准确的步骤，请参阅 OpenShift Container Platform 指南使用 Operator 的最新版本中的使用 Web 控制台从 OperatorHub 安装。

先决条件

使用具有 cluster-admin 权限的账户访问 OpenShift Container Platform 集群。

流程

在 OpenShift Container Platform Web 控制台中，导航到 Operators→ OperatorHub。
向下滚动，或在 Filter by keyword 框中键入 EAP，以查找 EAP 操作器。
选择 JBoss EAP 操作器并单击 Install。
在 Create Operator Subscription 页面：
1. 任选以下一项：
  - All namespaces on the cluster(default)，将 Operator 安装至默认的 openshift-operators 命名空间，以便供集群中的所有命名空间监视和使用。该选项并非始终可用。
  - 集群上的特定命名空间会在您选择的特定单一命名空间中安装 Operator。Operator 仅在这个单一命名空间中可用。
2. 选择一个 Update Channel。
3. 如前面所述，选择自动或手动批准策略。
单击 Subscribe，使 EAP 操作器可供 OpenShift Container Platform 集群上的所选命名空间使用。
1. 如果您选择了手动批准策略，订阅的升级状态将保持在 Upgrading，直到您审核并批准了安装计划。在 Install Plan 页面批准安装计划后，订阅升级状态将变为 Up to date。
2. 如果您选择了自动批准策略，则升级状态会在无需干预的情况下变为 Up to date。
在订阅的升级状态变为 Up to date 后，选择 Operators → Installed Operators 来验证 EAP ClusterServiceVersion(CSV)是否显示，并在相关命名空间中显示其 Status 更改为InstallSucceeded。
注意
对于 All namespaces… 安装模式，openshift-operators 命名空间中显示的状态为 InstallSucceeded。在其他命名空间中，显示的状态为 Copied。
如果 Status 字段没有更改为 InstallSucceeded，请检查 openshift-operators 项目（如果选择了 特定命名空间… 安装模式）中任何 pod 的日志，这会在 Workloads → Pods 页面中报告问题以便进一步排除故障。

7.2. 使用 CLI 安装 EAP Operator

作为 JBoss EAP 集群管理员，您可以使用 OpenShift Container Platform CLI 安装来自红帽 OperatorHub 的 EAP operator。然后，您可以将 EAP 操作器订阅到一个或多个命名空间，供集群上的开发人员使用。

使用 CLI 从 OperatorHub 安装 EAP operator 时，请使用 oc 命令创建 Subscription 对象。

先决条件

可以使用具有 cluster-admin 权限的账户访问 OpenShift Container Platform 集群。
已在本地系统中安装了 oc 工具。

流程

查看 OperatorHub 中集群可用的操作器列表：

$ oc get packagemanifests -n openshift-marketplace | grep eap
NAME        CATALOG               AGE
...
eap         Red Hat Operators     43d
...

创建一个 Subscription 对象 YAML 文件（如 eap-operator-sub.yaml），以便为 EAP operator 订阅命名空间。以下是 Subscription 对象 YAML 文件示例：
```
apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: eap
  namespace: openshift-operators
spec:
  channel: alpha
  installPlanApproval: Automatic
  name: eap 1
  source:  redhat-operators 2
  sourceNamespace: openshift-marketplace
```
1
要订阅的操作器的名称。
2
EAP Operator 由 redhat-operators CatalogSource 提供。
有关频道和批准策略的详情，请查看此流程的 Web 控制台版本。
从 YAML 文件创建 Subscription 对象：
```
$ oc apply -f eap-operator-sub.yaml
$ oc get csv -n openshift-operators
NAME                  DISPLAY     VERSION   REPLACES   PHASE
eap-operator.v1.0.0   JBoss EAP   1.0.0                Succeeded
```
EAP 操作器已安装成功。此时，OLM 已了解 EAP 操作器。Operator 的 ClusterServiceVersion(CSV)会出现在目标命名空间中，EAP 操作器提供的 API 可用于创建。

7.3. 使用 EAP 操作器在 OpenShift 上部署 Java 应用

利用 EAP 操作器，您可以在 OpenShift 上自动化 Java 应用部署。如需有关 EAP Operator API 的信息，请参阅 EAP Operator: API Information。

您可以选择以下应用程序镜像类型之一在 OpenShift 中部署 Java 应用程序：

基于构建器镜像或运行时镜像的应用镜像。您可以使用 eap-s2i-build 模板准备这样的镜像。
基于基础镜像 registry.access.redhat.com/ubi8/openjdk-11 或提供更高 JDK 版本的任何其他红帽 ubi8 的可引导 JAR 应用程序镜像。

在使用 EAP 操作器在 OpenShift 上部署 Java 应用时，需要进行一些配置。只有在应用的 EAP 操作器 CustomResource(CR)引用 Secret 对象或 ConfigMap 时，才需要一些其他配置。

其他资源

如需有关 eap-s2i-build 模板的信息，请参阅用于创建应用映像的 eap-s2i-build 模板。
有关使用 eap-s2i-build 模板构建应用映像的更多信息，请参阅使用 eap- s2i-build 模板构建应用映像。
有关使用可引导 JAR 应用镜像的信息，请参阅 Bootable JAR 以打包 EAP 服务器和 Java 应用。
有关将应用程序镜像打包为可引导 JAR 的信息，请参阅在 JBoss EAP OpenShift 平台上使用可引导 JAR。
有关在 OpenShift 中部署 Java 应用时完成强制配置的信息，请参阅使用 EAP 操作器部署 Java 应用：完成强制配置。
有关在 OpenShift 中部署 Java 应用时完成可选配置的信息，请参阅使用 EAP 操作器部署 Java 应用：完成可选配置。

7.3.1. 用于创建应用镜像的 eap-s2i-build 模板

使用 eap-s2i-build 模板来创建应用映像。eap-s2i-build 模板添加多个参数，以配置应用源存储库的位置，以及用于构建应用的 EAP S2I 镜像。

eap-s2i-build 模板中的 APPLICATION_IMAGE 参数指定与应用镜像对应的镜像流的名称。例如，如果您从 eap-s2i -build 模板创建了名为 my- app 的应用程序镜像，您可以使用 my-app 镜像流中的 my-app:latest imagestreamtag 来部署应用。如需有关 eap-s2i-build 模板中使用的参数的更多信息，请参阅使用 eap-s2i-build 模板构建应用映像。

使用此模板时，EAP 操作员可以无缝升级 OpenShift 上部署的应用。要启用无缝升级，您必须在 GitHub 存储库中配置 webhook，并在构建配置中指定 webhook。当您的存储库更新并且触发新构建时，webhook 会通知 OpenShift。

您可以使用此模板来使用任何 JBoss EAP 版本（如 JBoss EAP 7.3、JBoss EAP XP 或 JBoss EAP CD）的镜像流来构建应用镜像。

其他资源

使用 eap-s2i-build 模板构建应用映像.

7.3.2. 使用 eap-s2i-build 模板构建应用镜像

eap-s2i-build 模板添加多个参数，以配置用于构建应用的应用源存储库的位置和 EAP S2I 镜像。通过此模板，您可以将镜像流用于任何 JBoss EAP 版本，如 JBoss EAP 7.3、JBoss EAP XP 或 JBoss EAP CD。

流程

在 OpenShift 中导入 EAP 映像。如需更多信息，请参阅导入 JBoss EAP XP 的最新 OpenShift 镜像流和模板。
配置镜像流以接收关于应用镜像流更改和触发新构建的更新。如需更多信息，请参阅配置定期导入 imagestreamtag。
创建 eap-s2i-build 模板，以使用 EAP S2I 镜像构建应用映像：
```
$ oc replace --force -f https://raw.githubusercontent.com/jboss-container-images/jboss-eap-openshift-templates/master/eap-s2i-build.yaml
```
此 eap-s2i-build 模板会创建两个构建配置和两个镜像流，对应于中间构建构件和最终应用镜像。
使用参数处理 eap-s2i-build 模板，以创建最终应用镜像的资源。以下示例创建了应用程序镜像 my-app ：
```
$ oc process eap-s2i-build \
  -p APPLICATION_IMAGE=my-app \ 1
  \
  -p EAP_IMAGE=jboss-eap-xp1-openjdk11-openshift:1.0 \ 2
  -p EAP_RUNTIME_IMAGE=jboss-eap-xp1-openjdk11-runtime-openshift:1.0 \ 3
  -p EAP_IMAGESTREAM_NAMESPACE=$(oc project -q) \ 4
  \
  -p SOURCE_REPOSITORY_URL=https://github.com/jboss-developer/jboss-eap-quickstarts.git \ 5
  -p SOURCE_REPOSITORY_REF=xp-1.0.x \ 6
  -p CONTEXT_DIR=microprofile-config | oc create -f - 7
```
1
应用程序镜像流的名称。应用镜像带有 latest 标签。
2
EAP 构建器镜像的 imagestreamtag。
3
EAP 运行时镜像的 imagestreamtag。
4
安装 Red Hat Middleware 镜像的镜像流的命名空间。如果省略，则使用 openshift 命名空间。只有在 openshift 以外的命名空间中安装了镜像流时，才修改此项。
5
应用的 Git 源 URL。
6
Git 分支或标签引用
7
包含要构建的应用的 Git 存储库中的路径。
使用 EAP 操作器准备应用镜像以进行部署。
1. 配置 WildFlyServer 资源：
```
$ cat > my-app.yaml<<EOF

apiVersion: wildfly.org/v1alpha1
kind: WildFlyServer
metadata:
  name: my-app
spec:
 applicationImage: 'my-app:latest'
 replicas: 1
EOF
```
2. 应用这些设置，并让 EAP 操作器创建一个新的 WildFlyServer 资源来引用此应用程序镜像：
```
$ oc apply -f my-app.yaml
```
3. 使用以下命令查看 WildFlyServer 资源：
```
$ oc get wfly my-app
```
  其他资源
  - 有关导入应用镜像流的更多信息，请参阅导入 JBoss EAP XP 的最新 OpenShift 镜像流和模板。
  - 有关定期导入镜像流的更多信息，请参阅配置定期导入 imagestreamtag。

7.3.3. 可引导 JAR 用于打包 JBoss EAP 服务器和 Java 应用程序

您可以将 JBoss EAP 服务器和 Java 应用程序打包为可执行 JAR 文件，也称为可引导 JAR。此可引导 JAR 可用于构建可引导的 JAR 应用镜像，其中包含服务器、打包应用和启动服务器所需的运行时。以这种方式构建的可引导 JAR 应用镜像可以利用 EAP 操作器部署到 OpenShift 上。

若要使用 EAP 操作器在 OpenShift 上部署可引导 JAR 镜像，您必须使用基础镜像 registry.access.redhat.com/ubi8/openjdk-11 或提供更高 JDK 版本的任何其他红帽 ubi8。

必须为云环境配置的服务器构建可引导 JAR。您可以通过在 wildfly-jar-maven-plugin 配置中启用，为 云环境配置服务器。

在 JBoss EAP OpenShift 平台中使用可引导 JAR 部分，完成第 1 到 6 步，以构建可引导 JAR 应用镜像。完成这些步骤后，您的可引导 JAR 应用镜像可在 OpenShift 中作为镜像流提供，您可以在 EAP 操作器配置中使用 imagestreamtag。

注意

当运行可引导 JAR 应用镜像的 pod 缩减时，EAP 操作器不会恢复事务。EAP 操作器记录一个跟踪，描述在 pod 缩减时无法恢复事务。

其他资源

有关可引导 JAR 的更多信息，请参阅关于可引导 JAR。
有关为云环境配置服务器的更多信息，请参阅为 OpenShift 配置可引导 JAR。
有关在 OpenShift 中部署可引导 JAR 应用镜像的信息，请参阅使用 EAP 操作器部署 Java 应用：完成强制配置。

7.3.4. 使用 EAP 操作器部署 Java 应用：完成强制配置

在使用 EAP 操作器在 OpenShift 中部署 Java 应用时，您必须进行下列配置：

先决条件

已安装 EAP operator。如需有关安装 EAP 操作器的更多信息，请参阅使用 Webconsole 和 CLI 安装 EAP Operator。

如果您使用 eap-s2i-build 模板构建应用程序镜像：

您已使用 JBoss EAP for OpenShift Source-to-Image(S2I)构建器镜像构建了用户应用的 Docker 镜像。
如果要在 OpenShift 上部署应用后启用自动升级 ，则 eap-s2i-build 模板中的 APPLICATION_IMAGE 参数包含镜像流。有关使用 eap-s2i-build 模板构建应用镜像的更多信息，请参阅使用 eap- s2i-build 模板构建应用镜像。

如果您使用可引导 JAR 应用程序镜像：

您已使用基础镜像 registry.access.redhat.com/ubi8/openjdk-11 或提供更高 JDK 版本的任何其他红帽 ubi8 构建了可引导 JAR 应用程序镜像。
您已为云环境配置了服务器。

流程

打开 Web 浏览器并登录到 OperatorHub。
选择您要用于 Java 应用程序的项目或命名空间。
导航到 Installed Operator，再选择 JBoss EAP operator。
在 Overview 选项卡上，单击 Create Instance 链接。
指定应用程序镜像详情。
应用镜像指定包含 Java 应用的 Docker 镜像。如果 applicationImage 字段与 imagestreamtag 对应，对镜像的任何更改都会触发应用程序的自动升级。
您可以提供用于 OpenShift 应用镜像的 JBoss EAP 的任何引用，如下例所示：
- 镜像名称：mycomp/myapp
- 标签：mycomp/myapp:1.0
- 摘要： mycomp/myapp:@sha256:0af38bc38be93116b6a1d86a9c78bd14cd527121970899d719baf78e5dc7bfd2
- imagestreamtag: my-app:latest
- 镜像哈希：quay.io/bootable-jar/myapp@sha256:47c06c96e80d0defb777686cdb468c636d9b3b7081a35b784330a050a403e15b
指定应用程序的大小。例如：
```
spec:
  replicas:2
```
- 可选：如果您使用可引导 JAR 打包应用程序，请按以下示例所示：
```
spec:
  bootableJar: true
```
使用 env spec 配置应用程序环境。环境变量可以直接来自值，如 POSTGRESQL_SERVICE_HOST 或 Secret 对象，如 POSTGRESQL_USER。例如：
```
spec:
  env:
  - name: POSTGRESQL_SERVICE_HOST
    value: postgresql
  - name: POSTGRESQL_SERVICE_PORT
    value: '5432'
  - name: POSTGRESQL_DATABASE
    valueFrom:
      secretKeyRef:
        key: database-name
        name: postgresql
  - name: POSTGRESQL_USER
    valueFrom:
      secretKeyRef:
        key: database-user
        name: postgresql
  - name: POSTGRESQL_PASSWORD
    valueFrom:
      secretKeyRef:
        key: database-password
        name: postgresql
```
其他资源
- 有关在 OpenShift 中部署 Java 应用时完成可选配置的更多信息，请参阅使用 EAP 操作器部署 Java 应用：完成可选配置。
- 有关使用 eap-s2i-build 模板构建应用镜像的更多信息，请参阅使用 eap-s2i-build 模板构建应用镜像。
- 有关将应用镜像打包为可引导 JAR 的更多信息，请参阅在 JBoss EAP OpenShift 平台上使用可引导 JAR。
- 如需环境变量列表，请参阅环境变量。

7.3.5. 使用 EAP 操作器部署 Java 应用：完成可选配置

如果应用的 EAP 操作器 CustomResource(CR)引用 Secret 对象或 ConfigMap，请在使用 EAP 操作器在 OpenShift 中部署应用时完成以下可选配置：

注意

JBoss EAP 7 不支持从 ConfigMap 提供 standalone.xml 文件。

先决条件

已安装 EAP operator。如需有关安装 EAP 操作器的更多信息，请参阅使用 Webconsole 和 CLI 安装 EAP Operator。
您已完成在 OpenShift 中部署 Java 应用的必要配置。
如果应用的 EAP operator CR 引用了一个对象，则您已创建了 Secret 对象。有关创建 Secret 对象的详情，请参阅创建 Secret。
如果应用的 EAP operator CR 引用了一个 ConfigMap，则已创建了 ConfigMap。有关创建 ConfigMap 的详情，请参阅创建 ConfigMap。
可选：您已从 standalone.xml 文件创建了 ConfigMap。有关从 standalone.xml 文件创建 ConfigMap 的详情，请参考从 standalone.xml 文件创建 ConfigMap。

流程

完成与应用程序部署相关的以下可选配置：
1. 指定服务器数据目录的存储要求。
2. 指定您在 WildFlyServerSpec 中创建的 Secret 名称，以便您可以将 Secret 对象作为运行应用程序的 Pod 中的卷挂载。例如：
```
spec:
  secrets:
    - my-secret
```
  Secret 挂载于 /etc/secrets/<secret name>，每个键/值都保存为一个文件。文件的名称是键，内容是值。Secret 作为 pod 中的卷挂载。以下示例演示了可用于查找键值的命令：
```
$ ls /etc/secrets/my-secret/
my-key  my-password
$ cat /etc/secrets/my-secret/my-key
devuser
$ cat /etc/secrets/my-secret/my-password
my-very-secure-pasword
```
  注意
  修改 Secret 对象可能会导致项目不一致。为避免项目的不一致，请创建一个内容与旧对象相同的新 Secret 对象。然后，您可以根据需要更新内容，并将 EAP 操作器自定义资源(CR)中的引用从旧改为 new。这被视为一个新的 CR 更新，pod 会被重新载入。
3. 指定您在 WildFlyServerSpec 中创建的 ConfigMap 名称，将其挂载为运行应用程序的 Pod 中的卷。例如：
```
spec:
  configMaps:
  - my-config
```
  ConfigMap 挂载于 /etc/configmaps/<configmap name>，每个键/值都存储为一个文件。文件的名称是键，内容是值。ConfigMap 挂载为 pod 中的卷。查找键值：
```
$ ls /etc/configmaps/my-config/
key1 key2
$ cat /etc/configmaps/my-config/key1
value1
$ cat /etc/configmaps/my-config/key2
value2
```
  注意
  修改 ConfigMap 可能会导致项目不一致。为了避免项目不一致，请创建一个内容与旧 ConfigMap 相同的新 ConfigMap。然后，您可以根据需要更新内容，并将 EAP 操作器自定义资源(CR)中的引用从旧改为 new。这被视为一个新的 CR 更新，pod 会被重新载入。
4. 如果您选择有自己的独立 ConfigMap，请提供 ConfigMap 的名称以及 standalone.xml 文件的键：
```
  standaloneConfigMap:
    name: clusterbench-config-map
    key: standalone-openshift.xml
```
  注意
  JBoss EAP 7 不支持从 standalone.xml 文件创建 ConfigMap。
5. 如果要禁用 OpenShift 中创建默认 HTTP 路由，请将 disableHTTPRoute 设置为 true ：
```
spec:
  disableHTTPRoute: true
```

其他资源

有关为服务器数据目录指定存储要求的更多信息，请参阅为应用程序配置持久性存储。
有关在 OpenShift 中部署 Java 应用时完成强制配置的更多信息，请参阅使用 EAP 操作器在 OpenShift 上部署 Java 应用。

7.3.6. 创建 Secret

如果应用的 EAP 操作器 CustomResource(CR)引用 Secret，您必须先创建 Secret 对象，然后才能使用 EAP 操作器将应用部署到 OpenShift 中。

流程

创建 Secret ：

$ oc create secret generic my-secret --from-literal=my-key=devuser --from-literal=my-password='my-very-secure-pasword'

7.3.7. 创建 ConfigMap

如果应用程序的 EAP 操作器 CustomResource(CR)引用 spec.ConfigMaps 字段中的 ConfigMap，您必须先创建 ConfigMap，然后才能使用 EAP 操作器在 OpenShift 中部署应用程序。

流程

创建 configmap：

 $ oc create configmap my-config --from-literal=key1=value1 --from-literal=key2=value2
configmap/my-config created

7.3.8. 从 standalone.xml 文件创建 ConfigMap

您可以创建自己的 JBoss EAP 单机配置，而不使用来自 JBoss EAP for OpenShift Source-to-Image(S2I)的应用镜像中的配置。standalone.xml 文件必须放在可由 Operator 访问的 ConfigMap 中。

注意

注意：JBoss EAP 7 不支持从 ConfigMap 提供 standalone.xml 文件。

流程

从 standalone.xml 文件创建 ConfigMap ：

 $ oc create configmap clusterbench-config-map --from-file examples/clustering/config/standalone-openshift.xml
configmap/clusterbench-config-map created

7.3.9. 为应用程序配置持久性存储

如果您的应用程序需要对一些数据进行持久性存储，如在 pod 重启后必须保留的事务或消息传递日志，请配置存储规格。如果存储 spec 为空，应用程序的每个 pod 都会使用一个 EmptyDir 卷。但是，此卷在对应的 pod 停止后不会保留。

流程

指定 volumeClaimTemplate，以配置资源要求，以存储 JBoss EAP 单机数据目录。模板的名称派生自 JBoss EAP 的名称。对应的卷被挂载为 ReadWriteOnce 访问模式。
```
spec:
  storage:
    volumeClaimTemplate:
      spec:
        resources:
          requests:
            storage: 3Gi
```
满足此存储要求的持久卷挂载到 /eap/standalone/data 目录。

7.4. 使用 EAP 操作器查看应用的指标

您可以使用 EAP 操作器查看 OpenShift 上部署的应用的指标。

当集群管理员在项目中启用了指标监控时，EAP 操作器会自动在 OpenShift 控制台中显示指标。

先决条件

集群管理员已为项目启用了监控。如需更多信息，请参阅为用户定义的项目启用监控。

流程

在 OpenShift Container Platform Web 控制台中，导航到 Monitoring→ Metrics。
在 Metrics 屏幕上，在文本框中输入应用程序名称以选择应用程序。您的应用程序的指标会出现在屏幕上。

注意

与 JBoss EAP 应用服务器相关的所有指标都以 jboss 为前缀。例如，jboss_undertow_request_count_total。

7.5. 使用 Web 控制台卸载 EAP Operator

若要从集群中删除或卸载 EAP operator，可以删除订阅，将其从订阅的命名空间中删除。您也可以移除 EAP 操作器的 ClusterServiceVersion(CSV)和部署。

注意

为确保数据一致性和安全性，请在卸载 EAP 操作器之前将集群中的 pod 数量向下扩展到 0。

您可以使用 Web 控制台卸载 EAP 操作器。

警告

如果您决定删除整个 wildflyserver 定义(oc delete wildflyserver <deployment_name>)，则不会启动事务恢复过程，无论未完成的交易都会终止 pod。此操作结果的未完成工作可能会阻止您稍后启动的数据更改。涉及与此 wildflyserver 交互 EJB 远程调用的其他 JBoss EAP 实例的数据更改也可能被阻止。

流程

在 Operators→ Installed Operators 页面中，选择 JBoss EAP。
在 Operator Details 页面的右侧，从 Actions 下拉菜单中选择 Uninstall Operator。
如果要删除所有安装相关组件，则在看到 Remove Operator Subscription 窗口提示时，勾选 Also completely remove the Operator from the selected namespace 复选框。这会删除 CSV，从而删除与 Operator 关联的 pod、部署、自定义资源定义(CRD)和自定义资源(CR)。
点击 Remove。EAP 操作器将停止运行，并且不再接收更新。

7.6. 使用 CLI 卸载 EAP Operator

若要从集群中删除或卸载 EAP operator，可以删除订阅，将其从订阅的命名空间中删除。您也可以移除 EAP 操作器的 ClusterServiceVersion(CSV)和部署。

注意

为确保数据一致性和安全性，请在卸载 EAP 操作器之前将集群中的 pod 数量向下扩展到 0。

您可以使用命令行卸载 EAP 操作器。

使用命令行时，您可以通过从目标命名空间中删除订阅和 CSV 来卸载 Operator。

警告

流程

在 currentCSV 字段中检查 EAP operator 订阅的当前版本：

$ oc get subscription eap-operator -n openshift-operators -o yaml | grep currentCSV
  currentCSV: eap-operator.v1.0.0

删除 EAP Operator 的订阅：

$ oc delete subscription eap-operator -n openshift-operators
subscription.operators.coreos.com "eap-operator" deleted

使用上一步中的 currentCSV 值，在目标命名空间中删除 EAP Operator 的 CSV：

$ oc delete clusterserviceversion eap-operator.v1.0.0 -n openshift-operators
clusterserviceversion.operators.coreos.com "eap-operator.v1.0.0" deleted

7.7. Safe Transaction Recovery 的 EAP Operator

EAP 操作器在终止应用集群之前确保数据一致性，方法是验证所有事务在缩减副本之前已完成，并将 pod 标记为 干净 以进行终止。

这意味着，如果要在没有数据不一致的情况下安全地删除部署，您必须首先将 pod 数量缩减为 0，等待所有 pod 终止，然后才删除 wildflyserver 实例。

警告

当扩展过程开始 pod 状态(oc get pod <pod_name>)仍然标记为 Running，因为 pod 必须完成所有未完成事务，包括针对它的远程 EJB 调用。

如果要监控 scaledown 进程的状态，请观察 wildflyserver 实例的状态。如需更多信息，请参阅监控缩减过程。有关扩展过程中 pod 状态的信息，请参阅 Pod 在缩减期间的状态。

注意

当运行可引导 JAR 应用镜像的 pod 缩减时，EAP 操作器不会恢复事务。EAP 操作器记录一个跟踪，描述在 pod 缩减时无法恢复事务。

7.7.1. Stable 网络主机名的 StatefulSets

管理 wildflyserver 的 EAP 操作器将创建 StatefulSet 作为管理 JBoss EAP pod 的底层对象。

StatefulSet 是管理有状态应用程序的工作负载 API 对象。它管理一组容器集的部署和扩展，并且对这些容器集的顺序和唯一性提供保证。

StatefulSet 可确保以预定义的顺序命名集群中的 pod。它也确保 pod 终止遵循相同的顺序。例如，让我们说，pod-1 具有具有启发式结果的交易，因此处于 SCALING_DOWN_RECOVERY_DIRTY 状态。即使 pod-0 处于 SCALING_DOWN_CLEAN 状态，它也不会在 pod-1 之前终止。在 pod-1 被 清理 并被终止前，pod-0 仍然处于 SCALING_DOWN_CLEAN 状态。但是，即使 pod-0 处于 SCALING_DOWN_CLEAN 状态，它也不会收到任何新的请求，实际上也没有闲置。

注意

减少 StatefulSet 的副本大小或删除 pod 本身无效，并会恢复此类更改。

7.7.2. 监控扩展过程

如果要监控 scaledown 进程的状态，您必须观察 wildflyserver 实例的状态。如需有关扩展过程中不同 pod 状态的更多信息，请参阅 Pod 在缩减期间的状态。

流程

观察缩减过程的状态：
```
oc describe wildflyserver <name>
```
- WildFlyServer.Status.Scalingdown Pod 和 WildFlyServer.Status.Replicas 字段显示活跃和非主动 Pod 的整体状态。
- Scalingdown Pods 字段显示所有未完成事务完成后将终止的 pod 数量。
- WildFlyServer.Status.Replicas 字段显示当前运行的容器集数量。
- WildFlyServer.Spec.Replicas 字段显示处于 ACTIVE 状态的 pod 数量。
- 如果没有缩放过程中的 pod，则 WildFlyServer.Status.Replicas 和 WildFlyServer.Spec.Replicas 字段中的 pod 数量是相等的。

7.7.2.1. 在扩展过程中的 Pod 状态

下表描述了扩展过程中的不同 pod 状态：

表 7.1. Pod 状态描述

Pod 状态	描述
ACTIVE	pod 处于活跃状态，并处理请求。
SCALING_DOWN_RECOVERY_INVESTIGATION	pod 即将缩减。纵向缩减流程正在调查 JBoss EAP 中的事务状态。
SCALING_DOWN_RECOVERY_DIRTY	JBoss EAP 包含一些不完整的交易。在清理完 pod 前，pod 不会被终止。事务恢复过程在 JBoss EAP 定期运行，它会等待事务完成
SCALING_DOWN_CLEAN	pod 通过缩减事务处理来处理，标记为 `干净`，可从集群中删除。

7.7.3. 使用 Heuristic Outcomes 扩展事务期间的故障

当交易的结果未知时，无法自动恢复交易。然后必须手动恢复您的事务。

先决条件

pod 的状态停留在 SCALING_DOWN_RECOVERY_DIRTY。

流程

使用 CLI 访问您的 JBoss EAP 实例。
解决事务对象存储中的所有启发式事务记录。如需更多信息，请参阅 JBoss EAP 管理事务中的恢复 Heuristic Outcomes。
从 EJB 客户端恢复文件夹中删除所有记录。
1. 从 pod EJB 客户端恢复目录中删除所有文件：
```
$JBOSS_HOME/standalone/data/ejb-xa-recovery
oc exec <podname> rm -rf $JBOSS_HOME/standalone/data/ejb-xa-recovery
```
pod 的状态变为 SCALING_DOWN_CLEAN，pod 将被终止。

7.7.4. 配置事务子系统，以使用 JDBC 存储进行事务日志

如果系统不提供文件系统来存储 事务日志，请使用 JBoss EAP S2I 镜像配置 JDBC 对象存储。

重要

当 JBoss EAP 部署为可引导 JAR 时，S2I 环境变量不可用。在这种情况下，您必须创建 Galleon 层，或配置 CLI 脚本以进行必要的配置更改。

JDBC 对象存储可以使用环境变量 TX_DATABASE_PREFIX_MAPPING 进行设置。此变量的结构与 DB_SERVICE_PREFIX_MAPPING 相同。

前提条件

您已基于环境变量的值创建了数据源。
您已确保数据库和通过 JDBC 对象存储通信 的交易管理器 之间存在一致的数据读取和写入权限。如需更多信息，请参阅配置 JDBC 数据源

流程

通过 S2I 环境变量设置和配置 JDBC 对象存储。

示例

# Narayana JDBC objectstore configuration via s2i env variables
- name: TX_DATABASE_PREFIX_MAPPING
  value: 'PostgresJdbcObjectStore-postgresql=PG_OBJECTSTORE'
- name: POSTGRESJDBCOBJECTSTORE_POSTGRESQL_SERVICE_HOST
  value: 'postgresql'
- name: POSTGRESJDBCOBJECTSTORE_POSTGRESQL_SERVICE_PORT
  value: '5432'
- name: PG_OBJECTSTORE_JNDI
  value: 'java:jboss/datasources/PostgresJdbc'
- name: PG_OBJECTSTORE_DRIVER
  value: 'postgresql'
- name: PG_OBJECTSTORE_DATABASE
  value: 'sampledb'
- name: PG_OBJECTSTORE_USERNAME
  value: 'admin'
- name: PG_OBJECTSTORE_PASSWORD
  value: 'admin'

验证

您可以通过检查 standalone-openshift.xml 配置文件 oc rsh <podname> cat /opt/eap/standalone/configuration/standalone-openshift.xml 来验证数据源配置和事务子系统配置。

预期输出：

<datasource jta="false" jndi-name="java:jboss/datasources/PostgresJdbcObjectStore" pool-name="postgresjdbcobjectstore_postgresqlObjectStorePool"
    enabled="true" use-java-context="true" statistics-enabled="${wildfly.datasources.statistics-enabled:${wildfly.statistics-enabled:false}}">
    <connection-url>jdbc:postgresql://postgresql:5432/sampledb</connection-url>
    <driver>postgresql</driver>
    <security>
        <user-name>admin</user-name>
        <password>admin</password>
    </security>
</datasource>

<!-- under subsystem urn:jboss:domain:transactions -->
<jdbc-store datasource-jndi-name="java:jboss/datasources/PostgresJdbcObjectStore">
     <!-- the pod name was named transactions-xa-0 -->
    <action table-prefix="ostransactionsxa0"/>
    <communication table-prefix="ostransactionsxa0"/>
    <state table-prefix="ostransactionsxa0"/>
</jdbc-store>

其他资源

有关使用管理控制台或管理 CLI 创建数据源的更多信息，请参阅 JBoss EAP 配置指南中的创建数据源 。

7.8. OpenShift 上的 EJB 移除

要使 JBoss EAP 正确处理 OpenShift 上的不同 JBoss EAP 集群之间的 EJB 远程调用，您必须了解 OpenShift 上的 EJB 远程配置选项。

注意

在 OpenShift 上部署时，请考虑使用 EAP 操作器：EAP 操作器使用 StatefulSet 来适当处理 EJB 远程处理和事务恢复处理。StatefulSet 确保 持久性存储和网络主机名的稳定性，即使在 pod 重启后也是如此。

当使用带有事务传播的 EJB 远程调用联系 JBoss EAP 实例时，需要保持网络主机名稳定性。即使 pod 重新启动，也必须在同一主机名下访问 JBoss EAP 实例。事务管理器是一个有状态的组件，可将持久交易数据绑定到特定的 JBoss EAP 实例。由于事务日志绑定到特定的 JBoss EAP 实例，它必须在同一实例中完成。

为防止使用 JDBC 事务日志存储时数据丢失，请确保您的数据库提供一致的数据读取和写入。当数据库横向扩展时，数据读写的一致性非常重要。

EJB 远程调用器有两个选项可用于配置远程调用：

定义远程出站连接。如需更多信息，请参阅配置远程出站连接。
将编程 JNDI 查找用于远程服务器上的 Bean。如需更多信息，请参阅使用远程 EJB 客户端。

您必须根据 EJB 远程调用配置方法重新配置代表目标节点地址的值。

注意

远程调用的目标 EJB 的名称必须是第一个容器集的 DNS 地址。

StatefulSet 强制取决于 pod 的顺序。容器集按照预定义的顺序命名。例如，如果您将应用缩放为三个副本，您的容器集的名称为 eap-server-0、eap-server-1 和 eap-server-2。

EAP 操作器也使用无头服务来确保为 pod 分配特定的 DNS 主机名。如果应用使用 EAP 操作器，则会使用名称（如 eap-server-headless ）创建无头服务。在本例中，第一个容器集的 DNS 名称为 eap-server-0.eap-server-headless。

使用主机名 eap-server-0.eap-server-headless 可确保 EJB 调用到达与集群连接的任何 EAP 实例。Bootstrap 连接用于初始化 EJB 客户端，它将在下一步收集 EAP 集群的结构。

7.8.1. 在 OpenShift 中配置 EJB

您必须配置充当 EJB 远程调用者的 JBoss EAP 服务器。目标服务器必须配置有权接收 EJB 远程调用的用户。

先决条件

您已使用 EAP 操作器和支持的 JBoss EAP for OpenShift S2I 镜像在 OpenShift 上部署和管理 JBoss EAP 应用实例。
集群设置正确。有关 JBoss EAP 集群的更多信息，请参阅集群部分。

流程

在目标服务器中创建有权接收 EJB 远程调用的用户：
```
$JBOSS_HOME/bin/add-user.sh
```

配置调用者 JBoss EAP 应用服务器。

使用自定义配置功能，在 $JBOSS_HOME/standalone/configuration 中创建 eap-config.xml 文件。如需更多信息，请参阅自定义配置。

使用 wildfly.config.url 属性配置调用者 JBoss EAP 应用服务器：

JAVA_OPTS_APPEND="-Dwildfly.config.url=$JBOSS_HOME/standalone/configuration/eap-config.xml"

注意

如果您在配置中使用以下示例，请将 >>PASTE_…_HERE<< 替换为您配置的用户和密码。

配置示例

<configuration>
  <authentication-client xmlns="urn:elytron:1.0">
  <authentication-rules>
          <rule use-configuration="jta">
              <match-abstract-type name="jta" authority="jboss"/>
      </rule>
      </authentication-rules>
      <authentication-configurations>
       <configuration name="jta">
               <sasl-mechanism-selector selector="DIGEST-MD5"/>
               <providers>
                   <use-service-loader />
           </providers>
       <set-user-name name=">>PASTE_USER_NAME_HERE<<"/>
           <credentials>
                    <clear-password password=">>PASTE_PASSWORD_HERE<<"/>
           </credentials>
               <set-mechanism-realm name="ApplicationRealm" />
           </configuration>
      </authentication-configurations>
  </authentication-client>
</configuration>

第 8 章参考信息

注意

本节中的内容来源于此图像的工程文档。它仅供参考，因为它可用于开发用途和超出产品文档范围进行测试。

8.1. 持久性模板

部署 JBoss EAP 和数据库 pod 的 JBoss EAP 数据库模板具有临时和持久性的变化。

永久模板包括用于调配持久卷声明的环境变量，它与可用作 OpenShift 部署的 JBoss EAP 存储卷的可用持久卷绑定。定时器架构、日志处理或数据更新等信息存储在存储卷中，而不是临时容器内存中。如果 pod 因任何原因停机，如项目升级、部署回滚或意外错误，则此信息会保留。

如果没有用于部署的永久存储卷，此信息仅存储在容器内存中，并在容器集因任何原因停机时丢失。

例如，如果容器集重启，由持久存储支持的 EE 定时器将继续运行。当应用程序再次运行时，计时器在重启过程中触发的所有事件都会被触发。

相反，如果 EE 定时器在容器内存中运行，则容器集重启后会丢失定时器状态，并在容器集再次运行时从开始开始。

8.2. 信息环境变量

以下环境变量旨在为镜像提供信息，并且不应由用户修改：

表 8.1. 信息环境变量

变量名称	描述和值
JBOSS_IMAGE_NAME	镜像名称。值： `jboss-eap-7/eap73-openjdk8-openshift-rhel7` (JDK 8 / RHEL 7) `jboss-eap-7/eap73-openjdk11-openshift-rhel8` (JDK 11 / RHEL 8)
JBOSS_IMAGE_VERSION	镜像版本。 Value：这是镜像版本号。如需获得最新值，请参阅 Red Hat Container Catalog： JDK 8 / RHEL 7 JDK 11 / RHEL 8
JBOSS_MODULES_SYSTEM_PKGS	可供应用使用的 JBoss EAP 系统模块软件包的逗号分隔列表。 value: `org.jboss.logmanager`,`jdk.nashorn.api`
STI_BUILDER	为 `jee` 项目类型提供 OpenShift S2I 支持。值： `jee`

8.3. 配置环境变量

您可以配置以下环境变量来调整镜像，而无需重新构建。

注意

有关此处未列出的其他环境变量，请参见 JBoss EAP 文档。

表 8.2. 配置环境变量

变量名称	描述
AB_JOLOKIA_AUTH_OPENSHIFT	为 OpenShift TLS 通信打开客户端身份验证。此参数的值可以是 `true`、`false` 或相对可分辨名称，该名称必须包含在所呈现的客户端证书中。默认 CA 证书被设置为 `/var/run/secrets/kubernetes.io/serviceaccount/ca.crt`。设置为 `false`，以禁用 OpenShift TLS 通信的客户端身份验证。设置为 `true`，以使用默认的 CA 证书和客户端主体为 OpenShift TLS 通信启用客户端身份验证。设置为相对可分辨的名称，如 `cn=someSystem`，为 OpenShift TLS 通信启用客户端身份验证，但会覆盖客户端主体。这种可分辨名称必须包含在所出示客户端的证书中。
AB_JOLOKIA_CONFIG	如果设置，将此完全限定的文件路径用于 Jolokia JVM 代理属性，具体如 Jolokia 参考文档中所述。如果您设置了自己的 Jolokia 属性配置文件，则忽略本文档中的其余 Jolokia 设置。如果没有设置，`则使用 Jolokia 参考文档中定义的设置来创建 /opt/jolokia/etc/jolokia.properties`。示例值： `/opt/jolokia/custom.properties`
AB_JOLOKIA_DISCOVERY_ENABLED	启用 Jolokia 发现。默认值为 `false`。
AB_JOLOKIA_HOST	要绑定到的主机地址。默认值为 `0.0.0.0`。示例值： `127.0.0.1`
AB_JOLOKIA_HTTPS	使用 HTTPS 打开安全通信. 如果 `AB_JOLOKIA_OPTS 中没有提供 serverCert 配置，则默认生成自签名服务器证书`。示例值： `true`
AB_JOLOKIA_ID	要使用的代理 ID。默认值为 `$HOSTNAME`，即容器 ID。示例值： `openjdk-app-1-xqlsj`
AB_JOLOKIA_OFF	如果设置为 `true，则` 禁用 Jolokia 的激活，这将回显空值。默认启用 Jolokia。
AB_JOLOKIA_OPTS	要附加到代理配置的其他选项。它们应当以 `key=value, key=value, …` 形式提供。示例值： `tasks=20`
AB_JOLOKIA_PASSWORD	基本身份验证的密码。默认情况下关闭身份验证。示例值： `mypassword`
AB_JOLOKIA_PASSWORD_RANDOM	确定是否应生成随机 `AB_JOLOKIA_PASSWORD`。设置为 `true` 以生成随机密码。生成的值保存在 `/opt/jolokia/etc/jolokia.pw` 文件中。
AB_JOLOKIA_PORT	要侦听的端口。默认值为 `8778`。示例值： `5432`
AB_JOLOKIA_USER	用于基本身份验证的用户名称。默认为 `jolokia`。示例值： `myusername`
AB_PROMETHEUS_ENABLE	如果设置为 `true，则` 此变量将激活 `jmx-exporter` java 代理，该代理公开 Prometheus 格式指标。默认值为 `false`。注意 MicroProfile 指标子系统是以 Prometheus 格式公开数据的首选方法。如需有关 MicroProfile 指标 susbsystem 的更多信息，请参阅 JBoss EAP 配置指南中的 Eclipse MicroProfile。
AB_PROMETHEUS_JMX_EXPORTER_CONFIG	容器内的用户指定 `配置.yaml` 的路径，用于要使用的 `jmx-exporter` 代理，而不是默认的 `configuration.yaml` 文件。要了解用于合并其他配置文件的 `S2I` 机制的更多信息，请参阅 S2I 工件。
AB_PROMETHEUS_JMX_EXPORTER_PORT	`jmx-exporter` 代理在其上侦听 Prometheus 服务器提取的端口。默认值为 `9799`。代理侦听 `localhost`。通过将应用的 `DeploymentConfig` 文件配置为包含公开此端点的服务，可以在容器外部提供指标。
CLI_GRACEFUL_SHUTDOWN	如果设置为任何非零长度值，映像将阻止通过 `TERM 信号` 关机，并且需要使用 JBoss EAP 管理 CLI 执行 `关闭` 命令。示例值： `true`
CONTAINER_HEAP_PERCENT	将最大 Java 堆大小设置为可用容器内存的百分比。示例值： `0.5`
CUSTOM_INSTALL_DIRECTORIES	用于在 S2I 过程中安装和配置镜像工件的目录列表。示例值： `custom,shared`
DEFAULT_JMS_CONNECTION_FACTORY	此值用于指定 JMS 连接工厂的默认 JNDI 绑定，如 `jms-connection-factory='java:jboss/DefaultJMSConnectionFactory'`。示例值： `java:jboss/DefaultJMSConnectionFactory`
DISABLE_EMBEDDED_JMS_BROKER	在 OpenShift 容器中使用嵌入式消息传递代理已弃用。在以后的发行版本中将删除对嵌入式代理的支持。如果满足以下条件，则会记录警告。容器配置为使用嵌入式消息传递代理。没有为容器配置远程代理。此变量未设置，或使用值 `false` 设置。如果包含此变量的值设为 `true`，则会禁用嵌入的消息传递代理，且不会记录任何警告。对于没有配置远程消息传递目的地的容器，请将此变量设为 `true`。
ENABLE_ACCESS_LOG	启用记录访问标准输出频道的消息。使用以下方法实现访问信息日志记录： JBoss EAP 6.4 OpenShift 映像使用自定义 JBoss Web 访问日志 Valve。用于 OpenShift 镜像的 JBoss EAP 使用 Undertow `AccessLogHandler`。默认值为 `false`。
INITIAL_HEAP_PERCENT	设置初始 Java 堆大小，作为最大堆大小的百分比。示例值： `0.5`
JAVA_OPTS_APPEND	服务器启动选项. 示例值： `-Dfoo=bar`
JBOSS_MODULES_SYSTEM_PKGS_APPEND	以逗号分隔的软件包名称列表，附加到 `JBOSS_MODULES_SYSTEM_PKGS` 环境变量中。示例值： `org.jboss.byteman`
JGROUPS_CLUSTER_PASSWORD	用于对节点进行身份验证的密码，以便能够加入 JGroups 群集。使用 `ASYM_ENCRYPT` JGroups 集群流量加密协议时需要。如果没有设置身份验证，则禁用身份验证，不会加密群集通信并发出警告。可选，在使用 `SYM_ENCRYPT` JGroups 集群流量加密协议时。示例值： `mypassword`
JGROUPS_ENCRYPT_KEYSTORE	使用 `SYM_ENCRYPT JGroups 集群流量加密协议时，通过 JGROUPS_ENCRYPT_SECRYPT 变量` 指定的 secret 中的密钥存储文件名称。如果没有设置，则不会加密群集通信并发出警告。示例值： `jgroups.jceks`
JGROUPS_ENCRYPT_KEYSTORE_DIR	使用 `SYM_ENCRYPT JGroups 集群流量加密协议时，通过 JGROUPS_ENCRYPT_ SECRET` 变量指定的 secret 中的密钥存储文件目录路径。如果没有设置，则不会加密群集通信并发出警告。示例值： `/etc/jgroups-encrypt-secret-volume`
JGROUPS_ENCRYPT_NAME	在使用 `SYM_ENCRYPT` JGroups 集群流量加密协议时，与服务器证书关联的名称。如果没有设置，则不会加密群集通信并发出警告。示例值： `jgroups`
JGROUPS_ENCRYPT_PASSWORD	在使用 `SYM_ENCRYPT` JGroups 集群流量加密协议时，用于访问密钥存储和证书的密码。如果没有设置，则不会加密群集通信并发出警告。示例值： `mypassword`
JGROUPS_ENCRYPT_PROTOCOL	用于加密群集流量的 JGroups 协议.可以是 `SYM_ENCRYPT` 或 `ASYM_ENCRYPT`。默认为 `SYM_ENCRYPT`。示例值： `ASYM_ENCRYPT`
JGROUPS_ENCRYPT_SECRET	包含 `JGroups 密钥存储` 文件的机密名称，以便在使用 `SYM_ENCRYPT` JGroups 集群流量加密协议时保护 JGroups 通信。如果没有设置，则不会加密群集通信并发出警告。示例值： `eap7-app-secret`
JGROUPS_PING_PROTOCOL	用于节点发现的 JGroups 协议。可以是 `dns.DNS_PING` 或 `kubernetes.KUBE_PING`。
MQ_SIMPLE_DEFAULT_PHYSICAL_DESTINATION	为向后兼容，设置为 `true` `以使用 MyQueue` 和 `MyTopic` 作为物理目标名称默认值，而不使用 `queue/MyQueue` 和 `topic/MyTopic`。
OPENSHIFT_DNS_PING_SERVICE_NAME	在服务器上公开 ping 端口的服务名称，用于 DNS 发现机制。示例值： `eap-app-ping`
OPENSHIFT_DNS_PING_SERVICE_PORT	DNS 发现机制的 ping 端口的端口号。如果没有指定，则会尝试从服务的 SRV 记录中发现端口号，否则使用默认的 `8888`。默认值为 `8888`。
OPENSHIFT_KUBE_PING_LABELS	Kubernetes 发现机制的集群标签选择器。示例值： `app=eap-app`
OPENSHIFT_KUBE_PING_NAMESPACE	集群用于 Kubernetes 发现机制的项目命名空间。示例值：my `project`
SCRIPT_DEBUG	如果设置为 `true`，请确保使用 `-x` 选项执行 Bash 脚本，在命令及其执行过程中打印命令及其参数。

8.4. 应用程序模板

表 8.3. 应用程序模板

变量名称描述

变量名称	描述
AUTO_DEPLOY_EXPLODED	控制是否应自动部署展开式部署内容。示例值： `false`

AUTO_DEPLOY_EXPLODED

控制是否应自动部署展开式部署内容。

示例值： false

8.5. 公开的端口

表 8.4. 公开的端口

端口号	描述
8443	HTTPS
8778	Jolokia Monitoring

8.6. datasources

根据某些环境变量的值自动创建数据源。

最重要的环境变量是 DB_SERVICE_PREFIX_MAPPING，因为它为数据源定义 JNDI 映射。这个变量允许的值是一个用逗号分开的 POOLNAME-DATABASETYPE=PREFIX trip lets 列表，其中：

POOLNAME 用作数据源中的 pool-name。
DATABASETYPE 是要使用的数据库驱动程序。
PREFIX 是环境变量名称中用于配置数据源的前缀。

8.6.1. 数据源的 JNDI 映射

对于 DB_SERVICE_ PREFIX_MAPPING 环境变量中定义的每个POOLNAME-DATABASETYPE= PRE FIX_MAPPING 环境变量，启动脚本会创建一个单独的数据源，在运行镜像时执行。

注意

DB_SERVICE_PREFIX_MAPPING 的第一个部分（在等号前） 应小写。

The DATABASETYPE 决定数据源的驱动程序。

有关配置驱动程序的更多信息，请参阅模块、驱动程序和通用部署。JDK 8 镜像默认配置了 postgresql 和 mysql 的驱动程序。

警告

不要对 POOLNAME 参数使用任何特殊字符。

数据库驱动程序

现在，弃用了对将红帽提供的内部数据源驱动程序与 JBoss EAP 搭配使用的支持。红帽建议您将数据库供应商获取的 JDBC 驱动程序用于 JBoss EAP 应用。

JBoss EAP for OpenShift 镜像不再提供以下内部数据源：

MySQL
PostgreSQL

有关安装驱动程序的更多信息，请参阅模块、驱动程序和通用部署。

有关使用 JBoss EAP 配置 JDBC 驱动程序的更多信息，请参阅 JBoss EAP 配置指南中的 JDBC 驱动程序。

请注意，如果您想将其添加到置备的服务器中，您也可以创建自定义层来安装这些驱动程序和数据源。

8.6.1.1. 数据源配置环境变量

若要配置其他数据源属性，可使用以下环境变量：

重要

务必将下列变量名称中的 POOLNAME、DATABASETYPE 和 PREFIX 的值替换为适当的值。本节和 Datasources 部分中描述了这些可替换值。

变量名称	描述
POOLNAME _DATABASETYPE_SERVICE_HOST	定义要在数据源的 `connection-url` 属性中使用的数据库服务器的主机名或 IP 地址。示例值：192. `168.1.3`
POOLNAME _DATABASETYPE_SERVICE_PORT	定义数据源的数据库服务器端口。示例值： `5432`
前缀 _BACKGROUND_VALIDATION	当设置为 `true` 数据库连接时，会在使用前在后台线程中定期验证数据库连接。默认为 `false`，表示默认情况下启用了 `validate-on-match` 方法。
PREFIX_BACKGROUND_VALIDATION_MILLIS	在启用了 `background-validation` 数据库连接验证机制时（`PREFIX_BACKGROUND_VALIDATION` 变量设置为 `true`），以毫秒为单位指定验证频率。默认值为 `10000`。
前缀 _CONNECTION_CHECKER	指定连接检查器类，用于验证正在使用的特定数据库的连接。示例值： `org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker`
前缀_DATABASE	定义数据源的数据库名称。示例值： `myDatabase`
前缀_DRIVER	为数据源定义 Java 数据库驱动程序。示例值： `postgresql`
PREFIX_EXCEPTION_SORTER	指定异常分类器类，用于在致命数据库连接异常后正确检测和清理。示例值： `org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter`
PREFIX_JNDI	定义数据源的 JNDI 名称。默认为 `java:jboss/datasources/POOLNAME_DATABASETYPE`，其中 `POOLNAME` 和 `DATABASETYPE` 从上面的三边图获取。如果要覆盖默认生成的 JNDI 名称，此设置很有用。示例值： `java:jboss/datasources/test-postgresql`
PREFIX_JTA	为非 XA 数据源定义 Jakarta Transactions 选项。默认情况下，XA 数据源已经能够支持 Jakarta Transactions。默认值为 `true`。
PREFIX_MAX_POOL_SIZE	为数据源定义最大池大小选项。示例值： `20`
PREFIX_MIN_POOL_SIZE	定义数据源的最小池大小选项。示例值 `：1`
PREFIX_NONXA	将数据源定义为非 XA 数据源。默认值为 `false`。
前缀_PASSWORD	定义数据源的密码。示例值： `password`
PREFIX_TX_ISOLATION	定义数据源的 java.sql.Connection 事务隔离级别。示例值： `TRANSACTION_READ_UNCOMMITTED`
前缀_URL	定义数据源的连接 URL。示例 value: `jdbc:postgresql://localhost:5432/postgresdb`
前缀_USERNAME	定义数据源的用户名。示例值： `admin`

在 OpenShift 中运行此镜像时，POOLNAME_DATABASETYPE_SERVICE_HOST 和 POOLNAME_DATABASETYPE_SERVICE_PORT 环境变量会自动从 OpenShift 应用模板中的数据库服务定义设置，而其他变量则直接在模板中配置为各个容器集模板的容器镜像 条目。

8.6.1.2. 示例

这些示例演示了 DB_SERVICE_PREFIX_MAPPING 环境变量的值如何影响数据源创建。

8.6.1.2.1. 单个映射

考虑值 test-postgresql=TEST.

这将创建一个带有 java:jboss/datasources/test_postgresql 名称的数据源。此外，密码和用户名等所有必要设置都应作为环境变量提供，并附带 TEST_ 前缀，如 TEST_USERNAME 和 TEST_PASSWORD。

8.6.1.2.2. 多个映射

您可以指定多个数据源映射。

注意

始终使用逗号分隔多个数据源映射。

请考虑 DB_SERVICE_PREFIX_MAPPING 环境变量的以下值：cloud -postgresql=CLOUD,test-mysql=TEST_MYSQL。

这会创建以下两个数据源：

java:jboss/datasources/test_mysql
java:jboss/datasources/cloud_postgresql

然后，您可以使用 TEST_MYSQL 前缀来配置诸如 MySQL 数据源的用户名和密码等操作，如 TEST_MYSQL_USERNAME。对于 PostgreSQL 数据源，使用 CLOUD_ 前缀，如 CLOUD_USERNAME。

8.7. 集群

8.7.1. 配置 JGroups 发现机制

要在 OpenShift 上启用 JBoss EAP 集群，请在 JBoss EAP 配置中配置 JGroups 协议堆栈，以使用 kubernetes.KUBE_PING 或 dns.DNS_PING 发现机制。

虽然您可以使用自定义 standalone-openshift.xml 配置文件，但建议您使用环境变量在镜像构建中配置 JGroups。

以下说明使用环境变量来配置 JBoss EAP 用于 OpenShift 镜像的发现机制。

重要

如果您使用其中一个可用的应用模板在 JBoss EAP for OpenShift 镜像基础上部署应用，则默认发现机制为 dns.DNS_PING。

dns.DNS_PING 和 kubernetes.KUBE_PING 发现机制彼此不兼容。无法从两个独立的子集群组成一个超级集群，一个使用 dns.DNS_PING 机制进行 发现，另一个使用 kubernetes.KUBE_PING 机制。同样，在执行滚动升级时，对源和目标集群的发现机制需要相同。

8.7.1.1. 配置 KUBE_PING

使用 KUBE_PING JGroups 发现机制：

JGroups 协议堆栈必须配置为使用 KUBE_PING 作为发现机制。
您可以通过将 JGROUPS_PING_PROTOCOL 环境变量设置为 kubernetes.KUBE_PING 来做到这一点 ：
```
JGROUPS_PING_PROTOCOL=kubernetes.KUBE_PING
```
KUBERNETES_NAMESPACE 环境变量必须设置为您的 OpenShift 项目名称。如果没有设置，服务器会作为单节点集群（"一个群集"）的行为。例如：
```
KUBERNETES_NAMESPACE=PROJECT_NAME
```
应设置 KUBERNETES_LABELS 环境变量。这应该与在服务级别设置的标签匹配。如果没有设置，则应用程序之外的 pod（您的命名空间中的某个 pod）将尝试加入。例如：
```
KUBERNETES_LABELS=application=APP_NAME
```
必须将授权授予 Pod 在下运行的服务帐户，以允许访问 Kubernetes 的 REST API。这通过 OpenShift CLI 完成。以下示例在当前项目命名空间中使用 default 服务帐户：
```
oc policy add-role-to-user view system:serviceaccount:$(oc project -q):default -n $(oc project -q)
```
在项目命名空间中使用 eap-service-account:
```
oc policy add-role-to-user view system:serviceaccount:$(oc project -q):eap-service-account -n $(oc project -q)
```
注意
有关添加策略到服务帐户的更多信息，请参阅为应用程序部署准备 OpenShift。

8.7.1.2. 配置 DNS_PING

使用 DNS_PING JGroups 发现机制：

JGroups 协议堆栈必须配置为使用 DNS_PING 作为发现机制。
您可以通过将 JGROUPS_PING_PROTOCOL 环境变量设置为 dns.DNS_PING 来做到这一点 ：
```
JGROUPS_PING_PROTOCOL=dns.DNS_PING
```
OPENSHIFT_DNS_PING_SERVICE_NAME 环境变量必须设置为集群的 ping 服务的名称。
```
OPENSHIFT_DNS_PING_SERVICE_NAME=PING_SERVICE_NAME
```
OPENSHIFT_DNS_PING_SERVICE_PORT 环境变量应设置为公开 ping 服务的端口号。DNS_PING 协议尝试从 SRV 记录辨别端口，否则默认为 8888。
```
OPENSHIFT_DNS_PING_SERVICE_PORT=PING_PORT
```
必须定义公开 ping 端口的 ping 服务。这个服务应该是无头的(ClusterIP=None)，且必须具有以下内容：
1. 端口必须命名为。
2. 该服务必须使用 service. alpha.kubernetes.io/tolerate-unready-endpoints 和 publishNotReadyAddresses 属性进行注解，两者都设置为 true。
  注意
  使用 service.alpha.kubernetes.io/tolerate-unready-endpoints 和 publishNotReadyAddresses 属性来确保 ping 服务在较旧和较新的 OpenShift 版本中正常工作。
  省略这些注解会导致每个节点在启动过程中形成自己的"集群"。然后，每个节点在启动后将其集群合并到其他节点的集群中，因为其他节点在启动后才会检测到。
```
kind: Service
apiVersion: v1
spec:
    publishNotReadyAddresses: true
    clusterIP: None
    ports:
    - name: ping
      port: 8888
    selector:
        deploymentConfig: eap-app
metadata:
    name: eap-app-ping
    annotations:
        service.alpha.kubernetes.io/tolerate-unready-endpoints: "true"
        description: "The JGroups ping port for clustering."
```

注意

DNS_PING 不需要对服务帐户进行任何修改，并使用默认权限。

8.7.2. 配置 JGroups 来加密集群流量

若要加密 OpenShift 上 JBoss EAP 的集群流量，您必须在 JBoss EAP 配置中配置 JGroups 协议堆栈，以使用 SYM_ENCRYPT 或 ASYM_ENCRYPT 协议。

虽然您可以使用自定义 standalone-openshift.xml 配置文件，但建议您使用环境变量在镜像构建中配置 JGroups。

以下说明使用环境变量来配置用于 OpenShift 镜像的 JBoss EAP 集群流量加密的协议。

重要

SYM_ENCRYPT 和 ASYM_ENCRYPT 协议彼此不兼容。无法从两个独立的子集群组成一个超级集群，一个使用 SYM_ENCRYPT 协议加密集群流量，另一个使用 ASYM_ENCRYPT 协议加密。同样，在执行滚动升级时，该协议对于源和目标集群需要相同。

8.7.2.1. Configuring SYM_ENCRYPT

使用 SYM_ENCRYPT 协议加密 JGroups 集群流量：

JGroups 协议堆栈必须配置为使用 SYM_ENCRYPT 作为加密协议。
您可以通过将 JGROUPS_ENCRYPT_PROTOCOL 环境变量设置为 SYM_ENCRYPT 来做到这一点 ：
```
JGROUPS_ENCRYPT_PROTOCOL=SYM_ENCRYPT
```
JGROUPS_ENCRYPT_SECRET 环境变量必须设置为包含用于保护 JGroups 通信的 JGroups 密钥存储文件的机密的名称。如果没有设置，则不会加密群集通信并发出警告。例如：
```
JGROUPS_ENCRYPT_SECRET=eap7-app-secret
```
JGROUPS_ENCRYPT_KEYSTORE_DIR 环境变量必须设置为通过 JGROUPS_ENCRYPT_SECRET 变量指定的机密中密钥存储文件的目录路径。如果没有设置，则不会加密群集通信并发出警告。例如：
```
JGROUPS_ENCRYPT_KEYSTORE_DIR=/etc/jgroups-encrypt-secret-volume
```
JGROUPS_ENCRYPT_KEYSTORE 环境变量必须设置为通过 JGROUPS_ENCRYPT_SECRET 变量指定的机密中的密钥存储文件的名称。如果没有设置，则不会加密群集通信并发出警告。例如：
```
JGROUPS_ENCRYPT_KEYSTORE=jgroups.jceks
```
JGROUPS_ENCRYPT_NAME 环境变量必须设置为与服务器证书关联的名称。如果没有设置，则不会加密群集通信并发出警告。例如：
```
JGROUPS_ENCRYPT_NAME=jgroups
```
JGROUPS_ENCRYPT_PASSWORD 环境变量必须设置为用于访问密钥存储和证书的密码。如果没有设置，则不会加密群集通信并发出警告。例如：
```
JGROUPS_ENCRYPT_PASSWORD=mypassword
```

8.7.2.2. Configuring ASYM_ENCRYPT

注意

JBoss EAP 7.3 包括新版本的 ASYM_ENCRYPT 协议。之前版本的协议已被弃用。如果指定 JGROUPS_CLUSTER_PASSWORD 环境变量，则使用已弃用的协议版本，并在 pod 日志中显示警告。

要使用 ASYM_ENCRYPT 协议加密 JGroups 集群流量，请指定 ASYM_ENCRYPT 作为加密协议，并将它配置为使用 elytron 子系统中配置的密钥存储。

-e JGROUPS_ENCRYPT_PROTOCOL="ASYM_ENCRYPT" \
-e JGROUPS_ENCRYPT_SECRET="encrypt_secret" \
-e JGROUPS_ENCRYPT_NAME="encrypt_name" \
-e JGROUPS_ENCRYPT_PASSWORD="encrypt_password" \
-e JGROUPS_ENCRYPT_KEYSTORE="encrypt_keystore" \
-e JGROUPS_CLUSTER_PASSWORD="cluster_password"

8.8. 健康检查

用于 OpenShift 镜像的 JBoss EAP 默认利用 OpenShift 中包含的存活度和就绪度探测。此外，此镜像还包括 Eclipse MicroProfile 健康，如配置指南中所述。

下表演示了这些健康检查通过所需的值。如果状态是下面找到的值以外的任何内容，则检查将失败，并且镜像按照镜像的重启策略重新启动。

表 8.5. 存活度和就绪度检查

已执行的测试	存活度	就绪
服务器状态	任何状态	Running
引导错误	无	无
部署状态 ^[a]	不适用或无 `失败` 条目	不适用或无 `失败` 条目
Eclipse MicroProfile 健康 ^[b]	无或 `UP`	无或 `UP`
^[a] 仅当没有部署时，N/A 才有效。 ^[b] 仅当 `microprofile-health-smallrye` 子系统被禁用后，N/A 才有效状态。

8.9. 消息传递

8.9.1. 配置外部 Red Hat AMQ Broker

您可以使用环境变量为 OpenShift 镜像配置 JBoss EAP，以连接外部红帽 AMQ 代理。

OpenShift 应用程序定义示例

以下示例使用模板来创建连接到外部红帽 AMQ 7 代理的 JBoss EAP 应用：

示例：JDK 8

oc new-app eap73-amq-s2i \
-p APPLICATION_NAME=eap73-mq \
-p MQ_USERNAME=MY_USERNAME \
-p MQ_PASSWORD=MY_PASSWORD

示例：JDK 11

oc new-app eap73-openjdk11-amq-s2i \
-p APPLICATION_NAME=eap73-mq \
-p MQ_USERNAME=MY_USERNAME \
-p MQ_PASSWORD=MY_PASSWORD

重要

本例中使用的模板为所需的参数提供有效的默认值。如果不使用模板并提供自己的参数，请注意 MQ_SERVICE_PREFIX_MAPPING 名称必须与 APPLICATION_ NAME 名称匹配，并附加有 "-amq7=MQ"。

8.10. 安全域

要配置新的安全域，用户必须定义 SECDOMAIN_NAME 环境变量。

这将创建以环境变量命名的安全域。用户也可以定义以下环境变量来自定义域：

表 8.6. 安全域

变量名称	描述
SECDOMAIN_NAME	定义一个额外的安全域。示例值： `myDomain`
SECDOMAIN_PASSWORD_STACKING	如果定义，则启用 `password-stacking` 模块选项，并设置为值 `useFirstPass`。示例值： `true`
SECDOMAIN_LOGIN_MODULE	要使用的登录模块。默认为 `UsersRoles`
SECDOMAIN_USERS_PROPERTIES	包含用户定义的属性文件的名称。默认为 `users.properties`
SECDOMAIN_ROLES_PROPERTIES	包含角色定义的属性文件的名称。默认为 `roles.properties`

8.11. HTTPS 环境变量

变量名称描述

变量名称	描述
HTTPS_NAME	如果与 `HTTPS_PASSWORD` 和 `HTTPS_KEYSTORE` 一起定义，请启用 HTTPS 并设置 SSL 名称。如果您使用 `keytool -genkey` 命令创建该值，则该值应该是您的密钥存储的别名名称。示例值： `example.com`
HTTPS_PASSWORD	如果与 `HTTPS_NAME` 和 `HTTPS_KEYSTORE` 一起定义，请启用 HTTPS 并设置 SSL 密钥密码。示例值： `passw0rd`
HTTPS_KEYSTORE	如果与 `HTTPS_PASSWORD` 和 `HTTPS_NAME` 一起定义，请启用 HTTPS，并将 SSL 证书密钥文件设置为 `EAP_HOME/standalone/configuration`下的相对路径示例值： `ssl.key`

HTTPS_NAME

如果与 HTTPS_PASSWORD 和 HTTPS_KEYSTORE 一起定义，请启用 HTTPS 并设置 SSL 名称。

如果您使用 keytool -genkey 命令创建该值，则该值应该是您的密钥存储的别名名称。

示例值： example.com

HTTPS_PASSWORD

如果与 HTTPS_NAME 和 HTTPS_KEYSTORE 一起定义，请启用 HTTPS 并设置 SSL 密钥密码。

示例值： passw0rd

HTTPS_KEYSTORE

如果与 HTTPS_PASSWORD 和 HTTPS_NAME 一起定义，请启用 HTTPS，并将 SSL 证书密钥文件设置为 EAP_HOME/standalone/configuration下的相对路径

示例值： ssl.key

8.12. 管理环境变量

表 8.7. 管理环境变量

变量名称描述

变量名称	描述
ADMIN_USERNAME	如果定义了此和 `ADMIN_PASSWORD`，则用于 JBoss EAP 管理用户名。示例值： `eapadmin`
ADMIN_PASSWORD	指定 `ADMIN_USERNAME` 的密码。示例值： `passw0rd`

ADMIN_USERNAME

如果定义了此和 ADMIN_PASSWORD，则用于 JBoss EAP 管理用户名。

示例值： eapadmin

ADMIN_PASSWORD

指定 ADMIN_USERNAME 的密码。

示例值： passw0rd

8.13. S2I

镜像包含 S2I 脚本和 Maven。

目前仅支持 Maven 作为构建工具，用于应在 OpenShift 上的基于 JBoss EAP 的容器（或相关/子镜像）上部署的应用。

目前只支持 WAR 部署。

8.13.1. 自定义配置

可以为镜像添加自定义配置文件。放入 configuration/ 目录中的所有文件将复制到 EAP_HOME/standalone/configuration/。例如，若要覆盖镜像中使用的默认配置，只需将自定义 standalone-openshift.xml 添加到 configuration/ 目录中：请参阅此类部署的示例。

8.13.1.1. 自定义模块

可以添加自定义模块。模块/ 目录中的所有文件将复制到 EAP_HOME/modules/。请参阅此类部署的示例。

8.13.2. Deployment Artifacts

默认情况下，将部署来自源 目标 目录中的工件。要从不同目录部署，请在 BuildConfig 定义中设置 ARTIFACT_DIR 环境变量。ARTIFACT_DIR 是一个以逗号分隔的列表。例如：ART IFACT_DIR=app1/target,app2/target,app3/target

8.13.3. artifact Repository Mirrors

Maven 中的存储库包含各种类型的构建构件和依赖项，如所有项目 JAR、库 JAR、插件或其他特定于项目的工件。它还指定执行 S2I 构建时从哪里下载工件的位置。除了使用中央存储库外，组织通常要部署本地自定义镜像存储库。

使用镜像的好处包括：

同步镜像的可用性，在地理上更加接近，速度更快。
能够更好地控制存储库内容。
有可能在不同团队（开发人员、CI）之间共享构件，而无需依赖公共服务器和存储库。
缩短构建时间.

通常，存储库管理器可以作为镜像的本地缓存。假设存储库管理器已在 https://10.0.0.1:8443/repository/internal/ 外部部署并可访问，S2I 构建可以通过向应用程序的构建配置提供 MAVEN_MIRROR_URL 环境变量来使用此管理器：

识别要对其应用 MAVEN_MIRROR_URL 变量的构建配置名称。
```
oc get bc -o name
buildconfig/eap
```

使用 MAVEN_MIRROR_URL 环境变量更新 eap 的构建配置。

oc env bc/eap MAVEN_MIRROR_URL="https://10.0.0.1:8443/repository/internal/"
buildconfig "eap" updated

验证设置。

oc env bc/eap --list
# buildconfigs eap
MAVEN_MIRROR_URL=https://10.0.0.1:8443/repository/internal/

计划应用的新构建。

注意

在应用构建期间，您会注意到 Maven 依赖项是从存储库管理器（而非默认的公共存储库）中提取的。另外，构建完成后，您会看到镜像已填充构建期间检索和使用的所有依赖项。

8.13.3.1. 安全工件存储库镜像 URL

为通过 Maven 存储库防止"man-in-the-middle"攻击，JBoss EAP 需要将安全 URL 用于工件存储库镜像 URL。

URL 应指定一个安全 http("https")和安全端口。

默认情况下，如果您指定了不安全的 URL，则会返回一个错误。您可以使用属性 -Dinsecure.repositories=WARN 来覆盖此行为。

8.13.4. 脚本

run: 此脚本使用 openshift-launch.sh 脚本，通过 standalone-openshift.xml 配置配置和启动 JBoss EAP。
assemble: 此脚本使用 Maven 构建来源，创建软件包(WAR)，并将它移到 EAP_HOME/standalone/deployments 目录。

8.13.5. 自定义脚本

您可以在启动 pod 之前添加自定义脚本，在 JBoss EAP 启动之前运行。

您可以添加在启动 pod 时有效的任何脚本，包括 CLI 脚本。

从镜像启动 JBoss EAP 时有两个选项可用于包括脚本：

将要以 postconfigure.sh 执行的 configmap 挂载
在指定的安装目录中添加 install.sh 脚本

8.13.5.1. 挂载 configmap 来执行自定义脚本

如果要在运行时将自定义脚本挂载到现有镜像（换句话说，是已构建的镜像），请挂载 configmap。

挂载 configmap：

创建一个包含您要包含在 postconfigure.sh 中的内容的 configmap。
例如，在项目根目录中创建一个名为 extensions 的目录，以包含脚本 postconfigure.sh 和 extensions.cli 并运行以下命令：
```
$ oc create configmap jboss-cli --from-file=postconfigure.sh=extensions/postconfigure.sh --from-file=extensions.cli=extensions/extensions.cli
```

通过部署控制器(dc)将 configmap 挂载到容器集中。

$ oc set volume dc/eap-app --add --name=jboss-cli -m /opt/eap/extensions -t configmap --configmap-name=jboss-cli --default-mode='0755' --overwrite

postconfigure.sh示例

#!/usr/bin/env bash
set -x
echo "Executing postconfigure.sh"
$JBOSS_HOME/bin/jboss-cli.sh --file=$JBOSS_HOME/extensions/extensions.cli

extensions.cli示例

embed-server --std-out=echo  --server-config=standalone-openshift.xml
:whoami
quit

8.13.5.2. 使用 install.sh 执行自定义脚本

如果要在构建时包含脚本作为镜像的一部分，请使用 install.sh。

使用 install.sh 执行自定义脚本：

在 s2i 构建期间要使用的项目的 git 存储库中，创建一个名为 .s2i 的目录。
在 s2i 目录中，添加包含以下内容的名为 environment 的文件：
```
$ cat .s2i/environment
CUSTOM_INSTALL_DIRECTORIES=extensions
```
创建名为 扩展名 的目录。

在 扩展 目录中，创建包含以下内容的 postconfigure.sh 文件（将占位符代码替换为您的环境的适当代码）：

$ cat extensions/postconfigure.sh
#!/usr/bin/env bash
echo "Executing patch.cli"
$JBOSS_HOME/bin/jboss-cli.sh --file=$JBOSS_HOME/extensions/some-cli-example.cli

在扩展目录中，创建类似于以下内容的文件 install.sh（用适合您的环境替换占位符代码）：

$ cat extensions/install.sh
#!/usr/bin/env bash
set -x
echo "Running $PWD/install.sh"
injected_dir=$1
# copy any needed files into the target build.
cp -rf ${injected_dir} $JBOSS_HOME/extensions

8.13.6. 环境变量

您可以通过向 s2i build 命令提供环境变量来影响构建的执行方式。可以提供的环境变量有：

表 8.8. s2i 环境变量

变量名称	描述
ARTIFACT_DIR	此目录中的 `.war`、`. ear 和.jar` 文件将复制到 `deployments/` 目录中。示例值： `target`
ENABLE_GENERATE_DEFAULT_DATASOURCE	可选。当带有值 `true` 时，服务器会被置备为 default 数据源。否则，默认数据源不包含在内。
GALLEON_PROVISION_DEFAULT_FAT_SERVER	可选。如果值为 `true`，并且未设置 galleon 层，则调配了一个默认的 JBoss EAP 服务器。
GALLEON_PROVISION_LAYERS	可选。指示 S2I 进程调配指定的层。该值是一个要调配的以逗号分隔的层列表，包括一个基础层和任意数量的 decorator 层。示例值： `jaxrs、sso`
HTTP_PROXY_HOST	用于 Maven 的 HTTP 代理的主机名或 IP 地址。示例值：192. `168.1.1`
HTTP_PROXY_PORT	Maven 使用的 HTTP 代理的 TCP 端口。示例值：80 `80`
HTTP_PROXY_USERNAME	如果提供了 `HTTP_PROXY_PASSWORD`，请将凭证用于 HTTP 代理。示例值： `myusername`
HTTP_PROXY_PASSWORD	如果提供了 `HTTP_PROXY_USERNAME`，请对 HTTP 代理使用凭据。示例值： `mypassword`
HTTP_PROXY_NONPROXYHOSTS	如果提供，配置的 HTTP 代理将忽略这些主机。示例值： `some.example.org\|*.example.net`
MAVEN_ARGS	覆盖构建期间提供给 Maven 的参数。示例值： `-e -Popenshift -DskipTests -Dcom.redhat.xpaas.repo.redhatga 软件包`
MAVEN_ARGS_APPEND	在构建期间将用户参数附加到 Maven。示例值： `-Dfoo=bar`
MAVEN_MIRROR_URL	要配置的 Maven Mirror/repository Manager 的 URL。示例值： `https://10.0.0.1:8443/repository/internal/` 请注意，指定的 URL 应该安全。详情请查看第 8.13.3.1 节 “安全工件存储库镜像 URL”。
MAVEN_CLEAR_REPO	（可选）在构建后清除本地 Maven 存储库。如果镜像中的服务器与本地缓存高度耦合，则不会删除缓存并打印警告。示例值： `true`
APP_DATADIR	如果定义，则在复制数据文件的源中的目录。示例值： `mydata`
DATA_DIR	镜像中复制 `$APP_DATADIR` 数据的目录。示例值： `EAP_HOME/data`

注意

如需更多信息，请参阅在用于 OpenShift 镜像的 JBoss EAP 上构建和运行 Java 应用，该镜像使用 Maven 和 JBoss EAP 中为 OpenShift 镜像中包含的 S2I 脚本。

8.14. 单点登录镜像

此镜像包括启用了红帽单点登录的应用程序。

有关使用 JBoss EAP for OpenShift 镜像为 OpenShift 镜像部署红帽单点登录的更多信息，请参阅红帽单点登录 OpenShift 指南中部署红帽单点登录 JBoss EAP 镜像。

表 8.9. 单点登录环境变量

变量名称	描述
SSO_URL	单点登录服务器的 URL。
SSO_REALM	已部署应用的单点登录域.
SSO_PUBLIC_KEY	单点登录域的公钥.此字段是可选的，但如果忽略，可能会使应用程序容易遭受中间人攻击。
SSO_USERNAME	访问单点登录 REST API 所需的单点登录用户. 示例值： `mySsoUser`
SSO_PASSWORD	`SSO_USERNAME` 变量定义的 Single Sign-On 用户的密码。示例值： `6fedmL3P`
SSO_SAML_KEYSTORE	SAML 的密钥存储位置.默认为 `/etc/sso-saml-secret-volume/keystore.jks`。
SSO_SAML_KEYSTORE_PASSWORD	SAML 的密钥存储密码.默认为 `mykeystorepass`。
SSO_SAML_CERTIFICATE_NAME	用于 SAML 的密钥/证书别名.默认为 `jboss`。
SSO_BEARER_ONLY	单点登录客户端访问类型.（可选）示例值： `true`
SSO_CLIENT	单点登录的路径重新指向应用。默认为匹配 `module-name`。
SSO_ENABLE_CORS	如果为 `true`，请为单点登录应用启用 CORS。（可选）
SSO_SECRET	用于机密访问的单点登录客户端机密。示例值： `KZ1QyIq4`
SSO_DISABLE_SSL_CERTIFICATE_VALIDATION	如果 JBoss EAP 和 RH 单点登录服务器之间的 SSL/TLS 通信 `正确`，则无法使用 `curl` 禁用证书验证。默认情况下不设置。示例值： `true`

8.15. 事务恢复

当集群缩减时，事务分支可能会有疑问。在这些情况下，可能需要手动恢复事务。

重要

Automated Transaction Recovery 功能仅支持 OpenShift 3，该功能仅作为技术预览提供。

对于 OpenShift 4，您可以使用 EAP Operator 安全地恢复事务。请参阅 EAP Operator for Safe Transaction Recovery。

8.15.1. 不支持的交易恢复方案

JTS 事务
由于父级的网络端点在恢复协调器 IOR 中编码，如果子节点或父节点恢复具有新 IP 地址，或者打算使用虚拟化 IP 地址访问，则恢复将无法可靠地工作。
XTS 事务
XTS 在集群场景中无法用于恢复目的。详情请查看 JBTM-2742。
OpenShift 3 不支持在 JBoss 远程上传播的事务.

注意

OpenShift 4 和 EAP 操作员支持通过 JBoss 远程传播的事务。

通过 XATerminator 传播的事务
由于 EIS 旨在连接到 Java EE 应用服务器的单一实例，因此没有清晰定义的方法来组合这些流程。

8.15.2. 手动交易恢复过程

8.15.2.1. 注意事项

这个步骤只描述了如何手动恢复在单个 JVM 中完全包含的交易。该程序不描述如何恢复传播到其他 JVM 的 JTA 事务。

重要

在各种不同的网络分区情景中，OpenShift 可能会启动具有相同 IP 地址和相同节点名称的同一容器集的多个实例，其中由于分区，旧容器集仍在运行。在手动恢复过程中，这可能会导致您连接到具有对象存储过时视图的 pod。如果您认为在这种情况下，建议关闭所有 JBoss EAP pod，以确保没有使用任何资源管理器或对象存储。

在 XA 事务中获取资源时，您负责确保支持每种资源类型进行恢复。例如，PostgreSQL 和 MySQL 在恢复方面表现良好，但对于 A-MQ 和 JDV 资源管理器等，您应该检查特定 OpenShift 版本的文档。

部署必须使用 JDBC 对象存储。

重要

事务管理器取决于节点标识符的唯一性。XID 的最大字节长度由 XA 规范设置，且不可更改。由于 OpenShift EAP 的 JBoss EAP 必须包含在 XID 中的数据，这会在节点标识符中留有 23 字节的空间。

OpenShift 对节点标识符进行合并，使其符合这个 23 字节限制：

对于所有节点名称，即便是 23 字节下的节点名称，也会去除 - （短划线）字符。
如果名称仍超过 23 字节，则字符将从名称开头截断，直至名称的长度在 23 字节限制之内。

但是，这个过程可能会影响标识符的唯一性。例如，名称 aa123456789012345678m0jwh 和 bbb123456789012345678m0jwh 都被截断为 123456789012345678m0jwh，这会破坏预期名称的唯一性。在另一个示例中，t -pod-is-m0jwh 和 thispod-is-m0jwh 都截断到 thispodism0jwh，再次破坏名称的唯一性。

您负责确保您配置的节点名称是唯一的，但要注意上述截断过程。

8.15.2.2. 前提条件

它假定 OpenShift 实例已配置了 JDBC 存储，并且存储表使用与容器集名称对应的表前缀进行分区。每当使用 JBoss EAP 部署时，这都应是自动的。您可以通过查看正在运行的 pod 中的 transaction 子系统配置，验证 JBoss EAP 实例是否使用 JDBC 对象存储：

确定 /opt/eap/standalone/configuration/openshift-standalone.xml 配置文件是否包含用于事务子系统的元素：
```
<subsystem xmlns="urn:jboss:domain:transactions:3.0">
```
如果使用 JDBC 对象存储，则有一个类似于以下内容的条目：
```
<jdbc-store datasource-jndi-name="java:jboss/datasources/jdbcstore_postgresql"/>
```
注意
JNDI 名称标识用于存储事务日志的数据源。

8.15.2.3. 流程

重要

以下流程只详细描述了数据源的手动交易恢复过程。

使用数据库供应商工具列出内部分支的 XID（事务分支标识符）。需要列出 由 pod 上运行或已缩减的 pod 上运行的任何部署使用的所有数据源 的 XID。有关使用的数据库产品，请参阅供应商文档。
对于每个这样的 XID，确定哪个 pod 创建了事务，并检查该 pod 是否仍然在运行。
1. 如果正在运行，则让该分支单独保留。
2. 如果 pod 没有运行，假设它已从集群中移除，您必须应用此处所述的手动解析流程。查看失败 pod 使用的事务日志存储，以查看是否有对应的事务日志：
  1. 如果有日志，则使用供应商工具手动提交 XID。
  2. 如果没有日志，请假定它是一个孤立分支，并使用供应商工具回滚 XID。

此过程的其余部分详细说明了如何执行这些步骤。

8.15.2.3.1. 解决 In-doubt 分支

首先，查找部署使用的所有资源。

建议您使用 JBoss EAP 管理 CLI 执行此操作。尽管这些资源应该在 JBoss EAP standalone-openshift.xml 配置文件中定义，但也可以使用其他方式供应用服务器内的事务子系统使用。例如，这可以通过部署中的文件来实现，或者在运行时使用管理 CLI 动态完成。

在失败的 pod 群集中运行 JBoss EAP 实例的 pod 上打开一个终端。如果没有这样的 pod，请向上扩展为一个 pod。
使用 /opt/eap/bin/add-user.sh 脚本创建管理用户。
使用 /opt/eap/bin/jboss-cli.sh 脚本登录管理 CLI。

列出服务器上配置的数据源。这些可能包含doubt 事务分支。

/subsystem=datasources:read-resource
{
    "outcome" => "success",
    "result" => {
    	"data-source" => {
        	"ExampleDS" => undefined,
        	...
    	},
  ...
}

拥有列表后，查找每个数据源的连接 URL。例如：

/subsystem=datasources/data-source=ExampleDS:read-attribute(name=connection-url)
{
    "outcome" => "success",
    "result" => "jdbc:h2:mem:test;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE",
    "response-headers" => {"process-state" => "restart-required"}
}

连接到每个数据源并列出任何 in-doubt 事务分支。

注意

存储 in-doubt 分支的表名称会因数据源供应商而异。

JBoss EAP 具有默认的 SQL 查询工具(H2)，可用于检查每个数据库。例如：

java -cp /opt/eap/modules/system/layers/base/com/h2database/h2/main/h2-1.3.173.jar \
-url "jdbc:postgresql://localhost:5432/postgres" \
-user sa \
-password sa \
-sql "select gid from pg_prepared_xacts;"

或者，您可以使用资源的原生工具。例如，对于名为 sampledb 的 PostGreSQL 数据源，您可以使用 OpenShift 客户端工具远程登录到 pod 并查询 in-doubt 事务表：

$ oc rsh postgresql-2-vwf9n # rsh to the named pod
sh-4.2$ psql sampledb
psql (9.5.7)
Type "help" for help.

sampledb=# select gid from pg_prepared_xacts;
131077_AAAAAAAAAAAAAP//rBEAB440GK1aJ72oAAAAGHAtanRhLWNyYXNoLXJlYy0zLXAyY2N3_AAAAAAAAAAAAAP//rBEAB440GK1aJ72oAAAAGgAAAAEAAAAA

8.15.2.3.2. 从每个 XID 中提取全局事务 ID 和节点标识符

识别所有用于 in-doubt 分支的 XID 时，将 XID 转换为您可以与事务管理器的交易表中存储的日志进行比较的格式。

例如，以下 Bash 脚本可用于执行这一转换：假设 $PG_XID 从上述选择语句中保存 XID，则 JBoss EAP 事务 ID 可以按如下方式获取：

PG_XID="$1"
IFS='_' read -ra lines <<< "$PG_XID"
[[ "${lines[0]}" = 131077 ]] || exit 0; # this script only works for our own FORMAT ID
PG_TID=${lines[1]}

a=($(echo "$PG_TID"| base64 -d  | xxd -ps |tr -d '\n' | while read -N16 i ; do echo 0x$i ; done))
b=($(echo "$PG_TID"| base64 -d  | xxd -ps |tr -d '\n' | while read -N8 i ; do echo 0x$i ; done))
c=("${b[@]:4}") # put the last 3 32-bit hexadecimal numbers into array c
# the negative elements of c need special handling since printf below only works with positive
# hexadecimal numbers
for i in "${!c[@]}"; do
  arg=${c[$i]}
  # inspect the MSB to see if arg is negative - if so convert it from a 2’s complement number
  [[ $(($arg>>31)) = 1 ]] && x=$(echo "obase=16; $(($arg - 0x100000000 ))" | bc) || x=$arg
  if [[ ${x:0:1} = \- ]] ; then # see if the first character is a minus sign
     neg[$i]="-";
     c[$i]=0x${x:1} # strip the minus sign and make it hex for use with printf below
  else
     neg[$i]=""
     c[$i]=$x
  fi
done
EAP_TID=$(printf %x:%x:${neg[0]}%x:${neg[1]}%x:${neg[2]}%x ${a[0]} ${a[1]} ${c[0]} ${c[1]} ${c[2]})

完成后，$EAP_TID 变量保存创建此 XID 的交易的全局事务 ID。启动事务的 pod 的节点标识符由以下 bash 命令的输出提供：

echo "$PG_TID"| base64 -d | tail -c +29

注意

节点标识符从 PostgreSQL 全局事务 ID 字段的 29 字符开始。

如果此 pod 仍在运行，则仅保留此 in-doubt 分支，因为事务仍在运行。
如果此 pod 未在运行，您需要为事务日志搜索相关的事务日志存储。日志存储位于 JDBC 表中，它命名如下 os<node-identifier>jbosststxtable 模式。
- 如果没有这样的表，将分支单独保留为归某些其他事务管理器所有。包含此表的数据源的 URL 在下方显示的 transaction 子系统描述中定义。
- 如果有这样的表，请查找与全局事务 ID 匹配的条目。
  - 如果表中有一个与全局事务 ID 匹配的条目，则需要使用数据源供应商工具提交 in-doubt 分支，如下所述。
  - 如果没有这样的条目，则分支是孤立的，可以安全地回滚。

以下是如何提交 in-doubt PostgreSQL 分支的示例：

$ oc rsh postgresql-2-vwf9n
sh-4.2$ psql sampledb
psql (9.5.7)
Type "help" for help.
psql sampledb
commit prepared '131077_AAAAAAAAAAAAAP//rBEAB440GK1aJ72oAAAAGHAtanRh
 ----
LWNyYXNoLXJlYy0zLXAyY2N3_AAAAAAAAAAAAAP//rBEAB440GK1aJ72oAAAAGgAAAAEAAAAA';

重要

对所有数据源和 in-doubt 分支重复此步骤。

8.15.2.3.3. 获取任何可联系资源管理器的集群中所有运行 JBoss EAP 实例的节点标识符列表

节点标识符配置为与 pod 名称同名。您可以使用 oc 命令获取所使用的 pod 名称。使用以下命令列出正在运行的 pod：

$ oc get pods | grep Running
eap-manual-tx-recovery-app-4-26p4r   1/1       Running     0          23m
postgresql-2-vwf9n                   1/1       Running     0          41m

对于每个正在运行的容器集，查看容器集日志的输出中，并获取节点名称。例如，对于上述输出中显示的第一个 pod，请使用以下命令：

$ oc logs eap-manual-tx-recovery-app-4-26p4r | grep "jboss.node.name" | head -1
jboss.node.name = tx-recovery-app-4-26p4r

重要

上述 JBoss 节点名称标识符将始终截断到总共 23 个字符的最大长度，方法是从开始删除字符并保留尾随字符，直至达到最多 23 个字符。

8.15.2.3.4. 查找事务日志

事务日志驻留在 JDBC 支持的对象存储中。此存储的 JNDI 名称在 JBoss EAP 配置文件的 transaction 子系统定义中定义。
查看配置文件，以查找与上述 JNDI 名称对应的数据源定义。
使用 JNDI 名称生成连接 URL。
您可以使用 URL 连接数据库，并对相关的 in-doubt 事务表发出 选择 查询。
或者，如果您知道数据库在哪一容器集上运行，并且您知道数据库的名称，那么直接使用数据库工具的 OpenShift 远程 shell 或许更容易。
例如，如果 JDBC 存储由名为 sampledb 的 PostgreSQL 数据库托管，在 pod postgresql-2-vwf9n 上运行，您可以使用以下命令查找事务日志：
注意
以下命令中列出的 The ostxrecoveryapp426p4rjbosststxtable 表名称已选定，因为它遵循保存日志存储条目的 JDBC 表名称的模式。在您的环境中，表名称具有类似格式：
- 从 前缀 开始.
- 中间的部分源自以上 JBoss 节点名称，如果存在，可能会删除"-"（短划线）字符。
- 最后，附加 jbosststxtable 后缀，以创建表的最终名称。
```
$ oc rsh postgresql-2-vwf9n
sh-4.2$ psql sampledb
psql (9.5.7)
Type "help" for help.

sampledb=# select uidstring from ostxrecoveryapp426p4rjbosststxtable where TYPENAME='StateManager/BasicAction/TwoPhaseCoordinator/AtomicAction'
;
              uidstring
 -------------------------------------
 0:ffff0a81009d:33789827:5a68b2bf:40
 (1 row)
```

8.15.2.3.5. 为 Reconciled In-doubt branchs 清理事务日志

警告

请不要删除日志，除非您确定没有剩余的 in-doubt 分支。

当给定交易的所有分支均已完成，并且已检查所有潜在资源管理器（包括 A-MQ 和 JDV）时，可以安全地删除事务日志。

发出以下命令，指定要使用适当的 uid 字符串 删除的事务日志：

DELETE FROM ostxrecoveryapp426p4rjbosststxtable where uidstring = UIDSTRING

重要

如果您没有删除日志，那么在准备后完成但现已解决失败的事务不会从事务日志存储中删除。因此，使用不必要的存储，将来手动协调将变得更加困难。

8.16. 包括的 JBoss 模块

下表列出了用于 OpenShift 镜像的 JBoss EAP 中含有的 JBoss 模块。

表 8.10. 包括的 JBoss 模块

JBoss 模块
org.jboss.as.clustering.common
org.jboss.as.clustering.jgroups
org.jboss.as.ee
org.jboss.logmanager.ext
org.jgroups
org.openshift.ping
net.oauth.core

8.17. EAP Operator: API Information

EAP 操作器引入了以下 API：

8.17.1. WildFlyServer

WildFlyServer 定义自定义 JBoss EAP 资源。

表 8.11. WildFlyServer

字段	描述	Scheme	必填
`metadata`	标准对象的元数据	ObjectMeta v1 meta	false
`spec`	规定 JBoss EAP 部署的所需行为.	`WildFlyServerSpec`	true
`status`	JBoss EAP 部署的最新观察到状态。只读.	WildFlyServerStatus	false

8.17.2. WildFlyServerList

WildFlyServerList 定义 JBoss EAP 部署列表。

表 8.12. 表

字段	描述	Scheme	必填
`metadata`	标准列表的元数据	metav1.ListMeta	false
`项`	`WildFlyServer`列表	`WildFlyServer`	true

8.17.3. WildFlyServerSpec

WildFlyServerSpec 是 JBoss EAP 资源所需行为的规范。

它使用带有 pod 规格的 StatefulSet，该 spec 挂载 /opt/jboss/wildfly/standalone/data 上存储指定的卷。

表 8.13. WildFlyServerSpec

字段	描述	Scheme	必填
`applicationImage`	要部署的应用程序镜像的名称	字符串	false
`replicas`	应用程序所需的副本数	int32]	true
`standaloneConfigMap`	spec 以指定如何从 `ConfigMap` 中读取独立配置。	`StandaloneConfigMapSpec`	false
`storage`	用于指定应如何使用存储的存储规格。如果省略，则使用 `EmptyDir` （不会在 pod 重启后持久保留数据）	`StorageSpec`	false
`serviceAccountName`	用于运行 JBoss EAP pod 的 ServiceAccount 名称	字符串	false
`envFrom`	`configMap` 或 secret 中的容器中存在的环境变量列表	`corev1.EnvFromSource`	false
`env`	容器中存在的环境变量列表	corev1.EnvVar	false
`secrets`	要作为卷挂载到容器中的机密名称列表。每个 secret 都作为只读卷挂载到 `/etc/secrets/<secret name>`	字符串	false
`configMaps`	要作为卷挂载到容器中的 `ConfigMap` 名称列表。每个 `ConfigMap` 都作为只读卷挂载到 `/etc/configmaps/<config map name> 下`	字符串	false
`disableHTTPRoute`	禁用到应用程序服务的 HTTP 端口的创建路由（如果省略，则为false）	布尔值	false
`sessionAffinity`	如果每次来自同一客户端 IP 的连接传递给同一 JBoss EAP 实例/pod（如果省略，则为 false）	布尔值	false

8.17.4. StorageSpec

StorageSpec 为 WildFlyServer 资源定义已配置的存储。如果未定义 EmptyDir 或 volumeClaimTemplate，则使用默认的 EmptyDir。

EAP Operator 配置 StatefulSet，使用此 StorageSpec 的信息挂载专用于 JBoss EAP 自己数据的独立/数据目录的卷。例如，事务日志）。如果使用 EmptyDir，则数据不会在 pod 重启后保留。如果部署在 JBoss EAP 上的应用依赖于事务，请指定 volumeClaimTemplate，以便在 pod 重启后重复使用相同的持久卷。

表 8.14. 表

字段	描述	Scheme	必填
`emptyDir`	JBoss EAP `StatefulSet`使用的 `EmptyDirVolumeSource`	corev1.EmptyDirVolumeSource	false
`volumeClaimTemplate`	PersistentVolumeClaim 规格，用于配置 `资源要求`，以存储 JBoss EAP 单机数据目录。模板的名称派生自 `WildFlyServer` 名称。对应的卷被挂载为 `ReadWriteOnce` 访问模式。	corev1.PersistentVolumeClaim	false

8.17.5. StandaloneConfigMapSpec

StandaloneConfigMapSpec 定义如何从 ConfigMap 中读取 JBoss EAP 单机配置。如果省略，JBoss EAP 将使用其镜像中的 standalone.xml 配置。

表 8.15. StandaloneConfigMapSpec

字段	描述	Scheme	必填
`name`	包含独立配置 XML 文件的 `ConfigMap` 名称。	字符串	true
key	`ConfigMap 的键`，其值为独立配置 XML 文件。如果省略，spec 会找到 `standalone.xml` 键。	字符串	false

8.17.6. WildFlyServerStatus

WildFlyServerStatus 是 JBoss EAP 部署的最新观察到状态。只读.

表 8.16. WildFlyServerStatus

字段	描述	Scheme	必填
`replicas`	应用程序的实际副本数	int32	true
`主机`	路由到应用 HTTP 服务的主机	字符串	true
`pods`	pod 状态	PodStatus	true
`scalingdownPods`	正在缩减清理过程的 pod 数量	int32	true

8.17.7. PodStatus

PodStatus 是运行 JBoss EAP 应用的 pod 的最新观察到状态。

表 8.17. PodStatus

字段	描述	Scheme	必填
`name`	pod 的名称	字符串	true
`podIP`	分配给 pod 的 IP 地址	字符串	true
`状态`	scale 进程中的容器集状态。状态默认为 ACTIVE，这表示它为请求提供服务。	字符串	false

修订了 2022 年 2 月 16 日 16:41:53 +1000

Language and Page Formatting Options

适用于 OpenShift 的 JBoss EAP 在线版入门

用于 OpenShift 在线的红帽 JBoss 企业应用平台开发指南

第 1 章 简介

1.1. 什么是红帽 JBoss 企业应用平台(JBoss EAP)？

1.2. JBoss EAP 如何在 OpenShift 上工作？

1.3. 比较：用于 OpenShift 的 JBoss EAP 和 JBoss EAP

1.4. 版本兼容性和支持

JDK 8 镜像

JDK 11 镜像

Eclipse OpenJ9 镜像

1.4.1. OpenShift 4.x 支持

1.4.2. IBM Z 和 IBM Power 系统支持

1.4.3. 在 OpenShift 中从 JBoss EAP 7.1 升级到 JBoss EAP 7.3

1.5. 部署选项

第 2 章 在用于 OpenShift 镜像的 JBoss EAP 上构建并运行 Java 应用

2.1. 先决条件

2.2. 为应用部署准备 OpenShift

2.3. 导入适用于 OpenShift 镜像流和模板的最新 JBoss EAP

为 JDK 8 导入命令

JDK 11 导入命令

在 IBM Z 和 IBM Power 系统上为 Eclipse OpenJ9 导入命令

2.4. 将 JBoss EAP Source-to-Image(S2I)应用部署到 OpenShift

2.5. 部署后的任务

2.6. JBoss EAP 中针对 OpenShift 的连锁构建支持

第 3 章 为 Java 应用程序配置 JBoss EAP for OpenShift 镜像

3.1. 用于 OpenShift S2I 流程的 JBoss EAP 如何工作

3.2. 使用环境变量为 OpenShift 配置 JBoss EAP

3.2.1. JVM 内存配置

3.2.1.1. JVM 默认内存设置

3.2.1.2. JVM Garbage Collection Settings

3.2.1.3. 默认设置中的资源限制

3.2.1.4. JVM 环境变量

3.3. 构建扩展和项目工件

3.3.1. S2I 工件

3.3.1.1. 模块、驱动程序和通用部署

3.3.2. Runtime Artifacts

3.3.2.1. datasources

3.3.2.2. 资源适配器

3.4. 为 OpenShift 使用 JBoss EAP 模板的结果

3.5. 用于 OpenShift 镜像的红帽 JBoss 企业应用平台的 SSO 配置

3.6. 默认数据源

3.7. 用于 OpenShift 镜像的 JBoss EAP 的部署注意事项

3.7.1. 扩展和持久性存储分区

3.7.2. 扩展缩减和交易恢复

第 4 章 针对 OpenShift 的 JBoss EAP 的功能调试

4.1. 调配自定义 JBoss EAP 服务器

4.2. 可用的 JBoss EAP 层

4.2.1. base Layers

datasources-web-server

jaxrs-server

cloud-server

4.2.2. decorator Layers

sso

Observability（可观察性）

web-clustering

4.3. 在 JBoss EAP 中配置用户开发的层

4.3.1. 为 JBoss EAP 构建自定义层

4.3.2. JBoss EAP 的自定义配置文件

4.3.3. 使用用户开发的层构建应用程序

第 5 章 将应用从 OpenShift 4 上的 JBoss EAP Imagestreams 迁移到 eap73 Imagestreams

5.1. eap73 镜像流的存活度和就绪度探测配置更新

5.2. 默认数据源删除

5.3. 在 OpenShift 中将 JBoss EAP 7.1 升级到 JBoss EAP 7.3 时对 standalone-openshift.xml 的更新

第 6 章 故障排除

6.1. Pod 重启故障排除

6.2. 使用 JBoss EAP 管理 CLI 进行故障排除

第 7 章 用于在 OpenShift 上自动部署应用的 EAP Operator

7.1. 使用 Web 控制台安装 EAP Operator

7.2. 使用 CLI 安装 EAP Operator

7.3. 使用 EAP 操作器在 OpenShift 上部署 Java 应用

7.3.1. 用于创建应用镜像的 eap-s2i-build 模板

7.3.2. 使用 eap-s2i-build 模板构建应用镜像

7.3.3. 可引导 JAR 用于打包 JBoss EAP 服务器和 Java 应用程序

7.3.4. 使用 EAP 操作器部署 Java 应用：完成强制配置

7.3.5. 使用 EAP 操作器部署 Java 应用：完成可选配置

7.3.6. 创建 Secret

7.3.7. 创建 ConfigMap

7.3.8. 从 standalone.xml 文件创建 ConfigMap

7.3.9. 为应用程序配置持久性存储

第 1 章简介

第 2 章在用于 OpenShift 镜像的 JBoss EAP 上构建并运行 Java 应用

第 3 章为 Java 应用程序配置 JBoss EAP for OpenShift 镜像

第 4 章针对 OpenShift 的 JBoss EAP 的功能调试

第 5 章将应用从 OpenShift 4 上的 JBoss EAP Imagestreams 迁移到 eap73 Imagestreams

5.3. 在 OpenShift 中将 JBoss EAP 7.1 升级到 JBoss EAP 7.3 时对 `standalone-openshift.xml` 的更新

第 6 章故障排除

第 7 章用于在 OpenShift 上自动部署应用的 EAP Operator

第 8 章参考信息