Files
Resume/portfolio.md
T

20 KiB

강동현 · Backend / Platform Engineering Portfolio

Email donghyeonka68@gmail.com
GitHub github.com/donghyeon-ka
TechLog hyeonworks.com
Blog velog.io/@donghyeon2

About

Java / Spring Boot를 중심으로 백엔드를 공부하고 있습니다.
현업 개발자의 멘토링 아래 약 6개월 동안 인증, 데이터 조회, 아키텍처, Kubernetes 인프라를 직접 구현하고 검증했습니다.

제가 가장 많이 시간을 쓴 부분은 기술을 적용하는 것보다 실제 동작을 설명할 수 있게 만드는 과정이었습니다.

  • BFF를 적용했다면 브라우저에서 사라진 token은 어디로 갔는지
  • N+1을 없앴다면 쿼리 수 대신 다른 비용이 커지지는 않았는지
  • Kubernetes manifest에 설정이 있다면 실제 runtime에서도 집행되고 있는지
  • API 계약이 맞다면 값이 왜 화면까지 도착하지 않는지

이 포트폴리오에는 그 질문이 가장 잘 드러나는 네 가지 사례만 담았습니다.


한눈에 보기

주제 시작한 질문 핵심 판단
TechLog 계약을 한 곳에서 관리하는데 왜 화면에서는 값이 사라질까? 계약 자체보다 값이 지나가는 경계와 수동 목록이 더 자주 깨졌다
Keycloak 인증 경계 브라우저에서 token을 없애면 더 좋은 구조일까? token이 사라지는 것이 아니라 다른 계층이 state와 검증 책임을 가져간다
피드 조회 성능 N+1은 fetch join으로 해결하면 끝일까? 쿼리 수뿐 아니라 row 수, paging, index, Top-N 비용을 같이 봐야 했다
Home Platform 서비스가 접속되면 인프라 구성이 끝난 걸까? TLS, proxy trust, secret, state의 실제 경로를 runtime에서 확인할 수 있어야 했다

01. TechLog

기술 기록을 다시 읽을 수 있는 서비스로 만들기

인증, 성능, 인프라 과제를 진행하면서 문서가 계속 늘었습니다.
문제는 기록이 부족한 것이 아니라 나중에 왜 이런 결정을 했는지 다시 따라가기 어려운 것이었습니다.

그래서 단순 블로그가 아니라 프로젝트 → 주제 → 기록의 맥락을 유지하면서 작성·검증·미리보기·게시까지 할 수 있는 TechLog를 만들기 시작했습니다.

현재 공개 화면은 hyeonworks.com에서 확인할 수 있습니다.

구조

OpenAPI contract
      │
      ├── Backend
      │     domain / application / inbound / outbound
      │
      └── Frontend
            domain / application / adapter / presentation

Studio
Create → Save → Validate → Preview → Publish
                                  │
                                  ▼
                              Public

Backend는 현재 18개 Gradle module로 나누고, module registry를 기준으로 허용 dependency와 runtime membership을 검증하도록 구성했습니다.

가장 어려웠던 문제 — 계약은 맞는데 값이 사라졌다

처음에는 OpenAPI 계약을 한 저장소에서 관리하고 Backend와 Frontend가 같은 계약을 사용하면 서로 어긋날 일이 적을 것이라고 생각했습니다.

실제 문제는 다른 곳에서 나왔습니다.

PostgreSQL
  → SQL adapter
  → application view
  → response mapper
  → generated DTO
  → HTTP
  → frontend gateway
  → application port
  → component

값 하나가 화면에 도착하기까지 여러 경계를 지나면서 어느 한 곳이 값을 조용히 버려도 타입 검사나 화면에서 오류가 나지 않는 경우가 있었습니다.

예를 들어 DB에는 값이 있고 API 계약에도 필드가 존재하지만, 중간 mapper가 해당 필드를 전달하지 않아 화면에서는 빈 값으로 보였습니다. 화면은 이를 오류가 아니라 “데이터가 없음”으로 표현했습니다.

문제를 어떻게 좁혔는가

증상을 “화면이 비었다”로 보지 않고 값의 이동 경로를 끝까지 따라갔습니다.

  • DB row에 값이 있는지
  • persistence adapter가 읽었는지
  • application model에 남아 있는지
  • HTTP response mapper가 전달했는지
  • generated contract type에 필드가 있는지
  • frontend adapter가 mapping했는지
  • 최종 component가 받은 값이 무엇인지

