Edu/Support

オンライン定期点検
サービス開始

クバネティス(Kubernetes) 環境で Redis-Cluster Java App 構築 ①

概要

Redis-Cluster 用 Java(Spring) App

クバネティス(Kubernetes) ポッド(Pod) 環境で構築した Redis-Cluster 用 Java(Spring) App を書いてテストします。

Java 21
Spring Boot 3.4.3
Redis 8.8.2 🔗 Redis-Cluster はここで構築したものを使います。
PC(ノートPC) IntelliJ で Java(Spring) app 開発
サーバ: Linux(Rocky9.6)、Redis-Cluster 実行中

Java Spring Project

Java Spring Project 生成

Java Spring Project を生成してアプリケーションを書いてみます。
Spring initializr を使って Java Spring Project を生成する URL: start.spring.io

Project: Gradle-Groovy
Language: Java
Spring Boot: 4.1.1 ➡📍IntelliJ の build.gradle ファイルで 3.4.3 に変更します。
Project Metadata
- Group: com.redisgate
- Artifact: KubeRedisClusterApp -> Project 名称。この名前で圧縮ファイルができます。
- Package name: com.redisgate.KubeRedisClusterApp -> Package Name
- Packaging: Jar
- Configuration: Properties
- Java: 21 -> Java バージョン選択
Dependencies で [ADD … CTRL + B] ボタンをクリックして、次の3つを追加します。
- Spring Web
- Lombok
- Spring Data Redis(Access+Driver)
最後に [GENERATE CTRL + ⏎ ] ボタンをクリックして圧縮ファイル(zip)をダウンロードします。

💾 build.gradle ファイル

位置: workspace\KubeRedisClusterAsync\build.gradle
'org.springframework.boot' version '4.1.0' -> '3.4.3' に修正
'webmvc' -> 'web' を2箇所修正 -> '3.4.3' に下げると 'webmvc' でエラーになるので 'web' に直します
次の2つのライブラリを追加
implementation 'org.springframework.retry:spring-retry' // Spring Retry ライブラリを追加
implementation 'org.springframework:spring-aspects' // AOP サポート
IntelliJ 画面右上の 'ゾウ(Gradle)' アイコンをクリック -> メニューの '再読み込み' アイコン 'すべての Gradle プロジェクトを再ロード(Reload All Gradle Projects)' をクリック
下のステータスバーでビルドが終わるまで待ちます

📄 build.gradle

plugins {
	id 'java'
	id 'org.springframework.boot' version '3.4.3' 📍
	id 'io.spring.dependency-management' version '1.1.7'
}
group = 'com.redisgate'
version = '0.0.1-SNAPSHOT'
java {
	toolchain {
		languageVersion = JavaLanguageVersion.of(21) 
	}
}
repositories {
	mavenCentral()
}
dependencies {
	implementation 'org.springframework.retry:spring-retry' // Spring Retry ライブラリを追加 📍
	implementation 'org.springframework:spring-aspects' // AOPサポート 📍
	implementation 'org.springframework.boot:spring-boot-starter-data-redis'
	implementation 'org.springframework.boot:spring-boot-starter-web' 📍
	compileOnly 'org.projectlombok:lombok'
	annotationProcessor 'org.projectlombok:lombok'
	testImplementation 'org.springframework.boot:spring-boot-starter-data-redis-test'
	testImplementation 'org.springframework.boot:spring-boot-starter-web-test' 📍
	testCompileOnly 'org.projectlombok:lombok'
	testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
	testAnnotationProcessor 'org.projectlombok:lombok'
}
tasks.named('test') {
	useJUnitPlatform()
}

💾 Dockerfile ファイル

• 位置: workspace\KubeRedisClusterAsync\Dockerfile

📄 Dockerfile

# 1. Java 21 実行環境を指定 (軽量 Alpine Linux ベース)
FROM eclipse-temurin:21-jre-alpine
# 2. コンテナ内部の作業ディレクトリを設定 (自動作成される)
WORKDIR /app
# 3. ビルドした JAR ファイルを app.jar という一貫した名前でコンテナ内部にコピー
COPY *.jar app.jar
# 4. コンテナ起動時に Spring Boot アプリを実行
ENTRYPOINT ["java", "-jar", "app.jar"]

💾 application.properties ファイル

• 位置: workspace\KubeRedisClusterAsync\src\main\resources\application.properties
• 'spring.data.redis.cluster.nodes' に、次のように redis-cluster-0 から 5 まですべて書いてください。

