이 글은 Apache Kafka 입문 시리즈의 두 번째 글입니다. 1편에서 살펴본 구성 요소들 위에서, 메시지가 실제로 어떤 구조로 저장되고 관리되는지 알아보겠습니다.

1편을 마치며 세 가지 질문을 남겼습니다.

• 메시지는 브로커 안에서 어떤 구조로 저장될까?
• 토픽과 파티션은 정확히 무엇이고, 왜 필요할까?
• 컨슈머의 오프셋은 어떻게 동작할까?

이번 편에서 이 질문들에 하나씩 답하겠습니다.

Topic: 메시지의 논리적 분류

토픽(Topic)은 메시지를 분류하는 논리적 단위입니다. 1편에서 "메시지가 저장되는 카테고리"라고 소개한 바로 그것입니다.

쇼핑몰 시스템이라면 orders, payments, notifications처럼 용도에 따라 토픽을 나눕니다. 프로듀서는 토픽을 지정하여 메시지를 보내고, 컨슈머는 관심 있는 토픽을 구독하여 메시지를 읽습니다.

flowchart LR
    subgraph Producers
        P1[Order Service]
        P2[Payment Service]
    end

    subgraph Topics
        T1[orders]
        T2[payments]
    end

    subgraph Consumers
        C1[Analytics Service]
        C2[Notification Service]
    end

    P1 -->|"publish"| T1
    P2 -->|"publish"| T2
    T1 -->|"subscribe"| C1
    T2 -->|"subscribe"| C2
    T1 -->|"subscribe"| C2

토픽은 로그다

토픽의 본질은 추가 전용 로그(append-only log)입니다. 새로운 메시지는 항상 로그의 끝에만 추가됩니다. 한번 기록된 메시지는 수정하거나 삭제할 수 없습니다. 이 불변성(immutability)은 카프카의 핵심 설계 원칙입니다.

flowchart LR
    subgraph Log["Append-Only Log"]
        M0["msg 0"]
        M1["msg 1"]
        M2["msg 2"]
        M3["msg 3"]
        M4["msg 4"]
    end

    M0 --> M1 --> M2 --> M3 --> M4

    P["Producer"] -->|"append"| M4

그렇다면 오래된 메시지는 영원히 남아 있을까요? 아닙니다. 카프카는 보존 정책(retention policy)에 따라 오래된 메시지를 자동으로 정리합니다.

보존 정책

기본 설정에서는 7일이 지난 메시지가 삭제됩니다. 로그 컴팩션은 조금 다른 개념인데, 키별로 가장 마지막 값만 남기는 것을 목표로 백그라운드에서 점진적으로 정리하는 방식입니다. 컴팩션이 아직 실행되지 않은 시점에는 같은 키의 메시지가 여러 개 존재할 수 있습니다. 예를 들어 사용자 프로필을 저장하는 토픽이라면, 같은 사용자 ID를 키로 가진 메시지 중 최종 상태만 보존합니다.

flowchart LR
    subgraph Before Compaction
        A1["key=A, val=1"]
        B1["key=B, val=2"]
        A2["key=A, val=3"]
        B2["key=B, val=4"]
        A3["key=A, val=5"]
    end

    A1 --> B1 --> A2 --> B2 --> A3

    subgraph After Compaction
        A3c["key=A, val=5"]
        B2c["key=B, val=4"]
    end

    A3c --> B2c

Partition: 토픽을 나누는 단위

토픽 하나에 모든 메시지를 순서대로 쌓으면 간단하겠지만, 한 대의 브로커에 부하가 집중됩니다. 이 문제를 해결하기 위해 카프카는 토픽을 파티션(Partition)이라는 더 작은 단위로 나눕니다.

왜 파티션이 필요한가?

핵심은 병렬 처리입니다.

flowchart TB
    subgraph Topic: orders
        subgraph Broker 1
            P0["Partition 0"]
        end
        subgraph Broker 2
            P1["Partition 1"]
        end
        subgraph Broker 3
            P2["Partition 2"]
        end
    end

    Producer -->|"write"| P0
    Producer -->|"write"| P1
    Producer -->|"write"| P2

파티션이 3개라면:

• 쓰기 분산: 프로듀서가 3개의 브로커에 동시에 메시지를 보낼 수 있습니다
• 읽기 분산: 컨슈머 3대가 각각 하나의 파티션을 담당하여 동시에 읽을 수 있습니다
• 저장 분산: 데이터가 3개의 브로커에 나뉘어 저장됩니다

파티션 수가 곧 병렬 처리의 상한선입니다. 컨슈머 그룹 내에서 하나의 파티션은 하나의 컨슈머만 읽을 수 있으므로, 파티션이 3개면 동시에 읽는 컨슈머도 최대 3대입니다.

파티션 내부의 순서 보장

1편 Q&A에서 잠깐 언급했던 내용입니다. 카프카는 파티션 단위로 순서를 보장합니다.

하나의 파티션 안에서 메시지는 들어온 순서 그대로 저장되고, 같은 순서로 읽힙니다. 하지만 서로 다른 파티션 간에는 순서가 보장되지 않습니다.

flowchart TB
    subgraph Partition 0
        A1["offset 0: Order Created"]
        A2["offset 1: Order Paid"]
        A3["offset 2: Order Shipped"]
    end
    A1 --> A2 --> A3

    subgraph Partition 1
        B1["offset 0: Order Created"]
        B2["offset 1: Order Cancelled"]
    end
    B1 --> B2

같은 파티션 내에서는 Created → Paid → Shipped이 보장되지만, Partition 0의 Shipped과 Partition 1의 Cancelled 중 어느 것이 먼저 처리될지는 알 수 없습니다.

메시지는 어떤 파티션으로 가는가?

프로듀서가 메시지를 보낼 때, 어떤 파티션에 넣을지를 결정하는 것이 파티셔닝 전략입니다.

키가 있는 경우: 해시 기반 분배

메시지에 키(key)가 있으면, 카프카는 키의 해시값으로 파티션을 결정합니다.

partition = toPositive(murmur2(key)) % numPartitions

murmur2 해시는 음수를 반환할 수 있으므로, toPositive()로 양수 변환 후 나머지 연산을 수행합니다.

같은 키는 항상 같은 파티션으로 갑니다. 따라서 같은 키를 가진 메시지끼리 순서가 보장됩니다.

flowchart LR
    subgraph Producer
        M1["key=user-1"]
        M2["key=user-2"]
        M3["key=user-1"]
    end

    subgraph Topic
        P0["Partition 0"]
        P1["Partition 1"]
    end

    M1 -->|"hash % 2 = 0"| P0
    M2 -->|"hash % 2 = 1"| P1
    M3 -->|"hash % 2 = 0"| P0

주문 시스템에서 사용자 ID를 키로 설정하면, 같은 사용자의 주문 이벤트는 항상 같은 파티션에 쌓이므로 이벤트 순서가 보장됩니다.

주의: 파티션 수가 변경되면 같은 키라도 다른 파티션으로 갈 수 있습니다. murmur2(key) % 3과 murmur2(key) % 5는 다른 결과를 냅니다. 키 기반 순서 보장이 중요하다면 파티션 수를 처음에 잘 정해야 합니다.

키가 없는 경우: 스티키 파티셔너

키가 없는 메시지는 어떻게 분배될까요? 과거에는 라운드 로빈 방식으로 한 건씩 돌아가며 보냈지만, 이 방식은 작은 배치를 많이 만들어 비효율적이었습니다.

현재 카프카(3.3+)는 스티키 파티셔너(Sticky Partitioner)를 기본으로 사용합니다. 하나의 파티션에 배치가 가득 찰 때까지 메시지를 모은 뒤, 다음 파티션으로 전환합니다.

스티키 파티셔너 도입으로 p99 지연 시간이 1017ms에서 204ms로 감소한 벤치마크 결과도 있습니다 (KIP-480).

Segment: 파티션의 물리적 저장 구조

지금까지 토픽과 파티션은 논리적인 개념이었습니다. 이제 파티션이 디스크에 실제로 어떻게 저장되는지 살펴보겠습니다.

파티션 = 디렉토리

각 파티션은 브로커의 디스크에 하나의 디렉토리로 존재합니다. 디렉토리 이름은 {토픽명}-{파티션번호} 형식입니다.

/kafka-logs/
├── orders-0/          ← Topic: orders, Partition: 0
│   ├── 00000000000000000000.log
│   ├── 00000000000000000000.index
│   ├── 00000000000000000000.timeindex
│   ├── 00000000000000001007.log
│   ├── 00000000000000001007.index
│   └── 00000000000000001007.timeindex
├── orders-1/          ← Topic: orders, Partition: 1
└── orders-2/          ← Topic: orders, Partition: 2

세그먼트 파일 구조

파티션 안의 데이터는 세그먼트(Segment)라는 단위로 나뉩니다. 하나의 세그먼트는 세 개의 파일로 구성됩니다.

파일 이름은 해당 세그먼트의 첫 번째 메시지 오프셋을 20자리로 표현한 것입니다. 00000000000000001007.log는 오프셋 1007부터 시작하는 세그먼트입니다.

활성 세그먼트와 세그먼트 롤링

파티션에서 현재 쓰기가 진행 중인 세그먼트를 활성 세그먼트(Active Segment)라고 합니다. 활성 세그먼트는 파티션당 항상 하나만 존재합니다.

flowchart LR
    subgraph Partition 0
        S1["Segment 0 (closed)"]
        S2["Segment 1007 (closed)"]
        S3["Segment 2014 (active)"]
    end

    S1 --> S2 --> S3

    P["Producer"] -->|"append"| S3

    R["Retention Policy"] -.->|"delete/compact"| S1
    R -.->|"delete/compact"| S2
    R -.->|"NOT applied"| S3

활성 세그먼트가 일정 조건에 도달하면, 해당 세그먼트를 닫고 새로운 세그먼트를 생성합니다. 이것을 세그먼트 롤링(rolling)이라 합니다.

중요한 점은, 보존 정책은 닫힌 세그먼트에만 적용된다는 것입니다. 활성 세그먼트는 삭제되거나 컴팩션되지 않습니다. 따라서 실제 데이터 보존 기간은 retention.ms보다 최대 한 세그먼트 기간만큼 길어질 수 있습니다.

인덱스로 빠르게 찾기

컨슈머가 "오프셋 1500번 메시지를 달라"고 요청하면, 카프카는 매번 로그 파일 전체를 스캔하지 않습니다.

1. .index 파일에서 오프셋 1500에 가장 가까운 인덱스 항목을 이진 탐색합니다
2. 해당 바이트 위치로 .log 파일을 열어 약간만 순방향 스캔합니다

.index 파일은 모든 오프셋을 기록하지 않고, 기본적으로 4KB마다 하나의 항목을 기록하는 희소 인덱스(sparse index)입니다. 전체 인덱스를 유지하는 것보다 파일 크기와 메모리 사용을 크게 줄이면서도 충분히 빠른 검색이 가능합니다.

Offset: 메시지의 위치 추적

오프셋(Offset)은 파티션 내에서 각 메시지에 부여되는 순차적 번호입니다. 1편에서 "책갈피"에 비유했던 개념입니다.

오프셋의 종류

하나의 파티션에는 여러 종류의 오프셋이 존재합니다.

flowchart LR
    subgraph Partition
        M0["0"]
        M1["1"]
        M2["2"]
        M3["3"]
        M4["4"]
        M5["5"]
        M6["6"]
        M7["7"]
    end

    M0 --> M1 --> M2 --> M3 --> M4 --> M5 --> M6 --> M7

    LSO["Log-Start Offset = 0"]
    CO["Committed Offset = 3"]
    CP["Consumer Position = 5"]
    HW["High Watermark = 6"]
    LEO["Log-End Offset = 8"]

    LSO -.-> M0
    CO -.-> M3
    CP -.-> M5
    HW -.-> M6
    LEO -.->|"next write"| M7

이 중 Committed Offset과 Consumer Position이 컨슈머 입장에서 가장 중요합니다.

Committed Offset과 Consumer Position의 차이

두 개념의 차이가 중요한 이유는 장애 시 재처리 범위를 결정하기 때문입니다.

flowchart LR
    subgraph Partition
        M0["0"]
        M1["1"]
        M2["2"]
        M3["3"]
        M4["4"]
    end

    M0 --> M1 --> M2 --> M3 --> M4

    CO["Committed = 2"] -.-> M2
    CP["Position = 4"] -.-> M4

    subgraph Risk Zone
        M2
        M3
    end

• Consumer Position: poll()로 메시지를 가져올 때마다 자동으로 앞으로 이동합니다
• Committed Offset: 명시적으로 커밋해야 이동합니다

컨슈머가 오프셋 4까지 읽었지만 2까지만 커밋한 상태에서 장애가 발생하면, 재시작 시 오프셋 2부터 다시 읽기 시작합니다. 오프셋 2, 3의 메시지는 중복 처리될 수 있습니다. 이 간격이 바로 "위험 구간"입니다.

오프셋은 어디에 저장되는가?

컨슈머가 커밋한 오프셋은 __consumer_offsets라는 카프카 내부 토픽에 저장됩니다.

이 토픽의 키는 (컨슈머 그룹, 토픽, 파티션) 조합이고, 값은 커밋된 오프셋입니다. 로그 컴팩션이 적용되어 각 키의 최신 값만 유지됩니다.

컨슈머 그룹의 코디네이터 브로커는 이 값을 메모리에 캐시하여 빠르게 응답합니다. 코디네이터는 hash(group.id) % 50으로 결정되는 __consumer_offsets 파티션의 리더 브로커입니다.

오프셋 커밋 방식

오프셋을 커밋하는 방법은 자동 커밋과 수동 커밋 두 가지입니다.

자동 커밋

기본적으로 카프카 컨슈머는 5초마다 자동으로 오프셋을 커밋합니다. 편리하지만, 메시지를 처리하는 도중 장애가 나면 처리하지 못한 메시지의 오프셋까지 커밋되어 메시지를 놓칠 수 있습니다. 반대로 커밋 직전에 장애가 나면 이미 처리한 메시지를 중복 처리할 수 있습니다.

수동 커밋

// 동기 커밋 — 커밋 완료를 기다림
consumer.commitSync();

// 비동기 커밋 — 커밋 완료를 기다리지 않음
consumer.commitAsync();

• commitSync(): 커밋이 완료될 때까지 블로킹합니다. 실패하면 자동 재시도합니다
• commitAsync(): 커밋 요청을 보내고 즉시 반환합니다. 실패해도 재시도하지 않습니다 (순서 역전 방지)

정확한 오프셋 관리가 필요한 시스템에서는 자동 커밋을 끄고 수동 커밋을 사용합니다.

오프셋 리셋 정책

컨슈머가 처음 시작하거나, 커밋된 오프셋이 보존 정책에 의해 삭제된 경우에는 읽기 시작할 위치가 없습니다. 이때 auto.offset.reset 설정이 적용됩니다.

이 설정은 유효한 커밋 오프셋이 없을 때만 적용됩니다. 한번 오프셋이 커밋되면 이후에는 이 설정과 무관하게 커밋 지점부터 읽습니다.

전체 구조 한눈에 보기

토픽, 파티션, 세그먼트, 오프셋의 관계를 하나의 그림으로 정리하면 다음과 같습니다.

flowchart TB
    subgraph Topic: orders
        subgraph Broker 1
            subgraph Partition 0
                S0_0["Segment 0 (closed)"]
                S0_1["Segment 1007 (active)"]
            end
        end
        subgraph Broker 2
            subgraph Partition 1
                S1_0["Segment 0 (closed)"]
                S1_1["Segment 985 (active)"]
            end
        end
        subgraph Broker 3
            subgraph Partition 2
                S2_0["Segment 0 (active)"]
            end
        end
    end

    P["Producer (key=user-1)"] -->|"hash % 3 = 0"| S0_1
    C["Consumer"] -->|"offset=1010"| S0_1

정리

이번 글에서는 카프카의 데이터 저장 구조를 살펴보았습니다.

• 토픽은 메시지의 논리적 분류이며, 본질은 추가 전용 로그입니다
• 파티션은 토픽을 물리적으로 나누어 병렬 처리를 가능하게 합니다
• 세그먼트는 파티션이 디스크에 저장되는 실제 파일 단위입니다
• 오프셋은 파티션 내 메시지의 순차 번호이며, 컨슈머는 이를 커밋하여 읽기 진행 상태를 관리합니다

하지만 아직 답하지 못한 질문들이 있습니다.

• 카프카는 어떻게 초당 수백만 건의 메시지를 처리할 수 있을까?
• 순차적 디스크 I/O, Zero-Copy, 배치 처리 — 이 설계 결정들은 어떻게 연결될까?

이 질문들에 대한 답은 다음 편인 "카프카의 핵심 기능과 설계 철학"에서 이어집니다.

부록: Q&A

Q1. 파티션 수는 어떻게 정하는가?

Q2. 파티션 수를 나중에 변경하면 어떻게 되는가?

Q3. High Watermark는 왜 필요한가?

Q4. 로그 컴팩션에서 메시지를 삭제하려면?

Q5. 자동 커밋은 언제 위험한가?

Q6. __consumer_offsets 토픽이 손상되면?

이 글은 Apache Kafka 4.1 공식 문서를 기반으로 작성되었습니다.

이 글은 Apache Kafka를 처음 접하는 분들을 위한 입문 시리즈의 첫 번째 글입니다. 카프카를 구성하는 핵심 요소들을 하나씩 살펴보며, 전체 구조를 머릿속에 그려보겠습니다.

카프카란?

Apache Kafka는 이벤트 스트리밍 플랫폼입니다. 단순한 메시지 큐가 아니라, 이벤트를 **발행(publish)하고, 저장(store)하고, 처리(process)**할 수 있는 분산 시스템입니다.

"쇼핑몰에서 사용자가 주문 버튼을 눌렀다"는 이벤트가 발생하면, 이 이벤트를 결제 시스템, 재고 시스템, 알림 시스템이 각각 받아서 처리해야 합니다. 카프카는 이런 시스템 간의 데이터 흐름을 연결하는 중앙 허브 역할을 합니다.

flowchart LR
    subgraph Producers
        A[Order Service]
        B[Payment Service]
        C[User Service]
    end

    K[Apache Kafka]

    subgraph Consumers
        D[Notification Service]
        E[Analytics Service]
        F[Inventory Service]
    end

    A --> K
    B --> K
    C --> K
    K --> D
    K --> E
    K --> F

이제 카프카를 구성하는 핵심 요소들을 하나씩 살펴보겠습니다.

Broker: 카프카의 서버

**브로커(Broker)**는 카프카 클러스터에서 **저장소 계층(storage layer)**을 구성하는 서버입니다. 데이터를 받아서 저장하고, 요청이 오면 데이터를 내려주는 역할을 합니다.

브로커의 핵심 역할은 네 가지입니다.

• 메시지 수신: Producer가 보낸 메시지를 받아 디스크에 저장합니다

• 메시지 제공: Consumer의 요청에 따라 저장된 메시지를 전달합니다

• 데이터 복제: 다른 브로커와 데이터를 복제하여 장애에 대비합니다

• 메타데이터 제공: 클라이언트에게 파티션 리더 위치 등 클러스터 상태 정보를 알려줍니다

하나의 브로커가 하나의 카프카 서버라고 이해하면 됩니다. 실제 운영 환경에서는 여러 대의 브로커를 묶어서 사용하는데, 이것이 바로 **클러스터(Cluster)**입니다.

Cluster: 브로커의 집합

**클러스터(Cluster)**는 여러 브로커가 모여 하나의 카프카 시스템을 구성한 것입니다.

flowchart TB
    subgraph Kafka Cluster
        B1[Broker 1]
        B2[Broker 2]
        B3[Broker 3]
    end

    P[Producer] --> B1
    P --> B2
    B1 <--> B2
    B2 <--> B3
    B1 <--> B3
    B1 --> C[Consumer]
    B3 --> C

왜 브로커를 여러 대 사용할까요?

• 고가용성: 브로커 한 대가 죽어도 다른 브로커가 데이터를 제공합니다

• 확장성: 데이터가 많아지면 브로커를 추가하여 부하를 분산합니다

• 데이터 안전성: 데이터를 여러 브로커에 복제하여 유실을 방지합니다

운영 환경에서는 일반적으로 복제 계수(replication factor)를 3으로 설정합니다. 데이터 사본을 3개 유지한다는 의미이므로, 이를 위해 최소 3대의 브로커가 필요합니다. 이렇게 하면 1대가 장애가 나더라도 나머지 2대가 정상 동작을 유지할 수 있습니다.

Producer: 메시지를 보내는 쪽

**프로듀서(Producer)**는 카프카에 메시지를 발행하는 클라이언트 애플리케이션입니다.

프로듀서의 동작은 직관적입니다.

1. 보내고 싶은 **토픽(Topic)**을 지정합니다

2. 메시지를 구성합니다 (키, 값, 타임스탬프)

3. 카프카 브로커로 전송합니다

flowchart LR
    P[Producer] -->|1. Send message| B[Broker]
    B -->|2. Write to disk| D[(Log)]
    B -->|3. Acknowledge| P

프로듀서는 브로커에 메타데이터를 조회하여 어떤 브로커가 어떤 파티션의 리더인지 파악하고, 해당 브로커에 직접 메시지를 전송합니다. 중간 라우터 같은 것이 따로 필요 없습니다.

여기서 "토픽"이라는 용어가 나왔습니다. 토픽은 메시지를 분류하는 논리적 단위인데, 자세한 내용은 2편에서 다루겠습니다. 지금은 "메시지가 저장되는 카테고리"라고 이해하면 충분합니다.

Consumer: 메시지를 받는 쪽

**컨슈머(Consumer)**는 카프카에서 메시지를 읽어가는 클라이언트 애플리케이션입니다.

카프카에서 데이터의 흐름은 방향에 따라 다릅니다. 프로듀서는 브로커에게 메시지를 밀어넣고(Push), 컨슈머는 브로커에서 메시지를 당겨옵니다(Pull). 특히 컨슈머의 Pull 방식은 카프카의 중요한 설계 결정입니다.

왜 Pull 방식인가?

Push 방식은 브로커가 컨슈머에게 메시지를 보내는 것이고, Pull 방식은 컨슈머가 브로커에게 메시지를 달라고 요청하는 것입니다.

Pull 방식 덕분에 컨슈머는 자신의 처리 능력에 맞춰 메시지를 가져올 수 있습니다. 빠른 컨슈머는 빠르게, 느린 컨슈머는 느리게 — 각자의 속도로 동작합니다.

오프셋(Offset)

컨슈머는 **오프셋(offset)**이라는 숫자로 "다음에 읽을 메시지의 위치"를 관리합니다. 책갈피와 같은 개념이라고 보면 됩니다.

flowchart LR
    subgraph Partition
        M0["msg 0"]
        M1["msg 1"]
        M2["msg 2"]
        M3["msg 3"]
        M4["msg 4"]
    end

    M0 --> M1 --> M2 --> M3 --> M4

    CO["Consumer Offset = 3"]
    CO -.->|"next read"| M3

오프셋 덕분에 컨슈머가 중간에 죽었다가 다시 살아나더라도, 마지막으로 읽었던 지점부터 이어서 읽을 수 있습니다. 과거의 오프셋으로 되감아 메시지를 재처리하는 것도 가능합니다. 오프셋에 대해서도 2편에서 더 자세히 다루겠습니다.

Controller: 클러스터의 관리자

**컨트롤러(Controller)**는 카프카 클러스터 전체를 관리하는 역할을 합니다. 비유하자면 브로커들을 지휘하는 관제탑입니다.

컨트롤러가 하는 일은 다음과 같습니다.

• 파티션 리더 선출: 어떤 브로커가 어떤 파티션의 리더가 될지 결정합니다

• 브로커 감시: 브로커가 정상 동작하는지 모니터링하고, 장애가 발생하면 대응합니다

• 메타데이터 관리: 토픽, 파티션, 브로커 정보 등 클러스터의 모든 상태 정보를 관리합니다

• 설정 관리: 토픽 설정 변경 등 관리 작업을 처리합니다

카프카 클러스터에는 항상 **하나의 활성 컨트롤러(Active Controller)**가 존재합니다. 이 컨트롤러가 죽으면, 대기 중인 다른 컨트롤러가 즉시 역할을 이어받습니다.

KRaft: 카프카의 두뇌

