Apache Ignite Kubernetes 模块构建与 IP Finder 端到端测试实战指南

原创2026-10-14 13:29:581,359 阅读
文章标签:分布式数据库缓存

Apache Ignite Kubernetes 模块构建与 IP Finder 端到端测试实战指南

本文以 Apache Ignite 仓库中 modules/kubernetes/DEVNOTES.md 为主线,完整讲解如何在 Kubernetes 环境中构建 Apache Ignite 二进制、将其打包为 Docker 镜像、借助 Kubernetes 原生资源部署集群,并验证 TcpDiscoveryKubernetesIpFinder(Kubernetes IP finder)的节点自动发现与弹性伸缩能力。读完本文,你将掌握从源码构建、镜像打包到 RBAC 授权、Service 寻址、Deployment 部署、扩容验证与镜像重部署的完整闭环,并理解 IP finder 底层调用 Kubernetes API 解析 Pod 地址的实现原理。

一、Kubernetes 模块与 IP Finder 工作原理

Apache Ignite Kubernetes 模块的核心职责,是为运行在 Kubernetes 环境中的 Ignite 节点提供基于 TCP Discovery 的 IP 查找能力:它借助一个专用的 Kubernetes Service(headless 服务),动态解析出所有 Ignite Pod 的 IP 地址,从而使容器化的 Ignite 节点之间能够相互发现并组建集群。

从 README.md 的定位看,该模块仅面向容器化部署场景——所有 Ignite 节点必须以 Kubernetes Pod 形式运行,并且作为集群入口的 Ignite 客户端节点同样需要容器化;运行在 Kubernetes 之外的进程无法与容器化节点互通。这一点在 IP finder 的类注释中有明确说明,因此本地或家庭网络的联调测试应选择其他 TcpDiscoveryIpFinder 实现。

核心实现类为 TcpDiscoveryKubernetesIpFinder(见 TcpDiscoveryKubernetesIpFinder.java):

  • 继承自 TcpDiscoveryIpFinderAdapter,构造时默认创建 KubernetesConnectionConfiguration 实例并标记为共享(shared)IP finder;
  • getRegisteredAddresses() 是核心方法:它通过 KubernetesServiceAddressResolver 从 Kubernetes API 拉取 Service 对应的 Pod 地址列表,再为每个地址附加 cfg.getDiscoveryPort() 指定的发现端口(默认 0 时使用 TcpDiscoverySpi.DFLT_PORT,即 47500)组成 InetSocketAddress 集合返回;
  • registerAddresses() 与 unregisterAddresses() 均为空实现(No-op),因为 Kubernetes 场景下节点地址完全由 API Server 动态维护,无需本地注册;
  • 该类还保留了一批 @Deprecated 的 setter(setServiceName、setNamespace、setMasterUrl、setAccountToken、includeNotReadyAddresses),官方建议统一改用 KubernetesConnectionConfiguration 进行配置。

模块引入方式:在 Maven 项目中添加 org.apache.ignite:ignite-kubernetes 依赖(版本替换为实际使用的 Ignite 版本)即可;对以二进制发行版启动的独立节点,将 optional/ignite-kubernetes 目录移动到 libs 目录后再运行 ignite.{sh|bat},模块内容会被自动加入 classpath。

二、前置条件:准备 Docker 与 Minikube

按 DEVNOTES 的指引,完整的测试链路要求具备:

  1. 一个可用的 Apache Ignite 二进制发行包(zip 格式,构建方法见下文);
  2. 本地开发环境中的 Docker 与 Minikube;
  3. 用于本地联调的 Kubernetes 环境(Minikube 即可满足)。

启动 Minikube 前,需要让 Minikube 能够看到本地构建的 Docker 镜像,即把 Docker 客户端指向 Minikube 内部的 Docker daemon:

eval $(minikube docker-env)

随后启动 Minikube:

minikube start

说明:eval $(minikube docker-env) 的效果仅对当前终端会话有效。务必在同一个会话中完成后续的 docker build 与 kubectl 操作,否则 Minikube 将无法引用本地镜像。

三、构建 Apache Ignite 二进制