📄 application.properties

spring.application.name=KubeRedisClusterApp
# JVM Heap / CPU メモリ注意: スレッドが1つ生成されるたびに約1MBの Stack メモリ(`-Xss`)が割り当てられます。
# 'threads.max=600' 設定時、スレッドだけで約600MBのメモリが必要なため、
# K8s Pod メモリ Limit(例: `2Gi` 以上) および CPU Request を余裕をもって割り当てる必要があります。
# Tomcat 最大ワーカースレッド数 (500~800)
server.tomcat.threads.max=600
# 最大スレッド超過時に待機できる作業キューサイズ
server.tomcat.accept-count=1000
# 同時に受け入れ可能な最大ソケット接続数
server.tomcat.max-connections=8192

# Redis Cluster Config 📍
spring.data.redis.cluster.nodes=redis-cluster-0.redis-cluster-service.default.svc.cluster.local:18504,\
  redis-cluster-1.redis-cluster-service.default.svc.cluster.local:18504,\
  redis-cluster-2.redis-cluster-service.default.svc.cluster.local:18504,\
  redis-cluster-3.redis-cluster-service.default.svc.cluster.local:18504,\
  redis-cluster-4.redis-cluster-service.default.svc.cluster.local:18504,\
  redis-cluster-5.redis-cluster-service.default.svc.cluster.local:18504
spring.data.redis.database=0
# 👨‍💻 password, clientName: Set it up according to the project.
spring.data.redis.password=redisgate
spring.data.redis.clientName=redisgate
# 🔗 ref: https://redisgate.kr/redis/clients/springboot_readfrom.php
# Recommended: replicaPreferred: first Replica -> Second Master
spring.data.redis.readFrom=replicaPreferred
# 📝 NOTE: The 'connect-timeout' and 'timeout' configurations are explicitly
# defined in RedisClusterConfig.java via LettuceClientConfigurationBuilderCustomizer.
# To change these timeout values, please update RedisClusterConfig.java directly.

💾 KubeRedisClusterAppApplication.java ファイル

📄 KubeRedisClusterAppApplication.java

package com.redisgate.KubeRedisClusterApp;

import lombok.extern.slf4j.Slf4j;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.scheduling.annotation.EnableScheduling;
import org.springframework.retry.annotation.EnableRetry;

@SpringBootApplication
@EnableScheduling // 📍 スケジューラ有効化は必須
@EnableRetry // 📍 Spring Retry 機能を有効化
@Slf4j
public class KubeRedisClusterAppApplication {
	public static void main(String[] args) {
		SpringApplication.run(KubeRedisClusterAppApplication.class, args);
		log.info("----- クバネティス Redis-Cluster App(Spring Boot 3.4.3 / Lettuce, Java 21) ------");
	}
}

💾 RedisClusterConfig.java ファイル

主な設定に 📍 を付けました(コメント参照)

📄 RedisClusterConfig.java

package com.redisgate.KubeRedisClusterApp;

import io.lettuce.core.ClientOptions;
import io.lettuce.core.SocketOptions;
import io.lettuce.core.TimeoutOptions;
import io.lettuce.core.cluster.ClusterClientOptions;
import io.lettuce.core.cluster.ClusterTopologyRefreshOptions;
import org.springframework.boot.autoconfigure.data.redis.LettuceClientConfigurationBuilderCustomizer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import java.time.Duration;

@Configuration
public class RedisClusterConfig {

