AWS Advanced JDBC Wrapper의 blue/green 플러그인을 통하여 전환 시 최소의 다운타임 달성하기

최신 애플리케이션은 무중단에 가까운 가용성을 요구합니다. Amazon RDS와 Aurora의 Blue/Green 배포는 데이터베이스 업그레이드 시 다운타임을 크게 줄여주지만, 전환 과정에서 여전히 연결 종료, DNS 전파 지연, 수동 개입이 필요한 연결 실패 등의 문제가 발생할 수 있습니다.

AWS Advanced JDBC Wrapper(2023년 출시)는 표준 JDBC 드라이버 위에 AWS 특화 기능을 추가하는 래퍼입니다. 이 게시물에서는 AWS Advanced JDBC Wrapper의 Blue/Green 배포 플러그인을 소개합니다. 이 플러그인은 전환 중 연결 라우팅, 상태 감지, 트래픽 관리를 자동으로 처리하여 다운타임을 최소화합니다. 최근 Amazon RDS는 Blue/Green 배포의 가동 중지 시간을 5초 미만으로 최적화하는 기능을 출시했으며, 이 플러그인과 함께 사용하면 애플리케이션 수준에서도 전환 영향을 최소화할 수 있습니다.

또한 전환시 일반 JDBC 드라이버에서 갖는 한계점을 AWS Advanced JDBC Wrapper아래와 같이 해결할 수 있습니다.

AWS Advanced JDBC Wrapper Blue/Green 배포 플러그인 소개

AWS Advanced JDBC Wrapper의 Blue/Green 배포 플러그인은 RDS Aurora Blue/Green 전환 과정에서 발생하는 연결 종료, DNS 전파 지연, 엔드포인트 변경 등을 자동으로 감지하고 처리하는 플러그인입니다. 애플리케이션 코드 변경 없이 JDBC 연결 설정만으로 다음 기능을 제공합니다:

• 자동 전환 감지: 백그라운드 모니터링으로 Blue/Green 배포 상태 변화를 실시간 감지
  • 백그라운드 모니터링 스레드가 RDS 메타데이터를 주기적으로 조회하여 Blue/Green 배포 상태와 전환 Phase 변화를 자동 감지합니다.
  • Phase가 바뀌면 즉시 라우팅 전략과 제어 정책을 교체합니다.
• 지능형 트래픽 관리: 전환 단계별로 연결과 쿼리 실행을 자동 제어
• DNS 독립적 라우팅: IP 기반 라우팅으로 stale DNS 문제 방지
  • 내부적으로 IP 인벤토리를 유지해, 전환 구간에는 호스트명이 아닌 IP 기준으로 연결을 잡으면서 DNS 캐시/전파 지연에서 오는 stale DNS 문제를 최소화합니다.
• 연결 인벤토리 관리: 양쪽 환경의 엔드포인트와 IP 주소를 사전 수집

wrapper 플러그인의 동작

• Blue/Green 상태 모니터링
  • RDS가 제공하는 메타데이터 테이블·함수를 주기적으로 조회해 Blue/Green 배포 상태와 전환 Phase(예: NOT_CREATED, CREATED, PREPARATION, IN_PROGRESS, POST, COMPLETED)를 감지합니다.
  • Phase 변화가 감지되면 그에 맞는 트래픽 라우팅/제어 정책을 곧바로 적용합니다.
• Blue/Green 양쪽 환경의 연결 인벤토리 유지
  • 전환 시작 전에 Blue/Green 양쪽의 클러스터·인스턴스 엔드포인트와 각 엔드포인트의 IP 주소 목록을 미리 수집해 기준선으로 삼습니다.
  • 이 인벤토리를 기반으로 “어떤 Blue 엔드포인트가 어느 Green 엔드포인트에 대응하는지” 관계를 정리해 둡니다.
• 전환 단계별 트래픽 라우팅
  • 전환 중에는 Blue 노드로 향하는 JDBC 호출을 일시적으로 멈춰 Blue 쪽 부하를 줄이고, Green으로의 전환·복제 완료를 돕습니다.
  • 새로운 Blue 연결을 만들 때는 호스트명을 IP로 치환해 연결하여, DNS 캐시/전파 지연으로 인한 stale DNS 이슈를 제거합니다.