이 방식으로 contract 자체의 오류와 contract 이후의 연결 오류를 분리했습니다.

반복해서 깨진 것 — 손으로 관리한 목록

Record 종류나 route 종류를 배열·삼항식으로 직접 나열한 곳에서는 새 종류를 추가할 때 누락이 반복됐습니다.

// 이런 구조에서는 새 종류를 빠뜨려도 마지막 분기로 조용히 떨어질 수 있다.
const path =
  kind === "CASE" ? "/cases/" :
  kind === "REFERENCE" ? "/references/" :
  "/projects/";

이를 Record<Kind, Value>, exhaustive switch, contract coverage test처럼 누락 자체를 실패로 만드는 구조로 바꿨습니다.

핵심은 “사람이 잘 기억하자”가 아니라 컴파일러나 테스트가 목록의 완전성을 확인하도록 만드는 것이었습니다.

이 프로젝트에서 남은 기준

  • 값은 중간 layer가 아니라 최종 사용자에게 보이는 지점까지 확인한다.
  • 종류를 수동으로 나열해야 한다면 completeness를 검증할 방법을 같이 둔다.
  • “없음”과 “읽지 못함”을 같은 UI 상태로 표현하지 않는다.
  • 테스트가 존재하는 것보다 실제 CI / verification 경로에서 그 테스트가 실행되는지가 중요하다.

Stack

Java 21 Spring Boot JPA PostgreSQL Gradle ArchUnit
React TypeScript OpenAPI Vitest Playwright


02. Keycloak 인증 경계

“브라우저에서 token을 없애면 더 안전하다”를 구조로 확인하기

OAuth2 / OIDC를 공부할 때 SPA, BFF, Forward-Auth라는 이름은 많이 볼 수 있었습니다.

하지만 이름만으로는 다음 질문에 답하기 어려웠습니다.

  • authorization code는 누가 token으로 교환하는가?
  • access token과 refresh token은 어디에 남는가?
  • 실제 API caller는 browser인가, server인가?
  • Resource Server는 JWT를 검증하는가, trusted header를 믿는가?

같은 기능 요구사항을 두고 네 가지 구조를 직접 구현해 비교했습니다.

네 패턴을 credential 소유권으로 비교

구조 Browser Server / Edge API가 받는 값
SPA access / refresh token 관리 없음 Bearer JWT
Token Mediator access token 사용 refresh token / client state 관리 Browser가 보낸 Bearer JWT
BFF session cookie OAuth token + server session BFF가 만든 Bearer JWT
Forward-Auth proxy session cookie OAuth login + identity projection trusted identity header

처음에는 SPA → BFF → Forward-Auth로 갈수록 token이 브라우저에서 멀어지므로 더 좋은 구조처럼 보였습니다.

직접 구현해보니 없어진 책임은 없었습니다.

BFF — token 대신 state를 운영한다

BFF에서는 JavaScript가 OAuth token을 받지 않습니다.

대신 Backend가 다음을 맡습니다.

  • server-side session
  • authorized client / refresh token 저장
  • CSRF 검증
  • downstream API 호출
  • logout 시 session과 token state 정리
  • replica가 늘어났을 때 state 공유

즉 브라우저 token 노출을 줄이는 대신 stateful backend를 운영하는 비용이 생겼습니다.

Forward-Auth — JWT 대신 header를 믿는다

Forward-Auth에서는 upstream이 OAuth token을 직접 이해하지 않아도 됩니다.

하지만 edge가 만든 identity header를 신뢰하려면 조건이 필요했습니다.

  • backend로 직접 들어가는 외부 경로를 닫는다.
  • browser가 보낸 인증 관련 header를 edge에서 덮어쓴다.
  • edge와 upstream 사이의 신뢰 범위를 제한한다.
  • endpoint가 늘어나도 동일한 인가 검증을 적용할 수 있어야 한다.

결국 “token이 없다”가 아니라 신뢰할 credential의 형태가 JWT에서 header로 바뀐 것이었습니다.


단일 인스턴스 설명에서 2-node 환경으로

인증 구조를 구현한 뒤에는 다음 질문이 남았습니다.

Keycloak replica를 늘리면 session은 실제로 어디에 존재하는가?