模块的构建指引指向仓库根目录的 DEVNOTES.txt。当前仓库使用 Maven Wrapper 统一构建流程,Unix 系环境(含 Cygwin、WSL、git-bash)下均以 ./mvnw 形式调用:

# 编译并安装(跳过测试)
./mvnw clean install -Pall-java,licenses -DskipTests

# 构建 Apache Ignite assembly 发行包
./mvnw initialize -Prelease

执行完 -Prelease 后,在 ./target/bin 目录下会生成 apache-ignite-<version>-bin.zip 文件,这就是后续 Docker 镜像组装所需的二进制包。当前仓库 parent/pom.xml 中定义的版本为 2.19.0-SNAPSHOT(以仓库实际 revision 为准),组装镜像时 IGNITE_VERSION 构建参数必须与 zip 包名严格一致。

DEVNOTES 特别提醒:如果修改了构建流程,务必同步更新 modules/kubernetes/config 目录下的相关文件(如 Dockerfile 中 COPY 的 zip 文件名),避免构建产物与镜像打包脚本脱节。

四、组装 Apache Ignite Docker 镜像

新建一个用于放置 Docker 镜像内容的目录,将以下文件拷贝进去:

  • 上一步构建出的 Apache Ignite 二进制 zip 包(如 apache-ignite-2.19.0-SNAPSHOT-bin.zip);
  • Dockerfile(来自 ignite-kubernetes/config/Dockerfile);
  • 启用了 Kubernetes IP finder 的 Ignite 配置文件 example-kube.xml(来自 ignite-kubernetes/config/example-kube.xml);
  • 启动 Ignite 节点的可执行脚本 run.sh(来自 ignite-kubernetes/config/run.sh)。

进入该目录执行镜像构建:

docker build -t ignite-kube:v1 --build-arg IGNITE_VERSION=<构建产物版本> .

Dockerfile 关键点解读

config/Dockerfile 中的关键指令与含义如下:

指令 / 参数 含义 默认值
ARG IGNITE_CFG_XML 镜像内 Ignite 配置文件名 example-kube.xml
ARG IGNITE_VERSION Apache Ignite 版本,必须与 zip 包名匹配 仓库当前为 2.18.0 示例
ENV IGNITE_HOME 解压后 Ignite 安装目录 /opt/ignite/apache-ignite-${IGNITE_VERSION}-bin
ENV CONFIG_URI 传给 run.sh 的配置路径 ${IGNITE_HOME}/config/$IGNITE_CFG_XML
ENV OPTION_LIBS 需要从 libs/optional 复制到 libs 的模块 ignite-kubernetes
ENV IGNITE_QUIET 是否开启安静模式(false 时以 -v 详细模式启动) false
COPY / RUN unzip 将本地构建包复制并解压进镜像 ——
CMD 容器启动命令 $IGNITE_HOME/run.sh
EXPOSE 暴露的端口 11211 47100 47500 49112

其中 EXPOSE 暴露的端口对应:11211(JDBC)、47100(communication SPI)、47500(discovery SPI)、49112(JMX);实际生产镜像通常还会暴露 8080(REST)与 10800(SQL)。

run.sh 启动脚本逻辑