    @Bean
    public LettuceClientConfigurationBuilderCustomizer lettuceCustomizer() {
        return builder -> {
            // 1. クラスタトポロジ自動更新(Refresh)オプション設定
            ClusterTopologyRefreshOptions refreshOptions = ClusterTopologyRefreshOptions.builder()
                    // 定期的に CLUSTER NODES を照会してスロット-ノードマッピングを更新
                    .enablePeriodicRefresh(Duration.ofSeconds(1)) 📍
                    // MOVED、ASK、PERSISTENT_RECONNECTS などの障害発生時、60秒待たずに直ちにトポロジを更新
                    // -> ノードダウン、スロット移動(rebalancing)などに備える
                    .enableAllAdaptiveRefreshTriggers() 📍
                    // 適応型更新イベント発生時の最大タイムアウト1秒 -> イベント発生ごとに収集せず
                    // 1秒間隔で (cluster nodes) を収集: クールタイム(Throttling) または待機時間
                    .adaptiveRefreshTriggersTimeout(Duration.ofSeconds(1)) 📍
                    .build();

            // 2. Cluster 専用 Options の構成
            ClusterClientOptions clusterClientOptions = ClusterClientOptions.builder()
                    .topologyRefreshOptions(refreshOptions)
                    // 接続切断時にコマンド拒否を設定 -> コマンドを再起動したノード(既存IP)へ送り続けないように
                    // -> クバネティス環境ではノードが再起動するとIPが変わるため、既存ノードIPへコマンドを
                    //    送り続けてはいけない
                    .disconnectedBehavior(ClientOptions.DisconnectedBehavior.REJECT_COMMANDS)
                    .timeoutOptions(TimeoutOptions.enabled(Duration.ofSeconds(1))) ✅ 
                    .socketOptions(SocketOptions.builder()
                            .connectTimeout(Duration.ofSeconds(1)) 📍
                            .build())
                    .build();

            // 3. Lettuce Builder に反映
            builder.commandTimeout(Duration.ofSeconds(1)) ✅
                    .clientOptions(clusterClientOptions);
        };
    }
}

✅ commandTimeout() と timeoutOptions() は何が違うか？

1. Spring 設定: commandTimeout(Duration.ofSeconds(1))
- 適用位置: `LettuceClientConfigurationBuilder` (Spring Data Redis の上位設定)
- 主な役割: Spring Data Redis が Lettuce クライアント経由でコマンドを送るときに使う基本の同期コマンド実行タイムアウトです。
- 動作方式: `RedisTemplate` や `StringRedisTemplate` を使うとき、Redis サーバから 1秒以内に応答(Response)が来なければ `QueryTimeoutException` または `RedisCommandTimeoutException` を発生させます。
- 特徴: 最も標準的な基本設定値で、特別な TimeoutOptions が定義されていなければ Lettuce が内部でこの値を基本タイムアウトとして使い、コマンドをキャンセルします。
2. Lettuce 設定: timeoutOptions(TimeoutOptions.enabled(Duration.ofSeconds(1)))
- 適用位置: `ClientOptions` (Lettuce ドライバ自身の Native オプション)
- 主な役割: Lettuce 内部エンジンレベルで各コマンドのライフサイクル(Lifecycle)とタイムアウト処理戦略を精密に制御します。
- 動作方式: Lettuce の非同期/リアクティブ(Reactive)パイプライン内部でコマンド(Command)が送られた後、1秒間結果応答がない、またはネットワーク遅延で応答を受け取れないと、そのコマンドのカスタムタイムアウトスケジューラが介入してコマンドを強制キャンセル(Cancel)します。
- 特徴:
  - より精密な失敗制御: `disconnectedBehavior(REJECT_COMMANDS)` オプションと組み合わせると、サーバとの接続が切れた、または再接続(Reconnect)中にキュー(Queue)で待っているコマンドが無限に閉じ込められず、1秒で即座にキャンセルされるよう強く強制します。
  - 動的タイムアウト(Dynamic Timeout)可能: `TimeoutOptions` は単一の `Duration` だけでなく、コマンド種類(READ/WRITE)や状況に応じてタイムアウトを変えられる `TimeoutSource` をサポートします。 (例: `GET` は 500ms、`FLUSHALL` は 5s など)

💾 RedisOperationService.java ファイル

📄 RedisOperationService.java

package com.redisgate.KubeRedisClusterApp;

import lombok.RequiredArgsConstructor;
import org.springframework.data.redis.core.StringRedisTemplate;
import org.springframework.retry.annotation.Backoff;
import org.springframework.retry.annotation.Retryable;
import org.springframework.stereotype.Service;

@Service
@RequiredArgsConstructor
public class RedisOperationService {

    private final StringRedisTemplate redisTemplate;

    // 📍 障害発生時、1秒間隔で最大5回再試行 
    @Retryable(
            retryFor = { Exception.class },
            maxAttempts = 5,
            backoff = @Backoff(delay = 1000)
    )
    public String executeSetAndGet(String key, String value) {
        // 1. Redis 保存
        redisTemplate.opsForValue().set(key, value);
        // 2. Redis 照会
        return redisTemplate.opsForValue().get(key);
    }
}

💾 RedisFailoverTestService.java ファイル

📄 RedisFailoverTestService.java

package com.redisgate.KubeRedisClusterApp;

