通过

将 WildFly 应用程序迁移到 Azure Kubernetes 服务上的 WildFly

  • 项目

本指南介绍在需要迁移现有 WildFly 应用程序以使之在 Azure Kubernetes 服务容器中的 WildFly 上运行时应注意的事项。

注意

本文仅提供一般性建议。 Microsoft 和 Red Hat 都不支持 WildFly，但 WildFly 社区可以提供帮助。 有关 Red Hat 和 Microsoft 联合支持的产品/服务的信息，请参阅 Azure 上的 Red Hat JBoss EAP。

预迁移

若要确保迁移成功，请在开始之前完成以下各节中所述的评估和清点步骤。

清点服务器容量

记录当前生产服务器的硬件（内存、CPU、磁盘）、平均值和峰值请求计数，以及资源利用率。 无论选择了哪种迁移路径，都将需要此信息。 例如，它有助于指导选择节点池中 VM 的大小、容器要使用的内存量以及容器需要多少 CPU 份额。

可以在 AKS 中调整节点池的大小。 若要了解如何操作，请参阅重设 Azure Kubernetes 服务 (AKS) 中的节点池大小。

清点所有机密

检查生产服务器上的所有属性和配置文件中是否有机密和密码。 请确保在 WAR 中检查 jboss-web.xml。 还可以在应用程序中查找包含密码或凭据的配置文件。

请考虑将这些机密存储到 Azure KeyVault 中。 有关详细信息，请参阅 Azure Key Vault 基本概念。

清点所有证书

记录用于公共 SSL 终结点的所有证书。 可以通过运行以下命令来查看生产服务器上的所有证书：

keytool -list -v -keystore <path to keystore>

验证支持的 Java 版本是否正常运行

在 Azure Kubernetes 服务上使用 WildFly 需要特定版本的 Java，因此需要确认应用程序使用受支持的版本正确运行。

注意

如果当前服务器在不受支持的 JDK（如 Oracle JDK 或 IBM OpenJ9）上运行，则此验证尤其重要。

若要获取当前的 Java 版本，请登录到生产服务器并运行以下命令：

java -version

请参阅要求，了解使用什么版本来运行 WildFly。

清点 JNDI 资源

清点所有 JNDI 资源。 某些资源（如 JMS 消息代理）可能需要迁移或重新配置。

确定是否使用了会话复制

如果应用程序依赖于会话复制，则必须更改应用程序，摆脱此依赖关系。

在应用程序中

检查 WEB-INF/jboss-web.xml 和/或 WEB-INF/web.xml 文件。

记录数据源

如果应用程序使用任何数据库，则需捕获以下信息：

  • 数据源名称是什么？
  • 连接池配置是什么？
  • 在哪里可以找到 JDBC 驱动程序 JAR 文件？

有关详细信息，请参阅 WildFly 文档中的 DataSource 配置。

确定是否使用以及如何使用文件系统

使用应用程序服务器上的文件系统需要重新配置，在极少数情况下需要体系结构更改。 文件系统可供 WildFly 模块或应用程序代码使用。 可以标识以下部分所述的部分或全部方案。

只读静态内容

如果应用程序当前提供静态内容，则需为其提供一个备用位置。 可能需要考虑将静态内容移到 Azure Blob 存储，并添加 Azure CDN，方便用户在全球范围内快速下载。 有关详细信息，请参阅 Azure 存储中的静态网站托管和快速入门：将 Azure 存储帐户与 Azure CDN 集成。

动态发布的静态内容

如果应用程序允许那些通过应用程序上传/生成但在创建后不可变的静态内容，则可将上述 Azure Blob 存储和 Azure CDN 与 Azure 函数配合使用，以便处理上传和 CDN 刷新操作。 我们提供了一个示例实现，用于通过 Azure Functions 进行静态内容的上传和 CDN 预加载操作。

动态或内部内容

对于经常由应用程序写入和读取的文件（如临时数据文件），或者仅对应用程序可见的静态文件，可以将 Azure 存储共享作为持久卷进行装载。 有关详细信息，请参阅在 Azure Kubernetes 服务 (AKS) 中通过 Azure 文件存储创建并使用卷。

