Edu/Support

쿠버네티스 환경에서 Redis-Sentinel Java App 구축 ①

개요

Redis-Sentinel 용 Java(Spring) App

Kubernetes pod 환경에서 구축한 Redis-Sentinel 용 Java App를 작성해서 테스트한다.

Java 21
Spring Boot 3.4.3
Redis 8.8.2 🔗 Redis-Sentinel은 여기서 구축한 것을 이용한다.
PC(노트북) IntelliJ에서 Java(Spring) app 개발
서버: Linux(Rocky9.6), Redis-Sentinel 실행 중임

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.0 ➡📍IntelliJ build.gradle 파일에서 3.4.3으로 변경합니다.
Project Metadata
- Group: com.redisgate
- Artifact: KubeRedis -> Project 명칭, 이 이름으로 압축파일이 생긴다.
- Package name: com.redisgate.KubeRedis -> 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 파일

'org.springframework.boot' version '4.1.0' -> '3.4.3' 수정
'webmvc' -> 'web' 2곳 수정
아래 2개 라이브러리 추가
implementation 'org.springframework.retry:spring-retry' // Spring Retry 라이브러리를 추가
implementation 'org.springframework:spring-aspects' // AOP 지원
화면 오른쪽 상단 '코끼리(Gradle)' 아이콘 클릭 -> 메뉴 중 첫 번째 '모든 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 파일

# 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 파일

'spring.data.redis.sentinel.nodes'에 아래와 같이 'sentinel-0부터 2까지 모두 기록하세요. spring.application.name=KubeRedis # 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 Sentinel Config 📍 spring.data.redis.sentinel.nodes=sentinel-0.sentinel-service.default.svc.cluster.local:28504,\ sentinel-1.sentinel-service.default.svc.cluster.local:28504,\ sentinel-2.sentinel-service.default.svc.cluster.local:28504 spring.data.redis.sentinel.master=mymaster spring.data.redis.database=0 # 👨‍💻 password, clientName: Set it up according to the project. spring.data.redis.sentinel.password=redisgate spring.data.redis.password=redisgate spring.data.redis.clientName=redisgate # 🔗 ref: https://redisgate.kr/redis/clients/springboot_readfrom.php # Recommended: replicaPreferred -> (1) Replica -> (2) Master spring.data.redis.readFrom=replicaPreferred # 📝 NOTE: The 'connect-timeout' and 'timeout' configurations are explicitly # defined in RedisSentinelConfig.java via LettuceClientConfigurationBuilderCustomizer. # To change these timeout values, please update RedisSentinelConfig.java directly. #spring.data.redis.connect-timeout=1s ➡ 프로그램에서 설정합니다. #spring.data.redis.timeout=1s ➡ 프로그램에서 설정합니다.

💾 KubeRedisApplication.java 파일

package com.redisgate.KubeRedis; 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 KubeRedisApplication { public static void main(String[] args) { SpringApplication.run(KubeRedisApplication.class, args); log.info("----- 쿠버네티스 Redis Spring(Spring Boot 3.4.3)/Lettuce, Java 21 App ------"); } }

💾 RedisSentinelConfig.java 파일

주요 설정에 📍 표시했음(주석 참조) package com.redisgate.KubeRedis; import io.lettuce.core.ClientOptions; import io.lettuce.core.SocketOptions; import io.lettuce.core.TimeoutOptions; 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 RedisSentinelConfig { @Bean public LettuceClientConfigurationBuilderCustomizer lettuceCustomizer() { return builder -> builder // 1. 커맨드 타임아웃을 1초로 제한 (failover 동안 무한 대기 방지) .commandTimeout(Duration.ofSeconds(1)) ✅ // 2. Lettuce 클라이언트 세부 옵션 지정 .clientOptions(ClientOptions.builder() // Replica(Readonly) 상태의 옛 마스터로 명령 전송 시 예외 즉시 처리 옵션 .disconnectedBehavior(ClientOptions.DisconnectedBehavior.REJECT_COMMANDS) // 명령 응답 타임아웃 강제 지정 .timeoutOptions(TimeoutOptions.enabled(Duration.ofSeconds(1))) ✅ // 소켓 접속 타임아웃 1초 지정 .socketOptions(SocketOptions.builder() .connectTimeout(Duration.ofSeconds(1)) 📍 .build()) .build()); } }

✅ 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 파일

package com.redisgate.KubeRedis; 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 파일

package com.redisgate.KubeRedis; 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 [KubeRedis]> ./gradlew clean bootJar
2) 'KubeRedis-0.0.1-SNAPSHOT.jar', 'Dockerfile': 2개 파일을 서버(~/kube/app/sentinel/)로 전송한다.
app\IntelliJ\workspace\KubeRedis\build\libs\KubeRedis-0.0.1-SNAPSHOT.jar
app\IntelliJ\workspace\KubeRedis\Dockerfile
3) 도커 이미지 빌드 (서버에서 작업)
[~/kube/app/sentinel/] $ docker build -t spring-redis-sentinel-app:1.0 .
4) 생성된 도커 이미지를 k3s 내부(containerd)로 직접 임포트
[~/kube/app/sentinel/] $ docker save spring-redis-sentinel-app:1.0 | sudo k3s ctr images import -

💾 app-deployment.yaml 파일

서버 "~/kube/app/sentinel" dir에 작성 1 apiVersion: apps/v1 2 kind: Deployment 3 metadata: 4 name: spring-redis-sentinel-app 5 spec: 6 replicas: 1 7 selector: 8 matchLabels: 9 app: spring-redis-sentinel-app 10 template: 11 metadata: 12 labels: 13 app: spring-redis-sentinel-app 14 spec: 15 containers: 16 - name: spring-app 17 image: spring-redis-sentinel-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-sentinel-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-sentinel-app

➡ 이제 Java App 파드 생성했으니 Failover(장애 조치) 테스트하러 갑시다.

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

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