config/run.sh 承担了「按需装载可选模块并启动节点」的职责:

  • 若设置了 OPTION_LIBS(逗号分隔的模块列表),将 $IGNITE_HOME/libs/optional/<lib>/* 复制到 $IGNITE_HOME/libs/,从而把 ignite-kubernetes 加入 classpath;
  • 若设置了 EXTERNAL_LIBS,逐行写入临时文件并用 wget 下载到 libs 目录;
  • IGNITE_QUIET=false 时追加 -v 参数,以详细日志模式启动;
  • 未设置 CONFIG_URI 时调用 bin/ignite.sh 使用默认配置启动,否则追加配置路径参数。

启用 Kubernetes IP finder 的配置示例

example-kube.xml 展示了最小配置:在 IgniteConfiguration 中显式声明 TcpDiscoverySpi,并将其 ipFinder 指向 TcpDiscoveryKubernetesIpFinder(默认参数):

<bean class="org.apache.ignite.configuration.IgniteConfiguration">
    <!-- Explicitly configure TCP discovery SPI to provide list of initial nodes. -->
    <property name="discoverySpi">
        <bean class="org.apache.ignite.spi.discovery.tcp.TcpDiscoverySpi">
            <property name="ipFinder">
                <!-- Enables Kubernetes IP finder with default settings. -->
                <bean class="org.apache.ignite.spi.discovery.tcp.ipfinder.kubernetes.TcpDiscoveryKubernetesIpFinder" />
            </property>
        </bean>
    </property>
</bean>

若需要自定义命名空间等参数,可参考 example-kube-persistence.xml:通过构造参数注入 KubernetesConnectionConfiguration 并设置 namespace 属性(该示例同时开启了持久化 DataStorageConfiguration)。

五、创建 Kubernetes 角色、Service 与 Pod 部署

镜像就绪后,需要依次创建 Kubernetes 资源。DEVNOTES 给出的完整顺序如下({path_to} 替换为 modules/kubernetes/config 的实际路径)。

1) 创建 RBAC 资源:授权访问 Endpoints

IP finder 通过 Kubernetes API Server 读取 Service 的 Endpoints,因此必须为 ServiceAccount 授予对应权限。

创建只读访问 endpoints 资源的 Role(ignite-account-role.yaml):

kubectl apply -f {path_to}/ignite-account-role.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: ignite
rules:
- apiGroups: [""]
  resources: ["endpoints"]
  verbs: ["get", "list", "watch"]

创建 ServiceAccount 并通过 RoleBinding 绑定角色(ignite-service-account.yaml、ignite-role-binding.yaml):

kubectl apply -f {path_to}/ignite-service-account.yaml
kubectl apply -f {path_to}/ignite-role-binding.yaml

RoleBinding 将 default 命名空间下的 ServiceAccount ignite 与同名 Role 绑定,subject 中的 namespace: default 需与 Pod 所在命名空间一致。

2) 创建 Ignite 查找服务(Lookup Service)

创建用于 IP 地址查找的 Kubernetes Service(ignite-service.yaml):

kubectl create -f {path_to}/ignite-service.yaml
apiVersion: v1
kind: Service
metadata:
  # 该名称必须与 TcpDiscoveryKubernetesIpFinder 的 serviceName 参数一致
  name: ignite
spec:
  clusterIP: None
  ports:
    - port: 9042 # 自定义端口(可选)
  selector:
    # 必须与 Ignite Pod 上设置的标签一致
    app: ignite

要点:

  • 服务名默认为 ignite,与 KubernetesConnectionConfiguration 的默认 srvcName 对应;改名后需保持 Service 名与 IP finder 配置一致;
  • clusterIP: None 声明这是一个 headless service,用于直接暴露后端 Pod 的 Endpoints;
  • selector.app: ignite 决定了该 Service 覆盖哪些 Pod,通常建议只选择可被发现的节点(服务端与厚客户端节点)。

3) 创建并部署 Ignite Pod

使用 Deployment 配置创建 Ignite Pod(ignite-deployment.yaml):

kubectl create -f {path_to}/ignite-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: ignite-cluster
spec:
  replicas: 2            # 初始节点数
  template:
    metadata:
      labels:
        app: ignite       # 必须与 Ignite 的 Kubernetes 服务名一致
    spec:
      containers:
      - name: ignite-node
        image: ignite-kube:v1
        ports:
        - containerPort: 47100 # communication SPI 端口
        - containerPort: 47500 # discovery SPI 端口
        - containerPort: 49112 # JMX 端口
        - containerPort: 8080  # REST 端口
        - containerPort: 10800 # SQL 端口
      serviceAccountName: ignite
  selector:
    matchLabels:
      app: ignite

注意:Deployment 的 Pod 模板必须设置 serviceAccountName: ignite,且 Pod 标签 app: ignite 要与 Service 的 selector 完全匹配,IP finder 才能通过 Endpoints 找到它们。

六、验证集群与动态扩容

部署完成后,检查 Pod 是否正常运行:

# 查看 Pod 状态
kubectl get pod

# 查看指定 Pod 的日志(确认节点加入集群)
kubectl logs {pod name}

日志中应能看到节点通过 TCP Discovery 相互发现并形成集群的记录。随后通过扩容验证 IP finder 的动态发现能力——新增 Pod 后,Service 的 Endpoints 自动包含新 Pod 地址,新节点无需任何手工登记即可被集群接纳:

kubectl scale --replicas=4 -f {path_to}/ignite-deployment.yaml

扩容后再次执行 kubectl get pod,观察新 Pod 变为 Running 状态,并确认集群中节点数同步增长。同理,缩容时被删除的 Pod 地址会从 Endpoints 中移除,集群拓扑随之收敛。

七、Docker 镜像重新部署

当镜像内容更新、又不希望变更镜像版本标签时,可先删除当前的 Ignite Deployment(注意不要删除 Service):

kubectl delete deployment ignite-cluster

随后用相同的命令重新构建并部署更新后的镜像即可。由于 Service、RBAC 等资源仍在,重建 Deployment 后新 Pod 会立即通过原查找服务重新发现彼此、恢复集群。

八、KubernetesConnectionConfiguration 参数详解

IP finder 的全部连接参数集中在 KubernetesConnectionConfiguration.java,各项参数、默认值与语义如下:

参数 setter 默认值 说明
服务名 setServiceName(String) ignite 用于 Pod IP 查找的 Kubernetes Service 名称,必须与 Service 配置中的 name 一致
命名空间 setNamespace(String) default Service 所属的 Kubernetes 命名空间
API Server 地址 setMasterUrl(String) https://kubernetes.default.svc.cluster.local:443 Kubernetes API Server 的 URL,Pod 内默认即可直达
账户令牌路径 setAccountToken(String) /var/run/secrets/kubernetes.io/serviceaccount/token ServiceAccount 令牌文件路径,用于 API Server 鉴权
是否包含未就绪地址 setIncludeNotReadyAddresses(boolean) false 是否把 notReadyAddresses 中的 Pod 地址一并纳入
发现端口 setDiscoveryPort(int) 0 返回给调用方的发现端口;0 表示使用 TcpDiscoverySpi.DFLT_PORT(47500)

verify() 方法会在请求前校验上述四个字符串参数非空,任一参数为 null 或空串都会抛出 IgniteSpiException(错误信息以 "One or more configuration parameters are invalid" 开头)。参数可直接以 XML 构造参数方式注入 IP finder,例如 example-kube-persistence.xml 中注入 namespace=ignite 的用法(需预先创建对应命名空间并完成 RBAC 配置)。

九、源码级原理:KubernetesServiceAddressResolver 的寻址过程

IP finder 的地址解析由内部类 KubernetesServiceAddressResolver.java 完成,其工作流程可概括为四个步骤:

  1. 初始化连接:init() 先调用 cfg.verify() 校验配置,然后按格式 /api/v1/namespaces/{namespace}/endpoints/{serviceName} 拼接出访问 Kubernetes API Server 的 URL(如 /api/v1/namespaces/default/endpoints/ignite),并创建一个信任所有证书的 SSLContext(trust-all TrustManager 与 HostnameVerifier)。初始化过程由 AtomicBoolean 加 CountDownLatch 保护,保证并发下只初始化一次。
  2. 鉴权请求:通过 HttpsURLConnection 发起 GET 请求,请求头携带 Authorization: Bearer <token>;token 由 serviceAccountToken() 从默认路径 /var/run/secrets/kubernetes.io/serviceaccount/token(ServiceAccount 自动挂载)读取。
  3. 解析响应:使用 Jackson ObjectMapper 将 API Server 返回的 Endpoints JSON 反序列化为 Endpoints -> Subset -> Address 结构,遍历每个 subset 的 addresses;若开启了 includeNotReadyAddresses,还会合并 notReadyAddresses 中的地址。其中 Address 只关心 ip 字段,其余字段通过 @JsonIgnoreProperties(ignoreUnknown = true) 忽略。
  4. 返回地址集合:最终通过 InetAddress.getByName(addr.ip) 转换为 InetAddress 集合返回;上游 TcpDiscoveryKubernetesIpFinder 再为每个 IP 附加发现端口,交给 TCP Discovery SPI 使用。

一个值得注意的实现细节:即使请求失败(如令牌错误、API 返回 401),IP finder 也会将异常包装为 IgniteException("Failed to retrieve Ignite pods IP addresses.")向外抛出,从而中断启动流程,避免节点带着不完整拓扑启动。

十、测试支撑:单元测试与集成测试套件

该模块的测试覆盖在 modules/kubernetes/src/test 下,通过 IgniteKubernetesTestSuite.java 聚合了以下测试类:

  • KubernetesConnectionConfigurationTest:校验 verify() 的必填字段约束,逐一把 accountToken、masterUrl、namespace 置空或 serviceName 置空,断言抛出 IgniteSpiException(见 KubernetesConnectionConfigurationTest.java);
  • TcpDiscoveryKubernetesIpFinderSelfTest:同样验证无效配置下 getRegisteredAddresses() 抛出以 "One or more configuration parameters are invalid" 开头的异常(见 TcpDiscoveryKubernetesIpFinderSelfTest.java);
  • KubernetesServiceAddressResolverTest:用 mockserver 模拟 Kubernetes API Server 的 /api/v1/namespaces/ns01/endpoints/ignite 响应,验证地址解析结果——默认只解析 addresses(期望 10.1.1.1/2/4/5/7),开启 includeNotReadyAddresses 后额外包含 notReadyAddresses(期望 10.1.1.1~7 全部),并验证 401 失败路径(见 KubernetesServiceAddressResolverTest.java);
  • TestClusterClientConnection 与 TestKubernetesIpFinderDisconnection:基于 KubernetesDiscoveryAbstractTest.java 抽象基类,通过 mockserver 模拟 API 响应,验证配置了 Kubernetes IP finder 的节点集群连接与断连场景。

十一、云环境与持久化部署变体

除本地 Minikube 外,仓库在 modules/kubernetes/config 下提供了三大公有云的定制模板,目录分别为 gce(Google Cloud)、eks(AWS Elastic Kubernetes Service)、az(Azure Kubernetes Service)。与本地版本相比,云模板的主要差异在于:

  • 使用 StatefulSet 替代 Deployment,并配套持久化/ WAL 的 StorageClass 定义(如 GCE 的 kubernetes.io/gce-pd、EKS 的 kubernetes.io/aws-ebs、Azure 的 kubernetes.io/azure-disk),挂载 /persistence 与 /wal 卷;
  • Pod 通过 volumeClaimTemplates 声明持久化卷(示例中每卷 1Gi,ReadWriteOnce);
  • 通过环境变量注入配置:OPTION_LIBS=ignite-kubernetes,ignite-rest-http、CONFIG_URI(指向 example-kube-persistence-and-wal.xml)、IGNITE_QUIET=false、JVM_OPTS=-Djava.net.preferIPv4Stack=true;
  • 扩展端口声明(含 10900 thin client 端口)。

这些模板与本地流程遵循相同的构建与验证逻辑,可作为生产环境部署的起点。完整的文档化部署指南可参考 docs/_docs/installation/kubernetes 下的 gke-deployment.adoc、amazon-eks-deployment.adoc、azure-deployment.adoc 与 generic-configuration.adoc。

十二、使用边界与注意事项

综合源码注释与配置约定,使用 Kubernetes IP finder 时需注意以下边界:

  1. 仅适用于 Kubernetes 环境:IP finder 依赖 Kubernetes API 与 ServiceAccount 机制,脱离集群(如本地直连)无法工作;本地测试请改用其他 IP finder 实现。
  2. 发现端口必须一致:所有 Ignite Pod 必须使用相同的 discovery 端口(默认 47500),否则无法互相发现。若通过 setDiscoveryPort 自定义端口,需保证所有节点一致。
  3. 标签与服务选择器严格对应:Service 的 selector 与 Pod 的 labels、ServiceAccount 的绑定关系必须正确,任一环节不匹配都会导致 Endpoints 为空、集群无法形成。
  4. RBAC 权限最小化:Role 只需授予 endpoints 资源的 get/list/watch 权限即可满足寻址需求。
  5. 客户端同样需要容器化:作为网关的 Ignite 客户端节点也必须运行在 Kubernetes 内(厚客户端场景);对于 thin client,模块还提供了 ThinClientKubernetesAddressFinder.java,基于同一套 KubernetesServiceAddressResolver 解析服务端节点地址,并默认使用 ClientConnectorConfiguration.DFLT_PORT(10800)作为连接端口。
登录后查看全文
ignite