确定应用程序是否依赖于计划的作业

计划作业（例如，Quartz 计划程序任务或 Unix cron 作业）不应与 Azure Kubernetes 服务 (AKS) 一起使用。 Azure Kubernetes 服务不会阻止你部署内含计划任务的应用程序。 但是，如果应用程序横向扩展，则同一个计划的作业可能会按照计划期间运行多次。 这种情况可能会导致意外的后果。

若要在 AKS 群集上执行计划的作业，请按需定义 Kubernetes CronJob。 有关详细信息，请参阅使用 CronJob 运行自动化任务。

确定是否需要连接到本地

如果应用程序需要访问任何本地服务，则需预配 Azure 的某个连接服务。 有关详细信息，请参阅将本地网络连接到 Azure。 或者，你需要重构应用程序，以便使用本地资源公开的公开可用的 API。

确定 Java 消息服务 (JMS) 队列或主题是否正在使用中

如果应用程序使用 JMS 队列或主题，则需将其迁移到外部托管的 JMS 服务器。 Azure 服务总线和高级消息队列协议 (AMQP) 可成为那些使用 JMS 的项目的理想迁移策略。 有关详细信息，请参阅将 Java Message Service 1.1 与 Azure 服务总线标准和 AMQP 1.0 配合使用。

如果已配置 JMS 持久存储，则必须捕获其配置，并在迁移后应用它。

确定应用程序是否使用实体 Bean 或 EJB 2.x 样式的 CMP Bean

如果应用程序使用实体 Bean 或 EJB 2.x 样式的 CMP Bean，则需要重构应用程序以删除这些依赖项。

确定是否使用了 Java EE 应用程序客户端功能

如果客户端应用程序使用了 Java EE 应用程序客户端功能连接到（服务器）应用程序，则需要重构客户端应用程序和（服务器）应用程序以使用 HTTP API。

确定应用程序是否包含特定于 OS 的代码

如果应用程序包含的代码有主机 OS 的依赖项，则需重构该代码，删除那些依赖项。 例如，如果应用程序在 Windows 上运行，则可能需要将文件系统路径中的 / 或 \ 替换为 File.Separator 或 Paths.get。

确定是否使用了 EJB 计时器

如果应用程序使用了 EJB 计时器，则需要验证每个 WildFly 实例是否可以独立触发 EJB 计时器代码。 需要进行此验证是因为在 Azure Kubernetes 服务部署方案中，每个 EJB 计时器都将在其自己的 WildFly 实例上触发。

确定是否使用了 JCA 连接器

如果应用程序使用 JCA 连接器，则需验证是否可以在 WildFly 上使用 JCA 连接器。 如果 JCA 实现与 WildFly 相关联，则需重构应用程序，摆脱该依赖关系。 如果可以使用该连接器，则需将这些 JAR 添加到服务器 classpath 中，并将所需的配置文件放在 WildFly 服务器目录中的正确位置，使其可用。

确定是否使用了 JAAS

如果应用程序使用的是 JAAS，则需要捕获 JAAS 的配置方式。 如果使用的是数据库，则可以将其转换为 WildFly 上的 JAAS 域。 如果它是自定义实现，则需要验证它是否可在 WildFly 上使用。

确定应用程序是否使用资源适配器

如果应用程序需要资源适配器 (RA)，则它需要与 WildFly 兼容。 若要确定此 RA 在独立的 WildFly 实例上是否正常工作，需将其部署到服务器并对其进行正确配置。 如果可以正常使用 RA，则需将这些 JAR 添加到 Docker 映像的服务器 classpath 中，并将所需的配置文件放在 WildFly 服务器目录中的正确位置，使其可用。

确定应用程序是否由多个 WAR 组成

如果应用程序由多个 WAR 组成，则应将这些 WAR 中的每一个都视为单独的应用程序，并通过本指南了解这其中的每个应用程序。

确定应用程序是否打包为 EAR

