Apache Ignite Kubernetes 模块构建与 IP Finder 端到端测试实战指南
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 的指引,完整的测试链路要求具备:
- 一个可用的 Apache Ignite 二进制发行包(zip 格式,构建方法见下文);
- 本地开发环境中的 Docker 与 Minikube;
- 用于本地联调的 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 完成,其工作流程可概括为四个步骤:
- 初始化连接:
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保护,保证并发下只初始化一次。 - 鉴权请求:通过
HttpsURLConnection发起 GET 请求,请求头携带Authorization: Bearer <token>;token 由serviceAccountToken()从默认路径/var/run/secrets/kubernetes.io/serviceaccount/token(ServiceAccount 自动挂载)读取。 - 解析响应:使用 Jackson
ObjectMapper将 API Server 返回的 Endpoints JSON 反序列化为Endpoints -> Subset -> Address结构,遍历每个 subset 的addresses;若开启了includeNotReadyAddresses,还会合并notReadyAddresses中的地址。其中Address只关心ip字段,其余字段通过@JsonIgnoreProperties(ignoreUnknown = true)忽略。 - 返回地址集合:最终通过
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 时需注意以下边界:
- 仅适用于 Kubernetes 环境:IP finder 依赖 Kubernetes API 与 ServiceAccount 机制,脱离集群(如本地直连)无法工作;本地测试请改用其他 IP finder 实现。
- 发现端口必须一致:所有 Ignite Pod 必须使用相同的 discovery 端口(默认 47500),否则无法互相发现。若通过
setDiscoveryPort自定义端口,需保证所有节点一致。 - 标签与服务选择器严格对应:Service 的
selector与 Pod 的labels、ServiceAccount 的绑定关系必须正确,任一环节不匹配都会导致 Endpoints 为空、集群无法形成。 - RBAC 权限最小化:Role 只需授予
endpoints资源的get/list/watch权限即可满足寻址需求。 - 客户端同样需要容器化:作为网关的 Ignite 客户端节点也必须运行在 Kubernetes 内(厚客户端场景);对于 thin client,模块还提供了 ThinClientKubernetesAddressFinder.java,基于同一套
KubernetesServiceAddressResolver解析服务端节点地址,并默认使用ClientConnectorConfiguration.DFLT_PORT(10800)作为连接端口。