물리 서버 위에 VM 2대를 만들고 K3s server / agent로 구성해 Keycloak 두 인스턴스와 PostgreSQL, Redis를 배치했습니다.

예상과 달랐던 session 경로

Keycloak 26의 기본 persistent-user-sessions 조건에서 교차 노드 session 처리는 단순히 “Infinispan이 session을 복제해서” 설명되지 않았습니다.

실제 SQL과 runtime 상태를 확인하면서 두 인스턴스가 공유 PostgreSQL의 persistent session state를 사용할 수 있다는 점을 확인했습니다.

반대로 persistent session을 끈 조건에서는 JGroups, cache, restart, DB 장애가 결과에 미치는 영향이 달라졌습니다.

장애 명령을 실행했다고 장애가 만들어진 것은 아니었다

NetworkPolicy, iptables, tc를 이용해 network fault를 만들면서 가장 크게 바뀐 습관은 이것이었습니다.

장애 결과를 보기 전에 장애 자체가 실제로 주입됐는지 먼저 확인한다.

기존 connection이 conntrack에 남아 있거나 rule 방향이 틀리면 명령은 성공했지만 통신은 계속될 수 있었습니다.

그래서 결과를 보기 전에 다음을 따로 확인했습니다.

  • cluster membership
  • active connection / conntrack
  • packet counter
  • process / PID 상태
  • 실제 요청 결과

다중 replica에서만 보인 문제

  • Refresh Token Rotation 경쟁에서는 동시에 같은 refresh token을 사용했을 때 client session 자체가 무효화되는 조건을 확인했습니다.
  • Resource Server replica별 JWKS cache 상태가 다르면 같은 old token이 replica에 따라 다른 결과를 낼 수 있었습니다.
  • Session store와 OAuth2 Authorized Client store는 조회 key가 달라 session만 Redis로 옮긴다고 token state까지 해결되는 것은 아니었습니다.

이 실습에서 남은 기준

인증 구조를 볼 때 이제는 패턴 이름보다 먼저 다음을 확인합니다.

  1. credential의 실제 소유자는 누구인가
  2. state는 어느 저장소에 남는가
  3. replica가 늘어나면 그 state를 어떻게 찾는가
  4. 보호 자원이 최종적으로 무엇을 신뢰하는가
  5. 실패했을 때 어느 계층이 401 / 403 / 재로그인을 결정하는가

Stack

Keycloak OAuth2 / OIDC Spring Security PKCE JWT / JWKS
K3s PostgreSQL Redis JGroups Nginx oauth2-proxy


03. 피드 조회 성능

N+1을 없앤 뒤에도 느릴 수 있는 이유

피드에서 각 항목의 최신 Highlight와 공개 범위, pagination을 함께 조회하는 과제를 진행했습니다.

처음 문제는 명확했습니다.

FeedItem을 N개 읽으면 연관 데이터를 가져오기 위한 SQL도 N에 비례해 증가한다.

PostgreSQL 16 Testcontainers와 Hibernate Statistics를 이용해 실제 쿼리 수를 측정했습니다.

기준선

FeedItem 1,000개를 조회했을 때:

  • PreparedStatement: 2,022
  • Highlight collection fetch: 1,000
  • local warm-cache 기준 median 약 193.7ms

중요했던 것은 시간보다 왜 2,022개의 SQL이 발생했는지 분리하는 것이었습니다.


Fetch Join이 항상 답은 아니었다

N+1 해결책으로 가장 먼저 떠올릴 수 있는 fetch join을 적용했지만 다른 문제가 생겼습니다.

두 collection을 동시에 fetch

MultipleBagFetchException으로 실패했습니다.

collection 하나만 fetch

쿼리 수는 줄었지만 join으로 인해 DB가 보내는 row 수가 늘어났습니다.

fetch join + pagination

응답은 한 page였지만 SQL에는 기대한 LIMIT이 없고, 부모 데이터를 더 많이 읽은 뒤 memory에서 page를 잘라내는 문제가 나타났습니다.

즉 쿼리 수가 줄었다는 사실만으로 개선이라고 판단할 수 없었습니다.


Batch Fetch — 단순 조회를 유지하면서 쿼리 수 줄이기

Batch Fetch를 적용한 뒤 같은 N=1,000 조건에서:

PreparedStatement 2,022 → 23

으로 줄었습니다.

엔티티 조회 구조를 크게 바꾸지 않고 N+1과 pagination을 함께 다루기에는 유효했습니다.

하지만 여전히 화면에 필요하지 않은 entity까지 로드하는 비용이 남았습니다.

그래서 다음 단계로 DTO Projection을 비교했습니다.

  • entity load 0
  • N이 증가해도 고정된 수의 query
  • 필요한 컬럼 중심의 읽기 경로

부모마다 최신 3개 — Window vs LATERAL vs 2-step

다음 요구사항은 단순 LIMIT으로 해결되지 않았습니다.

“전체에서 3개”가 아니라 각 FeedItem마다 최신 Highlight 3개

세 가지 접근을 같은 데이터에서 비교했습니다.

  • Window Function
  • LATERAL
  • 2-step query

현재 데이터에서는 작은 K=3과 복합 인덱스 seek가 가능한 조건에서 LATERAL이 유리했습니다.

하지만 인덱스를 제거하거나 K가 커지면 이점이 줄었습니다.

따라서 결론을 “LATERAL이 빠르다”가 아니라 다음처럼 정리했습니다.

LATERAL의 이점은 문법 자체보다 부모별로 적은 수의 row를 index seek할 수 있는 조건에서 나온다.


깊은 페이지 — OFFSET vs Keyset

2,000행 데이터의 100번째 page를 비교했습니다.

  • OFFSET: 앞의 row를 포함해 2,000행 탐색
  • Keyset + 정렬키 index: 다음 page에 필요한 20행 탐색

실행계획에서도 scan-then-discard와 index seek의 차이를 확인했습니다.

Keyset 역시 항상 정답은 아니었습니다. 정렬 조건을 만족하는 index가 없으면 장점이 크게 줄었습니다.

이 실습에서 남은 기준

조회 성능을 볼 때 다음 순서로 확인합니다.

  1. query count
  2. DB가 실제 읽고 반환한 row
  3. entity materialization
  4. sort / index 사용 여부
  5. pagination이 DB에서 일어나는지 memory에서 일어나는지
  6. 데이터 분포와 K가 바뀌어도 같은 결론인지

Stack

Spring Data JPA Hibernate PostgreSQL 16 Testcontainers Flyway
EXPLAIN (ANALYZE, BUFFERS)


04. Home Platform

“서비스가 뜬다”에서 “요청 경계를 설명할 수 있다”로

개인 서버에 서비스를 하나씩 올리면서 처음에는 host에 Nginx 설정을 추가하고 K3s 안에 필요한 workload를 배치했습니다.

서비스가 늘어나자 다음 질문에 바로 답하기 어려워졌습니다.

  • TLS는 어디에서 종료되는가?
  • 외부 요청이 Kubernetes로 들어가는 문은 몇 개인가?
  • X-Forwarded-*는 누가 만들고 누가 신뢰하는가?
  • DB와 object storage는 외부에서 직접 접근 가능한가?
  • Secret은 어디가 원본인가?
  • manifest에 적힌 설정과 실제 cluster state가 같은가?

그래서 저장소 설정, 문서, live cluster를 대조하며 현재 구조를 다시 정리했습니다.


요청 경로

Client
  │ HTTPS
  ▼
Host Nginx :443
  │ TLS termination
  │ forwarded header overwrite
  │ source allowlist
  ▼
127.0.0.1:30080
  │
  ▼
Traefik NodePort
  │
  ▼
Kubernetes Service
  │
  ├── Gitea
  ├── Keycloak
  ├── Grafana
  ├── pgAdmin
  └── Object Storage Console

핵심은 두 가지였습니다.

TLS는 Host Nginx에서 한 번만 종료

Nginx 뒤의 cluster 진입은 HTTP로 단순화했습니다.

NodePort를 loopback에 제한

Traefik NodePort를 LAN 전체에 노출하지 않고 127.0.0.1 경로로 제한해 클러스터 진입점을 Host Nginx 뒤로 고정했습니다.

또한 외부에서 들어온 X-Forwarded-*를 Nginx가 다시 작성하고, Traefik은 실제 upstream source만 trusted proxy로 인정하도록 범위를 좁혔습니다.


상태를 어디에 둘 것인가

