构建 GraalVM Native Image(Alpha)

背景信息

本节主要介绍如何通过 GraalVMnative-image 组件构建 ShardingSphere-Proxy 的 Native Image 和对应的 Docker Image

注意事项

  1. version: "3.8"
  2. services:
  3. apache-shardingsphere-proxy-native:
  4. image: ghcr.io/apache/shardingsphere-proxy-native:latest
  5. volumes:
  6. - ./custom/conf:/opt/shardingsphere-proxy-native/conf
  7. ports:
  8. - "3307:3307"
  • 若你发现构建过程存在缺失的 GraalVM Reachability Metadata, 应当在 https://github.com/oracle/graalvm-reachability-metadata 打开新的 issue , 并提交包含 ShardingSphere 自身或依赖的第三方库缺失的 GraalVM Reachability Metadata 的 PR。

  • ShardingSphere 的 master 分支尚未准备好处理 Native Image 中的单元测试, 需要等待 Junit 5 Platform 的集成,你总是需要在构建 GraalVM Native Image 的过程中, 加上特定于 GraalVM Native Build Tools-DskipNativeTests-DskipTests 参数跳过 Native Image 中的单元测试。

  • 如下 3 个算法类由于涉及到 GraalVM Truffle Espresso 不方便在 host JVM 和 guest JVM 之间交互的 groovy.lang.Closure 类,暂未可在 GraalVM Native Image 下使用。

    • org.apache.shardingsphere.sharding.algorithm.sharding.complex.ComplexInlineShardingAlgorithm
    • org.apache.shardingsphere.sharding.algorithm.sharding.hint.HintInlineShardingAlgorithm
    • org.apache.shardingsphere.sharding.algorithm.sharding.inline.InlineShardingAlgorithm
  • 当前阶段,GraalVM Native Image 形态的 ShardingSphere Proxy 处于混合 AOT ( GraalVM Native Image ) 和 JIT ( GraalVM Truffle Espresso ) 运行的阶段。由于 https://github.com/oracle/graal/issues/4555 尚未关闭,GraalVM Truffle Espresso 运行需要的 .so 文件并不会进入 GraalVM Native Image 内。因此如果你需要在 Docker Image 外运行 ShardingSphere Proxy Native 的二进制文件,你需要确保系统环境变量 JAVA_HOME 指向 GraalVM 的 bin 目录,并且此 GraalVM 实例已经通过 GraalVM Updater 安装了 espresso 组件。

  • 本节假定处于 Linux(amd64,aarch64), MacOS(amd64)或 Windows(amd64)环境。 如果你位于 MacOS(aarch64/M1) 环境,你需要关注尚未关闭的 https://github.com/oracle/graal/issues/2666

前提条件

  1. 根据 https://www.graalvm.org/downloads/ 要求安装和配置 JDK 17 对应的 GraalVM CEGraalVM EE。 同时可以通过 SDKMAN! 安装 JDK 17 对应的 GraalVM CE

  2. 通过 GraalVM Updater 工具安装 native-imageespresso 组件。

  3. 根据 https://www.graalvm.org/22.3/reference-manual/native-image/#prerequisites 的要求安装本地工具链。

  4. 如果需要构建 Docker Image, 确保 docker-ce 已安装。