• 전환 직후 DNS 안정화 처리
  • 전환 직후 짧은 기간 동안 DNS를 계속 감시해, Blue 엔드포인트가 새 인프라 기준으로 제대로 재구성되었는지 확인합니다.
  • 이 과정에서 여전히 필요할 때는 호스트명→IP 치환을 유지하고, DNS가 충분히 안정됐다고 판단되면 점진적으로 이를 중단하여 다시 호스트명 기반 라우팅으로 복귀합니다.
  • 전환은 끝났지만 Green 쪽 DNS 레코드가 잠시 남아 있는 동안에는, Green 노드로의 신규 연결을 자동으로 거부해 잘못된 대상에 붙는 것을 방지합니다.
• 전환 중 연결 실패의 우아한 처리
  • 전환 과정에서 불가피하게 발생하는 연결 에러에 대해, 내부적으로 재시도·대기·타임아웃을 조합해 “완전 장애” 대신 “일시적 지연”으로 흡수하려고 시도합니다.
  • 전환 실패나 롤백도 감지해, 그에 맞춰 다시 Blue 중심으로 돌리거나 더 보수적인 제어 전략으로 전환함으로써 애플리케이션 안정성을 유지합니다.

플러그인은 내부적으로 3개의 레이어로 구성됩니다:

레이어 A: JDBC 호출 가로채기(Interception) — BlueGreenConnectionPlugin

• 신규 연결 개설을 가로채고, Phase에 따라 ConnectRouting을 적용합니다:
  • Suspend: 연결을 일시 대기
  • Substitute: 호스트명을 IP 주소로 치환하여 연결
  • Reject: 연결 요청 거부
  • SuspendUntilFound: 대응 노드 발견까지 대기
• 기존 커넥션의 JDBC 메서드 호출을 가로채고, ExecuteRouting을 적용합니다:
  • SuspendExecute: 쿼리 실행을 일시 대기

레이어 B: 상태/인벤토리/라우팅 정책의 단일 소스 — BlueGreenStatusProvider

• Blue/Green전환의 Phase를 정리하고, 그 Phase에 맞는 ConnectRouting/ExecuteRouting 리스트를 생성해 StorageService에 캐시
• 어떤 호스트가 SOURCE(Blue)인지 TARGET(green)인지, 그리고 Blue↔Green “대응 노드(corresponding node)” 매핑을 관리

레이어 C: 배경 모니터링(폴링) — BlueGreenStatusMonitor

• SOURCE용 모니터 1개 + TARGET용 모니터 1개, 총 2개의 모니터링 루프가 동작하며, 메타데이터를 읽어서 상태를 캐시로 전달합니다.
• 폴링 주기는 baseline → increased → high 형태로 Phase에 따라 가변적으로 조정됩니다.

사전 요구사항 및 제약사항

AWS Advanced JDBC Wrapper를 사용하기 위해서는 여러가지 요구사항 및 제약사항이 존재합니다.

네트워크 연결

AWS 클러스터 엔드포인트 및 인스턴스 엔드포인트가 클라이언트에서 직접 접근 가능해야 합니다.

• 애플리케이션에서 DB의 cluster endpoint / instance endpoint로 직접 연결이 가능해야 플러그인이 정상 동작합니다.
• 데이터베이스에 접속할 때 CNAME alias를 사용해 연결하는 방식은 지원되지 않습니다

데이터베이스 엔진 버전

데이터베이스 버전이 메타데이터 테이블을 지원하지 않으면, 드라이버가 이를 자동 감지하고 기존 동작(일반 드라이버)으로 동작 합니다.

애플리케이션 스택 요구사항

• AWS Advanced JDBC Wrapper 2.6.0 이상 (Blue/Green 플러그인 포함)
• PostgreSQL JDBC 드라이버 또는 MySQL/MariaDB JDBC 드라이버

사용자 권한(비관리자 계정 권한)

비관리자 계정으로 접속하는 경우, Blue/Green 메타데이터 조회를 위해 추가 권한이 필요합니다. 필요한 권한이 없으면, 메타데이터 테이블/함수가 보이지 않아 Blue/Green 플러그인 기능이 정상 동작하지 않습니다.