여기서 중요한 질문이 나옵니다. "컨트롤러는 클러스터 상태를 어디에 저장할까?"

ZooKeeper 시절 (과거)

과거에는 ZooKeeper라는 별도의 분산 시스템이 이 역할을 담당했습니다. 카프카를 운영하려면 ZooKeeper 클러스터를 별도로 구축하고 관리해야 했습니다.

flowchart TB
    subgraph Before["Before: Kafka + ZooKeeper"]
        direction TB
        subgraph ZK["ZooKeeper Cluster"]
            Z1[ZK Node 1]
            Z2[ZK Node 2]
            Z3[ZK Node 3]
        end
        subgraph BK["Kafka Cluster"]
            KB1[Broker 1]
            KB2[Broker 2]
            KB3[Broker 3]
        end
        KB1 <--> Z1
        KB2 <--> Z2
        KB3 <--> Z3
    end

이 구조에는 문제가 있었습니다.

• 운영 복잡성: 카프카와 ZooKeeper, 두 개의 분산 시스템을 동시에 관리해야 합니다

• 확장 한계: ZooKeeper에 저장할 수 있는 메타데이터 양에 제한이 있어, 파티션 수에 한계가 있었습니다

• 장애 복구 지연: 컨트롤러 장애 시 ZooKeeper에서 상태를 다시 읽어와야 해서 복구에 시간이 걸렸습니다

KRaft 시대 (현재)

**KRaft(Kafka Raft)**는 ZooKeeper 의존성을 완전히 제거하고, 카프카 자체적으로 메타데이터를 관리하는 방식입니다. Kafka 4.0부터 KRaft가 유일한 메타데이터 관리 방식이 되었습니다.

flowchart TB
    subgraph After["After: Kafka with KRaft"]
        direction TB
        subgraph Controllers["Controller Quorum"]
            C1[Controller 1]
            C2[Controller 2]
            C3[Controller 3]
        end
        subgraph Brokers
            KB1[Broker 1]
            KB2[Broker 2]
            KB3[Broker 3]
        end
        C1 <--> C2
        C2 <--> C3
        C1 <--> C3
        C1 --> KB1
        C2 --> KB2
        C3 --> KB3
    end

KRaft의 핵심 개념을 살펴보겠습니다.

컨트롤러 쿼럼 (Controller Quorum)

KRaft에서는 여러 컨트롤러 노드가 **쿼럼(quorum)**을 구성합니다. 쿼럼이란 "의사결정을 위해 필요한 최소 인원"이라는 뜻입니다.

• 3대 구성 → 1대 장애 허용

• 5대 구성 → 2대 장애 허용

• 공식: N대 중 (N/2 + 1)대가 살아 있으면 정상 동작

이 컨트롤러들은 Raft 합의 알고리즘을 사용하여 리더를 선출하고, 메타데이터 변경사항을 동기화합니다.

메타데이터 관리 방식

KRaft는 __cluster_metadata라는 내부 토픽에 모든 클러스터 메타데이터를 이벤트 로그로 기록합니다.

flowchart LR
    subgraph Metadata Log["__cluster_metadata"]
        E1["Topic Created"]
        E2["Partition Assigned"]
        E3["Broker Registered"]
        E4["Leader Changed"]
    end

    E1 --> E2 --> E3 --> E4

    Leader["Active Controller"] -->|"write"| E1
    Follower1["Follower Controller"] -->|"replicate"| E4
    Follower2["Follower Controller"] -->|"replicate"| E4

이 방식의 장점은 명확합니다.

• 빠른 장애 복구: 새 리더는 이미 모든 메타데이터를 메모리에 가지고 있으므로, 외부 시스템에서 다시 읽어올 필요가 없습니다

• 운영 단순화: ZooKeeper 없이 카프카만 관리하면 됩니다

• 확장성 향상: 메타데이터 관리에 카프카 자체의 로그 구조를 사용하므로 더 많은 파티션을 지원합니다

전체 구조 한눈에 보기

지금까지 살펴본 구성 요소들을 하나의 그림으로 정리하면 다음과 같습니다.

flowchart TB
    subgraph Clients
        P1[Producer]
        P2[Producer]
        C1[Consumer]
        C2[Consumer]
    end

    subgraph Kafka Cluster
        subgraph Controller Quorum
            CT1["Controller 1 (Leader)"]
            CT2[Controller 2]
            CT3[Controller 3]
        end

        subgraph Brokers
            B1["Broker 1"]
            B2["Broker 2"]
            B3["Broker 3"]
        end

        CT1 <--> CT2
        CT2 <--> CT3
        CT1 <--> CT3

        CT1 -.->|"metadata"| B1
        CT1 -.->|"metadata"| B2
        CT1 -.->|"metadata"| B3
    end

    P1 -->|"send"| B1
    P2 -->|"send"| B2
    B1 -->|"fetch"| C1
    B3 -->|"fetch"| C2

정리

이번 글에서는 카프카를 구성하는 핵심 요소들을 살펴보았습니다.

• 브로커가 메시지를 저장하고, 여러 브로커가 모여 클러스터를 이룹니다

• 프로듀서가 메시지를 보내고, 컨슈머가 메시지를 가져갑니다

• 컨트롤러가 클러스터를 관리하며, KRaft로 메타데이터를 자체 관리합니다

하지만 아직 답하지 못한 질문들이 있습니다.

• 메시지는 브로커 안에서 어떤 구조로 저장될까?

• 토픽과 파티션은 정확히 무엇이고, 왜 필요할까?

• 컨슈머의 오프셋은 어떻게 동작할까?

이 질문들에 대한 답은 다음 편인 **"토픽, 파티션, 오프셋"**에서 이어집니다.

부록: Q&A

Q1. 컨트롤러는 어떻게 선출되는가?

Q2. 컨슈머와 브로커는 어떤 프로토콜로 통신하는가?

Q3. 카프카가 높은 처리량을 가질 수 있는 이유는?

Q4. 브로커가 죽으면 어떤 일이 벌어지는가?

Q5. 하나의 서버에서 브로커와 컨트롤러를 동시에 실행할 수 있는가?

Q6. 카프카는 메시지 순서를 보장하는가?

이 글은 Apache Kafka 4.2 공식 문서를 기반으로 작성되었습니다.

C/C++ 개발자들이 malloc과 free로 메모리와 씨름하던 시절, Java는 Garbage Collector(GC)라는 자동 메모리 관리자를 들고 나왔다. 개발자는 객체를 만들기만 하면 되고, 치우는 건 GC가 알아서 한다.

하지만 "알아서"라는 말에는 대가가 있었다. GC가 동작하는 동안 애플리케이션이 멈추는 것이다. 이 멈춤을 Stop-The-World(STW) 일시 정지라고 부른다. Java GC의 역사는 이 일시 정지를 줄이기 위한 끊임없는 도전의 기록이다.

이 글은 Java GC의 진화를 세 시대로 나눠 살펴본다. G1GC 이전, G1GC, 그리고 G1GC 이후. 각 시대의 GC가 어떤 문제를 해결하려 했고, 어떤 한계를 남겼는지를 따라가 보자.

1부. G1GC 이전 — 단순함의 한계

Serial GC — 모든 것의 시작

Java 초기부터 존재해 온 가장 단순한 GC다. 이름 그대로, 단일 스레드로 동작한다.

App Threads:  ──────────┃ STW ┃──────────
GC Thread:              ┃█████┃

GC가 시작되면 모든 애플리케이션 스레드가 멈추고, GC 스레드 하나가 힙 전체를 정리한 뒤에야 애플리케이션이 다시 동작한다.

알고리즘은 두 가지를 조합한다:

• Young Generation: Mark-Copy — 살아있는 객체를 식별하고 새로운 영역에 복사
• Old Generation: Mark-Sweep-Compact — 살아있는 객체를 식별하고, 죽은 객체를 제거하고, 남은 객체를 압축

힙이 작고 CPU가 하나뿐인 환경에서는 이것으로 충분했다. 하지만 서버 환경에서 힙이 커지면서, GC 동안 애플리케이션이 수 초간 멈추는 것은 용납할 수 없었다.

-XX:+UseSerialGC

Parallel GC — 스레드를 늘려 처리량을 높이다

Serial GC의 해법은 단순했다. 스레드를 더 쓰자.

App Threads:  ──────────┃  STW  ┃──────────
GC Thread 1:            ┃██████ ┃
GC Thread 2:            ┃██████ ┃
GC Thread 3:            ┃██████ ┃
GC Thread 4:            ┃██████ ┃

여러 GC 스레드가 동시에 힙을 정리하므로, 같은 힙 크기에서 GC 시간이 크게 단축된다. 이름에 걸맞게 Throughput Collector라고도 불린다. 처리량(단위 시간당 처리하는 작업량)을 극대화하는 것이 목표다.

JDK 8까지 서버 환경의 기본 GC였다. -XX:GCTimeRatio=99로 GC 시간을 전체의 1% 이하로 유지하는 것이 기본 목표였고, -XX:+UseAdaptiveSizePolicy로 힙 크기를 자동 조절하는 기능도 갖추고 있었다.

하지만 근본적인 한계는 그대로였다. GC 동안 여전히 애플리케이션이 멈춘다. 스레드를 늘려서 STW 시간을 줄였을 뿐, STW 자체를 없앤 것이 아니다. 힙이 수 GB로 커지면 일시 정지가 수백 밀리초에서 수 초까지 늘어났다.

-XX:+UseParallelGC

CMS — 동시 수집의 첫 시도

Concurrent Mark Sweep(CMS)는 발상의 전환을 했다. GC 작업의 대부분을 애플리케이션과 동시에 수행하자는 것이다.

App Threads:  ─┃STW┃───────────────┃STW┃──
GC Threads:    ┃███┃▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒┃███┃
               Init  Concurrent     Remark
               Mark  Mark/Sweep

CMS는 4단계로 동작한다:

1. Initial Mark (STW) — GC Root에서 직접 참조하는 객체만 마킹. 짧은 일시 정지.
2. Concurrent Mark — 애플리케이션과 동시에 실행하며 참조 그래프를 순회. STW 없음.
3. Remark (STW) — Concurrent Mark 도중 변경된 참조를 보정. 짧은 일시 정지.
4. Concurrent Sweep — 죽은 객체를 제거. STW 없음.

핵심은 가장 시간이 오래 걸리는 Mark와 Sweep을 동시(Concurrent)에 처리한다는 것이다. STW는 Initial Mark와 Remark에서만 발생하고, 이 두 단계는 상대적으로 짧다.

혁신적이었지만, CMS에는 치명적인 약점이 있었다:

• 메모리 단편화: Sweep 후 Compact(압축)를 하지 않으므로, 힙에 빈 공간이 흩어진다. 큰 객체를 할당할 연속 공간이 없으면 Full GC가 발생한다.
• Concurrent Mode Failure: GC가 끝나기 전에 Old Generation이 가득 차면, Serial GC로 폴백하여 긴 STW가 발생한다.
• 복잡한 튜닝: CMS 전용 옵션만 72개. 일반 GC 옵션 50개까지 합치면 120개 이상의 매개변수를 다뤄야 했다.

결국 CMS는 JDK 9에서 deprecated, JDK 14에서 완전 제거되었다. JEP 363은 제거 사유로 "유지보수를 맡을 기여자가 없다"고 밝혔다. 72개의 튜닝 옵션이 만든 복잡성의 당연한 귀결이었다.

G1GC 이전 시대의 교훈

세 GC를 관통하는 딜레마가 있다. 처리량(Throughput)과 지연 시간(Latency)은 트레이드오프라는 것이다.

이 트레이드오프를 근본적으로 해결하려면, 힙을 관리하는 방식 자체를 바꿔야 했다. 그것이 G1GC다.

2부. G1GC — 힙을 쪼개다

Region이라는 발상

G1GC 이전의 모든 GC는 힙을 연속된 두 영역(Young, Old)으로 나눴다. G1GC는 이 구조를 완전히 바꿨다.

flowchart LR
    subgraph Heap["G1GC Heap — Region-based Layout"]
        direction LR
        E1["Eden"] --- E2["Eden"] --- S1["Survivor"]
        S1 --- O1["Old"] --- O2["Old"] --- H1["Humongous"]
        H1 --- E3["Eden"] --- O3["Old"] --- Free1["Free"]
        Free1 --- O4["Old"] --- E4["Eden"] --- Free2["Free"]
    end

    style E1 fill:#90EE90
    style E2 fill:#90EE90
    style E3 fill:#90EE90
    style E4 fill:#90EE90
    style S1 fill:#FFD700
    style O1 fill:#87CEEB
    style O2 fill:#87CEEB
    style O3 fill:#87CEEB
    style O4 fill:#87CEEB
    style H1 fill:#FF6347
    style Free1 fill:#f5f5f5
    style Free2 fill:#f5f5f5

힙을 동일한 크기의 Region(1~32MB)으로 쪼갠다. 각 Region은 Eden, Survivor, Old, Humongous(대형 객체용) 중 하나의 역할을 동적으로 맡는다. 고정된 영역 경계가 없다.

이 구조가 혁명적인 이유는, 전체 힙을 수집할 필요가 없어졌기 때문이다.

Garbage-First — 쓰레기가 많은 곳부터

G1GC의 이름인 Garbage-First는 동작 방식 그 자체다. 모든 Region의 "쓰레기 비율"을 추적하고, 쓰레기가 가장 많은 Region부터 수집한다.

Garbage ratio per Region:

Region A: ████████░░  80% garbage  ← collect first
Region B: ██████░░░░  60% garbage  ← next
Region C: ██░░░░░░░░  20% garbage  ← later
Region D: █░░░░░░░░░  10% garbage  ← if time permits

핵심은 예측 가능한 일시 정지 시간이다. -XX:MaxGCPauseMillis=200 (기본값)으로 목표 일시 정지 시간을 설정하면, G1GC는 그 시간 안에 수집할 수 있는 만큼만 Region을 선택한다. 200ms 안에 모든 Region을 수집하지 못해도 괜찮다. 쓰레기가 많은 곳부터 했으니, 제한된 시간 안에 최대한의 공간을 확보한 셈이다.

G1GC의 동작 사이클

Young GC (STW)
    │
    ▼
Concurrent Mark (Mostly Concurrent)
    │   ├── Initial Mark (STW, piggybacks on Young GC)
    │   ├── Root Region Scan
    │   ├── Concurrent Mark
    │   ├── Remark (STW)
    │   └── Cleanup (STW + Concurrent)
    ▼
Mixed GC (STW)  ← Young + high-garbage Old Regions

G1GC는 세 가지 모드로 동작한다:

1. Young GC: Eden이 가득 차면 발생. 살아남은 객체를 Survivor 또는 Old Region으로 이동.
2. Concurrent Mark: Old 영역의 사용량이 임계치(-XX:InitiatingHeapOccupancyPercent, 기본 45%)를 넘으면 시작. 어떤 Region에 쓰레기가 많은지 파악.
3. Mixed GC: Concurrent Mark 결과를 바탕으로, Young Region과 쓰레기가 많은 Old Region을 함께 수집.

CMS와 비교하면:

G1GC의 위상

• JDK 6u14: 실험적 도입
• JDK 7u4: 정식 지원
• JDK 9: 기본 GC로 채택 (Parallel GC를 대체)

G1GC는 현재까지도 가장 널리 사용되는 GC다. 대부분의 서버 애플리케이션에서 별도 튜닝 없이도 양호한 성능을 제공한다. 하지만 G1GC도 완벽하지 않다. 일시 정지 시간의 목표를 설정할 수는 있지만, 보장하지는 못한다. 힙이 수십 GB로 커지면, 일시 정지가 수백 밀리초에 이를 수 있다.

금융 거래 시스템, 실시간 데이터 처리, 대규모 인메모리 데이터베이스 — 이런 워크로드는 밀리초 단위의 일시 정지도 허용할 수 없다. 그래서 다음 세대가 필요했다.

3부. G1GC 이후 — 일시 정지를 밀리초 미만으로

ZGC — 힙 크기와 무관한 일시 정지

Z Garbage Collector(ZGC)는 JDK 11에서 실험적으로 등장하고, JDK 15에서 정식 지원된 초저지연 GC다. 설계 목표는 명확하다:

힙 크기에 관계없이 일시 정지 시간을 1ms 미만으로 유지한다.

8MB 힙이든 16TB 힙이든, 일시 정지 시간이 동일하다. 어떻게 가능할까?

ZGC의 핵심 기술은 Colored Pointers와 Load Barriers다.

Colored Pointers: ZGC는 객체 참조(포인터)의 상위 비트에 GC 메타데이터를 저장한다. 포인터 자체에 "이 객체가 이동되었는지", "마킹되었는지" 같은 정보가 담겨 있다. 별도의 마킹 비트맵을 참조할 필요가 없으므로, GC 상태 확인이 매우 빠르다.

Load Barriers: 애플리케이션이 객체 참조를 읽을 때 가로채서, 해당 참조가 최신 상태인지 확인한다. 객체가 이동되었다면 새 주소로 투명하게 갱신한다. 이 덕분에 ZGC는 객체 이동(Compaction)을 애플리케이션과 동시에 수행할 수 있다.

G1GC pause:

  ──────┃████████████████████┃──────
        ← tens~hundreds ms →

ZGC pause:

  ──────┃█┃───────────────────┃█┃──
        ←→                    ←→
       ~0.05ms              ~0.05ms

실제 벤치마크에서 ZGC의 평균 일시 정지 시간은 약 50μs(마이크로초), 최대 일시 정지 시간은 약 500μs로 측정되었다. G1GC가 20ms 이상의 일시 정지를 보이는 것과 비교하면, 평균 기준으로 400배 이상의 차이다.

-XX:+UseZGC

Generational ZGC — 세대를 되찾다

초기 ZGC에는 한 가지 약점이 있었다. 세대 구분이 없었다. 매번 힙 전체를 대상으로 GC를 수행해야 했고, 이는 두 가지 문제를 만들었다:

1. 처리량 손실: 수명이 짧은 객체(Young)도 긴 수명 객체(Old)와 같은 비용으로 수집
2. 할당 지연(Allocation Stall): GC가 메모리를 회수하는 속도보다 애플리케이션이 메모리를 할당하는 속도가 빠르면, 애플리케이션이 GC 완료를 기다려야 함

Netflix의 기술 블로그에 따르면, 동시 클라이언트 75개를 넘어서면 단일 세대 ZGC에서 할당 지연이 급격히 발생했다.

JDK 21에서 도입된 Generational ZGC(JEP 439)는 이 문제를 해결했다. "대부분의 객체는 금방 죽는다"는 약한 세대 가설(Weak Generational Hypothesis)을 ZGC에도 적용한 것이다.

Single-Generation ZGC:

  ┌───────────────────────────────────────┐
  │  Entire heap collected every cycle    │
  └───────────────────────────────────────┘

Generational ZGC:

  ┌──────────────┐  ┌────────────────────┐
  │    Young     │  │       Old          │
  │  frequent    │  │   infrequent       │
  └──────────────┘  └────────────────────┘

Young 객체를 자주, 빠르게 수집하고, Old 객체는 필요할 때만 수집한다. 결과는:

Generational ZGC는 JDK 21에서 정식 기능으로 도입되었고(단, 명시적 활성화 필요), JDK 23부터 기본 ZGC 모드가 되었다.

# JDK 21~22
-XX:+UseZGC -XX:+ZGenerational

# JDK 23+
-XX:+UseZGC  (Generational이 기본)

전체 타임라인

어떤 GC를 선택할 것인가

flowchart TD
    Start["What matters most?"] --> T["Throughput"]
    Start --> L["Latency"]
    Start --> B["Balance"]

    T --> Parallel["Parallel GC\n-XX:+UseParallelGC"]
    L --> HeapSize{"Heap > 4GB?"}
    B --> G1["G1GC\n-XX:+UseG1GC"]

    HeapSize -->|Yes| ZGC["ZGC\n-XX:+UseZGC"]
    HeapSize -->|No| G1

    style Parallel fill:#90EE90
    style G1 fill:#87CEEB
    style ZGC fill:#FFD700

확신이 없다면? G1GC를 쓰면 된다. JDK 9부터 기본 GC이고, 대부분의 워크로드에서 튜닝 없이도 충분한 성능을 제공한다. 일시 정지가 문제가 된다면 그때 ZGC를 고려하면 된다.

마무리

Java GC의 역사를 한 줄로 요약하면 이렇다:

"애플리케이션을 멈추지 않으면서, 어떻게 메모리를 회수할 것인가?"

Serial GC는 모든 것을 멈추고 청소했다. Parallel GC는 여러 명이 함께 청소해서 시간을 줄였다. CMS는 청소하면서 동시에 일도 했지만, 정리 정돈은 포기했다. G1GC는 구역을 나눠 효율적으로 관리했다. ZGC는 거의 멈추지 않는 경지에 이르렀다.

각 세대의 GC는 이전 세대의 한계를 넘기 위해 탄생했다. 그리고 이 진화는 계속되고 있다. Generational ZGC, Generational Shenandoah — 아직 끝나지 않았다.

중요한 것은 "최신 GC가 최고"가 아니라는 점이다. 배치 처리에 ZGC를 쓸 이유는 없고, 실시간 거래 시스템에 Serial GC를 쓸 이유도 없다. 자신의 워크로드를 이해하고, 그에 맞는 GC를 선택하는 것. 그것이 GC의 역사가 우리에게 남긴 교훈이다.

참고 자료

• JDK 21: The GCs keep getting better — JDK 21 GC 성능 벤치마크
• Introducing Generational ZGC – Inside.java — Oracle 공식 Generational ZGC 해설
• Bending pause times to your will with Generational ZGC | Netflix — Netflix의 Generational ZGC 적용기
• CMS GC algorithm removed from Java 14 | GCeasy — CMS 제거 배경
• How to choose the best Java garbage collector | Red Hat — GC 선택 가이드
• The Evolution of Garbage Collection in Java — Java GC 진화 타임라인

@Autowired를 붙이면 객체가 알아서 들어오고, @Transactional을 붙이면 트랜잭션이 알아서 관리되고, @Cacheable을 붙이면 캐시가 알아서 동작했다. "알아서"라는 말 뒤에 숨은 원리를 몰랐다. 그냥 마법이라고 생각했다.

그러다 문제가 생겼다. @Transactional을 붙였는데 롤백이 안 됐다. 같은 클래스 안에서 메서드를 호출했기 때문이었다. 원인을 찾는 데 반나절이 걸렸고, 결국 Spring AOP의 프록시 동작 원리를 이해하고 나서야 해결할 수 있었다.

그날 깨달았다. 어노테이션 뒤에 숨은 철학을 모르면, 문제가 생겼을 때 속수무책이라는 것을.

Spring Framework는 세 가지 핵심 철학 위에 서 있다. DI(Dependency Injection), AOP(Aspect-Oriented Programming), PSA(Portable Service Abstraction). 이 세 가지는 독립적인 기술이 아니라, 서로 맞물려 돌아가는 톱니바퀴다. 이 글은 각 철학이 왜 필요하고, 어떻게 동작하며, 어떤 문제를 해결하는지를 코드와 함께 파헤친다.

1. DI — 객체의 생사여탈권을 넘기다

의존성이란 무엇인가

public class OrderService {
    private final OrderRepository repository = new JdbcOrderRepository();

    public void placeOrder(Order order) {
        repository.save(order);
    }
}

이 코드의 문제가 보이는가? OrderService가 JdbcOrderRepository를 직접 생성하고 있다. OrderService는 OrderRepository의 구현체가 무엇인지 알고 있고, 그 생성 방법까지 알고 있다. 이것이 강한 결합(tight coupling)이다.

만약 데이터베이스를 MongoDB로 바꿔야 한다면? OrderService의 코드를 수정해야 한다. 테스트에서 가짜 저장소를 쓰고 싶다면? 역시 코드를 수정해야 한다. 사용하는 쪽이 구현체를 알고 있으면, 구현체가 바뀔 때 사용하는 쪽도 바뀌어야 한다.

제어의 역전 — 내가 만들지 않겠다

DI의 핵심은 Inversion of Control(IoC), 제어의 역전이다. 객체를 내가 만들지 않고, 외부에서 만들어서 넣어주는 것이다.

public class OrderService {
    private final OrderRepository repository;

    public OrderService(OrderRepository repository) {
        this.repository = repository;
    }

    public void placeOrder(Order order) {
        repository.save(order);
    }
}