如果将应用程序打包为 EAR 文件，请务必检查 application.xml 文件并捕获配置。

注意

如果希望能够独立缩放每个 Web 应用程序，以便更好地使用 Azure Kubernetes 服务 （AKS） 资源，则应将 EAR 分解为单独的 Web 应用程序。

确定在生产服务器上运行的所有外部进程和守护程序

如果在应用程序服务器外运行任何进程（如监视守护程序），则需消除它们或将它们迁移到其他位置。

执行就地测试

在创建容器映像之前，请将应用程序迁移到要在 AKS 上使用的 JDK 和 WildFly 版本。 全面测试应用程序，确保兼容性和性能。

迁移

预配 Azure 容器注册表和 Azure Kubernetes 服务

使用以下命令创建容器注册表和 Azure Kubernetes 群集（带有对注册表具有“读取者”角色的服务主体）。 确保根据群集的网络要求选择相应的网络模型。

az group create \
    --resource-group $resourceGroup \
    --location eastus
az acr create \
    --resource-group $resourceGroup \
    --name $acrName \
    --sku Standard
az aks create \
    --resource-group $resourceGroup \
    --name $aksName \
    --attach-acr $acrName \
    --network-plugin azure

创建 WildFly 的 Docker 映像

若要创建 Dockerfile，需要符合以下先决条件：

  • 受支持的 JDK。
  • 安装 WildFly。
  • JVM 运行时选项。
  • 可以通过某种方法传入环境变量（如果适用）。

然后，可以执行以下部分所述的步骤（如果适用）。 对于 Dockerfile 和 Web 应用程序，可以从使用 WildFly 容器快速入门存储库着手。

配置 KeyVault FlexVolume

创建 Azure KeyVault 并填充所有必要的机密。 有关详细信息，请参阅快速入门：使用 Azure CLI 在 Azure Key Vault 中设置和检索机密。 然后，配置 KeyVault FlexVolume，使这些机密可供 Pod 访问。

还需要更新用于启动 WildFly 的启动脚本。 此脚本必须在启动服务器之前将证书导入 WildFly 使用的密钥存储。

设置数据源

若要配置 WildFly 以访问数据源，需将 JDBC 驱动程序 JAR 添加到 Docker 映像，然后执行相应的 JBoss CLI 命令。 生成 Docker 映像时，这些命令必须设置数据源。

以下步骤提供了有关 PostgreSQL、MySQL 和 SQL Server 的说明。

  1. 下载 PostgreSQL、MySQL 或 SQL Server 的 JDBC 驱动程序。

    解压缩已下载的存档，获取驱动程序 .jar 文件。

  2. 创建一个名称类似于 module.xml 的文件，并添加以下标记。 将 <module name> 占位符（包括尖括号）替换为适用于 PostgreSQL 的 org.postgres、适用于 MySQL 的 com.mysql 或适用于 SQL Server 的 com.microsoft。 将 <JDBC .jar file path> 替换为上一步骤中 .jar 文件的名称，包括将文件置于 Docker 映像中时所在位置的完整路径，例如 /opt/database。

    <?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.1" name="<module name>">
    <resources>
       <resource-root path="<JDBC .jar file path>" />
    </resources>
    <dependencies>
        <module name="javax.api"/>
        <module name="javax.transaction.api"/>
    </dependencies>
</module>

  3. 创建一个名称类似于 datasource-commands.cli 的文件，并添加以下代码。 将 <JDBC .jar file path> 替换为在上一步使用的值。 将 <module file path> 替换为上一步中的文件名和路径，例如 /opt/database/module.xml。

    注意

    Microsoft 建议使用最安全的可用身份验证流。 此过程中所述的身份验证流（例如数据库、缓存、消息传送或 AI 服务）需要高度信任应用程序，并且存在其他流中不存在的风险。 仅当更安全的选项（例如无密码连接或无密钥连接的托管标识）不可行时，才使用此流。 对于本地计算机操作，首选无密码连接或无密钥连接的用户标识。

    batch
