Redis-Cluster Java App on Kubernetes ①

Overview

Java (Spring) App for Redis-Cluster

We write and test a Java (Spring) App for the Redis-Cluster built as Kubernetes Pods.

Java 21
Spring Boot 3.4.3
Redis 8.8.2 🔗 Use the Redis-Cluster built here.
Develop the Java (Spring) app in IntelliJ on a PC (laptop)
Server: Linux (Rocky 9.6), Redis-Cluster already running

Java Spring Project

Create a Java Spring Project

Create a Java Spring Project and write the application.
URL to create a Java Spring Project with Spring Initializr: start.spring.io

Project: Gradle-Groovy
Language: Java
Spring Boot: 4.1.1 ➡📍Change it to 3.4.3 in IntelliJ build.gradle.
Project Metadata
- Group: com.redisgate
- Artifact: KubeRedisClusterApp -> project name; the zip file is named this way.
- Package name: com.redisgate.KubeRedisClusterApp -> Package Name
- Packaging: Jar
- Configuration: Properties
- Java: 21 -> choose the Java version
In Dependencies, click [ADD … CTRL + B] and add the three items below.
- Spring Web
- Lombok
- Spring Data Redis(Access+Driver)
Finally click [GENERATE CTRL + ⏎ ] and download the zip file.

💾 build.gradle file

Path: workspace\KubeRedisClusterAsync\build.gradle
'org.springframework.boot' version '4.1.0' -> change to '3.4.3'
Change 'webmvc' -> 'web' in two places. Lowering to '3.4.3' makes 'webmvc' error, so it must be 'web'
Add the two libraries below
implementation 'org.springframework.retry:spring-retry' // Add the Spring Retry library
implementation 'org.springframework:spring-aspects' // AOP support
In IntelliJ, click the elephant (Gradle) icon at the top right -> click the refresh icon 'Reload All Gradle Projects'
Wait until the build finishes in the status bar

📄 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' // Add the Spring Retry library 📍
	implementation 'org.springframework:spring-aspects' // AOP support 📍
	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 file

• Path: workspace\KubeRedisClusterAsync\Dockerfile

📄 Dockerfile

# 1. Set the Java 21 runtime (lightweight Alpine Linux)
FROM eclipse-temurin:21-jre-alpine
# 2. Set the working directory inside the container (created automatically)
WORKDIR /app
# 3. Copy the built JAR into the container as a consistent name, app.jar
COPY *.jar app.jar
# 4. Start the Spring Boot app when the container starts
ENTRYPOINT ["java", "-jar", "app.jar"]

💾 application.properties file

• Path: workspace\KubeRedisClusterAsync\src\main\resources\application.properties
• In 'spring.data.redis.cluster.nodes', list redis-cluster-0 through 5 as shown below.

📄 application.properties

spring.application.name=KubeRedisClusterApp
# JVM Heap / CPU memory note: each thread gets about 1MB of stack (`-Xss`).
# With 'threads.max=600', threads alone need about 600MB,
# so give the K8s Pod a generous memory Limit (e.g. `2Gi`+) and CPU Request.
# Tomcat max worker threads (500~800)
server.tomcat.threads.max=600
# Queue size when max threads are exceeded
server.tomcat.accept-count=1000
# Max concurrent accepted socket connections
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 file

📄 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 // 📍 scheduler must be enabled
@EnableRetry // 📍 enable Spring Retry
@Slf4j
public class KubeRedisClusterAppApplication {
	public static void main(String[] args) {
		SpringApplication.run(KubeRedisClusterAppApplication.class, args);
		log.info("----- Kubernetes Redis-Cluster App (Spring Boot 3.4.3 / Lettuce, Java 21) ------");
	}
}

💾 RedisClusterConfig.java file

Key settings are marked 📍 (see comments)

📄 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. Cluster topology auto-refresh options
            ClusterTopologyRefreshOptions refreshOptions = ClusterTopologyRefreshOptions.builder()
                    // Periodically query CLUSTER NODES to refresh slot-node mapping
                    .enablePeriodicRefresh(Duration.ofSeconds(1)) 📍
                    // On MOVED, ASK, PERSISTENT_RECONNECTS, refresh topology immediately instead of waiting 60s
                    // -> prepare for node down, slot moves (rebalancing), etc.
                    .enableAllAdaptiveRefreshTriggers() 📍
                    // Max timeout 1s on adaptive refresh events -> do not collect on every event;
                    // collect (cluster nodes) every 1s: cooldown (throttling) / wait time
                    .adaptiveRefreshTriggersTimeout(Duration.ofSeconds(1)) 📍
                    .build();

            // 2. Cluster-only Options
            ClusterClientOptions clusterClientOptions = ClusterClientOptions.builder()
                    .topologyRefreshOptions(refreshOptions)
                    // Reject commands when disconnected -> do not keep sending to the old IP of a restarted node
                    // -> in Kubernetes the IP changes on restart, so you must not keep sending
                    //    commands to the old node IP
                    .disconnectedBehavior(ClientOptions.DisconnectedBehavior.REJECT_COMMANDS)
                    .timeoutOptions(TimeoutOptions.enabled(Duration.ofSeconds(1))) ✅ 
                    .socketOptions(SocketOptions.builder()
                            .connectTimeout(Duration.ofSeconds(1)) 📍
                            .build())
                    .build();

            // 3. Apply to the Lettuce Builder
            builder.commandTimeout(Duration.ofSeconds(1)) ✅
                    .clientOptions(clusterClientOptions);
        };
    }
}

