서킷 브레이커와 복원력 패턴 실전 가이드 — Resilience4j, Istio, 장애 격리 전략

              실패율 >= 임계값 (failureRateThreshold)
    ┌─────────────────────────────────────────────┐
    │                                             │
    ▼                                             │
┌──────────┐                                 ┌──────────┐
│          │     시험 호출 성공률 >= 임계값     │          │
│   OPEN   │ <─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ── │  CLOSED  │
│  (차단)   │                                 │  (정상)   │
└──────────┘                                 └──────────┘
     │                                            ▲
     │ waitDurationInOpenState 경과                │
     ▼                                            │
┌──────────────┐    시험 호출 성공               │
│  HALF-OPEN   │ ────────────────────────────────┘
│  (시험 허용)  │
└──────────────┘
     │
     │ 시험 호출 실패
     ▼
┌──────────┐
│   OPEN   │  (다시 차단)
└──────────┘

// build.gradle (Spring Boot 3.x)
dependencies {
    implementation 'io.github.resilience4j:resilience4j-spring-boot3:2.2.0'
    implementation 'io.github.resilience4j:resilience4j-micrometer:2.2.0'
    implementation 'org.springframework.boot:spring-boot-starter-actuator'
    implementation 'org.springframework.boot:spring-boot-starter-aop'
}

resilience4j:
  circuitbreaker:
    instances:
      paymentService:
        registerHealthIndicator: true
        slidingWindowType: COUNT_BASED
        slidingWindowSize: 10
        minimumNumberOfCalls: 5
        failureRateThreshold: 50
        waitDurationInOpenState: 10s
        permittedNumberOfCallsInHalfOpenState: 3
        slowCallDurationThreshold: 2s
        slowCallRateThreshold: 80
        recordExceptions:
          - java.io.IOException
          - java.util.concurrent.TimeoutException
          - org.springframework.web.client.HttpServerErrorException
        ignoreExceptions:
          - com.example.BusinessException

  retry:
    instances:
      paymentService:
        maxAttempts: 3
        waitDuration: 500ms
        enableExponentialBackoff: true
        exponentialBackoffMultiplier: 2
        retryExceptions:
          - java.io.IOException
          - java.util.concurrent.TimeoutException

  bulkhead:
    instances:
      paymentService:
        maxConcurrentCalls: 20
        maxWaitDuration: 500ms

  timelimiter:
    instances:
      paymentService:
        timeoutDuration: 3s
        cancelRunningFuture: true

  ratelimiter:
    instances:
      paymentService:
        limitRefreshPeriod: 1s
        limitForPeriod: 50
        timeoutDuration: 0s

@Service
@Slf4j
public class PaymentService {

    private final PaymentGatewayClient paymentGatewayClient;
    private final PaymentCacheService paymentCacheService;

    public PaymentService(PaymentGatewayClient paymentGatewayClient,
                          PaymentCacheService paymentCacheService) {
        this.paymentGatewayClient = paymentGatewayClient;
        this.paymentCacheService = paymentCacheService;
    }

    @CircuitBreaker(name = "paymentService", fallbackMethod = "paymentFallback")
    @Bulkhead(name = "paymentService")
    @Retry(name = "paymentService")
    @TimeLimiter(name = "paymentService")
    public CompletableFuture<PaymentResponse> processPayment(PaymentRequest request) {
        return CompletableFuture.supplyAsync(() -> {
            log.info("결제 요청 처리 중: orderId={}", request.getOrderId());
            return paymentGatewayClient.charge(request);
        });
    }

    // 폴백 메서드: 서킷이 OPEN이거나 예외 발생 시 호출
    private CompletableFuture<PaymentResponse> paymentFallback(
            PaymentRequest request, Throwable throwable) {
        log.warn("결제 서비스 폴백 실행: orderId={}, reason={}",
                request.getOrderId(), throwable.getMessage());

        if (throwable instanceof CallNotPermittedException) {
            // 서킷이 열린 상태 - 큐에 저장 후 비동기 처리
            return CompletableFuture.completedFuture(
                PaymentResponse.queued(request.getOrderId(),
                    "결제 서비스 일시 장애. 주문이 대기열에 등록되었습니다.")
            );
        }

        // 기타 예외 - 캐시된 결과 반환 시도
        return CompletableFuture.completedFuture(
            paymentCacheService.getCachedResponse(request.getOrderId())
                .orElse(PaymentResponse.error(request.getOrderId(),
                    "결제 처리 중 오류가 발생했습니다. 잠시 후 다시 시도해주세요."))
        );
    }
}