module add --name=org.postgres --resources=<JDBC .jar file path> --module-xml=<module file path>
/subsystem=datasources/jdbc-driver=postgres:add(driver-name=postgres,driver-module-name=org.postgres,driver-class-name=org.postgresql.Driver,driver-xa-datasource-class-name=org.postgresql.xa.PGXADataSource)
data-source add --name=postgresDS --driver-name=postgres --jndi-name=java:jboss/datasources/postgresDS --connection-url=$DATABASE_CONNECTION_URL --user-name=$DATABASE_SERVER_ADMIN_FULL_NAME --password=$DATABASE_SERVER_ADMIN_PASSWORD --use-ccm=true --max-pool-size=5 --blocking-timeout-wait-millis=5000 --enabled=true --driver-class=org.postgresql.Driver --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter --jta=true --use-java-context=true --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker
reload
run batch
shutdown

  4. 更新应用程序的 JTA 数据源配置：

    打开应用的 src/main/resources/META-INF/persistence.xml 文件，找到 <jta-data-source> 元素。 替换其内容，如下所示：

    <jta-data-source>java:jboss/datasources/postgresDS</jta-data-source>

  5. 将以下内容添加到 Dockerfile，以便在生成 Docker 映像时创建数据源

    RUN /bin/bash -c '<WILDFLY_INSTALL_PATH>/bin/standalone.sh --start-mode admin-only &' && \
sleep 30 && \
<WILDFLY_INSTALL_PATH>/bin/jboss-cli.sh -c --file=/opt/database/datasource-commands.cli && \
sleep 30

  6. 确定要使用的 DATABASE_CONNECTION_URL，它因数据库服务器而异，并且不同于 Azure 门户中的值。 此处所示的 URL 格式是必需的，方便 WildFly 使用：

    jdbc:postgresql://<database server name>:5432/<database name>?ssl=true

  7. 在以后创建部署 YAML 时，需使用适当的值传递环境变量 DATABASE_CONNECTION_URL、DATABASE_SERVER_ADMIN_FULL_NAME 和 DATABASE_SERVER_ADMIN_PASSWORD。

注意

Microsoft 建议使用最安全的可用身份验证流。 此过程中所述的身份验证流（例如数据库、缓存、消息传送或 AI 服务）需要高度信任应用程序，并且存在其他流中不存在的风险。 仅当更安全的选项（例如无密码连接或无密钥连接的托管标识）不可行时，才使用此流。 对于本地计算机操作，首选无密码连接或无密钥连接的用户标识。

若要详细了解如何通过 WildFly 配置数据库连接性，请参阅 PostgreSQL、MySQL 或 SQL Server。

设置 JNDI 资源

若要设置每个 JNDI 资源，需要在 WildFly 上进行配置，并且通常需要执行以下步骤：

  1. 下载必要的 JAR 文件，并将其复制到 Docker 映像中。
  2. 创建一个 WildFly module.xml 文件，该文件引用那些 JAR 文件。
  3. 创建特定 JNDI 资源所需的任何配置。
  4. 创建要在 Docker 生成期间使用的 JBoss CLI 脚本，以便注册 JNDI 资源。
  5. 将所有内容添加到 Dockerfile。
  6. 在部署 YAML 中传递适当的环境变量。