✅ How do commandTimeout() and timeoutOptions() differ?

1. Spring setting: commandTimeout(Duration.ofSeconds(1))
- Where it applies: `LettuceClientConfigurationBuilder` (upper Spring Data Redis setting)
- Role: the default synchronous command-execution timeout used when Spring Data Redis sends commands through the Lettuce client.
- Behavior: with `RedisTemplate` or `StringRedisTemplate`, if Redis does not respond within 1 second, it throws `QueryTimeoutException` or `RedisCommandTimeoutException`.
- Notes: the standard default. If no special TimeoutOptions are defined, Lettuce uses this value internally as the default timeout and cancels the command.
2. Lettuce setting: timeoutOptions(TimeoutOptions.enabled(Duration.ofSeconds(1)))
- Where it applies: `ClientOptions` (native Lettuce driver option)
- Role: fine-grained control of each command's lifecycle and timeout strategy at the Lettuce engine level.
- Behavior: inside Lettuce's async/reactive pipeline, if a command is sent and there is no result for 1 second or the network delays the response, a custom timeout scheduler cancels the command.
- Notes:
  - Tighter failure control: combined with `disconnectedBehavior(REJECT_COMMANDS)`, commands waiting in the queue while disconnected or reconnecting are not stuck forever; they are cancelled after 1 second.
  - Dynamic timeout: `TimeoutOptions` supports not only a single `Duration` but also a `TimeoutSource` that can vary timeout by command type (READ/WRITE) or situation. (e.g. `GET` 500ms, `FLUSHALL` 5s)

💾 RedisOperationService.java file

📄 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;

    // 📍 On failure, retry up to 5 times at 1-second intervals 
    @Retryable(
            retryFor = { Exception.class },
            maxAttempts = 5,
            backoff = @Backoff(delay = 1000)
    )
    public String executeSetAndGet(String key, String value) {
        // 1. Redis SET
        redisTemplate.opsForValue().set(key, value);
        // 2. Redis GET
        return redisTemplate.opsForValue().get(key);
    }
}

💾 RedisFailoverTestService.java file

📄 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; // 📍 inject retry service
    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 {
            // 📍 call the method that includes retry logic
            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) {
            // 📍 error log only if it still fails after 5 retries (5 seconds)
            log.error(" [FAIL] Key: {} -> Error after retries: {}", key, e.getMessage());
        }
    }
}

App Docker image build, YAML files

Build the App Docker image

1) Compile (make)
IntelliJ [KubeRedisClusterApp]> ./gradlew clean bootJar
2) Copy the two files 'KubeRedisClusterApp-0.0.1-SNAPSHOT.jar' and 'Dockerfile' to the server (~/kube/app/cluster/).
Example dirs on the local PC (laptop)
① app\IntelliJ\workspace\KubeRedisClusterApp\build\libs\KubeRedisClusterApp-0.0.1-SNAPSHOT.jar
② app\IntelliJ\workspace\KubeRedisClusterApp\Dockerfile
3) Build the Docker image (on the server)
[~/kube/app/cluster/] $ docker build -t spring-redis-cluster-app:1.0 .
4) Import the built Docker image into k3s (containerd) directly
[~/kube/app/cluster/] $ docker save spring-redis-cluster-app:1.0 | sudo k3s ctr images import -

💾 app-deployment.yaml file

Write it in the server "~/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   # 📍 Prefer the image loaded into local k3s
 19	        ports:
 20	        - containerPort: 8080
 21	        env:
 22	        - name: TZ
 23	          value: Asia/Seoul             # 📍 timezone env var
 24	        volumeMounts:
 25	        - name: host-time
 26	          mountPath: /etc/localtime     # 📍 Mount Host OS time config file
 27	          readOnly: true
 28	      volumes:
 29	      - name: host-time
 30	        hostPath:
 31	          path: /etc/localtime          # 📍 Host OS /etc/localtime path
 32	---
 33	apiVersion: v1
 34	kind: Service
 35	metadata:
 36	  name: spring-redis-cluster-app-service
 37	spec:
 38	  type: NodePort    # 📍 For test access from outside (browser/Postman)
 39	  ports:
 40	  - port: 8080
 41	    targetPort: 8080
 42	    nodePort: 30080   # Reachable as Rocky9 IP:30080
 43	  selector:
 44	    app: spring-redis-cluster-app

➡ The Java App Pod is ready. Let’s run the failover test.

<< K8s Redis-Cluster Test ③	K8s Redis-Cluster App ② >>

Email 답글이 올라오면 이메일로 알려드리겠습니다.