OrderService는 이제 OrderRepository가 JDBC인지, JPA인지, MongoDB인지 모른다. 인터페이스에만 의존한다. 구현체는 외부(Spring 컨테이너)가 결정하고 주입한다.

@Configuration
public class AppConfig {
    @Bean
    public OrderRepository orderRepository() {
        return new JpaOrderRepository();
    }

    @Bean
    public OrderService orderService(OrderRepository orderRepository) {
        return new OrderService(orderRepository);
    }
}

이제 저장소를 바꾸고 싶으면 AppConfig만 수정하면 된다. OrderService는 건드릴 필요가 없다.

생성자 주입이 권장되는 진짜 이유

Spring에서 DI를 하는 방법은 세 가지다. 필드 주입, 세터 주입, 생성자 주입. Spring 공식 문서는 생성자 주입을 권장한다. 왜일까?

필드 주입의 문제:

@Service
public class OrderService {
    @Autowired
    private OrderRepository repository;  // final이 아니다
}

생성자 주입의 장점:

@Service
public class OrderService {
    private final OrderRepository repository;  // final 선언 가능

    public OrderService(OrderRepository repository) {
        this.repository = repository;
    }
}

차이는 final 한 글자에 있다. 하지만 이 한 글자가 만드는 차이는 크다.

생성자의 파라미터가 10개가 넘어간다면? 그것은 생성자 주입의 문제가 아니라, 그 클래스가 너무 많은 책임을 지고 있다는 신호다. 생성자 주입은 이 신호를 눈에 보이게 만들어준다. 필드 주입은 이 신호를 숨긴다.

DI가 만드는 변화

DI는 단순히 "객체를 대신 만들어주는 편의 기능"이 아니다. DI는 설계를 바꾼다.

• 구현이 아닌 인터페이스에 의존하게 만든다 (DIP — 의존 역전 원칙)
• 객체의 생성과 사용을 분리한다 (SRP — 단일 책임 원칙)
• 구현체를 자유롭게 교체할 수 있게 만든다 (OCP — 개방-폐쇄 원칙)

DI는 SOLID 원칙을 코드에 자연스럽게 녹이는 장치다.

2. AOP — 흩어진 관심사를 한 곳에 모으다

OOP의 시선, AOP의 시선

전통적인 객체지향 프로그래밍에서 우리는 코드를 가로로 바라본다. Controller → Service → Repository, 레이어를 따라 위에서 아래로 흐르는 비즈니스 로직에 집중한다.

그런데 로깅, 트랜잭션, 보안 같은 관심사는 이 가로 흐름을 세로로 관통한다. 모든 레이어에 동일한 코드가 반복된다. OOP는 이 세로 방향의 중복을 해결할 도구가 없다.

flowchart TB
    subgraph Layer["OOP — Business Logic Flow →"]
        direction LR
        subgraph OrderService
            O1["placeOrder()"] --> O2["save()"] --> O3["insert()"]
        end
        subgraph PaymentService
            P1["process()"] --> P2["charge()"] --> P3["update()"]
        end
        subgraph NotificationService
            N1["notify()"] --> N2["send()"] --> N3["insert()"]
        end
    end

    subgraph AOP["AOP — Cross-Cutting Concerns ↓"]
        direction TB
        Logging["Logging"]
        Transaction["Transaction"]
        Security["Security"]
    end

    Logging -.-> O1 & P1 & N1
    Transaction -.-> O2 & P2 & N2
    Security -.-> O3 & P3 & N3

    style AOP fill:#f0e6ff,stroke:#9966cc
    style Logging fill:#f9f,stroke:#333
    style Transaction fill:#f9f,stroke:#333
    style Security fill:#f9f,stroke:#333

OOP의 시선은 가로(→)다. Controller → Service → Repository, 비즈니스 로직의 흐름을 따라간다. AOP의 시선은 세로(↑)다. 로깅, 트랜잭션, 보안이 모든 모듈을 관통한다.

OOP가 가로(비즈니스 로직의 흐름)를 모듈화한다면, AOP는 세로(여러 모듈을 관통하는 공통 관심사)를 모듈화한다. 관점(Aspect)이라는 이름이 붙은 이유가 여기에 있다. 코드를 바라보는 관점 자체를 바꾸는 것이다.

이 시선의 전환을 이해하면, AOP가 OOP를 대체하는 것이 아니라 보완하는 기술이라는 것이 명확해진다.

문제: 코드 전체에 퍼진 로깅

@Service
public class OrderService {
    public void placeOrder(Order order) {
        long start = System.currentTimeMillis();
        log.info("placeOrder 시작: {}", order.getId());
        try {
            // 비즈니스 로직
            orderRepository.save(order);
            paymentService.process(order);
            notificationService.notify(order);
        } finally {
            long elapsed = System.currentTimeMillis() - start;
            log.info("placeOrder 완료: {}ms", elapsed);
        }
    }
}

@Service
public class PaymentService {
    public void process(Order order) {
        long start = System.currentTimeMillis();
        log.info("process 시작: {}", order.getId());
        try {
            // 비즈니스 로직
            paymentGateway.charge(order.getAmount());
        } finally {
            long elapsed = System.currentTimeMillis() - start;
            log.info("process 완료: {}ms", elapsed);
        }
    }
}

실행 시간을 측정하는 로깅 코드가 모든 서비스에 복붙되어 있다. 이것이 횡단 관심사(Cross-Cutting Concern)다. 비즈니스 로직과는 무관하지만, 여러 모듈에 가로질러 존재하는 코드다.

횡단 관심사의 대표적인 예:

• 로깅/모니터링
• 트랜잭션 관리
• 보안/인증
• 캐싱
• 예외 처리

이런 코드를 각 서비스에 직접 작성하면 두 가지 문제가 생긴다. 비즈니스 로직이 부가 로직에 파묻히고, 변경이 필요할 때 모든 서비스를 수정해야 한다.

AOP의 해결책 — 관심사를 분리하다

AOP는 이 횡단 관심사를 Aspect라는 모듈로 분리한다.

@Aspect
@Component
public class ExecutionTimeAspect {

    @Around("execution(* com.example.service.*.*(..))")
    public Object measureExecutionTime(ProceedingJoinPoint joinPoint) throws Throwable {
        long start = System.currentTimeMillis();
        String methodName = joinPoint.getSignature().getName();
        log.info("{} 시작", methodName);
        try {
            return joinPoint.proceed();
        } finally {
            long elapsed = System.currentTimeMillis() - start;
            log.info("{} 완료: {}ms", methodName, elapsed);
        }
    }
}

이제 OrderService와 PaymentService에서 로깅 코드를 모두 제거할 수 있다. 비즈니스 로직만 남는다.

@Service
public class OrderService {
    public void placeOrder(Order order) {
        orderRepository.save(order);
        paymentService.process(order);
        notificationService.notify(order);
    }
}

서비스는 자신의 핵심 로직에만 집중한다. 로깅이라는 관심사는 Aspect가 담당한다. 로깅 방식을 바꾸고 싶으면 Aspect 하나만 수정하면 된다.

프록시 — AOP의 동작 원리

여기서 "왜?"라는 질문을 던져야 한다. Aspect의 코드가 서비스에 없는데, 어떻게 실행되는 걸까?

답은 프록시(Proxy)에 있다. Spring은 AOP가 적용된 빈을 생성할 때, 원본 객체 대신 프록시 객체를 만들어 컨테이너에 등록한다.

호출자 → [프록시] → 원본 객체
              │
              ├── Before Advice 실행
              ├── 원본 메서드 호출
              └── After Advice 실행

Spring Boot 2.0부터는 CGLIB 프록시를 기본으로 사용한다. CGLIB은 대상 클래스의 서브클래스를 런타임에 생성하여 메서드를 오버라이드하는 방식으로 프록시를 만든다.

이 프록시 메커니즘을 이해하면, 아까 내가 겪었던 문제의 원인이 명확해진다.

self-invocation 문제 — 프록시의 함정

@Service
public class OrderService {

    @Transactional
    public void placeOrder(Order order) {
        orderRepository.save(order);
        this.sendNotification(order);  // ← 프록시를 거치지 않는다!
    }

    @Transactional(propagation = Propagation.REQUIRES_NEW)
    public void sendNotification(Order order) {
        notificationRepository.save(new Notification(order));
    }
}

placeOrder()에서 this.sendNotification()을 호출하면, sendNotification()의 @Transactional이 동작하지 않는다. 왜? this는 프록시가 아니라 원본 객체이기 때문이다.

외부 호출자 → [프록시] → placeOrder()
                              │
                              └── this.sendNotification()  ← 프록시를 우회!

외부에서 orderService.sendNotification()을 호출하면 프록시를 거치므로 @Transactional이 동작한다. 하지만 같은 클래스 내부에서 this로 호출하면 프록시를 건너뛰고 원본 메서드가 직접 호출된다.

해결 방법: sendNotification()을 별도의 빈으로 분리하거나, ApplicationContext에서 프록시를 직접 가져와 호출한다. 근본적으로는 클래스의 책임을 분리하는 것이 올바른 접근이다.

이런 함정은 프록시 기반 AOP의 동작 원리를 이해해야만 피할 수 있다. 마법이 아니라 메커니즘으로 이해해야 하는 이유다.

3. PSA — 기술을 갈아끼워도 코드는 그대로

프레임워크에 종속된 코드의 시대

Spring 이전, Java 엔터프라이즈의 표준은 EJB(Enterprise JavaBeans)였다. EJB로 비즈니스 로직을 작성하려면 이런 코드가 필요했다.

// EJB 2.x 시절의 서비스 코드
public class OrderServiceBean implements SessionBean {
    private SessionContext ctx;

    public void setSessionContext(SessionContext ctx) { this.ctx = ctx; }
    public void ejbCreate() {}
    public void ejbRemove() {}
    public void ejbActivate() {}
    public void ejbPassivate() {}

    // 겨우 여기서부터 비즈니스 로직
    public void placeOrder(Order order) {
        // ...
    }
}

SessionBean 인터페이스를 구현해야 하고, ejbCreate, ejbRemove 같은 생명주기 메서드를 강제로 오버라이드해야 한다. 비즈니스 로직은 프레임워크 코드에 파묻힌다. 이 클래스는 EJB 컨테이너에 강하게 의존하기 때문에, 컨테이너 없이는 일반적인 단위 테스트가 사실상 불가능에 가까웠다. 코드가 프레임워크에 종속된 것이다.

Spring은 이 문제를 근본적으로 다르게 접근했다. 같은 비즈니스 로직을 Spring에서는 이렇게 작성한다.

// Spring의 서비스 코드
public class OrderService {
    private final OrderRepository repository;

    public OrderService(OrderRepository repository) {
        this.repository = repository;
    }

    public void placeOrder(Order order) {
        repository.save(order);
    }
}

프레임워크 클래스를 상속하지 않는다. 특정 인터페이스를 구현하지 않는다. 순수한 Java 객체, POJO다. 이 클래스는 Spring 없이도 new OrderService(mockRepo)로 인스턴스를 만들어 테스트할 수 있다.

그렇다면 트랜잭션, 캐싱, 보안 같은 엔터프라이즈 기능은 누가 처리하는가? 바로 PSA다. Spring이 추상화 계층을 제공하고, 개발자의 POJO 위에 기능을 입혀주는 것이다. 개발자는 @Transactional 하나만 선언하면 되고, 그 뒤의 복잡한 트랜잭션 관리는 Spring의 추상화가 처리한다.

정리하면 PSA에는 두 가지 측면이 있다:

• Spring 내부의 메커니즘 — PlatformTransactionManager 같은 인터페이스로 구현체를 추상화한다
• 개발자가 얻는 결과 — 비즈니스 코드가 프레임워크에 종속되지 않는 POJO로 남는다

인터페이스 추상화는 Spring 쪽의 이야기이고, POJO는 개발자 쪽의 이야기다. 둘은 동전의 양면이다.

추상화가 없는 세계

만약 Spring의 트랜잭션 추상화가 없다면, JDBC로 트랜잭션을 관리하는 코드는 이렇게 생겼을 것이다.

public void placeOrder(Order order) throws SQLException {
    Connection conn = dataSource.getConnection();
    try {
        conn.setAutoCommit(false);

        // 비즈니스 로직
        PreparedStatement ps = conn.prepareStatement("INSERT INTO orders ...");
        ps.executeUpdate();

        conn.commit();
    } catch (Exception e) {
        conn.rollback();
        throw e;
    } finally {
        conn.close();
    }
}

비즈니스 로직이 JDBC API에 완전히 종속되어 있다. 여기서 JPA로 전환하려면? 코드를 전부 다시 작성해야 한다. Connection, PreparedStatement, commit(), rollback() — 이 모든 것이 JDBC라는 특정 기술에 묶여 있기 때문이다.

PSA — 기술 위에 놓인 추상화 계층

PSA는 Portable Service Abstraction, 이동 가능한 서비스 추상화다. 특정 기술에 종속되지 않고, 추상화된 인터페이스를 통해 일관된 방식으로 기술을 사용할 수 있게 한다.

Spring의 트랜잭션 추상화를 보자. 핵심은 PlatformTransactionManager 인터페이스다.

public interface PlatformTransactionManager extends TransactionManager {
    TransactionStatus getTransaction(TransactionDefinition definition)
            throws TransactionException;
    void commit(TransactionStatus status) throws TransactionException;
    void rollback(TransactionStatus status) throws TransactionException;
}

이 인터페이스의 구현체는 기술에 따라 달라진다:

리액티브 환경에서는 별도의 ReactiveTransactionManager 인터페이스와 R2dbcTransactionManager 구현체가 존재한다. 명령형과 리액티브의 트랜잭션 관리가 완전히 분리된 것도 PSA 설계의 일부다.

하지만 개발자는 이 구현체를 직접 다루지 않는다. @Transactional 하나면 된다.

@Service
public class OrderService {

    @Transactional
    public void placeOrder(Order order) {
        orderRepository.save(order);
        paymentService.process(order);
    }
}

JDBC를 쓰든, JPA를 쓰든, R2DBC를 쓰든 — 이 코드는 변하지 않는다. 기술이 바뀌면 Spring이 알아서 다른 TransactionManager 구현체를 주입할 뿐이다. 이것이 Portable, 이동 가능하다는 의미다.

PSA가 적용된 곳들

@Transactional만 PSA인 것이 아니다. Spring 곳곳에 PSA가 녹아 있다.

캐시 추상화:

@Service
public class ProductService {

    @Cacheable("products")
    public Product findById(Long id) {
        return productRepository.findById(id).orElseThrow();
    }
}

@Cacheable 뒤에서 동작하는 CacheManager의 구현체는 바뀔 수 있다.

Caffeine에서 Redis로 캐시를 교체해도 @Cacheable이 붙은 서비스 코드는 한 줄도 바뀌지 않는다. 의존성과 설정만 바꾸면 된다.

Spring Data:

public interface OrderRepository extends JpaRepository<Order, Long> {
    List<Order> findByCustomerId(Long customerId);
}

이 인터페이스는 JPA에 종속된 것처럼 보이지만, Spring Data의 추상화 덕분에 같은 패턴으로 다양한 저장소를 사용할 수 있다.

메서드 이름 기반 쿼리 생성, 페이징, 정렬 — 이 모든 기능이 저장소 기술에 관계없이 동일한 방식으로 동작한다.

PSA의 본질 — DIP를 프레임워크 레벨에서 실현하다

PSA의 구조를 도식화하면 이렇다:

[내 애플리케이션 코드]
        │
        ▼
[Spring 추상화 계층]  ←── @Transactional, @Cacheable, Repository
        │
        ▼
[구현체]  ←── JpaTransactionManager, RedisCacheManager, ...
        │
        ▼
[실제 기술]  ←── Hibernate, Redis, Elasticsearch, ...

내 코드는 Spring의 추상화 계층에만 의존한다. 그 아래의 구현체와 실제 기술은 설정으로 교체할 수 있다. 이것은 앞서 살펴본 DI의 의존 역전 원칙(DIP)을 프레임워크 레벨에서 대규모로 적용한 것이다.

4. 세 철학의 연결 — 하나의 목표를 향해

DI, AOP, PSA는 독립적으로 존재하지 않는다. 서로 맞물려 돌아간다.

@Transactional 하나를 예로 들어보자. 이 어노테이션이 동작하려면 세 가지 철학이 모두 필요하다:

1. PSA — @Transactional은 PlatformTransactionManager라는 추상화에 의존한다. 기술에 종속되지 않는다.
2. AOP — @Transactional이 붙은 메서드를 프록시가 감싸서, 메서드 실행 전후에 트랜잭션을 시작하고 커밋/롤백한다.
3. DI — 프록시가 사용할 TransactionManager 구현체를 Spring 컨테이너가 주입한다.

@Transactional이 동작하는 과정:

1. [DI]  Spring 컨테이너가 JpaTransactionManager를 생성하고 주입
2. [AOP] 프록시가 메서드 호출을 가로챔
3. [PSA] PlatformTransactionManager.getTransaction() 호출
4.       원본 메서드 실행
5. [PSA] 성공 시 commit(), 예외 시 rollback()

DI가 없으면 AOP의 프록시가 올바른 TransactionManager를 받을 수 없다. AOP가 없으면 @Transactional을 메서드에 선언하는 것만으로는 트랜잭션이 적용되지 않는다. PSA가 없으면 기술이 바뀔 때마다 트랜잭션 로직을 다시 작성해야 한다.

세 철학이 향하는 궁극적 목표는 하나다. POJO 기반의 엔터프라이즈 개발. 비즈니스 로직을 담은 객체가 특정 프레임워크나 기술에 종속되지 않고, 순수한 Java 객체로 남을 수 있게 하는 것이다.

// 이 클래스는 Spring에 대해 아무것도 모른다.
// 하지만 DI, AOP, PSA 덕분에 트랜잭션, 캐싱, 로깅이 모두 적용된다.
public class OrderService {
    private final OrderRepository repository;

    public OrderService(OrderRepository repository) {
        this.repository = repository;
    }

    public void placeOrder(Order order) {
        repository.save(order);
    }
}

Spring의 어노테이션을 모두 걷어내도 이 클래스는 컴파일되고, 테스트되고, 동작한다. 이것이 Spring이 추구하는 코드의 품격이다.

마무리

Spring을 쓰면서 @Autowired, @Transactional, @Cacheable을 "그냥 붙이면 되는 것"으로 생각했다면, 이제는 그 뒤에서 세 가지 철학이 어떻게 맞물려 돌아가는지 보일 것이다.

• DI — 객체의 생성과 사용을 분리하여, 느슨한 결합과 유연한 구조를 만든다
• AOP — 횡단 관심사를 분리하여, 비즈니스 로직을 깨끗하게 유지한다
• PSA — 기술을 추상화하여, 구현체가 바뀌어도 코드가 바뀌지 않게 한다

이 세 가지는 결국 하나의 목표를 향한다. 내 코드가 특정 기술에 종속되지 않고, 변화에 유연하게 대응할 수 있는 구조를 만드는 것. Spring이 20년 넘게 Java 생태계의 표준으로 자리 잡은 이유가 여기에 있다.

어노테이션 뒤의 원리를 이해하자. 그래야 마법이 풀렸을 때 당황하지 않는다.

참고 자료

• Spring Framework Core - IoC Container — Spring 공식 IoC/DI 문서
• Spring Framework Core - AOP — Spring 공식 AOP 문서
• Understanding the Spring Framework Transaction Abstraction — Spring 트랜잭션 추상화 공식 문서
• Proxying Mechanisms :: Spring Framework — Spring AOP 프록시 메커니즘 공식 문서
• 왜 Constructor Injection을 사용해야 하는가? | Tecoble — 생성자 주입 권장 이유
• Spring PSA(Portable Service Abstraction) — PSA 개념 설명

FROM openjdk:17
COPY build/libs/app.jar app.jar
ENTRYPOINT ["java", "-jar", "app.jar"]

동작은 했다. 하지만 이미지 크기는 700MB를 넘겼고, 코드 한 줄 고칠 때마다 전체 JAR를 다시 빌드해야 했다. 프로덕션에 올릴 때는 root 권한으로 실행되고 있었다. "동작한다"와 "잘 동작한다"는 다르다는 걸 깨닫는 데 오래 걸리지 않았다.

이 글은 내가 Spring Boot Dockerfile을 다듬어가며 했던 고민의 기록이다. 한 줄 한 줄에 "왜?"라는 질문을 던지고, 그 답을 찾아가는 과정을 공유한다.

최종 Dockerfile

먼저 완성된 Dockerfile을 보자. 이후 섹션에서 각 부분의 고민을 하나씩 풀어간다.

ARG JAR_FILE=application-api/build/libs/application-api-*-SNAPSHOT.jar

FROM eclipse-temurin:24-jre AS extractor
ARG JAR_FILE
WORKDIR /extractor
COPY ${JAR_FILE} app.jar
RUN java -Djarmode=tools -jar app.jar extract --layers --launcher --destination extracted

FROM eclipse-temurin:24-jre
WORKDIR /app
ENV TZ=UTC

RUN groupadd -r appgroup && useradd -r -g appgroup appuser && chown -R appuser:appgroup /app

COPY --from=extractor --chown=appuser:appgroup /extractor/extracted/dependencies/ ./
COPY --from=extractor --chown=appuser:appgroup /extractor/extracted/spring-boot-loader/ ./
COPY --from=extractor --chown=appuser:appgroup /extractor/extracted/snapshot-dependencies/ ./
COPY --from=extractor --chown=appuser:appgroup /extractor/extracted/application/ ./

USER appuser
EXPOSE 8080

ENTRYPOINT ["java", \
    "-XX:+UseContainerSupport", \
    "-XX:MaxRAMPercentage=75.0", \
    "-Djava.security.egd=file:/dev/./urandom", \
    "org.springframework.boot.loader.launch.JarLauncher"]

1. 멀티 스테이지 빌드 — 빌드와 실행을 분리하다

가장 먼저 눈에 들어오는 건 FROM이 두 번 등장한다는 점이다. 이것이 멀티 스테이지 빌드다.

첫 번째 스테이지(extractor)에서는 JAR 파일을 레이어별로 추출한다. 두 번째 스테이지에서는 추출된 결과물만 복사해서 최종 이미지를 만든다.

왜 이렇게 나눌까? 최종 이미지에 불필요한 것을 남기지 않기 위해서다.

만약 빌드 도구(Gradle, Maven)까지 포함된 단일 스테이지를 쓴다면, 빌드에만 필요한 도구들이 프로덕션 이미지에 고스란히 남는다. 이미지 크기가 커지는 건 물론이고, 공격자가 컨테이너에 침입했을 때 활용할 수 있는 도구가 늘어난다.

이 Dockerfile에서는 빌드 자체는 CI 환경에서 이미 완료되었다고 가정하고, JAR 파일의 추출과 실행만 컨테이너 안에서 처리한다. 빌드와 실행의 관심사를 깔끔하게 분리하는 것이다.

2. 왜 JRE인가 — JDK를 프로덕션에서 쓰지 않는 이유

FROM eclipse-temurin:24-jre AS extractor

베이스 이미지로 eclipse-temurin:24-jre를 선택했다. JDK가 아니라 JRE다.

JDK(Java Development Kit)에는 컴파일러(javac), 디버거, 프로파일러 등 개발 도구가 포함되어 있다. 프로덕션에서 이것들이 필요할까? 필요 없다. 애플리케이션을 실행만 하면 된다.

크기 차이도 무시할 수 없다. 같은 버전 기준으로 JDK 이미지는 JRE 이미지보다 2~3배 이상 크다. 컴파일러, 헤더 파일, 개발 도구 등이 모두 포함되기 때문이다.

하지만 크기보다 중요한 건 보안이다. JDK에 포함된 javac, jdb 같은 도구는 공격자에게 유용한 무기가 될 수 있다. 컨테이너가 침해되었을 때, 개발 도구가 없는 환경은 공격자의 행동 반경을 크게 제한한다.

Eclipse Temurin을 선택한 이유는 Adoptium 프로젝트에서 관리하는 검증된 OpenJDK 빌드이기 때문이다. LTS 지원, 정기적인 보안 패치, Docker Hub 공식 이미지 지원까지 갖추고 있어 프로덕션 환경에서 신뢰할 수 있다.

3. Spring Boot 레이어 추출 — Docker 캐시를 이해하면 보이는 것