以下示例演示了创建 JNDI 资源以通过 JMS 连接到 Azure 服务总线所需的步骤。

  1. 下载 Apache Qpid JMS 提供程序

    解压缩已下载的存档，获取 .jar 文件。

  2. 创建一个名称类似于 module.xml 的文件，并在 /opt/servicebus 中添加以下标记。 请确保 JAR 文件的版本号与前一步骤的 JAR 文件的名称相符。

    <?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.1" name="org.jboss.genericjms.provider">
 <resources>
  <resource-root path="proton-j-0.31.0.jar"/>
  <resource-root path="qpid-jms-client-0.40.0.jar"/>
  <resource-root path="slf4j-log4j12-1.7.25.jar"/>
  <resource-root path="slf4j-api-1.7.25.jar"/>
  <resource-root path="log4j-1.2.17.jar"/>
  <resource-root path="netty-buffer-4.1.32.Final.jar" />
  <resource-root path="netty-codec-4.1.32.Final.jar" />
  <resource-root path="netty-codec-http-4.1.32.Final.jar" />
  <resource-root path="netty-common-4.1.32.Final.jar" />
  <resource-root path="netty-handler-4.1.32.Final.jar" />
  <resource-root path="netty-resolver-4.1.32.Final.jar" />
  <resource-root path="netty-transport-4.1.32.Final.jar" />
  <resource-root path="netty-transport-native-epoll-4.1.32.Final-linux-x86_64.jar" />
  <resource-root path="netty-transport-native-kqueue-4.1.32.Final-osx-x86_64.jar" />
  <resource-root path="netty-transport-native-unix-common-4.1.32.Final.jar" />
  <resource-root path="qpid-jms-discovery-0.40.0.jar" />
 </resources>
 <dependencies>
  <module name="javax.api"/>
  <module name="javax.jms.api"/>
 </dependencies>
</module>

  3. 在 /opt/servicebus 中创建 jndi.properties 文件。

    connectionfactory.${MDB_CONNECTION_FACTORY}=amqps://${DEFAULT_SBNAMESPACE}.servicebus.windows.net?amqp.idleTimeout=120000&jms.username=${SB_SAS_POLICY}&jms.password=${SB_SAS_KEY}
queue.${MDB_QUEUE}=${SB_QUEUE}
topic.${MDB_TOPIC}=${SB_TOPIC}

  4. 创建一个名称类似于 servicebus-commands.cli 的文件，并添加以下代码。

    batch