import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.data.redis.core.StringRedisTemplate;
import org.springframework.scheduling.annotation.Scheduled;
import org.springframework.stereotype.Service;

import java.util.concurrent.atomic.AtomicLong;

@Service
@RequiredArgsConstructor
@Slf4j
public class RedisFailoverTestService {
    private final RedisOperationService redisOperationService; // 📍 再試行サービスを注入
    private final AtomicLong counter = new AtomicLong(1);

    @Scheduled(fixedRate = 100)
    public void runFailoverTest() {
        long seq = counter.getAndIncrement();
        String key = String.format("keyA-%08d", seq);
        String value = String.format("valueA-%08d", seq);

        try {
            // 📍 再試行ロジックを含むメソッドを呼び出し
            String retrievedValue = redisOperationService.executeSetAndGet(key, value);

            if (value.equals(retrievedValue)) {
                if (seq % 10 == 0) {
                    log.info(" [SUCCESS] Key: {} -> Normal operation in progress...", key);
                }
            } else {
                log.warn(" [MISMATCH ERROR] Key: {}, Expected: {}, Got: {}", key, value, retrievedValue);
            }

        } catch (Exception e) {
            // 📍 5回再試行(5秒)後も最後まで失敗した場合のみエラーログを出す
            log.error(" [FAIL] Key: {} -> Error after retries: {}", key, e.getMessage());
        }
    }
}

App Docker イメージビルド、YAML ファイル

App Docker イメージビルド

1) コンパイル(make)
IntelliJ [KubeRedisClusterApp]> ./gradlew clean bootJar
2) 'KubeRedisClusterApp-0.0.1-SNAPSHOT.jar', 'Dockerfile': 2ファイルをサーバ(~/kube/app/cluster/)へ送ります。
Local PC(ノートPC) dir 例)
① app\IntelliJ\workspace\KubeRedisClusterApp\build\libs\KubeRedisClusterApp-0.0.1-SNAPSHOT.jar
② app\IntelliJ\workspace\KubeRedisClusterApp\Dockerfile
3) Docker イメージビルド (サーバで作業)
[~/kube/app/cluster/] $ docker build -t spring-redis-cluster-app:1.0 .
4) 生成した Docker イメージを k3s 内部(containerd)へ直接インポート
[~/kube/app/cluster/] $ docker save spring-redis-cluster-app:1.0 | sudo k3s ctr images import -

💾 app-deployment.yaml ファイル

サーバ "~/kube/app/cluster/" dir に作成

📄 app-deployment.yaml

  1	apiVersion: apps/v1
  2	kind: Deployment
  3	metadata:
  4	  name: spring-redis-cluster-app
  5	spec:
  6	  replicas: 1
  7	  selector:
  8	    matchLabels:
  9	      app: spring-redis-cluster-app
 10	  template:
 11	    metadata:
 12	      labels:
 13	        app: spring-redis-cluster-app
 14	    spec:
 15	      containers:
 16	      - name: spring-app
 17	        image: spring-redis-cluster-app:1.0
 18	        imagePullPolicy: IfNotPresent   # 📍 ローカル k3s に載せたイメージを優先使用
 19	        ports:
 20	        - containerPort: 8080
 21	        env:
 22	        - name: TZ
 23	          value: Asia/Seoul             # 📍 タイムゾーン環境変数を設定
 24	        volumeMounts:
 25	        - name: host-time
 26	          mountPath: /etc/localtime     # 📍 Host OS の時刻設定ファイルをマウント
 27	          readOnly: true
 28	      volumes:
 29	      - name: host-time
 30	        hostPath:
 31	          path: /etc/localtime          # 📍 Host OS の /etc/localtime パスを指定
 32	---
 33	apiVersion: v1
 34	kind: Service
 35	metadata:
 36	  name: spring-redis-cluster-app-service
 37	spec:
 38	  type: NodePort    # 📍 外部(Webブラウザ/Postman)からのテストアクセス用
 39	  ports:
 40	  - port: 8080
 41	    targetPort: 8080
 42	    nodePort: 30080   # Rocky9 IP:30080 でアクセス可能
 43	  selector:
 44	    app: spring-redis-cluster-app

➡ Java App ポッド(Pod) を生成したので、Failover(障害対応)テストに行きましょう。

<< K8s Redis-Cluster テスト ③	K8s Redis-Cluster App ② >>

Email 返事がかかってなれば、メールでお知らせします。