RUN java -Djarmode=tools -jar app.jar extract --layers --launcher --destination extracted

이 한 줄이 이 Dockerfile의 핵심이다. Spring Boot의 레이어드 JAR 기능을 활용해 fat JAR를 4개 레이어로 분해한다.

일반적인 Spring Boot fat JAR는 모든 것이 하나의 파일에 담겨 있다. 의존성 라이브러리, Spring Boot 로더, 내 애플리케이션 코드까지. 그래서 코드 한 줄만 바꿔도 수십 MB짜리 JAR 전체를 다시 Docker 레이어에 올려야 한다.

Docker는 레이어 기반으로 동작한다. 변경되지 않은 레이어는 캐시에서 재사용한다. 이 원리를 활용하면, 자주 바뀌는 것과 거의 바뀌지 않는 것을 분리해서 빌드 시간을 극적으로 줄일 수 있다.

--layers 옵션으로 추출하면 4개의 디렉토리가 생긴다:

--launcher 옵션은 Spring Boot 로더를 포함시켜서, 최종 이미지에서 java -jar 대신 org.springframework.boot.loader.launch.JarLauncher로 기동할 수 있게 한다. 이렇게 하면 Spring Boot의 클래스 로딩 최적화를 그대로 활용할 수 있다.

4. COPY 순서의 비밀 — 변경 빈도가 낮은 것부터

COPY --from=extractor --chown=appuser:appgroup /extractor/extracted/dependencies/ ./
COPY --from=extractor --chown=appuser:appgroup /extractor/extracted/spring-boot-loader/ ./
COPY --from=extractor --chown=appuser:appgroup /extractor/extracted/snapshot-dependencies/ ./
COPY --from=extractor --chown=appuser:appgroup /extractor/extracted/application/ ./

4개의 COPY가 특정한 순서로 나열되어 있다. 이 순서는 의도적이다.

Docker는 Dockerfile을 위에서 아래로 실행하면서 각 명령어의 결과를 레이어로 캐싱한다. 그런데 어떤 레이어가 변경되면, 그 아래의 모든 레이어도 무효화된다. 이것이 Docker의 레이어 캐시 무효화 규칙이다.

이 규칙을 이해하면 순서가 왜 중요한지 명확해진다:

1. dependencies — 거의 바뀌지 않는다. 맨 위에 놓으면 거의 항상 캐시된다.
2. spring-boot-loader — Spring Boot 버전을 올릴 때만 바뀐다.
3. snapshot-dependencies — 개발 중에 가끔 바뀐다.
4. application — 매 배포마다 바뀐다. 맨 아래에 놓는다.

결과적으로, 일상적인 코드 변경에서는 마지막 application 레이어만 다시 빌드된다. 나머지 세 레이어는 캐시에서 가져온다. 이것이 빌드 시간을 단축시키고, 레지스트리에 푸시할 때도 변경된 레이어만 전송하므로 네트워크 비용도 줄어든다.

5. 눈으로 확인하는 차이 — 이미지 레이어 비교

이론은 충분하다. 실제로 어떤 차이가 나는지 확인해보자.

실제 운영 중인 Spring Boot 애플리케이션(멀티 모듈, 의존성 라이브러리 40여 개 규모)으로 두 방식의 Docker 이미지를 빌드하고 docker history로 레이어를 비교했다.

Fat JAR 방식의 레이어 구조

docker history 명령어로 이미지의 레이어 구조를 확인할 수 있다. 초기 Dockerfile로 만든 이미지를 보면:

$ docker history hanpyo:fat-jar

SIZE        CREATED BY
89.3MB      COPY app.jar .                          ← 전체 JAR, 단일 레이어
0B          WORKDIR /app
274MB       eclipse-temurin:24-jre 베이스 이미지

전체 JAR가 하나의 레이어(89.3MB)로 들어간다. 구조는 단순하지만, 코드 한 줄만 바꿔도 이 89.3MB 레이어 전체가 무효화된다.

Layered JAR 방식의 레이어 구조

동일한 애플리케이션을 레이어 추출 방식으로 빌드하면:

$ docker history hanpyo:layered

SIZE        CREATED BY
1.7MB       COPY .../application/ .                  ← 내 코드
4.1KB       COPY .../snapshot-dependencies/ .        ← SNAPSHOT
692KB       COPY .../spring-boot-loader/ .           ← 로더
88MB        COPY .../dependencies/ .                 ← 외부 라이브러리
45.1KB      RUN groupadd && useradd ...
0B          WORKDIR /app
274MB       eclipse-temurin:24-jre 베이스 이미지

fat JAR 안에 있던 89.3MB가 4개 레이어로 분해되었다. 핵심은 비율이다:

전체의 97.4%를 차지하는 dependencies는 거의 바뀌지 않고, 매번 바뀌는 application은 전체의 1.9%에 불과하다.

직접 확인해보자. docker history <이미지명> 명령어로 자신의 이미지 레이어를 살펴보면, 대부분의 Spring Boot 애플리케이션에서 dependencies가 95% 이상을 차지하는 것을 확인할 수 있다.

코드 변경 시 재빌드 비교

실제로 코드를 한 줄 수정하고 다시 docker build를 실행했다. 두 방식의 차이를 시각화하면:

[Fat JAR — 코드 변경 후 재빌드]

  ┌──────────────────────────────┐
  │ eclipse-temurin:24-jre       │ 274MB   캐시 ──── 재사용
  ├──────────────────────────────┤
  │ app.jar                      │ 89.3MB  재빌드 ── 전체 전송 ★
  └──────────────────────────────┘
                                   전송량: 89.3MB

[Layered JAR — 코드 변경 후 재빌드]

  ┌──────────────────────────────┐
  │ eclipse-temurin:24-jre       │ 274MB   캐시 ──── 재사용
  ├──────────────────────────────┤
  │ dependencies                 │ 88MB    캐시 ──── 재사용
  ├──────────────────────────────┤
  │ spring-boot-loader           │ 692KB   캐시 ──── 재사용
  ├──────────────────────────────┤
  │ snapshot-dependencies        │ 4.1KB   캐시 ──── 재사용
  ├──────────────────────────────┤
  │ application                  │ 1.7MB   재빌드 ── 변경분만 ★
  └──────────────────────────────┘
                                   전송량: 1.7MB

재빌드 시 전송량: 89.3MB → 1.7MB. 약 98% 감소.

빌드 + 푸시 벤치마크

말로만 하면 설득력이 없다. 코드를 한 줄씩 바꿔가며 10회 반복 빌드 + 레지스트리 푸시를 실측했다.

측정 환경: 로컬 Docker 레지스트리 (registry:2), 10회 반복, 코드 변경 후 재빌드

주목할 점은 푸시 시간의 표준편차다. Fat JAR은 0.121초, Layered JAR은 0.036초. Layered 방식은 변경된 application 레이어(1.7MB)만 매번 동일하게 전송하므로 일관성이 높다. Fat JAR은 89.3MB 전체를 매번 전송하므로 I/O 상황에 따라 편차가 크다.

이 벤치마크는 로컬 레지스트리에서 측정한 것이라 네트워크 지연이 거의 없다. 실제 원격 레지스트리(Docker Hub, GHCR 등)에서는 차이가 훨씬 극적이다. 네트워크 대역폭 100Mbps 기준으로 추산하면:

• Fat JAR 푸시: 89.3MB ÷ 12.5MB/s ≈ ~7.1초
• Layered JAR 푸시: 1.7MB ÷ 12.5MB/s ≈ ~0.14초

CI/CD 파이프라인에서의 체감

Docker 이미지를 빌드하고 레지스트리에 푸시하는 CI/CD 파이프라인에서, 레이어 캐싱의 효과는 극적이다. 변경된 레이어만 I/O가 발생하기 때문이다.

일상적인 개발에서 가장 빈번한 시나리오는 코드만 변경하는 경우다. 하루에 10번 배포하는 팀이라면:

• Fat JAR 방식: 89.3MB × 10 = 일일 893MB 전송
• Layered JAR 방식: 1.7MB × 10 = 일일 17MB 전송
• 한 달(20 영업일) 기준: 약 17.9GB → 340MB

실측에서도 로컬 환경 기준 빌드+푸시가 4.33초 → 2.94초로 32% 단축되었다. 원격 레지스트리 환경에서는 네트워크 전송 비중이 커지면서 이 차이가 수 배로 벌어진다.

레이어 캐싱의 핵심은 간단하다. 변하지 않는 것은 다시 보내지 않는다. 코드만 바꿨다면, 코드만 보내면 된다.

6. 컨테이너 안의 JVM — 메모리를 제대로 인식시키기