• RDS PostgreSQL: rds_tools 확장 설치

RDS PostgreSQL 환경에서는 래퍼가 필요로 하는 메타데이터를 사용할 수 있도록 수동으로 rds_tools 확장을 설치해야 합니다:

CREATE EXTENSION rds_tools;

지원되지 않는 구성

아래의 구성에서는 Blue/Green 배포 플러그인이 지원되지않습니다.

• RDS MySQL 및 PostgreSQL Multi-AZ clusters
• Aurora Global Database

로깅 설정

Blue/Green 플러그인 에서는 전환 요약을 확인해보기 위하여 FINE 레벨 이상의 로깅을 요구합니다. 이는 전환 요약 뿐만 아니라, Driver의 동작에 대하여 확인 해볼 수 있습니다. 다만, FINE 레벨 로깅 활성화 시 전환 과정에서 상당한 양의 로그가 생성됩니다. 프로덕션 환경에서는 로그 로테이션 및 저장 공간을 사전에 확보해야 합니다.

• .properties file 설정 시

  .level=INFO
  handlers=java.util.logging.ConsoleHandler
  java.util.logging.ConsoleHandler.level=ALL
  software.amazon.jdbc.Driver.level=FINER
  software.amazon.jdbc.plugin.level=FINER

• Connection Parameter 설정 시

   final Properties properties = new Properties();
   properties.setProperty("wrapperLoggerLevel", "finest");
   Connection conn = DriverManager.getConnection(CONNECTION_STRING, properties);

wrapperLoggerLevel 설정 가능 값: OFF, SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST, ALL.

Blue/Green 배포 플러그인을 Java 애플리케이션에서 설정하기

AWS Advanced JDBC Wrapper를 애플리케이션에 통합하려면 종속성 관리를 위해 Maven 또는 Gradle 빌드 시스템을 사용하십시오.

Maven 설정

다음의 종속성을 포함하도록 pom.xml을 업데이트합니다.

<dependency>
    <groupId>software.amazon.jdbc</groupId>
    <artifactId>aws-advanced-jdbc-wrapper</artifactId>
    <version>2.6.0</version>
</dependency>
<dependency>
    <groupId>org.postgresql</groupId>
    <artifactId>postgresql</artifactId>
    <version>LATEST</version>
</dependency>

Blue/Green 배포 플러그인 구성 파라미터

아래의 예시처럼 .java파일에서 parameter를 설정할 수 있습니다.

import java.sql.*;
import java.util.Properties;

