Edu/Support

쿠버네티스 환경에서 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(노트북) 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. 컨테이너 기동 시 스프링 부트 앱 실행
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(노트북) dir 예)
① app\IntelliJ\workspace\KubeRedisClusterApp\build\libs\KubeRedisClusterApp-0.0.1-SNAPSHOT.jar
② app\IntelliJ\workspace\KubeRedisClusterApp\Dockerfile
3) 도커 이미지 빌드 (서버에서 작업)
[~/kube/app/cluster/] $ docker build -t spring-redis-cluster-app:1.0 .
4) 생성된 도커 이미지를 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    # 📍 외부(웹 브라우저/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 파드 생성했으니 Failover(장애 조치) 테스트하러 갑시다.

<< K8s Redis-Cluster 테스트 ③	K8s Redis-Cluster App ② >>

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