操作步骤

  1. 获取 Apache ShardingSphere Git Source
  1. 在命令行构建产物, 分两种情形。
  • 情形一:不需要使用存在 SPI 实现的 JAR 或第三方依赖的 JAR

  • 在 Git Source 同级目录下执行如下命令, 直接完成 Native Image 的构建。

  1. ./mvnw -am -pl distribution/proxy-native -B -Pnative -DskipTests -Dmaven.javadoc.skip=true -Dcheckstyle.skip=true -Dspotless.apply.skip=true -Drat.skip=true clean package
  • 情形二:需要使用存在 SPI 实现的 JAR 或 GPL V2 等 LICENSE 的第三方依赖的 JAR。

  • distribution/proxy-native/pom.xmldependencies 加入存在 SPI 实现的 JAR 或第三方依赖的 JAR。示例如下

  1. <dependencies>
  2. <dependency>
  3. <groupId>com.mysql</groupId>
  4. <artifactId>mysql-connector-j</artifactId>
  5. <version>8.0.32</version>
  6. </dependency>
  7. <dependency>
  8. <groupId>org.apache.shardingsphere</groupId>
  9. <artifactId>shardingsphere-sql-translator-jooq-provider</artifactId>
  10. <version>5.3.1</version>
  11. </dependency>
  12. </dependencies>
  • 通过命令行构建 GraalVM Native Image。
  1. ./mvnw -am -pl distribution/proxy-native -B -Pnative -DskipTests -Dmaven.javadoc.skip=true -Dcheckstyle.skip=true -Dspotless.apply.skip=true -Drat.skip=true clean package
  1. 通过命令行启动 Native Image, 需要带上 4 个参数。 第一个参数为 ShardingSphere Proxy 使用的端口,第二个参数为你编写的包含 server.yaml/conf 文件夹, 第三个参数为绑定端口的 Address,第四个参数为 Force Start,如果为 true 则保证 ShardingSphere Proxy Native 无论能否连接都能正常启动。 假设已存在文件夹./custom/conf,示例为
  1. ./apache-shardingsphere-proxy-native 3307 ./custom/conf "0.0.0.0" false
  1. 如果需要构建 Docker Image, 在添加存在 SPI 实现的依赖或第三方依赖后, 在命令行执行如下命令。
  1. ./mvnw -am -pl distribution/proxy-native -B -Pnative,docker.native -DskipTests -Dmaven.javadoc.skip=true -Dcheckstyle.skip=true -Dspotless.apply.skip=true -Drat.skip=true clean package
  • 假设存在包含server.yamlconf 文件夹为 ./custom/conf,可通过如下的 docker-compose.yml 文件启动 GraalVM Native Image 对应的 Docker Image。
  1. version: "3.8"
  2. services:
  3. apache-shardingsphere-proxy-native:
  4. image: apache/shardingsphere-proxy-native:latest
  5. volumes:
  6. - ./custom/conf:/opt/shardingsphere-proxy-native/conf
  7. ports:
  8. - "3307:3307"
  • 如果你不对 Git Source 做任何更改, 上文提及的命令将使用 oraclelinux:9-slim 作为 Base Docker Image。 但如果你希望使用 busybox:glicgcr.io/distroless/basescratch 等更小体积的 Docker Image 作为 Base Docker Image,你需要根据 https://www.graalvm.org/22.3/reference-manual/native-image/guides/build-static-executables/ 的要求, 做为 pom.xmlnative profile 添加 -H:+StaticExecutableWithDynamicLibCjvmArgs 等操作。 另请注意,某些第三方依赖将需要在 Dockerfile 安装更多系统库,例如 libdl。 因此请确保根据你的使用情况调整 distribution/proxy-native 下的 pom.xmlDockerfile 的内容。

可观察性

  1. 下载 https://dlcdn.apache.org/skywalking/java-agent/8.12.0/apache-skywalking-java-agent-8.12.0.tgz , 并解压到 ShardingSphere Git Source 的 distribution/proxy-native

  2. 修改 distribution/proxy-native/pom.xmlnative profile, 为 org.graalvm.buildtools:native-maven-pluginconfiguration 添加如下的 jvmArgs

  1. <jvmArgs>
  2. <arg>-Dskywalking.agent.service_name="your service name"</arg>
  3. <arg>-Dskywalking.collector.backend_service="your skywalking oap ip and port"</arg>
  4. <arg>-javaagent:./skywalking-agent/skywalking-agent.jar</arg>
  5. </jvmArgs>
  1. 通过命令行构建 GraalVM Native Image。
  1. ./mvnw -am -pl distribution/proxy-native -B -Pnative -DskipTests -Dmaven.javadoc.skip=true -Dcheckstyle.skip=true -Dspotless.apply.skip=true -Drat.skip=true clean package