Retry ( CircuitBreaker ( RateLimiter ( TimeLimiter ( Bulkhead ( Function ) ) ) ) )

apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: payment-service-circuit-breaker
  namespace: production
spec:
  host: payment-service.production.svc.cluster.local
  trafficPolicy:
    connectionPool:
      tcp:
        maxConnections: 100 # 최대 TCP 연결 수
        connectTimeout: 3s # TCP 연결 타임아웃
      http:
        h2UpgradePolicy: DEFAULT
        http1MaxPendingRequests: 50 # 대기 중인 HTTP 요청 최대 수
        http2MaxRequests: 100 # 활성 HTTP/2 요청 최대 수
        maxRequestsPerConnection: 10 # 연결당 최대 요청 수
        maxRetries: 3 # 최대 재시도 횟수
    outlierDetection:
      consecutive5xxErrors: 5 # 연속 5xx 에러 5회 시 제거
      interval: 10s # 분석 주기
      baseEjectionTime: 30s # 최소 제거 시간
      maxEjectionPercent: 50 # 최대 제거 비율 (50%)
      minHealthPercent: 30 # 최소 정상 인스턴스 비율

# ThreadPool Bulkhead 설정
resilience4j:
  thread-pool-bulkhead:
    instances:
      inventoryService:
        maxThreadPoolSize: 10
        coreThreadPoolSize: 5
        queueCapacity: 20
        keepAliveDuration: 100ms
        writableStackTraceEnabled: true

@Service
public class OrderOrchestrator {

    @Bulkhead(name = "paymentService", type = Bulkhead.Type.SEMAPHORE)
    public PaymentResult processPayment(Order order) {
        return paymentClient.charge(order.getPaymentInfo());
    }

    @Bulkhead(name = "inventoryService", type = Bulkhead.Type.THREADPOOL)
    public CompletableFuture<InventoryResult> reserveInventory(Order order) {
        return CompletableFuture.supplyAsync(() ->
            inventoryClient.reserve(order.getItems()));
    }

    @Bulkhead(name = "notificationService", type = Bulkhead.Type.SEMAPHORE)
    public void sendNotification(Order order) {
        notificationClient.send(order.getUserId(), "주문이 접수되었습니다.");
    }
}

@Configuration
public class ResilienceConfig {

    @Bean
    public Supplier<String> resilientSupplier(
            CircuitBreakerRegistry circuitBreakerRegistry,
            RetryRegistry retryRegistry,
            BulkheadRegistry bulkheadRegistry,
            RateLimiterRegistry rateLimiterRegistry) {

        CircuitBreaker circuitBreaker = circuitBreakerRegistry
                .circuitBreaker("externalApi");
        Retry retry = retryRegistry.retry("externalApi");
        Bulkhead bulkhead = bulkheadRegistry.bulkhead("externalApi");
        RateLimiter rateLimiter = rateLimiterRegistry
                .rateLimiter("externalApi");

        // 데코레이터 체이닝: 안쪽부터 바깥쪽으로 적용
        Supplier<String> decoratedSupplier = Decorators
                .ofSupplier(() -> externalApiClient.call())
                .withBulkhead(bulkhead)           // 1. 동시 호출 제한
                .withRateLimiter(rateLimiter)      // 2. 초당 호출 제한
                .withCircuitBreaker(circuitBreaker) // 3. 실패 감지/차단
                .withRetry(retry)                   // 4. 재시도
                .withFallback(Arrays.asList(
                    CallNotPermittedException.class,
                    BulkheadFullException.class,
                    RequestNotPermitted.class),
                    throwable -> "Fallback Response")
                .decorate();

        return decoratedSupplier;
    }
}

@Service
@Slf4j
public class ProductRecommendationService {

    private final RecommendationEngine primaryEngine;
    private final RecommendationEngine secondaryEngine;
    private final RedisTemplate<String, List<Product>> cache;

    @CircuitBreaker(name = "recommendation",
                    fallbackMethod = "secondaryRecommendation")
    public List<Product> getRecommendations(String userId) {
        return primaryEngine.recommend(userId);
    }

    // 1차 폴백: 보조 추천 엔진 사용
    private List<Product> secondaryRecommendation(
            String userId, Throwable t) {
        log.warn("1차 추천 엔진 장애, 보조 엔진으로 전환: {}", t.getMessage());
        try {
            return secondaryEngine.recommend(userId);
        } catch (Exception e) {
            return cachedRecommendation(userId, e);
        }
    }