ENTRYPOINT ["java", \
    "-XX:+UseContainerSupport", \
    "-XX:MaxRAMPercentage=75.0", \
    ...

JVM은 원래 베어메탈 서버에서 태어났다. 호스트의 전체 CPU와 메모리를 자기 것으로 인식하는 게 기본 동작이다. 그런데 컨테이너 환경에서는 이것이 문제가 된다.

Docker는 Linux의 cgroup을 통해 컨테이너에 메모리 제한을 건다. 예를 들어, --memory=1g로 1GB를 할당했다고 하자. UseContainerSupport가 없는 구버전 JVM은 호스트의 전체 메모리(예: 16GB)를 보고 힙 크기를 계산한다. 그러면 할당된 1GB를 넘어서 메모리를 사용하려 하고, Docker는 이 컨테이너를 OOM Kill한다.

-XX:+UseContainerSupport는 JVM이 cgroup의 메모리/CPU 제한을 인식하도록 한다. Java 10에서 도입되어 기본 활성화되었고, Java 8u191에도 백포트되었다. 즉, 현대 Java에서는 이미 기본값이다. 그런데도 나는 이것을 명시적으로 선언한다. 코드가 의도를 드러내야 하듯, 설정도 의도를 드러내야 한다고 생각하기 때문이다.

-XX:MaxRAMPercentage=75.0은 컨테이너에 할당된 메모리의 75%를 JVM 힙으로 사용하라는 의미다. 왜 100%가 아닐까?

JVM은 힙만 쓰지 않는다. 메타스페이스, 스레드 스택, GC 오버헤드, 네이티브 메모리, 소켓 버퍼 등이 힙 바깥에서 메모리를 사용한다. 75%로 힙을 제한하고 나머지 25%를 이런 비힙 영역에 남겨두는 것이다.

경험적으로 70~80%가 적절한 범위다. 너무 높이면 비힙 영역이 부족해 OOM이 발생하고, 너무 낮추면 힙이 부족해 GC 빈도가 올라간다.

7. Non-root 실행 — 최소 권한의 원칙

RUN groupadd -r appgroup && useradd -r -g appgroup appuser && chown -R appuser:appgroup /app
...
USER appuser

Docker 컨테이너의 기본 실행 사용자는 root다. 컨테이너 안의 root가 호스트의 root와 동일한 건 아니지만, 그래도 위험하다.

컨테이너 런타임의 취약점이 발견되면, root로 실행 중인 프로세스는 컨테이너 탈출(container escape) 시 호스트에 더 큰 영향을 줄 수 있다. 이것은 이론적인 위협이 아니라, 실제로 CVE가 보고된 바 있는 공격 벡터다.

최소 권한의 원칙(Principle of Least Privilege)을 따라, 애플리케이션이 필요로 하는 최소한의 권한만 부여한다:

1. groupadd -r appgroup — 시스템 그룹 생성 (-r은 시스템 계정을 의미)
2. useradd -r -g appgroup appuser — 시스템 사용자 생성, 홈 디렉토리 없이 최소 구성
3. chown -R appuser:appgroup /app — 작업 디렉토리 소유권 부여
4. USER appuser — 이후 모든 명령어를 이 사용자로 실행

주의할 점은 USER 지시어의 위치다. RUN으로 패키지 설치나 사용자 생성 같은 root 권한이 필요한 작업을 모두 먼저 수행하고, 그 이후에 USER appuser로 전환한다. COPY에서는 --chown=appuser:appgroup으로 파일 소유권을 함께 지정하여, 별도의 RUN chown 없이도 올바른 권한을 설정한다.

8. /dev/./urandom — 아직도 필요한가?

"-Djava.security.egd=file:/dev/./urandom"

이 설정은 Java의 SecureRandom이 난수를 생성할 때 사용하는 엔트로피 소스를 지정한다.

Linux에는 두 가지 난수 소스가 있다:

• /dev/random — 충분한 엔트로피가 모일 때까지 블로킹된다
• /dev/urandom — 블로킹 없이 유사 난수를 생성한다

컨테이너 환경은 물리적 입력 장치가 없어 엔트로피 수집이 느리다. 초기 Java 버전에서는 SecureRandom이 /dev/random을 사용해서, 애플리케이션 시작 시 수십 초간 멈추는 문제가 있었다. 특히 TLS 핸드셰이크나 세션 ID 생성 같은 곳에서 SecureRandom이 호출되므로, 이 지연은 실질적인 영향을 미쳤다.

그런데 왜 /dev/urandom이 아니라 /dev/./urandom일까? 경로에 ./가 끼어 있는 이유가 있다.

JDK 8 이전에는 SeedGenerator 클래스의 초기화 과정에서 문제가 있었다. securerandom.source 속성값이 file:/dev/urandom과 정확히 일치하면, 내부적으로 항상 /dev/random에서 읽는 NativeSeedGenerator를 사용했다. 즉, /dev/urandom을 지정해도 실제로는 /dev/random이 사용되는 문자열 매칭 기반의 분기 로직 문제였다. file:/dev/./urandom은 이 exact string matching을 피하면서도, OS 레벨에서는 같은 /dev/urandom 장치를 가리키는 워크어라운드였다.

JDK 8에서 이 문제는 수정되었다. 그리고 현대 Java의 기본 구현인 NativePRNG는 난수 생성(nextBytes())에는 /dev/urandom을, 시드 생성(generateSeed())에는 /dev/random을 사용한다. 즉, 용도에 따라 적절한 소스를 자동으로 선택한다. 그렇다면 이 설정은 불필요한 것인가?

솔직히 말하면, JDK 24를 사용하는 이 Dockerfile에서 이 설정은 기술적으로 불필요하다. 하지만 나는 이것을 방어적 설정으로 남겨두었다. 다양한 환경에서 실행될 가능성, 베이스 이미지의 java.security 설정이 변경될 가능성을 고려한 것이다. 해가 되지 않는 설정이라면, 한 줄의 보험으로 남겨두는 편이 나의 성향이다.

다만, 이 선택에 대해서는 의견이 갈릴 수 있다. 불필요한 설정은 제거하는 것이 깔끔하다는 주장도 충분히 합리적이다.

마무리

Dockerfile은 단순한 빌드 스크립트가 아니다. 그 안에는 보안, 성능, 운영 효율성에 대한 수많은 결정이 녹아 있다.

이 글에서 다룬 각 설정의 의미를 정리하면:

• 멀티 스테이지 빌드 → 불필요한 도구를 프로덕션에서 제거
• JRE 사용 → 공격 표면 축소 + 이미지 경량화
• 레이어 추출 → Docker 캐시 최적화로 빌드/배포 속도 향상
• COPY 순서 → 변경 빈도 기반 레이어 배치
• 레이어 비교 → 코드 변경 시 전송량 89.3MB에서 1.7MB로 98% 감소
• UseContainerSupport + MaxRAMPercentage → 컨테이너 환경에서의 안정적 메모리 관리
• Non-root 실행 → 최소 권한 원칙으로 보안 강화
• /dev/./urandom → 방어적 설정으로 엔트로피 블로킹 방지

Dockerfile을 작성할 때 "동작하는 것"에서 멈추지 말고, 한 줄 한 줄 "왜?"를 물어보자. 그 질문들이 모여 프로덕션에서 견고하게 살아남는 이미지를 만든다.

참고 자료

• Dockerfiles :: Spring Boot — Spring Boot 공식 Docker 가이드
• 9 Tips for Containerizing Your Spring Boot Code | Docker — Docker 공식 블로그의 Spring Boot 컨테이너화 팁
• What Does the UseContainerSupport VM Parameter Do in Docker? — UseContainerSupport 파라미터 상세 설명
• Best Practices: Java Memory Arguments for Containers — 컨테이너 환경 JVM 메모리 설정 가이드
• Understanding the Docker USER Instruction | Docker — Docker USER 지시어와 보안
• Reusing Docker Layers with Spring Boot | Baeldung — Spring Boot Docker 레이어 재사용

같은 팀, 같은 모델, 같은 IDE. 그런데 A 엔지니어는 10분 만에 복잡한 리팩토링을 끝내고, B 엔지니어는 1시간을 할루시네이션과 씨름한다. 이 차이는 코딩 실력에서 오는 것이 아니다.

LangChain 팀이 이를 증명했다. Terminal Bench 2.0에서 모델을 바꾸지 않고 환경만 개선했더니 52.8%에서 66.5%로 성능이 뛰었다. 모델은 그대로인데, 에이전트가 동작하는 환경을 바꾸자 결과가 달라진 것이다.

2025년이 에이전트의 해였다면, 2026년은 에이전트 하네스의 해다. 이제 "어떤 모델을 쓸 것인가"보다 "에이전트가 동작하는 환경을 어떻게 설계할 것인가"가 생산성을 결정한다.

Harness란 무엇인가

Harness는 말의 고삐에서 온 비유다. AI 모델은 강력하지만 예측 불가능한 말이다. 고삐 없이 놓아두면 아무 방향으로 달린다. 하네스는 그 힘을 원하는 방향으로 이끄는 장치다.

Terraform의 창시자 Mitchell Hashimoto가 2026년 2월 자신의 블로그에서 이 개념을 체계적으로 정리하며 대중화했다.

"에이전트가 실수할 때마다, 그 실수를 다시는 하지 않도록 환경을 엔지니어링한다."

구체적으로 하네스는 에이전트가 동작하는 제약, 도구, 문서, 피드백 루프의 총체다. CLAUDE.md 같은 설정 파일, pre-commit hook, 커스텀 린터, slash command, MCP 서버 — 이 모든 것이 하네스를 구성한다.

이전 글에서 다뤘던 Context Engineering이 "무엇을 줄 것인가"의 문제였다면, Harness Engineering은 "어떤 환경에서 동작하게 할 것인가"의 문제다. 컨텍스트는 하네스의 한 구성 요소이고, 하네스는 컨텍스트를 포함한 전체 시스템이다.

Anthropic의 접근: 장기 실행 에이전트를 위한 하네스

Anthropic은 "Effective Harnesses for Long-Running Agents"에서 핵심 문제를 짚었다. 에이전트가 여러 컨텍스트 윈도우에 걸쳐 일관된 진행을 유지하지 못한다. 새 세션이 시작되면 이전 작업의 기억이 없고, 토큰을 낭비하며 재탐색하거나 이전 진행을 되돌린다.

2단계 아키텍처

이 문제를 해결하기 위해 Anthropic은 에이전트를 둘로 나눴다.

Initializer Agent — 첫 세션에서만 실행되며 작업 환경을 구축한다.

• init.sh: 개발 서버를 띄우는 스크립트

• claude-progress.txt: 작업 이력을 기록하는 파일

• Feature list (JSON): 구현할 기능 200개 이상을 사전 분해

• 초기 git commit: 추가된 파일들의 스냅샷

Coding Agent — 이후 세션마다 실행되며, 세션당 하나의 기능만 구현한다.

매 세션의 시작 패턴은 동일하다:

pwd → claude-progress.txt 읽기 → feature_list.json 확인 → git log 확인
→ init.sh로 dev server 시작 → 기존 테스트 통과 확인 → 다음 기능 구현

왜 JSON인가

Feature list를 Markdown이 아닌 JSON으로 관리하는 것은 의도적인 설계다. 에이전트는 Markdown의 자유로운 형식에서 테스트 항목을 삭제하거나 수정하는 경향이 있다. JSON은 구조가 엄격해서 에이전트가 passes 필드 외에는 건드리기 어렵다.

{
  "category": "functional",
  "description": "새 채팅 버튼이 새 대화를 생성한다",
  "steps": ["메인 인터페이스 이동", "버튼 클릭", "생성 확인"],
  "passes": false
}

에이전트는 이 passes 값만 바꿀 수 있다. 테스트 자체를 삭제하거나 변경하는 것은 프롬프트에서 명시적으로 금지한다.

Git을 상태 복구 도구로

Anthropic이 발견한 가장 효과적인 패턴은 git을 에이전트의 상태 복구 도구로 활용하는 것이다. 에이전트에게 매 작업마다 설명적인 커밋 메시지로 커밋하게 하면, 나쁜 변경이 생겼을 때 git revert로 작동하던 상태로 되돌릴 수 있다.

progress 파일과 git history의 조합으로, 새 세션의 에이전트는 이전에 무슨 일이 있었는지 추측하느라 시간을 낭비하지 않는다. 명확한 상태와 이력이 있으니 바로 다음 작업에 들어간다.

토스의 접근: 팀의 생산성 저점을 올리는 하네스

토스 기술 블로그의 "Software 3.0 시대, Harness를 통한 조직 생산성 저점 높이기"는 다른 각도에서 같은 문제를 본다. Anthropic이 기술적 아키텍처에 집중했다면, 토스는 조직의 역량 편차에 집중한다.

문제: 각자도생

현재 많은 팀이 LLM을 도입했지만 실상은 "각자도생"이다. A 엔지니어는 작업 전에 레포의 코딩 가이드라인, lint 규칙, 기존 패턴을 에이전트에 주입한다. B 엔지니어는 단순 질문으로 시작해 수정 루프에 갇힌다. 도구는 같은데 결과가 다르다.

이 차이를 개인 역량에 맡겨두면, 팀 전체의 생산성은 가장 느린 사람에 의해 결정된다.

해법: 플러그인을 하네스로

토스는 Claude Code의 플러그인 생태계를 하네스로 활용한다. 핵심은 세 가지 특성이다.

Frictionless Integration — 브라우저로 나가서 챗봇에 코드를 붙여넣는 문맥 교환 비용을 없앤다. 터미널 안에서 자연어와 코드가 끊김 없이 섞인다.

Executable SSOT (실행 가능한 단일 진실 공급원) — Wiki나 Notion 문서는 작성되는 순간부터 낡는다. 하지만 플러그인 형태의 지식은 사람이 읽으면 업무 가이드라인이 되고, LLM이 읽으면 시스템 프롬프트가 된다. 플러그인 코드를 업데이트하면 팀원 모두의 에이전트 행동이 즉시 바뀐다.

저점 상향 평준화 — oh-my-zsh처럼 누군가 미리 고민해둔 베스트 프랙티스를 즉시 가져다 쓸 수 있다. 하지만 여기서 한 발 더, 팀의 도메인 맥락을 반영한 특화된 플러그인이 핵심이다.

3-Layer 아키텍처

토스는 지식을 세 계층으로 분리한다.

신입에게 전사 문서를 통째로 던지지 않듯, LLM에게도 현재 작업에 필요한 지식만 주입한다. 이 계층화된 플러그인들이 모이면 별도의 RAG 시스템 없이도 살아있는 지식 베이스가 된다.

노하우의 민주화

가장 인상적인 부분은 팀 최고 엔지니어의 워크플로우를 slash command로 배포하는 패턴이다.

/new-feature 입력
→ Claude가 구현 기능의 맥락 수집
→ Jira 이슈 발급, 브랜치 생성, 구현 계획 작성
→ 엔지니어 검토/승인
→ 구현 시작

B 엔지니어도 /new-feature 하나로 A 엔지니어와 동일한 품질의 워크플로우를 실행한다. LLM 활용 능력이 더 이상 개인의 센스 영역이 아니라, 팀이 설계하고 배포하는 시스템의 영역으로 넘어간다.

Harness Engineering의 4대 요소

Anthropic, 토스, OpenAI, Stripe 등의 사례를 종합하면 효과적인 하네스는 네 가지 요소로 구성된다.

1. Architecture as Guardrails: 구조가 곧 제약

여기서 짚고 넘어가야 할 것이 있다. CLAUDE.md에 "이 프로젝트는 헥사고날 아키텍처를 따릅니다"라고 적으면 에이전트가 지켜줄까? 아니다. CLAUDE.md는 본질적으로 비강제(non-enforcing)다. 에이전트는 할루시네이션에 의해 규칙을 잊거나 무시할 수 있다. "하지 마세요"라는 지시는 확률적으로 무시될 수 있지만, 빌드가 깨지는 것은 무시할 수 없다.

이것이 ArchUnit, Konsist 같은 아키텍처 테스트 도구가 하네스에서 핵심적인 이유다. 컨벤션을 문서가 아니라 코드로 강제한다.

Java 진영의 ArchUnit은 아키텍처 규칙을 단위 테스트로 작성한다:

@Test
void 도메인_레이어는_인프라에_의존하지_않는다() {
    noClasses()
        .that().resideInAPackage("..domain..")
        .should().dependOnClassesThat()
        .resideInAPackage("..infrastructure..")
        .check(importedClasses);
}

Kotlin 프로젝트라면 Konsist가 같은 역할을 한다. 네이밍 컨벤션, 패키지 구조, 클래스 가시성, 의존성 방향까지 — 코딩 규칙을 테스트 코드로 표현한다:

@Test
fun `UseCase 클래스는 반드시 execute 메서드를 가진다`() {
    Konsist.scopeFromProject()
        .classes()
        .withNameEndingWith("UseCase")
        .assertTrue { it.hasFunction { func -> func.name == "execute" } }
}

에이전트가 이 규칙을 어기면 테스트가 실패하고 빌드가 깨진다. 에이전트는 빌드 실패를 감지하면 스스로 수정한다. CLAUDE.md의 "~하지 마세요"는 무시할 수 있지만, 빨간 테스트는 무시할 수 없다. 이것이 "문서로 안내"와 "코드로 강제"의 결정적 차이다.

무신사도 이와 같은 접근을 적용하고 있다. AI 에이전트를 도입하면서 기존의 아키텍처 테스트와 린터를 하네스의 일부로 활용한다. 에이전트가 생성한 코드가 팀의 컨벤션을 위반하면 CI에서 잡히고, 에이전트가 자동으로 수정한다. 사람이 리뷰할 때쯤이면 이미 컨벤션을 준수한 코드가 나온다.

OpenAI도 같은 원리를 적용했다. Codex 에이전트로 수동 코드 0줄, 100만 줄 코드베이스를 5개월간 3명의 엔지니어로 만들었다. 이것이 가능했던 핵심은 엄격한 아키텍처 제약이다.

의존성 방향을 기계적으로 강제했다:

Types → Config → Repo → Service → Runtime → UI

에이전트는 이 레이어 안에서만 동작하고, 커스텀 린터가 구조적 위반을 자동으로 잡는다. 직관에 반하지만, AI가 생성하는 코드는 자유도를 줄여야 품질이 올라간다. Vercel도 처음엔 풍부한 도구 라이브러리를 제공했다가, 오히려 도구를 줄이고 선택지를 단순화하자 에이전트가 더 빠르고 안정적으로 동작했다.

정리하면, 컨벤션 강제의 스펙트럼은 이렇다:

효과적인 하네스는 이 수단들을 조합한다. 안내는 CLAUDE.md로, 검증은 hook으로, 강제는 아키텍처 테스트로.

2. Tools as Foundation: 도구가 곧 기반

에이전트에게는 인간 엔지니어와 동일한 도구 접근권이 필요하다.

Stripe의 Minions는 약 500개의 내부 도구를 MCP 서버로 노출해서 사전 준비된 샌드박스 환경에서 에이전트가 동작하게 한다. 개발자가 Slack에 태스크를 올리면, 에이전트가 코드를 작성하고, CI를 통과시키고, 리뷰 가능한 PR을 열어준다. 코딩 과정에서 인간의 개입은 없다. 최종 PR은 사람이 리뷰한 뒤 머지되며, 주간 1,000개 이상의 PR이 이 방식으로 처리된다.

핵심 인사이트: 커스텀 린터의 에러 메시지가 이중 목적을 수행한다. 위반을 표시하면서 동시에 에이전트에게 수정 방법을 알려준다. 도구가 교육 기제가 되는 것이다.

3. Documentation as Living System: 문서가 곧 인프라

CLAUDE.md(또는 AGENTS.md)는 단순한 문서가 아니라 살아있는 인프라다.

Hashimoto의 Ghostty 프로젝트에서 AGENTS.md는 빌드 명령어, 구조적 안내와 함께 과거 에이전트가 저질렀던 실패를 방지하는 규칙들을 담고 있다. 에이전트가 실수할 때마다 그 실수를 방지하는 규칙이 문서에 추가된다. Hashimoto 본인도 이 규칙들을 추가한 뒤 문제가 "거의 완전히 해결되었다"고 밝혔다.

OpenAI는 여기서 한 발 더 나아가, 백그라운드 에이전트가 주기적으로 문서를 스캔해서 오래된 내용을 감지하고 정리 PR을 자동으로 여는 구조를 만들었다.

효과적인 문서의 원칙:

• 에이전트가 실패할 때마다 업데이트

• 코드에서 유추할 수 없는 정보만 포함

• 모노레포에서는 중첩된 CLAUDE.md로 팀/패키지별 컨텍스트 분리

4. Verification & Feedback Loops: 검증과 피드백 순환

에이전트의 가장 흔한 실패 모드는 기능을 제대로 테스트하지 않고 완료로 표시하는 것이다.

Anthropic은 이를 해결하기 위해:

• Feature list를 JSON으로 구조화하여 에이전트가 테스트 항목을 삭제하지 못하게 함

• 브라우저 자동화(Puppeteer MCP)로 사용자 관점의 E2E 테스트 강제

• 스크린샷을 통한 시각적 버그 감지 (Vision 활용)

피드백 루프에서 중요한 것은 성공은 조용히, 실패만 상세하게다. 매번 전체 테스트 결과를 출력하면 컨텍스트 윈도우가 넘친다. 통과한 테스트는 무시하고 실패한 테스트만 상세 로그를 보여줘야 한다.

실전: 나만의 하네스 구성하기

이론은 충분하다. 실제로 하네스를 구성하는 방법을 살펴보자.

CLAUDE.md: 하네스의 시작점

CLAUDE.md는 하네스의 가장 기본적인 구성 요소다. 에이전트가 세션을 시작할 때 자동으로 읽는 프로젝트 설명서이자 행동 지침이다.

하지만 CLAUDE.md에 대한 가장 흔한 실수는 코드에서 이미 알 수 있는 것을 적는 것이다. "이 프로젝트는 Spring Boot를 사용합니다", "패키지 구조는 domain/application/infrastructure입니다" — 에이전트는 코드를 읽으면 이것을 안다. 이런 내용은 토큰만 낭비할 뿐 아니라, 코드와 문서가 어긋나면 오히려 혼란을 준다.

반대로, 코드에서 절대 알 수 없는 것은 반드시 적어야 한다:

# 빌드 & 테스트
./gradlew build              # 전체 빌드 (ArchUnit 테스트 포함)
./gradlew test --tests "*UseCase*"  # UseCase 단위 테스트만
docker compose up -d          # 로컬 DB/Redis 실행

# 배포
dev 환경: main 브랜치 push 시 자동 배포
prod 환경: 릴리스 태그 생성 시 배포 (수동 승인 필요)

# 작업 규칙
- PR은 반드시 Jira 티켓 번호를 포함: feat/PROJ-123-description
- hotfix 외에는 main 직접 커밋 금지

CLI 명령어, 배포 절차, 브랜치 전략, 외부 시스템 연동 방법 — 이런 것들은 코드를 아무리 읽어도 알 수 없다. 이것이 CLAUDE.md에 담아야 할 내용이다.

코드 패턴이나 아키텍처 규칙은? CLAUDE.md에 쓰지 말고 ArchUnit이나 Konsist 테스트로 강제하라. 에이전트가 규칙을 어기면 빌드가 깨지고, 에이전트가 스스로 고친다. 문서에 적는 것보다 확실하고, 문서가 낡을 걱정도 없다.

핵심 원칙은 두 가지다:

• "코드에서 알 수 있는가?" → 알 수 있으면 적지 않는다

• "이것이 없으면 에이전트가 실패하는가?" → 실패하지 않으면 적지 않는다

Hooks: CLAUDE.md가 안내라면, Hook은 강제다

CLAUDE.md에 "main 브랜치에 직접 커밋하지 마세요"라고 적어도, 에이전트는 이를 무시하고 main에 커밋할 수 있다. 하지만 hook은 다르다. 물리적으로 차단한다.

토스의 사례:

Claude가 git commit 시도
→ Hook이 현재 브랜치 검사
→ "현재 main 브랜치입니다. feature/ 브랜치 생성 후 작업하겠습니다"
→ 자동 교정

Claude Code의 hook 시스템이나 pre-commit hook으로 이런 검증을 걸 수 있다:

• 커밋 시점: 브랜치명 규칙 검사, lint 실행, ArchUnit/Konsist 테스트 실행

• 파일 수정 시점: 금지된 파일(.env, 설정 파일) 수정 차단

• 명령 실행 시점: 위험한 명령어(rm -rf, DROP TABLE) 차단

핵심은 안내와 강제의 역할 분리다. CLAUDE.md는 에이전트에게 방향을 알려주고, hook과 아키텍처 테스트는 그 방향을 벗어나지 못하게 강제한다. 안내만으로는 부족하고, 강제만으로는 맥락이 없다. 둘 다 필요하다.

Skills & Slash Commands: 워크플로우 패키징

반복되는 워크플로우를 스킬로 패키징하면 팀 전체의 역량 바닥이 올라간다.

좋은 스킬의 조건:

• 단일 책임: 하나의 스킬은 하나의 워크플로우만 담당

• 승인 게이트: 에이전트가 잘못된 방향으로 달리기 전에 사람이 검토

• 검증 단계 내장: 결과물을 자체적으로 확인하는 단계 포함

MCP 서버: 도구 확장

Model Context Protocol로 에이전트에게 외부 도구 접근권을 제공한다. Jira 연동, Slack 알림, 데이터베이스 조회, 모니터링 대시보드 확인 등 — 인간 엔지니어가 쓰는 도구를 에이전트도 쓸 수 있게 한다.

settings.local.json: 권한 설계

에이전트의 권한을 명시적으로 설계한다. 모든 것을 허용하는 것도, 모든 것을 차단하는 것도 답이 아니다.

{
  "permissions": {
    "allow": [
      "Read", "Edit", "Write",
      "Bash(git diff *)", "Bash(git commit *)",
      "WebSearch"
    ],
    "deny": [
      "Bash(git push *)"
    ]
  }
}

안전한 작업은 자동 허용하고, 돌이킬 수 없는 작업(push, 프로덕션 배포 등)은 차단하거나 승인 게이트를 둔다.

실제 성과로 증명된 패턴

하네스 엔지니어링은 이론이 아니다. 실제 성과가 이를 뒷받침한다.

공통점이 보인다. 모델을 바꾸지 않았다. 환경을 바꿨다. 제약을 설계했다. 도구를 정비했다. 문서를 살아있게 만들었다. 그러자 같은 모델에서 다른 결과가 나왔다.

모델은 commodity, 하네스가 성패를 가른다

이 글의 핵심을 한 문장으로 요약하면 이것이다.

에이전트의 결과 품질은 모델이 아니라 환경이 결정한다.

Claude든 GPT든 Gemini든, 모델의 성능 차이보다 그 모델이 동작하는 환경의 설계가 결과에 더 큰 영향을 미친다. 빈 컨텍스트에 강력한 모델을 놓으면 할루시네이션과 삽질이 나오고, 잘 설계된 하네스에 적당한 모델을 놓으면 일관된 고품질 산출물이 나온다.

이전 글에서 "스킬은 바닥을 올리고, 사람은 천장을 결정한다"고 했다. 하네스는 그 스킬을 포함한 더 큰 그림이다. CLAUDE.md, hooks, skills, MCP, 권한 설계, 아키텍처 제약, 피드백 루프 — 이 모든 것이 하나의 시스템으로 엮일 때 에이전트는 비로소 안정적으로 동작한다.

오늘 당장 할 수 있는 것부터 시작해보자. 에이전트가 실수할 때마다 CLAUDE.md에 한 줄을 추가하는 것. 이것이 하네스 엔지니어링의 첫걸음이다.

참고 자료

• Effective Harnesses for Long-Running Agents — Anthropic Engineering — 장기 실행 에이전트를 위한 2단계 하네스 아키텍처

• Software 3.0 시대, Harness를 통한 조직 생산성 저점 높이기 — 토스 기술 블로그 — 팀 단위 하네스 전략과 플러그인 마켓플레이스

• Harness Engineering — Martin Fowler — OpenAI 사례 분석과 하네스 엔지니어링 개요

• The Emerging "Harness Engineering" Playbook — 4대 구성 요소와 실전 사례 종합

• Building Agents with the Claude Agent SDK — Anthropic Engineering — Claude Agent SDK와 하네스의 관계

• Skill Issue: Harness Engineering for Coding Agents — HumanLayer — 코딩 에이전트 하네스의 실전 패턴

• 설 연휴에 Claude Code Agent Teams를 데려갔습니다 — 무신사 테크 블로그 — 무신사의 AI 에이전트 실전 적용 사례

• Konsist — Kotlin Architectural Linter — Kotlin 프로젝트의 아키텍처 규칙을 테스트로 강제

• ArchUnit — Unit Test Your Java Architecture — Java 아키텍처 규칙을 단위 테스트로 검증

요즘 AI 코딩 도구를 쓰지 않는 개발자를 찾기 어렵다. 하지만 솔직히 말하면, 대부분의 개발자가 비슷한 불만을 갖고 있다.

"어제는 잘 해줬는데 오늘은 왜 이러지?"

같은 도구, 같은 요청인데 결과가 들쭉날쭉하다. CLAUDE.md를 작성해달라고 하면 어떤 날은 프로젝트에 딱 맞는 걸 만들어주고, 어떤 날은 어디서 복사해온 듯한 일반적인 내용만 나열한다. 기능을 개발해달라고 하면 기존 코드를 완전히 무시하고 새로 작성하기도 한다.

나도 그랬다. Claude Code를 쓰면서 매번 같은 것을 반복해서 설명했다. "이 프로젝트는 이런 구조고, 이런 컨벤션을 쓰고, 이건 이렇게 해야 해." 매 세션마다 처음부터. 결과의 품질은 그날 내가 얼마나 상세하게 설명했느냐에 달려 있었다.

문제는 AI가 아니었다. 내가 AI에게 주는 맥락이 문제였다.

Prompt Engineering에서 Context Engineering으로

Andrej Karpathy는 이렇게 말했다.

"Context engineering is the delicate art and science of filling the context window with just the right information for the next step."

"프롬프트 엔지니어링"이라는 말을 들으면 뭐가 떠오르는가? 대부분은 짧은 질문을 잘 다듬는 기술을 떠올린다. "이렇게 물어보면 더 좋은 답이 나온다" 같은 팁. 하지만 실제로 AI를 업무에 활용하려면, 단순한 질문 하나로는 부족하다.

Karpathy가 제안한 Context Engineering은 더 넓은 개념이다. LLM을 CPU로, 컨텍스트 윈도우를 RAM으로 비유하면, 개발자의 역할은 운영체제다. 작업에 필요한 정확한 정보를 적시에 메모리에 올리는 것. 너무 적으면 AI가 제대로 된 결과를 못 내고, 너무 많으면 핵심이 묻힌다.

토스 기술 블로그의 "소프트웨어 3.0 시대를 맞이하며"에서는 이 개념을 더 구체화한다. Claude Code의 구조를 전통적인 레이어드 아키텍처에 비유하면서, CLAUDE.md는 package.json처럼 정적 설정을, Skills는 단일 책임 원칙(SRP)을 따르는 도메인 컴포넌트 역할을 한다고 설명한다.

핵심은 이것이다: 같은 모델이라도 어떤 맥락을 주느냐에 따라 결과가 극적으로 달라진다. 그리고 그 맥락을 체계적으로 설계하는 것이 바로 Context Engineering이다.

반복되는 맥락을 패키징하다: 스킬이라는 해법

이 깨달음은 자연스럽게 다음 질문으로 이어졌다. "매번 수동으로 맥락을 구성하는 대신, 잘 설계된 맥락을 재사용할 수는 없을까?"

Claude Code의 스킬(Skills) 시스템이 바로 그 답이었다. 스킬은 SKILL.md 파일에 정의된 지시사항으로, Claude가 특정 작업을 수행할 때 자동으로 로드되는 재사용 가능한 컨텍스트 패키지다.

나는 두 가지 스킬을 만들었다.

claude-md-writer: CLAUDE.md 작성 자동화

CLAUDE.md를 잘 쓰는 것은 Context Engineering의 기본이다. 하지만 "잘" 쓰는 것이 의외로 어렵다. Anthropic 공식 권장사항인 200줄 제한을 지키면서, 코드에서 유추할 수 없는 정보만 포함하고, 모든 명령어는 복사-붙여넣기로 실행 가능해야 한다.

이 스킬은 5단계 워크플로우를 따른다:

1. 탐색 — 기존 파일과 프로젝트 타입을 자동 감지

2. 분석 — 빌드 시스템, 아키텍처, 환경을 병렬로 조사

3. 인터뷰 — 코드에서 알 수 없는 정보를 사용자에게 질문

4. 생성 — 분석과 인터뷰 결과를 종합하여 CLAUDE.md 작성

5. 검증 — 품질 기준에 부합하는지 확인

핵심 설계 원칙은 "Would Claude fail without this?"다. 이 질문을 통과하지 못하는 정보는 포함하지 않는다. 코드를 읽으면 알 수 있는 것은 적지 않고, Claude가 모르면 틀릴 수밖에 없는 것만 남긴다.

new-feature: 기능 개발 워크플로우

기능 개발 요청을 받으면 바로 코드부터 작성하는 것이 AI의 본능이다. 하지만 이러면 기존 코드를 무시하고 새로 작성하거나, 잘못된 방향으로 한참을 달린 뒤에 되돌아오는 일이 생긴다.

이 스킬은 4단계 게이트를 강제한다:

1. 리서치 — 요구사항 수집, 기존 코드 분석, 외부 자료 조사

2. 작업 — 승인된 방향으로만 구현 (승인 없이는 코드를 쓰지 않음)

3. 검토 — 요구사항 대조, 엣지케이스 확인, 보안 점검

4. 보고 — 구현 내용과 검증 결과를 정리하여 전달

가장 중요한 설계 결정은 1단계와 2단계 사이의 승인 게이트다. AI가 조사 결과를 먼저 보여주고, 사용자의 승인을 받은 후에야 구현에 들어간다. "잘못된 방향으로 열심히 달리는" 문제를 구조적으로 차단한다.

스킬 도입 전과 후

Before:

• 매 세션마다 프로젝트 컨텍스트를 처음부터 설명

• 같은 요청에도 들쭉날쭉한 결과 품질

• 보안 체크, 엣지케이스 확인 등을 빠뜨리는 경우 발생

• "이번엔 잘 해줄까?" 하는 불확실함

After:

• /claude-md-writer create 한 번이면 프로젝트 분석부터 CLAUDE.md 생성까지 완료

• 누가 실행해도, 언제 실행해도 일관된 프로세스가 보장됨

• 체계적인 검토 단계 덕분에 빠뜨리는 것이 줄어듦

• 반복 작업에 들이던 시간이 줄어 핵심 의사결정에 집중 가능

가장 큰 변화는 일관성이었다. 스킬은 바닥을 올려준다. 최소한의 품질이 항상 보장되니, "오늘은 운이 좋아서 잘 나왔다"가 아니라 "항상 이 정도는 나온다"가 된다.

스킬은 바닥을 올리고, 사람은 천장을 결정한다

하지만 솔직하게 말해야 할 것이 있다. 스킬이 모든 것을 해결해주지는 않는다.

스킬은 프로세스를 패키징한 것이지, 판단력을 패키징한 것이 아니다. new-feature 스킬이 리서치 결과를 보여주고 승인을 요청할 때, 그 결과를 제대로 검토하고 올바른 방향을 제시하는 것은 여전히 사람의 몫이다. claude-md-writer가 인터뷰 질문을 할 때, 프로젝트의 진짜 맥락을 전달하는 것도 사람의 역할이다.

결국 최종 결과물의 품질은 그것을 검토하고 피드백하는 사람의 역량에 크게 좌우된다.

이것은 Context Engineering의 본질과도 맞닿아 있다. AI에게 좋은 맥락을 주는 것은 단순히 정보를 많이 넣는 것이 아니라, 올바른 정보를 올바른 시점에 제공하는 것이다. 스킬은 이 과정의 구조를 잡아주지만, 구조 안에 채워넣는 내용의 질은 사용하는 사람에게 달려 있다.

나는 이것을 이렇게 정리한다:

스킬은 바닥을 올려주고, 피드백은 천장을 결정한다.

AI 코딩 도구의 효과를 극대화하고 싶다면, 더 좋은 프롬프트를 고민하는 것을 넘어서 두 가지를 함께 해야 한다. 반복되는 맥락은 스킬로 체계화하고, 그 위에서 자신의 도메인 지식과 판단력으로 방향을 잡아주는 것. Context Engineering은 AI를 더 똑똑하게 만드는 기술이 아니다. 같은 AI에게서 더 나은 결과를 끌어내는 기술이다.

이 글에서 소개한 스킬들은 오픈소스로 공개되어 있습니다.GitHub: Tianea2160/claude-skills

참고 자료

• Andrej Karpathy on Context Engineering (X/Twitter) — "Context engineering is the delicate art and science of filling the context window with just the right information for the next step."

• 소프트웨어 3.0 시대를 맞이하며 — 토스 기술 블로그 — Claude Code를 레이어드 아키텍처로 비유한 Context Engineering 실전 가이드

• Extend Claude with skills — Claude Code 공식 문서 — Skills 시스템의 구조, 프론트매터, 설계 패턴 레퍼런스

• Context Engineering: A Complete Guide (2026) — Context Engineering 개념의 전반적 개요

• Context is AI coding's real bottleneck in 2026 — The New Stack — AI 코딩에서 컨텍스트가 실질적 병목인 이유

• Context Engineering for Coding Agents — Martin Fowler — 코딩 에이전트를 위한 Context Engineering 심화

문제

이 문제는 삼각 그래프의 가장 위쪽 가운데 정점에서 가장 아래쪽 가운데 정점으로 가는 최단 경로를 찾는 문제이다.

삼각 그래프는 사이클이 없는 그래프로 N ≥ 2 개의 행과 3열로 이루어져 있다. 삼각 그래프는 보통 그래프와 다르게 간선이 아닌 정점에 비용이 있다. 어떤 경로의 비용은 그 경로에서 지나간 정점의 비용의 합이다.

오른쪽 그림은 N = 4인 삼각 그래프이고, 가장 위쪽 가운데 정점에서 가장 아래쪽 가운데 정점으로 경로 중 아래로만 가는 경로의 비용은 7+13+3+6 = 29가 된다. 삼각 그래프의 간선은 항상 오른쪽 그림과 같은 형태로 연결되어 있다.

입력

입력은 여러 개의 테스트 케이스로 이루어져 있다. 각 테스트 케이스의 첫째 줄에는 그래프의 행의 개수 N이 주어진다. (2 ≤ N ≤ 100,000) 다음 N개 줄에는 그래프의 i번째 행에 있는 정점의 비용이 순서대로 주어진다. 비용은 정수이며, 비용의 제곱은 1,000,000보다 작다.

입력의 마지막 줄에는 0이 하나 주어진다.

출력

각 테스트 케이스에 대해서, 가장 위쪽 가운데 정점에서 가장 아래쪽 가운데 정점으로 가는 최소 비용을 테스트 케이스 번호와 아래와 같은 형식으로 출력한다.

k. n

k는 테스트 케이스 번호, n은 최소 비용이다.

예제 입력 1

4
13 7 5
7 13 6
14 3 12
15 6 16
0

예제 출력 1

1. 22

1차 시도(BFS)

문제를 너무 가볍게 봤을때네느 그래프 탐색으로 풀 수 있을 것으로 생각을 했습니다. 그런데 BFS/DFS로 해결이 안되는 문제 였고 첫번때 시도는 실패로 돌아갔습니다.

import java.util.*
import kotlin.math.min

val dx = arrayListOf(1, 1, 1, 0)
val dy = arrayListOf(-1, 0, 1, 1)

fun main() {
    val br = System.`in`.bufferedReader()
    val bw = System.out.bufferedWriter()
    var cnt = 1
    while (true) {
        val n = br.readLine().toInt()

        if (n == 0) break

        val array = Array(n) { br.readLine().split(" ").map { it.toInt() }.toIntArray() }

        val weight = bfs(0 to 1, n-1 to 1, array)

        bw.write("${cnt++}. $weight")
        bw.newLine()
    }

    br.close()
    bw.close()
}

fun bfs(
    start: Pair<Int, Int>,
    end: Pair<Int, Int>,
    array: Array<IntArray>
): Int {
    var answer = Int.MAX_VALUE
    val queue = LinkedList<Node>()
    val visited = mutableSetOf<Pair<Int, Int>>()

    queue.add(Node(start.first, start.second, array[start.first][start.second]))
    visited.add(start)

    while (queue.isNotEmpty()) {
        val cur = queue.poll()

        if (cur.x to cur.y == end) {
            answer = min(answer, cur.weight)
        }

        for (i in 0 until 4) {
            val nx = cur.x + dx[i]
            val ny = cur.y + dy[i]

            if (nx < 0 || ny < 0 || nx > array.lastIndex || ny > array[0].lastIndex) {
                continue
            }

            visited.add(nx to ny)
            queue.add(Node(nx, ny, array[nx][ny] + cur.weight))
        }
    }
    return answer
}

class Node(
    val x: Int,
    val y: Int,
    val weight: Int,
)

2차 시도(DP)

2번째로 다익스트라를 사용할까 했지만 다익스트라의 조건(가장 최선의 결과를 따라 갔을때 최적의 결과가 나온다는 보장을 할 수 있어야한다)을 만족할 수 없다는 생각을 하게 되었고 이건 DP로 푸는 것이 맞다라는 결론에 도달하게 됩니다.

그래서 점화식을 세우고 문제를 해결하게되었습니다.

점화식은 다음과 같습니다.

$$$$\begin{align} &DP[i][j] = (i, j)위치에서 가지는 가장 적은 비용 \\ &DP[i][0] = min(DP[i-1][0], DP[i-1][1]) + array[i][0] \\ &DP[i][1] = min(DP[i-1][0], DP[i-1][1], DP[i-1][2], DP[i][0]) + array[i][1] \\ &DP[i][2] = min(DP[i-1][1], DP[i-1][2], DP[i][1]) + array[i][2] \end{align}$$

$$

점화식이 복잡하다고 생각이되지만 삼각 그래프의 특성으로 인해서 같은 행, 열일때와 아닐때는 구분해서 점화식에 고려를 해줘야하기 때문에 복잡할 수 밖에 없다고 생각이 됩니다.

결론 적으로 코드로 적으면 아래와 같습니다.

fun main() {
    val br = System.`in`.bufferedReader()
    val bw = System.out.bufferedWriter()
    var cnt = 1

    while (true) {
        val n = br.readLine().toInt()

        if (n == 0) break

        val array = Array(n) { br.readLine().split(" ").map { it.toInt() }.toIntArray() }
        val dp = Array(n) { IntArray(3) { Int.MAX_VALUE } }

        // init
        dp[0][1] = array[0][1]
        dp[0][2] = dp[0][1] + array[0][2]

        for (i in 1 until n) {
            dp[i][0] = minOf(dp[i - 1][0], dp[i - 1][1]) + array[i][0]
            dp[i][1] = minOf(dp[i - 1][0], dp[i - 1][1], dp[i - 1][2], dp[i][0]) + array[i][1]
            dp[i][2] = minOf(dp[i - 1][1], dp[i - 1][2], dp[i][1]) + array[i][2]
        }

        bw.write("${cnt++}. ${dp[n - 1][1]}")
        bw.newLine()
    }

    br.close()
    bw.close()
}

여기서 주의할 점, 처음 row를 초기화를 잘 해야합니다.

        dp[0][1] = array[0][1]
        dp[0][2] = dp[0][1] + array[0][2]

(0, 1)에서 동작하기 때문에 (0, 1),(0, 2)에 대해서 초기화를 직접 해줘야하는 것을 고려해야합니다.

문제 설명

You are given a string s and a robot that currently holds an empty string t. Apply one of the following operations until s and t are both empty:

• Remove the first character of a string s and give it to the robot. The robot will append this character to the string t.

• Remove the last character of a string t and give it to the robot. The robot will write this character on paper.

Return the lexicographically smallest string that can be written on the paper.

Example 1:

Input: s = "zza"
Output: "azz"
Explanation: Let p denote the written string.
Initially p="", s="zza", t="".
Perform first operation three times p="", s="", t="zza".
Perform second operation three times p="azz", s="", t="".

Example 2:

Input: s = "bac"
Output: "abc"
Explanation: Let p denote the written string.
Perform first operation twice p="", s="c", t="ba". 
Perform second operation twice p="ab", s="c", t="". 
Perform first operation p="ab", s="", t="c". 
Perform second operation p="abc", s="", t="".

Example 3:

Input: s = "bdda"
Output: "addb"
Explanation: Let p denote the written string.
Initially p="", s="bdda", t="".
Perform first operation four times p="", s="", t="bdda".
Perform second operation four times p="addb", s="", t="".

Constraints:

• 1 <= s.length <= 10<sup>5</sup>

• s consists of only English lowercase letters.

문제 요약

• 로봇과 내가 각각 문자열 t, s를 들고 있습니다.

• t, s가 모두 빈 문자열이 될때까지 다음의 동작을 반복합니다

• s의 맨 앞 문자을 때서 t에 뒤로 붙입니다

• t의 맵 뒤 문자를 때서 로봇이 그걸 종이에 출력합니다.

• 이때 출력되는 문자가 사전적으로 가장 순서가 빠른 문자를 출력하도록 문자열을 구성하시오

분석

결국 해당 문제는 정해진 규칙 내에서 사전적으로 가장 순서가 빠른 문자를 출력할 수 있도록 하는 문제입니다.

가능 빠른 문자를 출력하기 위해서는 가장 작은 문자가 먼저 출력되도록 처리하는 것이 좋습니다.

그래서 문제를 탐욕적으로 해결 할 수 있을 것으로 보입니다.

첫 번째 접근: 직관적 해결법

가장 먼저 떠오르는 방법은 "현재 상황에서 최선의 선택하기"입니다.

kotlinclass Solution {
    fun robotWithString(s: String): String {
        var t = ""
        var u = s
        var answer = ""

        while (u.isNotEmpty()) {
            val a = u.min()  // 남은 문자 중 최소값
            val b = t.lastOrNull()  // 스택 top

            if (b == null || a < b) {
                // 더 작은 문자가 남아있으니 계속 스택에 쌓기
                val idx = u.indexOfFirst { it == a }
                for (i in 0..idx) {
                    t += u[i]
                }
                u = u.substring(idx + 1)
            } else {
                // 스택 top을 꺼내는 것이 유리
                answer += b
                t = t.substring(0, t.lastIndex)
            }
        }

        // 남은 스택 모두 pop
        for (i in t.lastIndex downTo 0) {
            answer += t[i]
        }

        return answer
    }
}

성능 문제점

이 접근법은 논리적으로는 맞지만 심각한 성능 문제가 있습니다:

1. 매번 u.min() 계산: O(n) × O(n) = O(n²)

2. 문자열 연결 연산: t += u[i]가 O(n²) 시간 소요

3. substring 연산: 매번 새로운 문자열 객체 생성

4. 전체 시간복잡도: O(n³)

최적화 아이디어: minSuffix 전처리

핵심 통찰: "매번 최소값을 찾지 말고, 미리 계산해두자!"

kotlin// 각 위치에서 그 위치부터 끝까지의 최소값을 미리 계산
val minSuffix = CharArray(n)
minSuffix[n-1] = s[n-1]
for (i in n-2 downTo 0) {
    minSuffix[i] = minOf(s[i], minSuffix[i+1])
}

예시로 이해하기

s = "bac"

minSuffix 계산:
minSuffix[2] = 'c'           // 위치 2부터 끝: "c" → 최소값 'c'
minSuffix[1] = min('a','c') = 'a'  // 위치 1부터 끝: "ac" → 최소값 'a'  
minSuffix[0] = min('b','a') = 'a'  // 위치 0부터 끝: "bac" → 최소값 'a'

결과: minSuffix = ['a', 'a', 'c']

해답

import java.util.*

class Solution {
    fun robotWithString(s: String): String {
        val answer = StringBuilder()
        val t = ArrayDeque<Char>()
        val minSuffix = CharArray(s.length)

        minSuffix[s.lastIndex] = s[s.lastIndex]

        for (i in s.length - 2 downTo 0) {
            minSuffix[i] = minOf(minSuffix[i + 1], s[i])
        }

        var i = 0
        val n = s.length

        while (i < n || t.isNotEmpty()) {

            while (t.isNotEmpty() && (i >= n || t.last() <= minSuffix[i])) {
                answer.append(t.removeLast())
            }

            if (i < n) {
                t.addLast(s[i])
                i++
            }
        }

        return answer.toString()
    }
}

이 글에서는 Kafka Streams의 대표적인 두 연산인 merge()와 join()의 차이점과 실제 구현 방법을 살펴보겠습니다. 실제 예제 코드와 함께 각 연산의 동작 방식, 성능 특성, 그리고 적합한 사용 사례를 비교해 보겠습니다.

Kafka Streams 소개

Kafka Streams는 Apache Kafka에서 제공하는 클라이언트 라이브러리로, 스트림 처리 애플리케이션을 쉽게 개발할 수 있도록 도와줍니다. 일반적인 ETL(Extract, Transform, Load) 도구나 데이터 처리 프레임워크와 달리, Kafka Streams는 별도의 클러스터나 인프라 없이 표준 Java 애플리케이션으로 실행됩니다.

Kafka Streams의 주요 특징:

• 상태 관리: 로컬 상태 저장소를 통한 효율적인 상태 관리

• 실시간 처리: 이벤트 발생 즉시 처리 가능

• 내결함성: 장애 발생 시 자동 복구 메커니즘

• 확장성: 수평적 확장을 통한 병렬 처리

• 정확히 한 번 처리: 정확히 한 번 처리 보장(exactly-once semantics)

프로젝트 설정

이 예제는 Spring Boot와 Kafka Streams를 사용하여 구현되었습니다. 주요 의존성은 다음과 같습니다:

kotlindependencies {
    implementation("org.springframework.boot:spring-boot-starter-web")
    implementation("org.springframework.kafka:spring-kafka")
    implementation("org.apache.kafka:kafka-streams")
    implementation("com.fasterxml.jackson.module:jackson-module-kotlin")
    implementation("org.jetbrains.kotlin:kotlin-reflect")
}

application.yml 파일에는 Kafka 및 Kafka Streams 관련 설정을 추가합니다:

yamlspring:
  kafka:
    bootstrap-servers: localhost:9092
    streams:
      application-id: kafka-stream-example
      properties:
        default.key.serde: org.apache.kafka.common.serialization.Serdes$StringSerde
        default.value.serde: org.apache.kafka.common.serialization.Serdes$StringSerde
        num.stream.threads: 3

기본 스트림 처리 구현

먼저 가장 기본적인 스트림 처리 로직을 구현해 보겠습니다. 하나의 입력 토픽에서 메시지를 읽어 처리한 후 출력 토픽으로 전송하는 예제입니다:

@Configuration
@EnableKafkaStreams
class StreamsProcessor {

    private val logger = LoggerFactory.getLogger(StreamsProcessor::class.java)

    @Value("\${kafka.input-topic:input-topic}")
    private lateinit var inputTopic: String

    @Value("\${kafka.output-topic:output-topic}")
    private lateinit var outputTopic: String

    @Bean
    fun kStream(streamsBuilder: StreamsBuilder): KStream<String, String> {
        // 입력 토픽에서 스트림 생성
        val stream = streamsBuilder.stream<String, String>(inputTopic)
        
        // 간단한 변환 수행
        stream
            .peek { key, value -> logger.info("스트림 입력: {} - {}", key, value) }
            .mapValues { value -> "$value (processed)" }
            .peek { key, value -> logger.info("스트림 출력: {} - {}", key, value) }
            .to(outputTopic)

        return stream
    }
}

이 코드는 StreamsBuilder를 사용하여 입력 토픽으로부터 스트림을 생성하고, 메시지를 처리한 후 출력 토픽으로 전송하는 기본적인 토폴로지를 구성합니다. peek() 메서드를 통해 처리 과정을 로깅하고, mapValues()를 사용하여 메시지 값을 변환합니다.

merge() 연산: 토픽 병합하기

이제 merge() 연산을 사용하여 두 개의 입력 토픽을 하나의 출력 토픽으로 병합하는 로직을 구현해 보겠습니다:

@Configuration
@EnableKafkaStreams
class TopicMergeProcessor {

    private val logger = LoggerFactory.getLogger(TopicMergeProcessor::class.java)

    @Value("\${kafka.merge-input-topic-1:merge-input-topic-1}")
    private lateinit var mergeInputTopic1: String

    @Value("\${kafka.merge-input-topic-2:merge-input-topic-2}")
    private lateinit var mergeInputTopic2: String

    @Value("\${kafka.merge-output-topic-1:merge-output-topic-1}")
    private lateinit var mergeOutputTopic1: String

    @Bean
    fun topicMergeStream(streamsBuilder: StreamsBuilder): KStream<String, String> {
        val stringSerde = Serdes.String()
        
        // 첫 번째 입력 토픽에서 스트림 생성
        val inputStream1: KStream<String, String> = streamsBuilder.stream(
            mergeInputTopic1,
            Consumed.with(stringSerde, stringSerde)
        )
        
        // 두 번째 입력 토픽에서 스트림 생성
        val inputStream2: KStream<String, String> = streamsBuilder.stream(
            mergeInputTopic2,
            Consumed.with(stringSerde, stringSerde)
        )
        
        // 첫 번째 스트림에 처리 지연 및 메타데이터 추가
        val taggedStream1: KStream<String, String> = inputStream1
            .peek { key, value -> 
                logger.info("입력 토픽1 처리 시작: key={}, value={}", key, value)
                Thread.sleep(500)  // 긴 처리 시간 (500ms)
                logger.info("입력 토픽1 처리 완료: key={}, value={}", key, value)
            }
            .mapValues { value -> "{ \"source\": \"\({mergeInputTopic1}\", \"data\": \"\)value\" }" }
        
        // 두 번째 스트림에 짧은 처리 지연 및 메타데이터 추가
        val taggedStream2: KStream<String, String> = inputStream2
            .peek { key, value -> 
                logger.info("입력 토픽2 처리 시작: key={}, value={}", key, value)
                Thread.sleep(50)  // 짧은 처리 시간 (50ms)
                logger.info("입력 토픽2 처리 완료: key={}, value={}", key, value)
            }
            .mapValues { value -> "{ \"source\": \"\({mergeInputTopic2}\", \"data\": \"\)value\" }" }
        
        // 두 스트림 병합
        val mergedStream: KStream<String, String> = taggedStream1
            .merge(taggedStream2)
            .peek { key, value -> logger.info("병합된 출력: key={}, value={}", key, value) }
        
        // 병합된 스트림을 출력 토픽으로 전송
        mergedStream.to(mergeOutputTopic1, Produced.with(stringSerde, stringSerde))
        
        return mergedStream
    }
}

이 예제에서는 두 스트림에 의도적으로 다른 처리 시간을 부여하여 병합 동작을 관찰할 수 있도록 했습니다. merge() 연산은 두 스트림의 모든 메시지를 도착 순서대로 하나의 스트림으로 결합합니다.

테스트 결과

merge() 연산을 테스트한 결과, 다음과 같은 특징을 관찰할 수 있었습니다:

1. 메시지 순서: 처리 시간이 짧은 토픽2의 메시지가 토픽1보다 먼저 출력 토픽에 도달

2. 처리 독립성: 각 토픽의 메시지는 서로 독립적으로 처리됨

3. 파티션 영향: 단일 파티션/스레드 환경에서는 발행 순서가 보존될 수 있지만, 멀티 파티션 환경에서는 순서가 섞임

로그 출력 예시:

입력 토픽1 처리 시작: key=topic1-key-1, value=Topic1 테스트 메시지 1
입력 토픽2 처리 시작: key=topic2-key-1, value=Topic2 테스트 메시지 1
입력 토픽2 처리 완료: key=topic2-key-1, value=Topic2 테스트 메시지 1
병합된 출력: key=topic2-key-1, value={ "source": "merge-input-topic-2", "data": "Topic2 테스트 메시지 1" }
입력 토픽2 처리 시작: key=topic2-key-2, value=Topic2 테스트 메시지 2
입력 토픽2 처리 완료: key=topic2-key-2, value=Topic2 테스트 메시지 2
병합된 출력: key=topic2-key-2, value={ "source": "merge-input-topic-2", "data": "Topic2 테스트 메시지 2" }
입력 토픽1 처리 완료: key=topic1-key-1, value=Topic1 테스트 메시지 1
병합된 출력: key=topic1-key-1, value={ "source": "merge-input-topic-1", "data": "Topic1 테스트 메시지 1" }

join() 연산: 키 기반 조인하기

join() 연산은 두 스트림에서 동일한 키를 가진 메시지를 결합합니다. 다음은 시간 윈도우 내에서 키 기반 조인을 수행하는 예제입니다:

@Configuration
@EnableKafkaStreams
class JoinStreamsProcessor {

    private val logger = LoggerFactory.getLogger(JoinStreamsProcessor::class.java)

    @Value("\${kafka.join-input-topic-1:join-input-topic-1}")
    private lateinit var joinInputTopic1: String

    @Value("\${kafka.join-input-topic-2:join-input-topic-2}")
    private lateinit var joinInputTopic2: String

    @Value("\${kafka.join-output-topic:join-output-topic}")
    private lateinit var joinOutputTopic: String

    @Bean
    fun joinStream(streamsBuilder: StreamsBuilder): KStream<String, String> {
        val stringSerde = Serdes.String()
        
        // 첫 번째 입력 토픽에서 스트림 생성
        val stream1: KStream<String, String> = streamsBuilder.stream(
            joinInputTopic1,
            Consumed.with(stringSerde, stringSerde)
        )
        
        // 두 번째 입력 토픽에서 스트림 생성
        val stream2: KStream<String, String> = streamsBuilder.stream(
            joinInputTopic2,
            Consumed.with(stringSerde, stringSerde)
        )
        
        // 로깅 추가
        val loggedStream1 = stream1.peek { key, value -> 
            logger.info("Join 입력 토픽1 수신: key={}, value={}", key, value)
        }
        
        val loggedStream2 = stream2.peek { key, value -> 
            logger.info("Join 입력 토픽2 수신: key={}, value={}", key, value)
        }
        
        // 윈도우 조인 설정 (5초 내에 도착한 메시지 결합)
        val joinWindow = JoinWindows.ofTimeDifferenceWithNoGrace(Duration.ofSeconds(5))
        
        // 스트림 조인 수행 (동일한 키를 가진 메시지 결합)
        val joinedStream: KStream<String, String> = loggedStream1.join(
            loggedStream2,
            { value1, value2 -> 
                """{"topic1": "\(value1", "topic2": "\)value2", "joinTime": "${System.currentTimeMillis()}"}"""
            },
            joinWindow,
            StreamJoined.with(stringSerde, stringSerde, stringSerde)
        )
        
        // 조인 결과 로깅
        val resultStream = joinedStream.peek { key, value -> 
            logger.info("Join 결과: key={}, value={}", key, value)
        }
        
        // 조인된 스트림을 출력 토픽으로 전송
        resultStream.to(joinOutputTopic, Produced.with(stringSerde, stringSerde))
        
        return resultStream
    }
}

이 코드는 5초 시간 윈도우 내에서 동일한 키를 가진 두 토픽의 메시지를 조인합니다. 조인 결과로 두 메시지의 값이 결합된 새로운 JSON 형식의 메시지가 생성됩니다.

윈도우 조인 테스트

윈도우 기반 조인을 테스트하기 위해 다음과 같은 시나리오를 구현했습니다:

1. 동일한 키, 윈도우 내: 같은 키로 두 토픽에 2초 간격으로 메시지 발행 (조인됨)

2. 동일한 키, 윈도우 밖: 같은 키로 두 토픽에 6초 간격으로 메시지 발행 (조인되지 않음)

3. 다른 키: 서로 다른 키로 메시지 발행 (조인되지 않음)

@GetMapping("/test-windowed")
fun testWindowedJoin(): Map<String, String> {
    // 동일한 키를 사용하지만 시간차를 두고 발행 (2초 간격, 윈도우 내)
    for (i in 1..3) {
        val key = "windowed-key-$i"
        joinProducerService.sendToTopic1(key, "Join 토픽1 윈도우 테스트 메시지 $i")
        
        // 2초 후 발행 (5초 윈도우 내에서 Join 됨)
        executor.schedule({
            joinProducerService.sendToTopic2(key, "Join 토픽2 윈도우 테스트 메시지 $i")
        }, 2, TimeUnit.SECONDS)
    }
    
    // 윈도우 범위를 벗어나는 케이스 (6초 후 발행)
    val lateKey = "late-key"
    joinProducerService.sendToTopic1(lateKey, "Join 토픽1 지연 테스트 메시지")
    
    // 6초 후 발행 (5초 윈도우를 벗어남)
    executor.schedule({
        joinProducerService.sendToTopic2(lateKey, "Join 토픽2 지연 테스트 메시지")
    }, 6, TimeUnit.SECONDS)
    
    // 서로 다른 키 테스트 (Join 되지 않음)
    joinProducerService.sendToTopic1("different-key-1", "Join 토픽1 다른 키 테스트")
    joinProducerService.sendToTopic2("different-key-2", "Join 토픽2 다른 키 테스트")
    
    return mapOf("result" to "Join 윈도우 테스트가 시작되었습니다. 약 6초간 메시지가 순차적으로 발행됩니다.")
}

테스트 결과

join() 연산을 테스트한 결과, 다음과 같은 특징을 관찰할 수 있었습니다:

1. 키 기반 조인: 동일한 키를 가진 메시지만 조인됨

2. 시간 윈도우: 5초 이내에 도착한 메시지만 조인됨 (윈도우 밖 메시지는 조인되지 않음)

3. 상태 저장: Join 연산은 스테이트풀 연산으로, 내부적으로 상태를 유지함

로그 출력 예시:

Join 입력 토픽1 수신: key=windowed-key-1, value=Join 토픽1 윈도우 테스트 메시지 1
Join 입력 토픽2 수신: key=windowed-key-1, value=Join 토픽2 윈도우 테스트 메시지 1
Join 결과: key=windowed-key-1, value={"topic1": "Join 토픽1 윈도우 테스트 메시지 1", "topic2": "Join 토픽2 윈도우 테스트 메시지 1", "joinTime": "1621487654321"}
Join 입력 토픽1 수신: key=late-key, value=Join 토픽1 지연 테스트 메시지
Join 입력 토픽2 수신: key=late-key, value=Join 토픽2 지연 테스트 메시지
// 주의: late-key는 6초 간격으로 발행되어 조인 결과가 없음
Join 입력 토픽1 수신: key=different-key-1, value=Join 토픽1 다른 키 테스트
Join 입력 토픽2 수신: key=different-key-2, value=Join 토픽2 다른 키 테스트
// 주의: 다른 키로 발행되어 조인 결과가 없음

파티션과 병렬 처리

Kafka는 토픽을 파티션으로 분할하여 병렬 처리를 지원합니다. 파티션 수와 스레드 수를 조정하여 처리 성능을 최적화할 수 있습니다.

파티션 설정

@Bean
fun joinInputTopic1(): NewTopic {
    return TopicBuilder.name(joinInputTopic1)
        .partitions(3)  // 파티션 수를 3으로 설정
        .replicas(1)
        .build()
}

스레드 설정

spring:
  kafka:
    streams:
      properties:
        num.stream.threads: 3  # Kafka Streams 처리 스레드 수

컨슈머 동시성 설정

@KafkaListener(
    topics = ["\${kafka.join-output-topic:join-output-topic}"],
    groupId = "join-consumer-group",
    concurrency = "3"  // 각 리스너마다 3개의 스레드 사용
)

테스트 결과, 파티션 수와 컨슈머 동시성을 함께 증가시켰을 때 처리량이 크게 향상되는 것을 확인할 수 있었습니다. 특히 merge() 연산의 경우 병렬 처리 효과가 더 두드러졌습니다.

시간 윈도우 기반 처리

Kafka Streams는 시간 윈도우 기반 처리를 지원합니다. 이는 특히 join() 연산에서 유용하게 사용됩니다.

// 5초 시간 윈도우 내에서 조인
val joinWindow = JoinWindows.ofTimeDifferenceWithNoGrace(Duration.ofSeconds(5))

시간 윈도우 설정을 통해 다양한 시나리오를 구현할 수 있습니다:

1. 텀블링 윈도우(Tumbling Window): 고정 크기, 겹치지 않는 윈도우

2. 호핑 윈도우(Hopping Window): 고정 크기, 겹치는 윈도우

3. 슬라이딩 윈도우(Sliding Window): 동적 크기, 연속적으로 이동하는 윈도우

4. 세션 윈도우(Session Window): 비활동 간격으로 구분되는 윈도우

시간 윈도우 기반 처리는 시간적 연관성이 중요한 이벤트를 처리할 때 유용합니다. 예를 들어, 사용자 행동 분석, 이상 탐지, 시계열 집계 등에 활용될 수 있습니다.

성능 테스트 및 결과 분석

merge()와 join() 연산의 성능을 비교하기 위해 다양한 조건에서 테스트를 수행했습니다.

테스트 환경

• 메시지 수: 각 토픽당 10,000개

• 파티션 수: 1, 3, 6개

• 스레드 수: 1, 3, 6개

• 키 분포: 균등 분포 vs 치우친 분포

주요 결과

1. 처리량(Throughput)

   • merge(): 평균 15,000 msgs/sec

   • join(): 평균 7,500 msgs/sec (동일한 키 분포 가정)

2. 지연 시간(Latency)

   • merge(): 평균 10ms

   • join(): 평균 25ms

3. 메모리 사용량

   • merge(): 낮음 (스테이트리스)

   • join(): 높음 (스테이트풀)

4. 파티션 확장성

   • merge(): 파티션 수에 거의 선형적으로 성능 증가

   • join(): 파티션 증가에 따른 성능 향상이 제한적

분석

성능 테스트 결과, merge() 연산은 단순히 두 스트림을 결합하는 스테이트리스 연산이기 때문에 더 높은 처리량과 낮은 지연 시간을 보였습니다. 반면 join() 연산은 상태를 유지하고 윈도우 내에서 메시지를 조인해야 하기 때문에 더 많은 리소스를 소비하고 처리 속도가 느렸습니다.

특히 키 분포가 치우친 경우(hot key), join() 연산의 성능이 크게 저하되는 것을 관찰할 수 있었습니다. 이는 특정 파티션에 부하가 집중되기 때문입니다.

결론

Kafka Streams의 merge()와 join() 연산은 각각 다른 특성과 사용 사례를 가지고 있습니다.

merge() 연산 요약

• 특징: 키나 값에 관계없이 모든 메시지를 하나의 스트림으로 병합

• 성능: 높은 처리량, 낮은 지연 시간, 낮은 리소스 사용량

• 사용 사례: 단순 로깅, 모니터링, 데이터 수집

join() 연산 요약

• 특징: 동일한 키를 가진 메시지만 조인, 시간 윈도우 적용 가능

• 성능: 중간 처리량, 중간 지연 시간, 높은 리소스 사용량

• 사용 사례: 트랜잭션 처리, 이벤트 상관관계 분석, 데이터 보강

선택 가이드

1. 단순히 여러 소스의 데이터를 결합하고 싶다면 → merge()

2. 관련 이벤트를 키 기반으로 결합하고 싶다면 → join()

3. 처리량이 중요하다면 → merge()

4. 데이터 일관성과 관계가 중요하다면 → join()

이번 블로그에서는 Kafka Streams API의 merge()와 join() 연산의 동작 방식과 성능 특성을 살펴보았습니다. 각 연산의 장단점과 적합한 사용 사례를 이해함으로써, 실시간 데이터 처리 애플리케이션을 더 효과적으로 설계할 수 있기를 바랍니다.

전체 코드와 더 자세한 내용은 GitHub 저장소에서 확인할 수 있습니다.

• 카프카 메세지 발행 후 컨슘이 안됨

• consume 로직이 파티션 할당부터 진행되지 않음

• 카프카 pod 오류 로그가 올라오고 있었음

[2025-05-18 11:17:18,121] INFO [Controller 1] CreateTopics result(s): CreatableTopic(name='__consumer_offsets', numPartitions=50, replicationFactor=3, assignments=[], configs=[CreateableTopicConfig(name='compression.type', value='producer'), CreateableTopicConfig(name='cleanup.policy', value='compact'), CreateableTopicConfig(name='segment.bytes', value='104857600')]): INVALID_REPLICATION_FACTOR (Unable to replicate the partition 3 time(s): The target replication factor of 3 cannot be reached because only 1 broker(s) are registered.) (org.apache.kafka.controller.ReplicationControlManager)

원인

로컬에서 테스트 중이라서 싱글 노드로 카프카 클러스터를 구성했는데 카프카 내부 토픽 중에서 __consumer_offsets에 대해서느 복제계수를 3으로 설정해서 생성하려고 하니 오류가 발생함

해결방법

카프카 자체의 복제계수를 1로 설정해서 재시작 진행

로컬 카프카는 docker compose 를 이용해서 구성하고 있어서 docker compose에 복제 계수 환경 변수를 추가함

• docker-compose.yml

version: '3'
services:
  kafka:
    image: confluentinc/cp-kafka:7.4.0
    container_name: kafka
    ports:
      - "9092:9092"
    environment:
      KAFKA_NODE_ID: 1
      KAFKA_PROCESS_ROLES: 'broker,controller'
      KAFKA_CONTROLLER_QUORUM_VOTERS: '1@kafka:29093'
      KAFKA_LISTENERS: 'PLAINTEXT://kafka:29092,CONTROLLER://kafka:29093,PLAINTEXT_HOST://0.0.0.0:9092'
      KAFKA_ADVERTISED_LISTENERS: 'PLAINTEXT://kafka:29092,PLAINTEXT_HOST://localhost:9092'
      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: 'CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT,PLAINTEXT_HOST:PLAINTEXT'
      KAFKA_CONTROLLER_LISTENER_NAMES: 'CONTROLLER'
      KAFKA_INTER_BROKER_LISTENER_NAME: 'PLAINTEXT'
      CLUSTER_ID: 'MkU3OEVBNTcwNTJENDM2Qk'
      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
    volumes:
      - ./kafka-data:/var/lib/kafka/data
    networks:
      - kafka-net

  kafka-ui:
    image: provectuslabs/kafka-ui:latest
    container_name: kafka-ui
    depends_on:
      - kafka
    ports:
      - "8080:8080"
    environment:
      KAFKA_CLUSTERS_0_NAME: local-kraft
      KAFKA_CLUSTERS_0_BOOTSTRAPSERVERS: kafka:29092
    networks:
      - kafka-net

networks:
  kafka-net:
    driver: bridge

Redis(Remote Dictionary Server)는 인메모리 데이터 구조 저장소로, 다양한 데이터 구조(문자열, 해시, 리스트, 셋, 정렬된 셋 등)를 지원하는 NoSQL 데이터베이스입니다. 주요 특징으로는:

• 인메모리 작동 방식으로 매우 빠른 읽기/쓰기 성능 제공

• 데이터 영속성 지원 (RDB 스냅샷, AOF 로그)

• 단일 스레드 아키텍처로 원자적 작업 보장

• 복제, 클러스터, 센티널 등의 고가용성 기능 제공

• 키-값 저장소지만, 다양한 데이터 타입을 지원해 활용도가 높음

Redis는 캐싱, 세션 저장소, 메시지 브로커, 실시간 분석 등 다양한 용도로 사용됩니다.

Redis가 장애가 났을 때 장애 복구를 위해서 할 수 있는 대응 방법

Redis 장애 상황에서 복구를 위한 여러 방법이 있습니다:

1. 복제(Replication): 마스터-슬레이브 구조로 데이터를 여러 서버에 복제하여 마스터 서버 장애 시 슬레이브가 데이터 제공

2. Redis Sentinel: 자동 장애 감지 및 페일오버를 통해 마스터 장애 시 슬레이브를 새 마스터로 승격

3. Redis Cluster: 여러 노드에 데이터를 분산 저장하고 자동 장애 복구 제공

4. 데이터 지속성 설정: RDB(Redis Database Backup) 스냅샷이나 AOF(Append Only File) 로그를 통해 데이터 복구 가능

5. 백업 및 복원: 정기적인 백업을 통해 장애 발생 시 데이터 복원

이 중에서 Redis Sentinel은 고가용성을 위한 가장 효과적인 솔루션 중 하나입니다.

센티널이란 무엇인가?

Redis Sentinel은 Redis의 고가용성 솔루션으로, 다음과 같은 기능을 제공합니다:

1. 모니터링: 마스터와 슬레이브 노드가 정상적으로 작동하는지 지속적으로 감시합니다.

2. 자동 장애 감지: 마스터 노드에 문제가 발생하면 이를 감지합니다. 여러 센티널이 쿼럼을 통해 마스터 장애를 합의합니다.

3. 자동 페일오버: 마스터 노드에 장애가 발생하면 적합한 슬레이브를 선택해 새로운 마스터로 승격시키고, 다른 슬레이브들이 새 마스터를 바라보도록 재구성합니다.

4. 클라이언트 통지: 클라이언트에게 현재 마스터의 주소를 알려주어 연결 관리를 도와줍니다.

5. 구성 제공자: 클라이언트가 현재 Redis 토폴로지를 조회할 수 있는 서비스 역할을 합니다.

센티널은 일반적으로 최소 3개 이상의 인스턴스로 구성하여 과반수 투표를 통한 안정적인 장애 감지를 보장합니다.

센티널과 클러스터는 무엇이 다른가?

클러스터는 여러 노드에 데이터를 분산해서 수평적인 확장을 할 수 있도록 하는 것이 목적입니다.

클러스터 내장으로 자체 자동 장애 감지가 있는 경우가 있습니다.

그래서 클러스터의 경우 각 마스터 노드가 대체로 전속 슬레이브 노드를 가지고 있습니다.

센티널의 경우 복제 환경을 기본전제로 두고 장애 상황에서 Master-Slave 간의 전환을 통해서 장애 대응을 하는 전략을 의미합니다.

따라서 기본적으로 Master-Slave 가 최소 1개 이상 존재해야하며 일반적으로 센티널 노드까지 일반적으로 최소 3개 이상 구성되어 있어야 합니다.

센티널 설정하고 직접 장애 내보기

센티널을 설정하고 장애 테스트를 하는 과정은 다음과 같습니다:

1. Docker Compose 파일 구성:

   • Redis 마스터 노드 1개

   • Redis 슬레이브 노드 2개

   • Sentinel 노드 2개

   • 각각 고정 IP 주소 할당

2. 센티널 설정 파일 구성:

    port 26379
    dir "/tmp"
    sentinel monitor mymaster 172.18.0.2 6379 2
    sentinel down-after-milliseconds mymaster 5000
    sentinel failover-timeout mymaster 60000
    sentinel auth-pass mymaster redispassword
    sentinel known-replica mymaster 172.18.0.5 6379
    sentinel known-replica mymaster 172.18.0.6 6379
    requirepass "redispassword"
   

3. 장애 테스트 시나리오:

   • 마스터 노드(172.18.0.2)를 강제 종료

   • 센티널이 장애를 감지하고 슬레이브 중 하나를 마스터로 승격

   • 새 마스터는 포트 번호 변경 없이 역할만 변경됨

   • 다른 슬레이브는 새 마스터를 바라보도록 재구성

   • 애플리케이션은 센티널을 통해 새 마스터 정보를 얻어 접속 계속

4. 실제 테스트 확인:

   • docker-compose stop redis-master 명령으로 마스터 노드 중단

   • redis-cli -h 172.18.0.3 -p 26379 -a redispassword sentinel masters 명령으로 새 마스터 확인

   • 센티널 로그를 통해 페일오버 과정 확인

그림을 통해서 보는 장애 시나리오

센터널 실제 로그 분석

센티널 노드의 전체 로그

1:X 04 May 2025 07:28:15.355 # +sdown master mymaster 172.18.0.2 6379
1:X 04 May 2025 07:28:15.447 # +odown master mymaster 172.18.0.2 6379 #quorum 2/2
1:X 04 May 2025 07:28:15.447 # +new-epoch 1
1:X 04 May 2025 07:28:15.447 # +try-failover master mymaster 172.18.0.2 6379
1:X 04 May 2025 07:28:15.455 # Could not rename tmp config file (Device or resource busy)
1:X 04 May 2025 07:28:15.455 # WARNING: Sentinel was not able to save the new configuration on disk!!!: Device or resource busy
1:X 04 May 2025 07:28:15.455 # +vote-for-leader abadec7630202c8c8c151e5ac8e9945f13c6d066 1
1:X 04 May 2025 07:28:15.462 * 6c10b56b55c5190b3b87376b575263fa1a871725 voted for abadec7630202c8c8c151e5ac8e9945f13c6d066 1
1:X 04 May 2025 07:28:15.508 # +elected-leader master mymaster 172.18.0.2 6379
1:X 04 May 2025 07:28:15.508 # +failover-state-select-slave master mymaster 172.18.0.2 6379
1:X 04 May 2025 07:28:15.565 # +selected-slave slave 172.18.0.5:6379 172.18.0.5 6379 @ mymaster 172.18.0.2 6379
1:X 04 May 2025 07:28:15.565 * +failover-state-send-slaveof-noone slave 172.18.0.5:6379 172.18.0.5 6379 @ mymaster 172.18.0.2 6379
1:X 04 May 2025 07:28:15.656 * +failover-state-wait-promotion slave 172.18.0.5:6379 172.18.0.5 6379 @ mymaster 172.18.0.2 6379
1:X 04 May 2025 07:28:16.461 # Could not rename tmp config file (Device or resource busy)
1:X 04 May 2025 07:28:16.462 # WARNING: Sentinel was not able to save the new configuration on disk!!!: Device or resource busy
1:X 04 May 2025 07:28:16.462 # +promoted-slave slave 172.18.0.5:6379 172.18.0.5 6379 @ mymaster 172.18.0.2 6379
1:X 04 May 2025 07:28:16.462 # +failover-state-reconf-slaves master mymaster 172.18.0.2 6379
1:X 04 May 2025 07:28:16.559 * +slave-reconf-sent slave 172.18.0.6:6379 172.18.0.6 6379 @ mymaster 172.18.0.2 6379
1:X 04 May 2025 07:28:17.544 * +slave-reconf-inprog slave 172.18.0.6:6379 172.18.0.6 6379 @ mymaster 172.18.0.2 6379
1:X 04 May 2025 07:28:17.544 * +slave-reconf-done slave 172.18.0.6:6379 172.18.0.6 6379 @ mymaster 172.18.0.2 6379
1:X 04 May 2025 07:28:17.611 # +failover-end master mymaster 172.18.0.2 6379
1:X 04 May 2025 07:28:17.611 # +switch-master mymaster 172.18.0.2 6379 172.18.0.5 6379
1:X 04 May 2025 07:28:17.611 * +slave slave 172.18.0.6:6379 172.18.0.6 6379 @ mymaster 172.18.0.5 6379
1:X 04 May 2025 07:28:17.611 * +slave slave 172.18.0.2:6379 172.18.0.2 6379 @ mymaster 172.18.0.5 6379
1:X 04 May 2025 07:28:17.615 # Could not rename tmp config file (Device or resource busy)
1:X 04 May 2025 07:28:17.615 # WARNING: Sentinel was not able to save the new configuration on disk!!!: Device or resource busy
1:X 04 May 2025 07:28:22.676 # +sdown slave 172.18.0.2:6379 172.18.0.2 6379 @ mymaster 172.18.0.5 6379
1:X 04 May 2025 07:29:31.905 # -sdown slave 172.18.0.2:6379 172.18.0.2 6379 @ mymaster 172.18.0.5 6379
1:X 04 May 2025 07:29:41.827 * +convert-to-slave slave 172.18.0.2:6379 172.18.0.2 6379 @ mymaster 172.18.0.5 6379

1. 마스터 노드가 모종의 이유(그것은 나)로 죽었고 fail-over 전략을 시도하는 것을 확인할 수 있습니다

1:X 04 May 2025 07:28:15.355 # +sdown master mymaster 172.18.0.2 6379
1:X 04 May 2025 07:28:15.447 # +odown master mymaster 172.18.0.2 6379 #quorum 2/2
1:X 04 May 2025 07:28:15.447 # +new-epoch 1
1:X 04 May 2025 07:28:15.447 # +try-failover master mymaster 172.18.0.2 6379

2. 슬레이브 노드 중 하나가 센티널에 의해서 마스터 노드로 승격될 대상으로 결정된 것을 볼 수 있습니다

1:X 04 May 2025 07:28:15.508 # +elected-leader master mymaster 172.18.0.2 6379
1:X 04 May 2025 07:28:15.508 # +failover-state-select-slave master mymaster 172.18.0.2 6379
1:X 04 May 2025 07:28:15.565 # +selected-slave slave 172.18.0.5:6379 172.18.0.5 6379 @ mymaster 172.18.0.2 6379

3. 다시 살아난 마스터노드는 이후에 슬레이브 노드로 좌천되는 것도 볼 수 있습니다

1:X 04 May 2025 07:29:41.827 * +convert-to-slave slave 172.18.0.2:6379 172.18.0.2 6379 @ mymaster 172.18.0.5 6379

결론 요약

• Redis는 메모리 기반의 Key-Value 저장소이다

• Redis 장애 대응을 위한 준비로 크게 아래의 것들을 할 수 있습니다

  • Cluster Setting

  • Redis Sentinel

  • Snapshot Backup

• Redis Sentinel은 최소 1개의 Master, Slave 노드가 존재해야하만 사용할 수 있고 Application 단에서도 장애 상황에 변경되는 마스터 노드를 확인하기 위한 대비가 application 단에서 되어 있어야합니다.

• Redis Sentinel는 특정 마스터 노드가 문제가 발생하였을 때 센티널들끼리 투표를 통해서 슬레이브 노드를 마스터 노드로 승격시키고 기존 마스터 노드가 회복되면 슬레이브 노드로 강등시킵니다.

느낀점

Redis Sentinel을 통한 고가용성 구성에서 배운 중요한 점들:

1. 무중단 서비스의 중요성: Redis와 같은 핵심 인프라 서비스는 장애 시에도 서비스 중단 없이 계속 작동해야 함을 실감했습니다.

2. 자동화된 장애 복구: 센티널을 통해 사람의 개입 없이 자동으로 마스터 노드 장애를 감지하고 복구하는 메커니즘의 효율성을 경험했습니다.

3. 애플리케이션 설계 고려사항: 고가용성 인프라를 활용하기 위해서는 애플리케이션도 적절히 설계되어야 함을 알게 되었습니다. 특히 Sentinel 클라이언트 라이브러리를 사용하여 마스터 노드 변경에 대응하는 방법이 중요합니다.

4. 포트 번호 유지와 역할 변경: 페일오버 시 IP와 포트는 그대로 유지되고 노드의 역할만 변경된다는 것이 매우 직관적이고 효과적인 설계임을 알게 되었습니다.

5. 분산 시스템 이해 증진: 마스터-슬레이브 아키텍처와 센티널을 통한 고가용성 구성을 통해 분산 시스템에 대한 이해가 깊어졌습니다.

이러한 경험을 통해 프로덕션 환경에서 안정적인 서비스를 제공하기 위한 인프라 구성의 중요성과 그 구현 방법에 대해 실질적인 지식을 얻게 되었습니다.

참고 자료

• 실습 코드 Github REPO

• Redis Sentinel 도커 배포하기

왜 Elasticsearch를 선택했는가?

1. 복잡한 점수 구조의 저장 및 분석

프로젝트에서는 OptaPlanner의 BendableScore를 사용하여 하드/소프트 제약 조건을 구분하고 있습니다. 각 제약 조건별로 상세한 점수가 기록되는데, 이러한 중첩된 데이터 구조를 Elasticsearch의 Nested 타입으로 효과적으로 저장할 수 있습니다.

data class ScoreCoordinate(
    val level: Int,
    val isHard: Boolean,
    val score: Int,
    val constraintName: String,
    val constraintDescription: String
)

2. 시계열 데이터의 효율적 관리

빈 패킹 작업의 히스토리를 날짜별로 관리하고, 최적화 성능의 추이를 분석해야 했습니다. Elasticsearch는 날짜 기반 인덱싱과 Index Lifecycle Management를 통해 이러한 요구사항을 효과적으로 처리할 수 있습니다.

3. 실시간 분석과 시각화

Grafana 대시보드와 통합하여 빈 패킹 성능 지표를 실시간으로 모니터링할 수 있고, 다양한 제약 조건별 점수 분포를 시각화할 수 있습니다.

Elasticsearch 적용 과정

1. 프로젝트 의존성 설정

Spring Boot 3.4.4와 호환되는 Elasticsearch 의존성을 추가하고, 설정 클래스를 작성합니다.

ES, Kibana는 docker compose를 이용해서 컨테이너를 띄웠습니다

YAML

services:
  elasticsearch:
    image: docker.elastic.co/elasticsearch/elasticsearch:8.11.3
    environment:
      - discovery.type=single-node
      - xpack.security.enabled=false
    ports:
      - "9200:9200"

  kibana:
    image: docker.elastic.co/kibana/kibana:8.11.3
    ports:
      - "5601:5601"

Kotlin

dependencies {
    implementation("org.springframework.boot:spring-boot-starter-data-elasticsearch")
}

application.yml에서 프로필별 Elasticsearch 연결 설정을 구성합니다:

spring:
  elasticsearch:
    uris: ${ELASTICSEARCH_URI:http://localhost:9200}
    username: ${ELASTICSEARCH_USERNAME:elastic}
    password: ${ELASTICSEARCH_PASSWORD:changeme}

2. Document 객체 생성

빈 패킹 결과와 점수 상세 정보를 저장할 Document 클래스를 생성합니다:

@Document(indexName = "bin-pack-recommend-result")
data class BinPackRecommendResult(
    @Id val id: String? = null,
    @Field(type = FieldType.Long) val solutionId: Long,
    @Field(type = FieldType.Nested) val scoreCoordinates: List<ScoreCoordinate>,
    @Field(type = FieldType.Date) val createdAt: OffsetDateTime,
    @Field(type = FieldType.Nested) val assignments: List<AssignmentDetail>
)

3. 날짜별 인덱스 생성 구현

매일 새로운 인덱스가 생성되도록 커스텀 리포지토리를 구현합니다:

object IndexNameGenerator {
    private const val BASE_INDEX_NAME = "bin-pack-recommend-result"
    private val DATE_FORMATTER = DateTimeFormatter.ofPattern("yyyy-MM-dd")

    fun generateIndexName(date: LocalDate = LocalDate.now()): String {
        return "${BASE_INDEX_NAME}-${date.format(DATE_FORMATTER)}"
    }
}

class BinPackRecommendResultCustomRepositoryImpl(
    private val operations: ElasticsearchOperations
) : BinPackRecommendResultCustomRepository {

    override fun saveWithDateIndex(document: BinPackRecommendResult) {
        val indexName = IndexNameGenerator.generateIndexName()
        val query = IndexQueryBuilder()
            .withId(document.id.toString())
            .withObject(document)
            .build()

        operations.index(query, IndexCoordinates.of(indexName))
    }
}

4. ILM 설정을 통한 인덱스 TTL 설정

인덱스가 자동으로 순환되도록 설정합니다. 이 프로젝트에서는 Elasticsearch 설정파일을 통해 구현할 예정이며, 현재는 날짜별 인덱스 구조를 먼저 구축했습니다. ILM 설정은 다음과 같이 적용할 계획입니다:

{
  "policy": {
    "phases": {
      "hot": {
        "actions": {
          "rollover": {
            "max_age": "30d",
            "max_size": "50GB"
          }
        }
      },
      "delete": {
        "min_age": "90d",
        "actions": {
          "delete": {}
        }
      }
    }
  }
}

5. 적용 결과 확인

이벤트 기반 아키텍처를 통해 PostgreSQL에 먼저 저장된 후, 비동기로 Elasticsearch에도 저장합니다:

@TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
fun handleRecommendResultSaved(event: RecommendResultSavedEvent) {
    try {
        val documentToSave = BinPackRecommendResult.from(
            result = event.recommendResult,
            skus = skuDocuments,
            scoreDescription = event.scoreDescription,
            scoreCoordinates = event.scoreCoordinates,
            assignments = event.assignments
        )

        binPackRecommendResultRepository.saveWithDateIndex(documentToSave)
        logger.info("Successfully saved recommend result ${event.recommendResult.id} to Elasticsearch")
    } catch (e: Exception) {
        logger.error("Failed to save recommend result ${event.recommendResult.id} to Elasticsearch", e)
    }
}

도커 환경에서 실행하면 다음과 같이 Elasticsearch와 Kibana가 함께 실행되어 데이터를 확인할 수 있습니다:

Kibana에서 추천 결과 확인

느낀점

1. Elasticsearch의 유연성: JSON 형태의 복잡한 중첩 데이터 구조를 자연스럽게 저장하고 쿼리할 수 있어 OptaPlanner의 상세한 점수 정보를 효과적으로 관리할 수 있었습니다.

2. 이벤트 기반 아키텍처의 장점: Spring의 @TransactionalEventListener를 활용하여 PostgreSQL 저장이 성공한 후에 Elasticsearch에 저장하는 구조로, 데이터 일관성을 보장하면서도 성능 저하를 최소화할 수 있었습니다.

3. 인덱스 관리의 중요성: 날짜별 인덱스 분리를 통해 오래된 데이터의 효율적인 삭제와 검색 성능 향상을 동시에 달성할 수 있었습니다. 아직 ILM 설정은 구현 예정이지만, 장기적인 데이터 관리 전략이 중요함을 깨달았습니다.

이 과정을 통해 Elasticsearch가 단순한 검색 엔진이 아닌, 복잡한 분석 데이터의 저장소로서도 매우 효과적임을 확인할 수 있었습니다. 특히 최적화 알고리즘의 결과 분석에 필요한 다차원 데이터를 효과적으로 다룰 수 있는 강력한 도구임을 실감했습니다.

문제 정의

You are given an integer array height of length n. There are n vertical lines drawn such that the two endpoints of the i<sup>th</sup> line are (i, 0) and (i, height[i]).

Find two lines that together with the x-axis form a container, such that the container contains the most water.

Return the maximum amount of water a container can store.

Notice that you may not slant the container.

Example 1:

Input: height = [1,8,6,2,5,4,8,3,7]
Output: 49
Explanation: The above vertical lines are represented by array [1,8,6,2,5,4,8,3,7]. In this case, the max area of water (blue section) the container can contain is 49.

Example 2:

Input: height = [1,1]
Output: 1

Constraints:

• n == height.length

• 2 <= n <= 10<sup>5</sup>

• 0 <= height[i] <= 10<sup>4</sup>

문제 분석

서로 다른 기둥이 있을 때 가장 많이 물을 담을 수 있는 범위를 구하는 문제입니다.

결국 서로 다른 기둥을 찾을 때에 최소 탐색으로 찾을 수 있도록 선택을 하는 것이 필요합니다.

이 문제는 직관적으로 ‘서로 다른 2개의 높이‘라는 부분에서 2 pointer 문제라는 것을 알 수 있기 때문에 그렇게 문제를 풀었습니다.

의사 코드는 다음과 같습니다

1. left, right, answer 선언

2. left < right 이면 반복

   1. height[left] < height[right]이면, left+1

   2. height[left] >= height[right]이면, right+1

의사 코드의 핵심은 높이가 낮은 쪽을 스킵하면서 진행된다는 것입니다.

왜냐하면 아무리 너비가 길어도 높이가 낮으면 최대 값이 되지 못하기 때문입니다.

해결 방안

import kotlin.math.min
import kotlin.math.max

class Solution {
    fun maxArea(height: IntArray): Int {
        var left = 0
        var right = height.lastIndex
        var maxArea = 0

        while (left < right) {
            val w = right - left
            val h = min(height[right], height[left])
            val area = w * h

            maxArea = max(maxArea, area)

            if (height[left] < height[right]) {
                left++
            } else {
                right--
            }
        }

        return maxArea
    }
}

느낀점

전형적인 2 pointer 문제이지만 아무 간단한 높이가 낮은 쪽부터 스킵한다는 생각을 못해서 시간을 많이 사용한 문제였던 것 같습니다.

지금부터 아무것도 모르는 상황에서 ArgoCD를 세팅해보도록 하겠습니다. 이번 글은 AI를 사용해서 아무것도 모르는 상황에서 과연 어디까지 인프라를 세팅할 수 있을지 테스트해보는 시간입니다.

우선 제가 미리 만들어둔 API 서버가 존재하고 이걸 다음과 같이 구성할 것입니다. 저의 목표는 잘 만드는 것이 아니라 돌아가도록 구성하는 것이 목표이기 때문에 수단과 방법을 가리지 않을 것입니다.

1. API Pod 2개

2. DB Pod 1개

로 구성할 예정이고 나머지는 어떻게 해야하는지 아무것도 모르는 것이 현재 상황입니다.

제가 알고 있는 기본 지식은 다음과 같습니다:

• Docker를 어떻게 사용하는지 간단히 알고 있습니다

• 혼자서 Application 서버를 만들고 포트와 같은 기본적인 세팅은 혼자서 할 수 있습니다

• 쿠버네티스는 이름만 알고 실제로 어떻게 동작하는지 어떻게 세팅하는지 하나도 모릅니다

• ArgoCD는 쿠버네티스랑 같이 사용하면 좋은건 알지만 정확히 모릅니다

이런 상황에서 클로드 MCP를 이용해서 ArgoCD를 세팅해보도록 하겠습니다

도커 파일 세팅 및 이미지를 빌드해보자

우선 간단하게 도커 이미지가 있어서 모든 것을 시작할 수 있으니 DockerFile을 클로드에게 만들어 달라고 했습니다. 너무 간단하게 프로젝트를 스캔하고 만들어줘서 1초만에 끝났습니다.

kotlinFROM openjdk:17-jdk-slim

WORKDIR /app

COPY build/libs/box-recommend-0.0.1-SNAPSHOT.jar app.jar

EXPOSE 8080

ENTRYPOINT ["java", "-jar", "/app/app.jar"]

이 Dockerfile은 나의 Spring Boot 애플리케이션(box-recommend)을 도커 이미지로 패키징하는 과정을 담고 있습니다. OpenJDK 17을 기반으로 하고, 빌드된 JAR 파일을 컨테이너 내부로 복사한 다음, 8080 포트를 노출시키고 Java 명령어로 애플리케이션을 실행합니다.

이제 이미지를 빌드해볼 차례입니다. 터미널을 열고 Dockerfile이 있는 디렉토리에서 다음 명령을 실행했습니다:

bash# Gradle로 애플리케이션 빌드
./gradlew build

# Docker 이미지 빌드
docker build -t box-recommend:v1 .

빌드가 성공적으로 완료되었고, 로컬에서 테스트해보기로 했습니다:

bashdocker run -p 8080:8080 box-recommend:v1

애플리케이션이 정상적으로 시작되는 것을 확인했습니다. 이제 실제 쿠버네티스 환경으로 넘어갈 준비가 되었습니다.

쿠버네티스를 세팅하여서 파드를 띄워보자

자, 이제 진짜 도전이 시작됩니다. 쿠버네티스에 대해 아무것도 모르지만, 일단 로컬 환경에서 테스트하기 위해 Minikube를 설치하기로 했습니다.

bash# Minikube 설치 (맥OS 기준)
brew install minikube

# Minikube 시작
minikube start

Minikube가 설치되고 실행되었습니다. 쿠버네티스 CLI인 kubectl도 함께 설치되었습니다.

이제 우리 애플리케이션을 위한 기본적인 쿠버네티스 매니페스트 파일들을 만들어야 합니다. 우선 API 서버 Deployment와 Service부터 정의해 보겠습니다:

yaml# api-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: box-recommend-api
spec:
  replicas: 2  # API Pod 2개를 요청했으니 replicas를 2로 설정
  selector:
    matchLabels:
      app: box-recommend
  template:
    metadata:
      labels:
        app: box-recommend
    spec:
      containers:
      - name: box-recommend
        image: box-recommend:v1
        ports:
        - containerPort: 8080
        env:
        - name: SPRING_DATASOURCE_URL
          value: jdbc:postgresql://box-recommend-db:5432/box_recommend
        - name: SPRING_DATASOURCE_USERNAME
          value: test1234
        - name: SPRING_DATASOURCE_PASSWORD
          value: test1234
---
# api-service.yaml
apiVersion: v1
kind: Service
metadata:
  name: box-recommend-api
spec:
  selector:
    app: box-recommend
  ports:
  - port: 80
    targetPort: 8080
  type: ClusterIP

다음으로 PostgreSQL 데이터베이스를 위한 매니페스트 파일을 만들었습니다:

yaml# db-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: box-recommend-db
spec:
  replicas: 1  # DB Pod 1개
  selector:
    matchLabels:
      app: box-recommend-db
  template:
    metadata:
      labels:
        app: box-recommend-db
    spec:
      containers:
      - name: postgres
        image: postgres:13
        ports:
        - containerPort: 5432
        env:
        - name: POSTGRES_DB
          value: box_recommend
        - name: POSTGRES_USER
          value: test1234
        - name: POSTGRES_PASSWORD
          value: test1234
        volumeMounts:
        - name: postgres-data
          mountPath: /var/lib/postgresql/data
      volumes:
      - name: postgres-data
        emptyDir: {}  # 실제 환경에서는 PersistentVolume을 사용해야 합니다
---
# db-service.yaml
apiVersion: v1
kind: Service
metadata:
  name: box-recommend-db
spec:
  selector:
    app: box-recommend-db
  ports:
  - port: 5432
    targetPort: 5432
  type: ClusterIP

이제 이 파일들을 사용하여 쿠버네티스에 리소스를 생성해보겠습니다:

bash# Minikube의 Docker 데몬에 이미지 빌드하기
eval $(minikube docker-env)
docker build -t box-recommend:v1 .

# 쿠버네티스 리소스 생성
kubectl apply -f api-deployment.yaml
kubectl apply -f api-service.yaml
kubectl apply -f db-deployment.yaml
kubectl apply -f db-service.yaml

생성된 리소스들을 확인해봅니다:

bashkubectl get deployments
kubectl get pods
kubectl get services

API 파드 2개와 DB 파드 1개가 정상적으로 실행 중인 것을 확인할 수 있었습니다.

레지스트리 세팅 및 이미지 저장하여 쿠버네티스에서 호출할 수 있도록 해보자

실제 프로덕션 환경에서는 도커 이미지를 도커 레지스트리에 푸시하고 쿠버네티스가 그곳에서 이미지를 가져와야 합니다. Minikube에서는 로컬 이미지를 사용할 수 있지만, GitOps 방식으로 ArgoCD를 사용하려면 레지스트리가 필요합니다.

간단하게 Docker Hub를 사용하기로 결정했습니다:

bash# Docker Hub에 로그인
docker login

# 이미지에 태그 지정 (내 Docker Hub 사용자명으로 대체)
docker tag box-recommend:v1 myusername/box-recommend:v1

# Docker Hub에 이미지 푸시
docker push myusername/box-recommend:v1

이제 매니페스트 파일을 업데이트하여 Docker Hub의 이미지를 사용하도록 변경합니다:

yaml# api-deployment.yaml (수정 부분)
      containers:
      - name: box-recommend
        image: myusername/box-recommend:v1  # Docker Hub 이미지로 변경

수정된 파일을 적용합니다:

bashkubectl apply -f api-deployment.yaml

ArgoCD 세팅하여서 UI로 지금까지 구성한 내용을 확인해보자

이제 ArgoCD를 설치하고 설정해보겠습니다. ArgoCD는 Git 저장소에서 쿠버네티스 매니페스트 파일을 가져와 클러스터에 자동으로 적용하는 GitOps 도구입니다.

bash# ArgoCD 네임스페이스 생성
kubectl create namespace argocd

# ArgoCD 설치
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

# ArgoCD CLI 설치 (맥OS 기준)
brew install argocd

ArgoCD 서비스를 외부에서 접속할 수 있도록 포트 포워딩을 설정합니다:

bashkubectl port-forward svc/argocd-server -n argocd 8080:443

이제 웹 브라우저에서 https://localhost:8080으로 접속할 수 있습니다. 초기 로그인 정보는 다음과 같습니다:

• 사용자명: admin

• 비밀번호: (자동 생성됨, 다음 명령어로 확인)

bashkubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d

로그인 후, 우리의 애플리케이션을 ArgoCD에 등록하기 위해 먼저 Git 저장소를 만들고 매니페스트 파일을 저장해야 합니다. GitHub에 새 저장소를 만들고 매니페스트 파일을 푸시했습니다:

bash# 로컬에 Git 저장소 초기화
mkdir box-recommend-k8s
cd box-recommend-k8s
git init

# 매니페스트 파일 복사
cp ../api-deployment.yaml .
cp ../api-service.yaml .
cp ../db-deployment.yaml .
cp ../db-service.yaml .

# 변경사항 커밋 및 푸시
git add .
git commit -m "Initial commit for Kubernetes manifests"
git remote add origin https://github.com/myusername/box-recommend-k8s.git
git push -u origin main

이제 ArgoCD UI에서 새 애플리케이션을 추가합니다:

1. "NEW APP" 버튼 클릭

2. 애플리케이션 정보 입력:

   • Application Name: box-recommend

   • Project: default

   • Sync Policy: Automatic

   • Repository URL: https://github.com/myusername/box-recommend-k8s.git

   • Path: .

   • Cluster: https://kubernetes.default.svc (기본 클러스터)

   • Namespace: default

3. "CREATE" 버튼 클릭

ArgoCD가 자동으로 Git 저장소에서 매니페스트 파일을 가져와 쿠버네티스 클러스터에 적용합니다. UI에서 애플리케이션의 상태를 시각적으로 확인할 수 있습니다. 모든 리소스가 정상적으로 동기화되고 실행 중인 상태로 표시됩니다.

만들어둔 API 호출하여 정상 동작하는지 확인해보자

이제 API가 정상적으로 동작하는지 확인해보겠습니다. 쿠버네티스 환경에서는 서비스를 통해 API에 접근할 수 있습니다. 간단하게 포트 포워딩을 사용하여 로컬에서 API에 접근해 보겠습니다:

bashkubectl port-forward svc/box-recommend-api 8081:80

이제 웹 브라우저나 curl을 사용하여 API를 호출할 수 있습니다:

bashcurl http://localhost:8081/api/recommend

그런데 API 응답이 없고 오류가 발생했습니다. 로그를 확인해보니 데이터베이스 연결 문제가 있었습니다:

bashkubectl logs deployment/box-recommend-api

로그를 살펴보니 PostgreSQL 데이터베이스가 초기화되지 않았거나, 연결 문제가 있었습니다. 먼저 데이터베이스 접속을 확인해보겠습니다:

bash# PostgreSQL 파드 이름 확인
kubectl get pods | grep db

# 데이터베이스 접속
kubectl exec -it box-recommend-db-<pod-id> -- psql -U test1234 -d box_recommend

데이터베이스에 접속할 수 있었고, 테이블이 없는 상태였습니다. Spring Boot 애플리케이션은 일반적으로 Hibernate/JPA를 통해 초기화 시 필요한 테이블을 생성하지만, 초기 연결 문제로 이 과정이 실패한 것 같습니다.

문제를 해결하기 위해 API 서버의 환경 변수 설정을 수정했습니다:

yaml# api-deployment.yaml (수정 부분)
        env:
        - name: SPRING_DATASOURCE_URL
          value: jdbc:postgresql://box-recommend-db:5432/box_recommend
        - name: SPRING_DATASOURCE_USERNAME
          value: test1234
        - name: SPRING_DATASOURCE_PASSWORD
          value: test1234
        - name: SPRING_JPA_HIBERNATE_DDL_AUTO
          value: update  # 추가: 데이터베이스 스키마 자동 업데이트
        - name: SPRING_JPA_SHOW_SQL
          value: "true"  # 추가: SQL 로깅 활성화

변경사항을 Git 저장소에 커밋하고 푸시합니다:

bashgit add api-deployment.yaml
git commit -m "Fix database connection settings"
git push

ArgoCD가 자동으로 변경사항을 감지하고 클러스터에 적용합니다. 잠시 후, API 파드가 재시작되고 정상적으로 동작하기 시작했습니다. 다시 API를 호출해봅니다:

bashcurl http://localhost:8081/api/recommend

이번에는 응답이 정상적으로 받아졌습니다! 모든 것이 제대로 동작하고 있습니다.

모험 성공 및 느낀점

처음에는 쿠버네티스와 ArgoCD에 대해 아무것도 모른 채 시작했지만, 단계적으로 접근하고 문제를 하나씩 해결해 나가면서 작동하는 시스템을 구축할 수 있었습니다. 이 과정에서 몇 가지 중요한 교훈을 얻었습니다:

1. 컨테이너 기술의 강력함: Docker를 통해 애플리케이션을 패키징하면 어디서든 일관되게 실행할 수 있습니다.

2. 선언적 인프라의 가치: 쿠버네티스 매니페스트 파일과 같은 선언적 접근 방식은 인프라를 코드로 관리할 수 있게 해줍니다.

3. GitOps의 효율성: ArgoCD를 통해 Git 저장소에 변경사항을 커밋하는 것만으로 자동으로 클러스터에 반영되는 경험은 놀라웠습니다.

4. 문제 해결 능력의 중요성: 초기 데이터베이스 연결 문제와 같은 장애가 발생했을 때, 로그를 확인하고 문제를 진단하여 해결하는 과정은 매우 중요했습니다.

이 모험을 통해 쿠버네티스와 ArgoCD의 기본 개념과 동작 방식을 이해할 수 있었고, 앞으로 더 복잡한 인프라를 구축하는 데 필요한 기초를 다질 수 있었습니다. 아무것도 모르던 상태에서 시작했지만, "돌아가는" 시스템을 구축하는 목표는 달성했습니다.

물론 이 설정은 프로덕션 환경에서 사용하기에는 부족한 부분이 많습니다. 영구 스토리지, 보안 설정, 리소스 제한, 모니터링, 고가용성 등 고려해야 할 요소가 많습니다. 하지만 이번 모험은 첫 발을 내딛는 과정이었고, 앞으로 더 깊이 탐구하고 개선해 나갈 수 있는 기반이 되었습니다.

쿠버네티스와 ArgoCD의 세계는 생각보다 넓고 깊지만, 한 걸음씩 나아가다 보면 어느새 복잡한 인프라도 자신 있게 다룰 수 있게 될 것입니다. 이번 모험은 그 여정의 시작점이었습니다.

물류센터, 창고관리(WMS), 배송 박싱 자동화 등의 문제에서 공통적으로 요구되는 기능 중 하나는 여러 물건(Item)을 제한된 공간(Bin)에 효과적으로 적재(Packing) 하는 것입니다.

이를 해결하기 위해서는 여러가지 알고리즘 밑 방법을 사용할 수 있는데 오늘은 Bin-Packing 알고리즘에 대해서 공부하고 이를 실제로 구현해보도록 하겠습니다.

이 글에서는 이러한 문제를 해결하기 위해 Java 기반의 제약 프로그래밍 프레임워크인 OptaPlanner와 JavaFX 기반 3D 시각화를 활용하여 3D Bin Packing 문제를 해결한 과정을 정리합니다.

2. 목표

• 다양한 크기와 모양(Shape)의 물건들을 제한된 박스 내부에 겹치지 않도록 배치

• 회전 가능한 물체의 방향(Rotation) 고려

• 실제 현실과 유사하게 물리 제약, 무게 제약, 부피 제약, 버퍼 영역 등을 반영

• 사용 박스 수를 최소화하는 방향으로 최적화

• 결과를 3D 화면으로 시각화하여 검증 가능하도록 구성

3. 시스템 구성

3.1 Item과 Bin 모델링

data class Item(val id: Int, val width: Long, val height: Long, val length: Long, val shape: Shape, ...)
data class Bin(val id: Int, val width: Long, val height: Long, val length: Long, val buffer: Double, ...)

• Item은 물건 하나를 나타내며, 회전 가능성과 형태 정보도 포함합니다.

• Bin은 적재 가능한 공간으로, 버퍼와 최대 무게 제한 등을 포함합니다.

3.2 PlanningEntity: ItemAssignment

@PlanningEntity
data class ItemAssignment(..., var bin: Bin?, var x: Long?, var y: Long?, var z: Long?, var rotation: Rotation?)

• 각 ItemAssignment는 특정 Item이 어떤 Bin의 어느 위치(x,y,z)에 어떤 방향(rotation)으로 배치될지를 나타냅니다.

4. 제약 조건 구성

4.1 주요 제약 조건

• itemMustFitInBin: 물건이 박스를 넘지 않도록 보장

• noOverlap: 두 아이템이 같은 공간을 차지하지 않도록 제한

• binCapacityExceeded: 버퍼를 고려한 부피 초과 방지

• binWeightLimitExceeded: 최대 무게 제한

• minimizeBinUsage: 사용한 박스 수를 줄이기 위한 소프트 제약

4.2 ConstraintPurpose를 통한 점수 구조

enum class ConstraintPurpose(val level: Int, val isHard: Boolean, val description: String)

• 하드 제약: 충돌, 무게 초과 등 현실적 충족 필수 조건

• 소프트 제약: 사용 박스 수 최소화, 빈 공간 최소화, 무게 배분 등

5. 솔버 구성

SolverFactory.create<BinPackingSolution>(
    SolverConfig()
        .withSolutionClass(...)
        .withEntityClasses(...)
        .withConstraintProviderClass(...)
        .withTerminationConfig(
            TerminationConfig().apply {
                unimprovedSecondsSpentLimit = 3L
            }
        )

• SolverFactory를 통해 제약 조건 기반의 최적해를 탐색

• 종료 조건은 3초 동안 점수 개선이 없을 경우 자동 종료

6. 시각화

6.1 JavaFX 기반 3D Viewer

주요 특징:

• 각 Bin은 검정 테두리의 박스로 시각화

• 각 Item은 반투명하고 색상 지정된 3D Box로 시각화

• 각 아이템은 Golden Angle 기반 Hue 값을 통해 고유 색상을 유지

• XYZ 축은 빨강, 초록, 파랑 선 및 라벨로 표현

• 카메라는 대각선 위에서 XY 평면을 내려다보는 구조로 배치

• 마우스 회전 및 확대 기능은 이후 단계에서 확장 가능

6.2 예시 화면

실행 시 결과 예시는 다음과 같습니다:

• 콘솔 화면

=== 결과 ===
Item 1 -> Bin 1 | Rotation: XYZ | X: 0, Y: 0, Z: 0
Item 2 -> Bin 1 | Rotation: YXZ | X: 1, Y: 0, Z: 0
...

Score: 0hard/0soft

Bin 1 [XY 평면 @ Z=0]
| 1 | 2 |   |
| 3 |   |   |
|   |   |   |

Bin 1 [XY 평면 @ Z=1]
| 4 | 5 |   |
|   |   |   |
|   |   |   |

• JavaFX 화면

콘솔에는 XY 평면 기준으로 z=0부터 아이템이 어떻게 적재되었는지를 확인할 수 있습니다.

7. 학습 및 구현에서의 주요 고려 사항

• 단순히 부피만 고려하는 것이 아니라, 모양에 따른 buffer 영역까지 고려해야 현실적인 배치가 가능

• 아이템 회전과 도형별 부피 공식, 특히 원통, 원뿔, 파우치형 등은 단순 박스형보다 복잡

• 3D 시각화는 디버깅 및 결과 검증에 매우 효과적

8. 마무리

이번 프로젝트를 통해 물류 시스템에서 자주 접하게 되는 Packing 최적화 문제에 대해 제약 기반의 방식으로 접근할 수 있음을 경험할 수 있었습니다.

OptaPlanner는 수많은 상태를 가진 조합 문제를 빠르게 탐색할 수 있게 해주며, JavaFX 기반의 3D 출력은 단지 “작동한다” 이상의 검증 도구로 활용할 수 있었습니다.

다음 확장 방향으로는 다음을 고려하고 있습니다:

• 사용자 마우스 회전, 확대 조작 추가

• 다양한 박스 규격 자동 선택 로직

• 병렬 Bin 추천 기능 및 우선순위 부여 로직

• 웹기반 3D View 또는 Blender 렌더링 자동화

9. 참고 자료

• Bin Packing 소스 코드

• Optaplanner 공식 문서