public class BlueGreenExample {
    public static void main(String[] args) throws SQLException {
        String url = "jdbc:aws-wrapper:postgresql://my-cluster.cluster-xxxx.ap-northeast-2.rds.amazonaws.com:5432/mydb";

        Properties props = new Properties();
        props.setProperty("user", "<db_user>");
        props.setProperty("password", "<db_password>");

        // Blue/Green 플러그인 활성화
        props.setProperty("wrapperPlugins", "bg,auroraConnectionTracker,failover2,efm2");

        // Blue/Green plugin parameters 설정
        // 필요 시 기본값 조정 (아래는 모두 기본값 — 변경이 필요한 항목만 설정)
        // props.setProperty("bgdId","1");
        // props.setProperty("bgConnectTimeoutMs","30000");
        // props.setProperty("bgBaselineMs","60000");
        // props.setProperty("bgIncreasedMs","1000");
        // props.setProperty("bgHighMs","100");
        // props.setProperty("bgSwitchoverTimeoutMs","180000");
        // props.setProperty("blue-green-monitoring-connectTimeout","20000");
        // props.setProperty("blue-green-monitoring-socketTimeout","20000");

        try (Connection conn = DriverManager.getConnection(url, props);
             Statement stmt = conn.createStatement();
             ResultSet rs = stmt.executeQuery("SELECT 1")) {
            while (rs.next()) {
                System.out.println("Result: " + rs.getInt(1));
            }
        }

위의 파라미터 설정 중 bgConnectTimeoutMs, bgHighMs, bgSwitchoverTimeoutMs는 다운타임 및 파라미터가 실제 Blue/Green 스위치 오버 중 커넥션 동작에 대하여 직접적인 영향을 미칠 수 있습니다.

• bgConnectTimeoutMs – Blue/Green 전환 진행 중 Blue/Green 트래픽이 일시 중단(suspend)된 상태에서 새로운 커넥션을 맺을 때 적용되는 최대 대기 시간입니다. 전환의 IN_PROGRESS 단계에서 드라이버는 모든 Blue/Green 노드 커넥션 요청을 suspend 상태로 만듭니다(2.6.7 버전 이상부터). 이때 새 커넥션 요청은 이 타임아웃 내에서 POST 이상 상태로 진행되는것을 기다립니다. 파라미터에 설정된 타임아웃을 초과하면 커넥션 시도가 실패합니다. 추가로 파라미터를 조정할때, 애플리케이션에서 커넥션 풀링을 사용중이라면, 해당 커넥션 풀링의 connectionTimeout값과 적절하게 설정해야합니다.
• bgHighMs – 해당 값이 작을수록, PREPARATION → IN_PROGRESS → POST의 모니터링 주기인 HIGH에서 Aurora/RDS 메타데이터 폴링 주기가 짧아지므로, 드라이버가 DNS 변경, 토폴로지 변경, 전환 단계 전환을 더 빠르게 감지할수있습니다.
• bgSwitchoverTimeoutMs – PREPARATION 단계 진입 시 타이머가 시작되고, 이후 모든 단계 (PREPARATION, IN_PROGRESS, POST, COMPLETED)에서 타임아웃을 체크합니다. 즉, 전체 전환 타임아웃을 설정하는 파라미터입니다. 설정된 시간을 초과할경우 드라이버에서는 상태를 COMPLETED으로 설정합니다. PREPARATION부터의 전체 드라이버 동작이 해당 시간내에서만 동작하므로, 시간을 너무 작게 설정할경우 rollback등의 필요한 워크플로우가 동작하지 않을 수 있습니다.

Blue/Green 배포 플러그인의 전환 단계별 동작

전환 수명 주기 (Lifecycle)

Blue/Green 배포의 전환은 다음과 같은 수명 주기를 따릅니다:

1. NOT_CREATED: Blue/Green 배포가 아직 생성되지 않은 초기 상태
2. CREATED: Blue/Green 배포가 생성됨. Green 환경이 Blue 환경의 복제본으로 준비됨
3. PREPARATION: 전환 준비 단계. 플러그인이 인벤토리(Blue/Green 노드 매핑)를 수집하고 IP 기반 연결로 전환
4. IN_PROGRESS: 실제 전환 진행 중. 모든 연결과 쿼리가 일시 중단됨
5. POST: 전환 완료 직후. DNS 전파 대기 중이며 IP 기반으로 green 환경에 라우팅
6. COMPLETED: 전환 완료. DNS 전파가 완료되면 정상 동작으로 복귀

Phase별 폴링 주기 및 라우팅 정책

Blue/Green 배포 플러그인은 RDS Aurora의 Blue/Green 배포 상태(Phase)에 따라 폴링 주기와 트래픽 라우팅 정책을 자동으로 조정합니다. 아래 표는 소스 코드(BlueGreenStatusProvider.java)에서 검증한 각 Phase별 동작을 정리한 것입니다.

Phase 전환 흐름

NOT_CREATED    →    CREATED    →    PREPARATION    →    IN_PROGRESS    →    POST    →   COMPLETED
(BASELINE)                  (BASELINE)        (INCREASED)                     (HIGH)                    (HIGH)          (정상 복귀)
평상시 감시                    배포 생성               IP 치환 시작                 전체 Suspend           Green 라우팅  DNS 완료 대기

주요 동작 상세

PREPARATION 단계 전환이 임박하면 플러그인은 Blue 호스트명 대신 Blue IP 주소로 연결을 치환(Substitute)합니다. 이는 전환 시 DNS가 변경되더라도 기존 연결이 끊기지 않도록 사전 대비하는 것입니다.

IN_PROGRESS 단계 실제 전환가 진행되는 동안, 플러그인은 모든 신규 연결과 기존 쿼리 실행을 일시 중단(Suspend)합니다. Blue, Green, IP 기반 연결 모두 예외 없이 중단됩니다. 이를 통해 전환 중 데이터 불일치나 연결 오류를 방지합니다.

POST 단계 전환이 완료된 직후, DNS가 아직 완전히 전파되지 않았을 수 있습니다. 플러그인은 다음과 같이 동작합니다: Blue 호스트명으로 들어오는 연결을 Green IP로 치환(Substitute) 토폴로지 변경이 감지된 후 green 엔드포인트로의 직접 연결은 거부(Reject) — 이미 IP 기반으로 라우팅되고 있으므로 대응 노드가 아직 발견되지 않은 경우 발견될 때까지 대기(SuspendUntilFound)

COMPLETED 단계 RDS가 COMPLETED를 보고하더라도, DNS가 완전히 업데이트되지 않은 경우 플러그인은 내부적으로 POST 동작을 유지합니다. DNS 전파가 완료되면 정상 동작으로 복귀합니다.

Blue/Green 배포 메타데이터 및 수명 주기 요약

Blue/Green 배포 전환 중 플러그인이 사용하는 메타데이터를 직접 조회하여, 배포 진행 상황을 모니터링할 수 있습니다.

Aurora PostgreSQL

SELECT FROM getblue_green_fast_switchover_metadata(‘aws_jdbc_driver-' || driver_version);

RDS PostgreSQL

SELECT FROM rdstools.show_topology();

Aurora MySQL / RDS MySQL

SELECT FROM mysql.rdstopology;

전환 요약 로그

전환이 완료되면 플러그인은 FINE 레벨로 전환 요약 로그를 출력합니다. 이 로그를 통해 전환 과정의 타임라인과 결과를 확인할 수 있습니다. 로그를 확인하려면 앞서 설명한 로깅 설정에서 software.amazon.jdbc.plugin.level을 FINE 이상으로 설정해야 합니다.

Feb 15, 2026 2:32:07 PM software.amazon.jdbc.plugin.bluegreen.BlueGreenStatusProvider logSwitchoverFinalSummaryINFO: [bgdId: '1']
timestamp time offset (ms) event
---------------------------------------------------------------------------------------
 2026-02-15T14:29:58.119946Z -51642 ms NOT_CREATED
 2026-02-15T14:29:58.198069Z -51564 ms CREATED
 2026-02-15T14:30:28.189251Z -21572 ms PREPARATION
 2026-02-15T14:30:49.762161Z 0 ms Monitors reset - start
 2026-02-15T14:30:49.762245Z 0 ms IN_PROGRESS
 2026-02-15T14:30:51.929499Z 2167 ms POST
 2026-02-15T14:31:22.347162Z 32584 ms Green topology changed
 2026-02-15T14:31:22.352705Z 32590 ms Monitors reset - green topology
 2026-02-15T14:31:31.314812Z 41552 ms Blue DNS updated
 2026-02-15T14:32:07.413345Z 77651 ms Green DNS removed
 2026-02-15T14:32:07.413883Z 77651 ms COMPLETED
 ---------------------------------------------------------------------------------------

위의 결과에서 볼수 있듯이 전환 중 실제 다운타임의 시간은 2.1초 정도의 낮은 수준임을 확인할 수 있습니다.

AWS Advanced JDBC Wrapper의 Blue/Green전환 롤백 메커니즘

AWS Advanced JDBC Wrapper의 Blue/Green Deployment 플러그인은 RDS 전환가 실패하거나 취소될 때 이를 자동으로 감지하고 처리하는 롤백 메커니즘을 내장하고 있습니다. 이 기능은 드라이버가 롤백을 능동적으로 실행하는 것이 아니라, RDS 엔진이 메타데이터 테이블의 상태를 되돌릴 때 이를 감지하여 반응하는 구조로 설계되었습니다.

롤백 감지 조건

드라이버는 Blue와 Green 각각에 독립적인 모니터링 커넥션을 유지하며, Green 모니터에서만 롤백을 감지합니다. 롤백은 다음 5가지 조건을 모두 만족할 때 트리거됩니다:

1. Green 모니터링 사용: Blue 모니터의 상태 변화는 롤백 판단에 사용되지 않습니다.
2. 이전 phase 존재: TARGET 모니터가 최소 1회 이상 phase를 보고한 상태여야 합니다.
3. 현재 phase 유효: 커넥션 끊김 등으로 phase가 null이면 롤백으로 판단하지 않습니다.
4. COMPLETED 이전: 이미 COMPLETED로 간주된 후에는 어떤 역행도 롤백으로 감지되지 않습니다.
5. Phase 값 역행: 새로 보고된 phase의 정수 값이 이전보다 작아야 합니다.

Blue/Green 전환은 NOT_CREATED(0) → CREATED(1) → PREPARATION(2) → IN_PROGRESS(3) → POST(4) → COMPLETED(5) 순서로 진행되며, 각 phase는 정수 값을 갖습니다. 예를 들어 IN_PROGRESS(3)에서 CREATED(1)로 되돌아가면 3 → 1 역행이 감지되어 롤백 플래그가 설정됩니다. 롤백이 동작하여 상태가 CREATED로 되돌아가면 모든 트래픽 제어(connect routing, execute routing)가 해제되고 정상 모드로 복귀합니다. 동시에 모니터는 IP 주소 맵, 시작 토폴로지, 호스트 이름 목록 등 이전 전환 시도에서 수집한 모든 데이터를 초기화합니다. 최종적으로 “ROLLED BACK” 레이블과 함께 전환 요약 로그가 출력되고, 모든 내부 상태가 초기화된 후 완전히 새로운 사이클로 모니터링이 재시작됩니다.

제약 사항

bgSwitchoverTimeoutMs가 먼저 만료되어 드라이버가 COMPLETED로 강제 전환하면, 이후 RDS가 실제로 롤백하더라도 롤백이 감지되지 않습니다. 따라서 타임아웃 값은 실제 전환 소요 시간의 1.5~2배로 충분히 여유 있게 설정하여, 롤백이 발생할 경우 타임아웃보다 먼저 감지될 수 있도록 해야 합니다.

또한 SOURCE(Blue) 모니터에서는 어떤 상태 역행도 롤백으로 판단하지 않으며, TARGET 모니터의 첫 번째 보고나 phase 조회 실패(null) 시에도 롤백이 감지되지 않습니다. 드라이버는 green 노드의 상태만을 확인하는데, 이는 전환 중 Blue 노드가 재구성/재시작되어 상태가 불안정한 반면, green 노드는 실패 시 가장 먼저 원래 상태로 복원되어 가장 신뢰할 수 있는 롤백 시그널을 제공하기 때문입니다.

결론

AWS Advanced JDBC Wrapper의 Blue/Green 배포 플러그인은 RDS/Aurora Blue/Green 전환 시 발생하는 연결 끊김과 다운타임을 최소화하는 강력한 도구입니다. 플러그인은 3개 레이어(JDBC 가로채기, 상태/인벤토리 관리, 백그라운드 모니터링)를 통해 전환 상태를 실시간으로 감지하고, Phase별로 최적화된 라우팅 정책을 자동 적용합니다.

핵심 이점을 요약하면:

• 무중단에 가까운 전환: IN_PROGRESS 구간에서 연결과 쿼리를 일시 중단(suspend)하고, POST 구간에서 IP 기반으로 green 환경에 자동 라우팅하여 연결 실패 0건 달성
• DNS 독립적 동작: IP 기반 라우팅으로 DNS 전파 지연에 영향받지 않음
• 애플리케이션 코드 변경 불필요: JDBC 연결 파라미터 설정만으로 활성화
• 유연한 튜닝: 폴링 주기, 타임아웃 등을 환경에 맞게 조정 가능

이 플러그인의 지능형 연결 라우팅과 트래픽 관리 기능을 활용하면, RDS 및 Aurora Blue/Green 배포 시 애플리케이션의 가용성과 복원력을 한층 높일 수 있습니다. 다만, 실제 전환 시간은 고객 환경과 구성에 따라 달라질 수 있으며, 전환 과정에서 발생할 수 있는 일시적인 예외에 대비해 애플리케이션 레벨에서 재시도 로직을 구현해 두시는 것을 권장드립니다.