    // 2차 폴백: 캐시된 추천 결과 반환
    private List<Product> cachedRecommendation(
            String userId, Throwable t) {
        log.warn("보조 추천 엔진도 장애, 캐시 조회: {}", t.getMessage());
        List<Product> cached = cache.opsForValue()
                .get("recommendation:" + userId);
        if (cached != null && !cached.isEmpty()) {
            return cached;
        }
        return defaultRecommendation(userId, t);
    }

    // 3차 폴백: 인기 상품 기본 목록 반환
    private List<Product> defaultRecommendation(
            String userId, Throwable t) {
        log.warn("캐시도 없음, 기본 인기 상품 반환");
        return List.of(
            Product.popular("BEST-001", "베스트셀러 상품 A"),
            Product.popular("BEST-002", "베스트셀러 상품 B"),
            Product.popular("BEST-003", "베스트셀러 상품 C")
        );
    }
}

// 제거
// implementation 'org.springframework.cloud:spring-cloud-starter-netflix-hystrix'

// 추가
implementation 'io.github.resilience4j:resilience4j-spring-boot3:2.2.0'
implementation 'io.github.resilience4j:resilience4j-micrometer:2.2.0'

resilience4j:
  retry:
    instances:
      paymentGateway:
        maxAttempts: 3
        waitDuration: 1s
        enableExponentialBackoff: true
        exponentialBackoffMultiplier: 2
        enableRandomizedWait: true # jitter 활성화
        randomizedWaitFactor: 0.5 # 50% 범위 내 무작위화

#!/bin/bash
# circuit-breaker-recovery.sh
# 서킷 브레이커 장애 복구 절차 스크립트

echo "===== 서킷 브레이커 상태 확인 ====="
# Actuator 엔드포인트로 서킷 브레이커 상태 확인
curl -s http://localhost:8080/actuator/circuitbreakers | jq '.circuitBreakers'

echo ""
echo "===== 다운스트림 서비스 헬스 체크 ====="
curl -s http://payment-service:8080/actuator/health | jq '.status'
curl -s http://inventory-service:8080/actuator/health | jq '.status'

echo ""
echo "===== 서킷 브레이커 강제 닫기 (다운스트림 복구 확인 후) ====="
# 주의: 다운스트림 서비스가 완전히 복구된 후에만 실행
# curl -X POST http://localhost:8080/actuator/circuitbreakers/paymentService/close

echo ""
echo "===== 현재 메트릭 확인 ====="
curl -s http://localhost:8080/actuator/metrics/resilience4j.circuitbreaker.state | jq '.'
curl -s http://localhost:8080/actuator/metrics/resilience4j.circuitbreaker.failure.rate | jq '.'

echo ""
echo "===== Istio Outlier Detection 상태 확인 ====="
kubectl get destinationrules -n production
kubectl describe destinationrule payment-service-circuit-breaker -n production

# Prometheus scrape 설정
scrape_configs:
  - job_name: 'spring-boot-resilience4j'
    metrics_path: '/actuator/prometheus'
    scrape_interval: 5s
    static_configs:
      - targets: ['payment-service:8080']
        labels:
          application: 'payment-service'

# Grafana Alert Rule (provisioning)
groups:
  - name: circuit-breaker-alerts
    rules:
      - alert: CircuitBreakerOpen
        expr: resilience4j_circuitbreaker_state{state="open"} == 1
        for: 10s
        labels:
          severity: critical
        annotations:
          summary: '서킷 브레이커 OPEN - {{ $labels.name }}'
          description: >
            {{ $labels.application }}의 {{ $labels.name }}
            서킷 브레이커가 OPEN 상태입니다.
            즉시 다운스트림 서비스 상태를 확인하세요.

      - alert: HighFailureRate
        expr: resilience4j_circuitbreaker_failure_rate > 40
        for: 30s
        labels:
          severity: warning
        annotations:
          summary: '높은 실패율 감지 - {{ $labels.name }}'
          description: >
            {{ $labels.name }}의 실패율이 {{ $value }}%입니다.
            서킷이 열리기 전에 원인을 파악하세요.

# Istio 메시 내 서비스 상태 확인
istioctl proxy-config cluster <pod-name> -n production | grep outlier

# Envoy 통계 확인
kubectl exec -it <pod-name> -n production -c istio-proxy -- \
  curl localhost:15000/stats | grep outlier_detection

# Kiali 대시보드 접근
istioctl dashboard kiali