같은 cluster 안에서도 state의 성격을 분리했습니다.

  • PostgreSQL — CloudNativePG
  • Keycloak — PostgreSQL 기반 identity state
  • Gitea — PostgreSQL + Local PV
  • Object Storage — 별도 XFS 영역
  • Observability — Prometheus / Loki / Tempo 등 각 저장 경로

Local PV는 노드와 디스크에 강하게 묶입니다.

따라서 Retain이나 PVC가 있다고 해서 이를 백업이나 HA로 표현하지 않았습니다.

현재 환경은 단일 노드 home lab이므로 노드 자체가 사라지면 플랫폼 전체가 영향을 받습니다. 오프사이트 백업도 별도 과제로 남아 있습니다.


Secret Delivery — Vault를 쓰는 이유를 경로로 설명하기

Secret을 Git에서 제거하는 것만으로는 secret 관리가 끝나지 않았습니다.

누가 Vault에 접근하고 workload는 무엇을 읽는지까지 분리했습니다.

Vault KV-v2
   │
   ▼
Vault Secrets Operator
   │
   ▼
Kubernetes Secret
   │
   ▼
Workload

애플리케이션이 Vault API를 직접 호출하지 않고 Kubernetes Secret만 소비하도록 구성했습니다.

  • Kubernetes Auth
  • role / policy 분리
  • VaultConnection / VaultAuth
  • VaultStaticSecret
  • bootstrap dependency

현재 lab Vault는 1 replica / file storage 기준이며 이를 HA 구성으로 표현하지 않습니다.


관측 — 선언과 runtime을 구분하기

인프라를 정리하면서 가장 중요하게 둔 기준은 다음 다섯 가지였습니다.

표현 의미
관측 실제 host / cluster에서 명령을 실행해 확인
선언 manifest나 설정 파일에 존재
기록 과거 문서에서 확인한 상태
추론 관측과 선언을 근거로 판단
미확인 아직 확인하지 못함

예를 들어 NetworkPolicy YAML이 저장소에 있다는 사실만으로 실제 통신이 막힌다고 판단하지 않았습니다.

Prometheus / Grafana / Loki / Tempo / Blackbox Exporter를 구성하고, 필요한 경우 실제 endpoint와 cluster state를 함께 확인했습니다.

이 프로젝트에서 남은 기준

  • manifest는 의도이고 runtime은 결과다.
  • 1/1 Ready는 HA를 의미하지 않는다.
  • Retain은 backup을 의미하지 않는다.
  • proxy header를 신뢰하려면 proxy를 우회할 경로도 같이 닫아야 한다.
  • 장애나 보안 정책은 “설정했다”가 아니라 실제 상태 변화로 확인한다.

Stack

K3s Kubernetes Nginx Traefik Kustomize
CloudNativePG Vault VSO Prometheus Grafana Loki Tempo


제가 문제를 확인하는 방식

네 프로젝트의 주제는 다르지만 문제를 확인하는 순서는 비슷했습니다.

1. 먼저 기준선을 만든다.
        ↓
2. 내가 예상한 동작을 적는다.
        ↓
3. 실제 요청 / SQL / packet / runtime state를 본다.
        ↓
4. 예상과 다른 지점을 가장 작은 경계까지 좁힌다.
        ↓
5. 수정 후 같은 관측 지점에서 다시 확인한다.
        ↓
6. 아직 확인하지 않은 범위를 따로 남긴다.

이 방식 때문에 결과가 기대와 다르게 나와도 실습을 실패했다고 보지 않습니다.

오히려 예상과 실제가 갈리는 지점이 다음 설계 판단의 근거가 되었습니다.


Additional Work

Clean Architecture Backend Template

Java / Spring 기반 프로젝트에서 domain과 application policy가 framework detail에 끌려가지 않도록 multi-module template을 구성하고 있습니다.

Gradle에는 module dependency direction을 두고, application / adapter / bootstrap의 책임을 분리하며 ArchUnit과 테스트로 경계를 검증하는 방향으로 개선했습니다.

Virtualization

CPU virtualization에서 시작해 Network, Storage, Memory까지 실제 host 관점에서 학습하고 문서화했습니다.

KVM / QEMU, vCPU와 VM-exit, virtio / vhost-net / TAP / Linux Bridge, NAT, IOMMU / VFIO 등의 흐름을 명령과 실제 구성 기준으로 정리했습니다.