/subsystem=ee:write-attribute(name=annotation-property-replacement,value=true)
/system-property=property.mymdb.queue:add(value=myqueue)
/system-property=property.connection.factory:add(value=java:global/remoteJMS/SBF)
/subsystem=ee:list-add(name=global-modules, value={"name" => "org.jboss.genericjms.provider", "slot" =>"main"}
/subsystem=naming/binding="java:global/remoteJMS":add(binding-type=external-context,module=org.jboss.genericjms.provider,class=javax.naming.InitialContext,environment=[java.naming.factory.initial=org.apache.qpid.jms.jndi.JmsInitialContextFactory,org.jboss.as.naming.lookup.by.string=true,java.naming.provider.url=/opt/servicebus/jndi.properties])
/subsystem=resource-adapters/resource-adapter=generic-ra:add(module=org.jboss.genericjms,transaction-support=XATransaction)
/subsystem=resource-adapters/resource-adapter=generic-ra/connection-definitions=sbf-cd:add(class-name=org.jboss.resource.adapter.jms.JmsManagedConnectionFactory, jndi-name=java:/jms/${MDB_CONNECTION_FACTORY})
/subsystem=resource-adapters/resource-adapter=generic-ra/connection-definitions=sbf-cd/config-properties=ConnectionFactory:add(value=${MDB_CONNECTION_FACTORY})
/subsystem=resource-adapters/resource-adapter=generic-ra/connection-definitions=sbf-cd/config-properties=JndiParameters:add(value="java.naming.factory.initial=org.apache.qpid.jms.jndi.JmsInitialContextFactory;java.naming.provider.url=/opt/servicebus/jndi.properties")
/subsystem=resource-adapters/resource-adapter=generic-ra/connection-definitions=sbf-cd:write-attribute(name=security-application,value=true)
/subsystem=ejb3:write-attribute(name=default-resource-adapter-name, value=generic-ra)
run-batch
reload
shutdown

  5. 将以下内容添加到 Dockerfile，以便在生成 Docker 映像时创建 JNDI 源

    RUN /bin/bash -c '<WILDFLY_INSTALL_PATH>/bin/standalone.sh --start-mode admin-only &' && \
sleep 30 && \
<WILDFLY_INSTALL_PATH>/bin/jboss-cli.sh -c --file=/opt/servicebus/servicebus-commands.cli && \
sleep 30

  6. 在以后创建部署 YAML 时，需使用适当的值传递环境变量 MDB_CONNECTION_FACTORY、DEFAULT_SBNAMESPACE、SB_SAS_POLICY、SB_SAS_KEY、MDB_QUEUE、SB_QUEUE、MDB_TOPIC 和 SB_TOPIC。

查看 WildFly 配置

查看 WildFly Admin Guide（WildFly 管理指南），该指南涵盖了上一指南未涵盖的任何其他预迁移步骤。

构建 Docker 映像并将其推送到 Azure 容器注册表

创建 Dockerfile 后，需要生成 Docker 映像并将其发布到 Azure 容器注册表。

如果你使用了我们的 WildFly 容器快速入门 GitHub 存储库，则构建映像并将其推送到 Azure 容器注册表的过程相当于调用以下三个命令。

在这些示例中，MY_ACR 环境变量保存 Azure 容器注册表的名称，MY_APP_NAME 变量保存要在 Azure 容器注册表中使用的 Web 应用程序的名称。

生成 WAR 文件：

mvn package

登录到 Azure 容器注册表：

az acr login --name ${MY_ACR}

生成并推送映像：

az acr build --image ${MY_ACR}.azurecr.io/${MY_APP_NAME} --file src/main/docker/Dockerfile .

也可使用 Docker CLI 在本地生成并测试映像，如以下命令所示。 此方法可以简化在一开始部署到 ACR 之前对映像进行的测试和优化。 但是，它要求安装 Docker CLI 并确保 Docker 后台程序正在运行。

生成映像：

docker build -t ${MY_ACR}.azurecr.io/${MY_APP_NAME}

在本地运行映像：

docker run -it -p 8080:8080 ${MY_ACR}.azurecr.io/${MY_APP_NAME}

现在可以在 http://localhost:8080 上访问你的应用程序。

登录到 Azure 容器注册表：

az acr login --name ${MY_ACR}

向 Azure 容器注册表推送映像：

docker push ${MY_ACR}.azurecr.io/${MY_APP_NAME}

若要更深入地了解如何在 Azure 中生成和存储容器映像，请参阅 Learn 模块：使用 Azure 容器注册表生成和存储容器映像。

预配公共 IP 地址

如果想要从内部网络或虚拟网络之外访问应用程序，则需要公共静态 IP 地址。 应在群集的节点资源组内预配此 IP 地址，如以下示例中所示：

export nodeResourceGroup=$(az aks show \
    --resource-group $resourceGroup \
    --name $aksName \
    --query 'nodeResourceGroup' \
    --output tsv)
export publicIp=$(az network public-ip create \
    --resource-group $nodeResourceGroup \
    --name applicationIp \
    --sku Standard \
    --allocation-method Static \
    --query 'publicIp.ipAddress' \
    --output tsv)
echo "Your public IP address is ${publicIp}."

部署到 Azure Kubernetes 服务 (AKS)

创建并应用 Kubernetes YAML 文件。 有关详细信息，请参阅快速入门：使用 Azure CLI 部署 Azure Kubernetes 服务 （AKS） 群集。 如果要创建外部负载均衡器（不管是针对应用程序，还是针对入口控制器），请确保提供在上一部分以 LoadBalancerIP 形式预配的 IP 地址。

包括环境变量形式的外部化参数。 有关详细信息，请参阅为容器定义环境变量。 不要包括机密（如密码、API 密钥和 JDBC 连接字符串）。 这些在下一部分中有所介绍。

创建部署 YAML 时，请确保包含内存和 CPU 设置，以便正确调整容器的大小。

配置持久性存储

如果应用程序需要非易失性存储，请配置一个或多个持久性卷。

迁移计划的作业

若要在 AKS 群集上执行计划的作业，请按需定义 Kubernetes CronJob。 有关详细信息，请参阅使用 CronJob 运行自动化任务。

迁移后

将应用程序迁移到 Azure Kubernetes 服务后，即应验证其运行是否符合预期。 完成该操作后，可以参考我们提供的一些建议，使应用程序的云原生性更好。

建议