ProbeHub

Django WSGI 최적화 - Granian 과 ARM64(Graviton)

개발프로브 — Tue, 2 Dec 2025 22:43:48 +0900

이 글은 최근 Django WSGI 를 다루게 된 백엔드 개발자가 문제를 인식하는 과정, 실험을 통해 데이터를 확보하고 실제 성능과 비용을 최적화한 경험을 다룹니다.

TL;DR

공식문서를 따르는게 아닌 실제 운영 환경에 맞춰 파라미터를 튜닝하고, linux/amd64 를 linux/arm64 로 교체하여 Req/s 지표를 2배 높일 수 있었습니다.
Gunicorn, gthread 기반 HTTP 서버를 Granian 으로 교체하여 부하 상황에서 발생하던 502 에러를 방지했습니다.

1. 문제 정의 및 가설 수립

"왜 우리 서비스만 Task가 70%나 더 많을까?" AWS 콘솔을 모니터링하던 중, 타 프로덕트 대비 비정상적으로 높은 ECS Task 수와 일일 최대 6만 건에 달하는 502 Bad Gateway 에러를 발견했습니다. 분석 결과, Python Worker(WSGI)의 부하로 인한 CPU Spike가 오토스케일링(Horizontal Scaling)과 에러의 주원인임을 확인했습니다.

이에 따라 HTTP Server(WSGI)의 세팅 최적화 또는 교체가 CPU 효율을 높이고 비용 및 에러율을 낮출 것이라는 가설을 세웠습니다.

2. 실험 설계

문제의 원인을 명확히 격리하고 최적값을 찾기 위해 변인을 통제하여 총 4단계의 실험을 설계했습니다.

2.1 변수 설정

구분	항목	내용
통제 변수(고정값)	하드웨어 스펙	동일한 CPU 및 RAM 할당
통제 변수(고정값)	부하 테스트 시나리오	• 단기 부하: 100 Users, 1분 (3개 Endpoint: Fast/Mid/Slow) • 중기 부하: 100 Users, 10분 (지속성 검증)
독립 변수(변경값)	워커 구성	Worker 개수, Thread 개수 조정
	서버 엔진	Gunicorn(기존) vs Granian(신규)
	운영체제	Linux OS 종류 변경
종속 변수(측정값)	성능 지표	CPU Spike, RPS(Req/s), Error Rate, Task Count

왜 Granian 인가?
Granian 은 Rust 를 기반으로하는 Python HTTP Server 입니다.
그들이 제시하는 성능 벤치마크에 따르면 WSGI 에서 gunicorn 대비 20배 빠른 성능을 보인다고 합니다.
또한 개인적으로는 Python 이 아니기 때문에 GC 로 인한 jitter 현상이 없을 것으로 기대도 됩니다.

2.2 실험 단계

최적의 구성을 찾기 위해 아래 순서로 실험을 진행합니다.

Worker/Thread 튜닝: 기존 환경에서 파라미터 튜닝만으로 개선 가능한지 확인 (단기 부하)
HTTP Server 교체: Gunicorn을 대체할 서버 테스트 (단기 부하)
OS 변경: 운영체제 레벨의 오버헤드 확인 (단기 부하)
최종 검증: 도출된 최적 조합으로 장시간 안정성 테스트 (중기 부하)

3. 실험 결과 데이터 및 해석

총 4단계의 실험을 통해 Worker 튜닝, HTTP Server 교체, 그리고 아키텍처 변경이 성능에 미치는 영향을 분석했습니다. 모든 데이터는 동일한 하드웨어 스펙에서 측정되었습니다.

3.1 Gunicorn 워커/스레드 튜닝 (단기 부하)

먼저 기존 Gunicorn 환경에서 파라미터 튜닝만으로 개선이 가능한지 확인했습니다. CPU 경합(Context Switching)을 줄이기 위해 워커와 스레드 수를 줄이는 접근을 시도했습니다.

기존 Worker / Thread 세팅은 Gunicorn 공식문서에서 추천하는 규칙을 따르고 있습니다.

"Generally we recommend(2x$num_cores)+1as the number of workers to start off with" 이 규칙을 해석해서 대부분의 국내 Python 개발자들은 아래의 세팅을 따르는 중입니다.

import multiprocessing
workers = multiprocessing.cpu_count() * 2 + 1

신규 Worker / Thread 세팅은 vCPU 개수와 Worker 개수를 일치시키고, Thread 개수는 Worker * 2 를 따르도록 했습니다.

3.1.1 실험 데이터

구분	설정 (Worker / Thread)	RPS (Req/s)	CPU Usage	Error Rate	비고
대조군	Gunicorn (기존 세팅)	35.6	71.9%	3.33%	기존 운영 세팅
실험군	Gunicorn (신규 세팅)	46.4	63.6%	0.76%	최적 효율

3.1.2 해석, 클라우드 환경의 vCPU 가 갖는 특수성

워커와 스레드 개수를 줄였음에도 불구하고 RPS는 약 30% 증가(35.6 → 46.4)하고, 에러율은 1/4 수준(3.33% → 0.76%)으로 대폭 감소했습니다. 이는 과도한 Thread 생성으로 인한 Context Switching 오버헤드가 성능 저하의 주원인이었음을 시사합니다.

하지만 이상합니다. 어째서 Gunicorn 공식문서 추천 세팅이 더 비효율적인걸까요? 공식문서의 "Obviously, your particular hardware and application are going to affect the optimal number of workers." 부분에 더 주의를 기울여야 했습니다.

현재 Django Application 은 Bear Metal 에서 돌아가는게 아니라 Docker 에서, 그것도 AWS ECS Fargate 의 vCPU 라는 가상의 CPU 를 이용하고 있습니다. 이런 특수한 상황을 고려한 실험이 필요했습니다.

다행입니다. 첫번째 실험으로 상당한 인사이트를 얻었습니다.

3.2 HTTP Server 교체 (Gunicorn vs Granian)

Gunicorn 최적화(실험군 A) 상태에서도 간헐적인 에러(0.76%)가 잔존했습니다. 이를 근본적으로 해결하기 위해 Rust 기반의 Granian을 도입하여 비교 실험을 진행했습니다.

3.2.1 실험 데이터

서버	설정 (Worker / Thread)	RPS (Req/s)	CPU Usage	Error Rate
Gunicorn	(기존 세팅)	46.4	63.6%	0.76%
Granian	(신규 세팅)	40.2	69.3%	0.00%
Granian	(기존 세팅)	41.8	92.1%	0.00%

3.2.2 해석, Python GIL 의 제약에 따른 502 에러

Granian은 Gunicorn 대비 RPS가 소폭 낮거나 비슷했지만, 가장 중요한 지표인 에러율이 0% (Zero Error)를 기록했습니다.

1) 502 에러가 바생하는 매커니즘

HTTP 요청이 들어오면 OS 레벨에서는 다음과 같은 과정이 일어납니다.

sync_queue, accept_queue 구조(https://blog.cloudflare.com/syn-packet-handling-in-the-wild/#the-tale-of-two-queues)

SYN Backlog: 클라이언트의 요청(SYN)이 들어오면 커널 큐에 쌓입니다.
Accept Queue: TCP 3-way Handshake가 완료되면 연결이 성립되어 Accept Queue로 이동합니다.
Application Accept: 애플리케이션(Gunicorn 등)이 accept() 시스템 콜을 통해 큐에서 연결을 가져가야 합니다.

이 과정에서 문제의 핵심은 애플리케이션이 바빠서 Accept Queue를 제때 비우지 못하면 큐가 가득 차게 되고, 커널은 들어오는 연결을 거부(RST)하는 현상을 서버 앞단의 ALB가 "서버가 죽었다"고 판단하여 502 Bad Gateway를 반환하는 것으로 보입니다.

2) Gunicorn 의 한계: Python 의 GIL 과 Accept Loop

Gunicorn, 특히 gthread 모드의 치명적인 단점은 연결 수락 과정이 Python 런타임 내부에 갇혀 있다는 점입니다.

동기적 Accept: Gunicorn 워커는 Python 루프 안에서 accept()를 호출합니다.
GIL 병목 (Bottleneck): 멀티 스레드를 써도 Python의 GIL 때문에 한 번에 하나의 스레드만 실행됩니다.
기아 상태 (Starvation): 요청이 폭주하면 워커 스레드들은 비즈니스 로직 처리와 I/O 대기로 바빠집니다. 이 와중에 GIL 획득 경쟁에서 밀리면 accept()를 호출할 기회조차 얻지 못합니다.

이러한 영향으로 CPU가 남아도는데도(20~60% 구간), accept()를 못 해서 큐가 터지고 502 에러가 발생합니다.

3) Grarnian 의 한계 돌파: GIL-Free Accept

Granian이 에러율 0%를 달성한 비결은 연결 수락과 HTTP 파싱을 Python 외부(Rust)로 끄집어낸 데 있습니다.

Rust 기반 런타임: Granian은 내부적으로 Rust 기반의 고성능 네트워크 라이브러리인 Hyper와 Tokio를 사용합니다. Python 로직이 아무리 바빠도, Rust 레이어는 GIL의 영향을 받지 않고 즉각적으로 연결을 수락(Accept)하여 내부 큐에 안전하게 쌓아둡니다.
지연된 위임: 연결이 안전하게 확보된 후에야 Python 비동기 태스크로 변환하여 애플리케이션에 전달합니다.

Granian 환경에서는 Python 처리가 늦어져 "응답 지연"이 발생할 수는 있어도, 연결 자체가 거부되어 "502 에러"가 발생하는 상황은 원천적으로 차단되는 것으로 보입니다.

3.3 아키텍처 변경 (amd64/X86 vs arm64/Graviton)

비용 효율과 기본 성능 향상을 위해 AWS Fargate의 아키텍처를 기존 Intel(x86) 기반에서 arm64(Graviton)로 변경하여 테스트했습니다. arm64 는 클라우드 환경에서 더 비용효율적이며 성능도 더 좋다고 알려져 있습니다.

3.3.1 실험 데이터

아키텍처서버 / 설정RPS (Req/s)CPU UsageError Rate성능 향상

아키텍처	서버 / 설정	RPS (Req/s)	CPU Usage	Error Rate	성능 향상
amd64	Gunicorn(신규 세팅)	46.4	63.6%	0.76%	-
arm64	Gunicorn (신규 세팅)	67.6	80.6%	0.40%	+45%
arm64	Granian (신규 세팅)	67.7	59.1%	0.00%	+46%

도출된 최적의 조합(Arm64 + Granian)이 장시간 부하에서도 안정성을 유지하는지 검증했습니다. (10분 테스트)

대상	RPS (Req/s)	CPU Usage	Eror Rate
Gunicorn (최적값)	69.1	87.9%	0.67%
Granian (최적값)	66.2	86.0%	0.00%

3.3.2 해석, vCPU 하이퍼스레딩 vs 물리 코어

아키텍처 변경만으로 RPS가 40% 이상 폭발적으로 증가했습니다. 특히 Arm64 환경에서 Granian은 더 적은 CPU 자원(59.1%)을 사용하면서도 최고 수준의 처리량을 보여주었습니다. Python과 Rust 모두 Arm 아키텍처에서 효율적인 퍼포먼스를 보였습니다.

10분간의 지속적인 부하 상황에서 Gunicorn은 여전히 0.67%의 502 에러가 발생했으나, Granian은 단 한 건의 에러도 발생시키지 않았습니다. 이를 통해 'arm64 + Granian' 조합이 성능과 안정성 두 마리 토끼를 잡는 최적의 솔루션임을 확신할 수 있었습니다.

왜 CPU 를 변경하는 것 만으로 이렇게 큰 성능 향상이 나타났을까요? 이는 amd64 대비 arm64 CPU 의 메모리 대역폭이 더 큰 것 등 다양한 영향이 있겠지만 amd64 와 arm64 에서 vCPU 의 실체가 다르기 때문에 나타난 현상입니다.

amd64 에서는 vCPU 두개가 하나의 물리 CPU 코어를 공유하지만 arm64에서의 vCPU와 물리 CPU 코어가 1대1로 매핑됩니다. 이러한 특징은 Python Applicaiton 에서 더 크리티컬하게 작용했을 것으로 보이는데요, GIL 제약으로 실제 활용 가능한 CPU 코어개수가 요청 처리량에 직접적으로 작용하기 때문입니다.

참고

gunicorn 공식문서: https://docs.gunicorn.org/en/latest/design.html#how-many-workers

garnian 벤치마크: https://github.com/emmett-framework/granian/blob/master/benchmarks/vs.md
cloudflare SYN packet: https://blog.cloudflare.com/syn-packet-handling-in-the-wild/#the-tale-of-two-queues

ORM의 편리함 속 함정 - SELECT *와 수직 분할의 중요성

개발프로브 — Sat, 8 Nov 2025 17:57:07 +0900

현대의 백엔드 개발자들(심지어 DB를 다루는 프론트엔드 개발까지)은 기본적으로 ORM(Object-Relational Mapper) 사용을 널리 받아들이고 있습니다. Python 생태계에서도 금쪽같은 Django의 ORM, 혹은 SQLAlchemy 가 있어서 Python 개발자들에게 정말 많은 편리함을 제공하고 있습니다.

하지만 "지옥으로 가는 길은 선의로 포장되어 있다" 라는 유명한 격언처럼, ORM 이 제공하는 편리함 속에는 함정이 숨어있습니다. 대표적인 문제인 N+1 현상은 널리 알려져있는 반면, 무심코 날리고 있는 SELECT * 쿼리와 Fat Model 문제가 성능에도 영향을 끼친다는 사실은 종종 무시 당하는것 같습니다.

성능에 집착하는 개발자 중 한명으로서 ORM 의 또다른 함정을 명확히 정리하고 해결하는 방법을 정리하는 글이 필요하다고 생각했고, 이러한 이유로 이 글을 씁니다.

**SELECT * 를 쓰면 왜 안좋은가?**

이 말은 왜 더 적은 칼럼을 가져올 수록 성능이 좋아지는가?와 같은 말입니다. 그리고 ORM 을 어느정도 사용해본 개발자라면 "특정 칼럼만 가져오면 더 빨라지던데?" 와 같은 경험을 해보셨을 겁니다. 하지만 도대체 왜 빨라지는 걸까요?

우선 SELECT * 가 아니라 SELECT {some_columns} 를 사용하면 세 개의 서로 다른 구간에서 성능 개선이 일어납니다. 네트워크 영역과 백엔드 서버 그리고 데이터베이스 서버입니다.

1. 네트워크에서의 성능 개선

네트워크 레벨에서의 성능 개선도 쉽게 짐작할 수 있습니다. 메모리 레벨에서 Applicaiton 서버와 Database 서버간 데이터 교환이 일어나는 것이 아니라면 대부분 네트워크를 거치게 됩니다. 더 적은 칼럼을 조회하면 당연히 네트워크 트래픽도 줄어들기 때문에 성능 개선이 일어나는 것이죠.

2. 백엔드 서버에서의 성능 개선

ORM 을 사용하는 백엔드 서버에서는 어떤 성능 개선이 일어날까요? 생각보다 아주 간단한데요. 바로 메모리 사용 최적화입니다. 일반적으로 Value Object 를 만드는것보다 ORM Object 를 만드는 것이 더 많은 오버헤드를 발생시킵니다. 즉, 특정 필드만 가져오도록 해서 ORM Object 가 아니라 Value Object 를 메모리에 적재하게 된다면 그 만큼 성능 최적화가 일어난다는 것이죠. 이러한 성능 최적화는 여러 요청을 동시에 처리하는 백엔드 서버가 대량의 데이터를 한번에 많이 가져와야하는 경우 더욱 두드러지게 나타납니다.

3. 데이터베이스 서버에서의 성능 개선

데이터베이스에서 성능 개선이 일어나는 부분은 백엔드 서버보다 조금 더 깊은 이해를 필요로 합니다. 하지만 이 글을 이해하기 위해 RDBMS 의 구조를 다 뜯어보고 그 설계철학을 모두 이해하기 위해 노력할 필요는 없습니다. 필요한 개념만 간단히 정리하겠습니다.

RDBMS 에서 데이터를 저장하고 읽는 방식

데이터베이스에 캐시가 존재합니다. '버퍼 풀', '공유 버퍼' 라고 합니다. 이러한 캐시에는 쿼리 결과값 뿐만 아니라 인덱스도 저장됩니다.
데이터베이스에서 I/O 는 물리적 I/O 와 논리적 I/O 로 구분 됩니다. 물리적 I/O 는 Disk I/O 를 의미하며, 논리적 I/O 는 버퍼 풀에서 데이터를 복제하는 과정을 의미합니다.
데이터베이스는 디스크에 데이터를 페이지 단위로 저장합니다. 이러한 페이지는 행의 데이터를 열의 순서에 맞게 저장합니다. 무슨 말이냐면 물리적 I/O 가 일어날때 일부 Column 만 선택해도 전체 Row 를 페이지 단위로 읽어오면서 메모리에 적재한다는 것입니다. 그리고 메모리와 캐시에 적재되는 데이터로 페이지 단위입니다.

이러한 사실을 바탕으로 하나의 쿼리가 데이터베이스 서버로 들어오고 결과값이 출력될때까지의 과정을 그려보자면 아래와 같습니다.

[쿼리] -> [캐시 에서 조회]

- 있으면 -> [논리 I/O, 페이지 단위] -> [결과 반환]

- 없으면 -> [물리 I/O, 페이지 단위] -> [캐시 저장(논리 I/O, 페이지 단위)] -> [결과 반환]

캐시Miss 가 발생하여 물리I/O 가 발생하면 적어도 캐시 Hit 시나리오보다 적어도 2배(현실은 수백배~수천배 더 느림)는 더 느립니다. 즉, 동일한 쿼리에 대해서 데이터베이스의 물리 I/O 를 최대한 적게 만드는 것이 데이터베이스 조회 성능을 끌어오는 핵심입니다. 그렇다면 우리는 최대한 인덱스 위주의 쿼리 결과값 조회 혹은 캐시 영역에 유효한 데이터가 오래 남도록 해야합니다.

SELECT * 와 SELECT {some_columns} 사이에는 어떤게 직접적으로 물리 I/O를 적게 일으키냐 결정할 수 없습니다. 칼럼 설계를 잘못해서 연속적이지 않은 칼럼을 조회할 경우 SElECT * 와 SELECT {some_columns} 가 물리 I/O 를 만들어내는 부하는 똑같을 것입니다.

하지만 캐시에 적재되는 순간부터는 완전히 다른 이야기가 됩니다. 물리 I/O 과정을 통해 디스크에서 나온 수많은 페이지들이 메모리에 적재되어 정제된 후 캐시에 들어갈때는 훨씬 작은 페이지가 되기 때문입니다. 만약 SELECT * 를 하고, 해당 테이블에 BLOB 이나 TEXT 타입의 데이터가 있고 해당 칼럼은 관심이 있는 칼럼이 아니라면? 캐시 메모리를 굉장히 비효율적으로 쓰게 될 것입니다. 반면 SELECT {some_columns} 를 통해 필요한 칼럼만 캐시에 적재한다면 캐시 메모리를 더 효율적으로 쓰게되어 더 많은 유효한 데이터를 더 오랫동안 캐시에 모아둘 수 있게 됩니다. (새로운 데이터를 캐싱해야할때 캐시 메모리가 부족하다면 가장 참조가 덜된 데이터를 밀어내기 때문에)

커버링 인덱스

그리고 캐시에는 인덱스 정보가 저장되기 때문에 인덱스에 맞는 특정 칼럼만 조회하는 것으로 성능 최적화(커버링 인덱스)를 만들어 낼 수도 있습니다.

Q. 무슨 데이터베이스를 기준으로 말하는 건가요?
A. 현대에는 여러 종류의 데이터베이스가 존재합니다. SQL, NoSQL 혹은 Row-Oriented, Column-Oriented 혹은 OLTP, OLAP 여러 조건들을 고려해야 할것입니다. 하지만 이 글은 일반적으로 많이 사용하는 SQL, Row-Oriented, OLTP 데이터베이스를 대상으로 작성되었습니다. 더 구체적으로 말하자면 MySQL InnoDB, PostgreSQL 을 생각하면서 글을 썼습니다.

Q. 데이터베이스 구조 설명이 너무 러프한데요?
A. 우리가 일반적으로 많이 사용하는 MySQL, PostgreSQL 과 같은 OLTP 용 RDBMS 의 엄밀한 구조는 공식문서나 인터넷, 혹은 서적에서 더 엄밀하고 양질의 자료를 찾을 수 있습니다. 이 글에서는 "칼럼을 적게 선택(SELECT) 할 수록 성능이 좋아지는 이유" 에 집중해서 설명하기 위해 데이터베이스 구조를 많이 단순화헀습니다.

어떻게 최적화 할 것인가?

왜 더 적은 칼럼을 조회할 수록 성능이 개선되는지 알게 되었습니다. 그럼 어떻게 성능을 최적화 할 수 있을 까요?

1. ORM 에서 특정 칼럼만 가져오기

Python 의 경우 아래와 같이 ORM 을 이용하면 모든 칼럼을 조회 (SELECT *) 하게 됩니다.

# Django
users = User.objects.all() 
# SELECT "user"."id", "user"."username", "user"."email", "user"."bio", ... FROM "user"

# SQLAlchemy
users = session.query(User).all()
# SELECT user.id, user.username, user.email, user.bio, ... FROM user

반면 Django의 경우 .only() 혹은 .values() 를 이용하거나 SQLAlchemy 는 .options(load_only()) 와 query({column_names...}) 를 이용해서 특정 칼럼만 가져올 수 있습니다.

왜 하나의 방법이 아닌 두개의 방법을 제공하는 걸까요? .only 와 .options(load_only()) 는 ORM 객체를 유지한다는 특징이 있습니다. 오...그러면 좋은걸까요? 백엔드 서버단에서의 성능 개선은 애매하지만 일단 데이터베이스와 네트워크에서의 성능 개선은 달성 하니까요? 일단 맞습니다. 하지만 일단 ORM 객체를 만들어주기 때문에 누구든지 load 되지 않은 필드에 접근을 한다면 아래와 같이 Deferred loading 현상을 만들어낼 위험이 존재합니다.

# SELECT "user"."id", "user"."username" FROM "user"

# Django ORM
users = User.objects.only('id', 'username')

for user in users:
    print(user.username)
    print(user.email)    # 추가 쿼리 발생 (Deferred loading)
    

# SQLAlchemy
users = session.query(User).options(load_only(User.id, User.username)).all()
for user in users:
    print(user.username)
    print(user.email)    # 추가 쿼리 발생 (Deferred loading)

반면 values() 와 query({column_names...}) 는 ORM 객체가 아니라 dict 를 반환하게 됩니다. ORM 특징적인 기능은 사용하지 못하겠지만 불편한 만큼 성능상 이득과 더 명확히 side-effect 를 막는 효과가 있습니다.

# SELECT "user"."id", "user"."username" FROM "user"

# Django ORM
users = User.objects.values('id', 'username')

# users[0] = {'id': 1, 'username': 'alice'}

# SQLAlchemy
users = session.query(User.id, User.username).all()
# users[0] = (1, 'alice')

2. 명확한 관심사 분리와 수직분리

수직분할 예시

그렇다면 특정 필요로 하는 칼럼만 dict 로 만들면 모든 문제가 해결될까요? 아쉽게도 그렇지 않습니다. 데이터베이스에서 물리 I/O 가 아예 발생하지 않을 수 없습니다. 그리고 물리 I/O 가 발생할때 최종적으로 반환하려는 칼럼들이 서로 떨어진 페이지에 저장되어 있다면 그 구간의 모든 페이지를 모두 디스크에서 읽어와야하는 불상사가 발생합니다. 그리고 무엇보다 dict 로 데이터를 반환받을거면 ORM 을 왜 씁니까!

즉, 개발 조직의 생산성을 떨어트리지 않으면서 성능도 챙길 수 있는 방법이 필요합니다. 기본값(default) 자체가 빠르도록 RDBMS 설계를 변경하는 것이 더 근본적인 해결책입니다. 각 테이블마다 명확한 관심사를 갖도록 설계하고, 관심사가 동일하더라도 Usecase상 접근 빈도가 더 낮으면서 디스크공간을 많이 차지하는 데이터들을 수직분할(Vertical Partitioning) 하는 방법을 적용하면 해결됩니다. 정말 RDBMS에서 테이블 설계가 잘 되었다면 모든 쿼리를 SELECT * 로 만들어도 큰 이슈가 없을 것입니다.

이렇게 까지 해야하나요?

빠른 속도의 장점은 종종 과소 평가 됩니다. "우리 고객들은 빠른 네트워크 환경에 있는데 100~200ms 정도 더 차이나는게 대수일까?" 하는 생각 때문일텐데요. 이러한 생각이 갖는 문제는 해당 조직의 성능 기준을 처음에는 100ms, 150ms 정도 더 느려지는 것을 용인하는 수준에서 나중에는 1000ms, 1500ms 까지 방치되는 수준으로 퇴화시키는 시작점이기 때문입니다.

그렇다면 조직 내에 빡빡한 성능 기준을 만들어야 할만큼 빠른 속도는 정말 중요할까요? Erricson의 보고서(2016), BBC의 사례(2018), Rakuten의 사례(2022) 에 따르면 사이트 로딩 속도가 느리면 사용자는 스트레스를 심하게 받으며, 이탈로 이어집니다. 반대로 사이트 로딩 속도가 빠르면 전환율이 오르기도 합니다. 즉, 속도는 고객의 이탈과 전환율에 직접적으로 관여하는 요소입니다.

제가 만난 많은 개발자들은 언제나 비즈니스 임팩트까지 만들어내고 싶어하는 분들이었습니다. 그런 개발자들의 고민은 "어떻게 고객들이 원하는 삐까뻔쩍한 기능을 만들까?" 에만 국한되어서는 안됩니다. 가장 기본이라고 할 수 있는 성능 즉, 속도를 빠르게 하는 것만으로도 정말 유의미한 비즈니스 임팩트를 만들어낼 수 있습니다.

저는 처음 개발자 커리어를 시작할 때부터 수억건의 데이터를 가진 N 개의 DB 테이블을 활용해서 200ms 내에게 데이터를 서빙하는데 주의를 기울였습니다. 이 속도를 Latency 를 1000ms 에서 500ms 로, 200ms 로, 100ms 이내로 줄일때마다 고객들이 명확하게 이를 인지하고 더 기쁜 마음으로 서비스를 사용한다는 사실을 눈앞에서 보았습니다. 저는 이러한 경험을 통해 성능에 집착하는 개발자가 되었습니다. 우리 모두 더 좋은 사용자 경험과 이를 통해 비즈니스 임팩트를 만들어 내는 개발자가 되어봅시다.

Python 과 zstd - middleware 적용하기

개발프로브 — Tue, 14 Oct 2025 21:55:47 +0900

이 시리즈 첫글에서 Python 3.14 정식 배포 버전에서 zstd 알고리즘 native 지원에 더 눈길이 갔던 이유가 I/O Bounded API Server 의 응답속도 개선에 주의를 기울이고 있기 때문이라고 말했었습니다. 특히 지금 맡은 업무가 웹 브라우저와 직접적으로 상호작용하는 그렇다면 Python 으로 작성된 Web Server (FastAPI, Django) 에서 zstd 를 어떻게 사용할 수 있을지 공유하고자 합니다.

전체 흐름 점검하기

우선 가장먼저 드는 의문점은 누가 언제 무엇을 인코딩하고 디코딩하냐는 겁니다. 정말 다양한 기준이 있겟지만 웹서버를 기준으로만 정리해보겠습니다. 이제부터 말하는 클라이언트는 웹브라우저(PC / Mobile) 이며 서버는 웹 서버입니다. 그리고 주된 "흐름"은 파일 데이터가 아니라 HTML, CSS, JS, JSON 과 같은 현대적인 웹서비를 만드는데 필요한 포맷의 데이터를 주고받는 것을 지칭합니다.

데이터 인코딩 / 디코딩 과정을 간략하게 본다면

클라이언트: 디코딩의 책임자

일반적인 HTTP 에서 연결이 이어지는 과정은 클라이언트와 서버간 SYNC, ACK 의 과정이 필요합니다. 이때 클라이언트가 먼저 서버에게 요청을 보내면서 연결이 확립되죠(server sent event 조차도 처음에는 클라이언트가 GET 요청을 보냅니다). 그렇다면 이때 클라이언트가 "나는 x, y, z 등등의 인코딩 데이터를 식별하고 디코딩할 수 있다" 는 정보를 서버에게 보내줘야 할겁니다. HTTP 는 무상태(Stateless) 프로토콜이기 때문에 당연히 이러한 정보는 모든 요청정보에서 반복적으로 등장할 겁니다.

RFC 9110 에서는 이러한 Spec을 Accept-Encoding 헤더를 보내는것으로 표준을 잡았습니다. 또한 q-factor 라는 값을 추가하여 클라이언트가 처리할 수 있는 인코딩 알고리즘과 선호하는 인코딩 알고리즘을 서버에서 해석할 수 있도록 하였습니다.

이런식으로 값이 구성됩니다.

Accept-Encoding: gzip;q=1.0, br;q=0.9, zstd;q=0.1

// 아래와 같은 내용들을 사용가능,
Accept-Encoding: gzip
Accept-Encoding: compress
Accept-Encoding: deflate
Accept-Encoding: br
Accept-Encoding: identity
Accept-Encoding: *

서버: 인코딩의 책임자

서버는 Accept-Encoding 을 읽고 q-factor 의 우선순위에 따라 자신이 인코딩 할 수 있는 방식으로 Response 를 인코딩하여 반환합니다. 이때 서버는 Content-Encoding 헤더에 이 Response 가 어떤 알고리즘으로 인코딩되었는지 명시해서 보내야합니다.

Content-Encoding: gzip

만약 인코딩 방식과 Content-Encoding 헤더에 담긴 이름이 다르다면 클라이언트를 데이터를 제대로 디코딩할 수 없고 브라우저 사용자에게 데이터가 표출되지 않는 오류가 발생하게 됩니다. 그리고 현대 웹프레임워크에서 이런 "인코딩" 과정은 비즈니스적인 관심사는 아니고 프레임워크 레벨에서의 관심사이기 때문에 필터(Filter) 혹은 미들웨어(Middleware) 단에서 구현되기 마련입니다.

Python Backend 시스템에 도입하기

결국 Python Web Server Framework 에서 클라이언트에게 응답을 인코딩하는 역할은 Middleware 에게 주어져있습니다. FastAPI, Django 모두 GzipMiddleware 를 지원하며 이를 이용해서 단순 HTTP 뿐만 아니라 스트림 데이터도 인코딩할 수 있습니다.

아래는 찾아본 Middleware 등의 정보를 간단히 공유합니다. Middleware 를 적용하는 방법은 너무 간단하고, 각 프로젝트의 README 에 잘 나타나 있으므로 굳이 내용을 추가하지 않겠습니다.

Middleware (ASGI)

ASGI 에서는 별 10개 이상 받은 Middleware 가 zstd-asgi, cramjam-asgi 두개를 찾을 수 있었습니다.

zstd-asgi 와 cramjam-asgi 를 비교했을때 zstd-asgi 가 약간 더 빠른 압축 속도(Python 3.13.9-slim 기준)를 보여주었습니다. 다양한 환경에서 테스트가 필요하겠지만 모든 요청에 대응하는 Middleware 이므로 약간의 성능 차이가 크게 작용할 수 있다는 점, 그리고 zstd-asgi 는 Python 3.14 를 까지 지원하는 업데트가 최근에 일어났다는 점을 봤을때 zstd-asgi 가 더 나은 선택인 것으로 보입니다. (CPU 사용은 별 차이가 없었음)

Middleware (WSGI)

Django 에서 사용할 수 있는 Middleware 로는 가장 최근까지 유지보수되었던 django-http-compression 을 발견했습니다.

djang-http-compression 는 굉장히 인상적이었습니다. RFC 9110 을 준수하기 위한 수 많은 옵션들과 DEFLATE, Brotli, Zstandard 등을 모두 지원하는 Middleware 를 구현해뒀다는 점이 인상적이었고, 역시 Python 백엔드 생태계에서는 Django 가 가장 성숙하다는 것을 다시 한번 확인할 수 있었습니다.

인코딩을 꼭 해야하나요?

우리는 근본적인 질문을 할 수 있습니다. 도대체 왜 인코딩을 해야하는걸까요? 인코딩을 하면 서버의 CPU 를 사용하게 되고 오버헤드가 추가 될겁니다. 그건 클라이언트(브라우저)도 마찬가지죠. 어떤 이득이 있기 때문에 웹 서버 생태계에서 인코딩을 위한 Middleware 들이 개발되고 있는걸까요?

인코딩을 적용하면 네트워크 레벨로 전송되는 절대저인 데이터량이 적어집니다. 당연히 브라우저가 다운로드 받아야하는 데이터량도 적어지는 것이죠. 이러한 이유로 네트워크 트래픽 감소에 따른 비용 절감과 다운로드 속도 향상으로 전반적인 웹 페이지 로딩 속도 개선을 기대할 수 있습니다. 물론 인코딩/디코딩에 따른 오버헤드(시간 및 CPU 사용)는 있으므로 트레이드 오프를 잘 보고 선택해야합니다.

지금 당장 우리 프로덕트에 적용해도 될까?

단적으로 봐도 JSON Request/Response 를 처리하는 API 서버는 DEFLATE 알고리즘을 이용하는 Gzip Middleware 를 Zstd Middleware 로 교체하는게 이득이 있을 것으로 보입니다.

아직 safari 에서는 zstd를 완전히 지원하는게 아닙니다.

다만, 25년 10월을 기준으로 아직 모든 브라우저들이 zstd 알고리즘을 지원하는 것은 아닙니다. 따라서 단순히 Gzip Middleware 를 걷어내고 Zstd Middleware 로 갈아탄다! 의사결정을 하기 보다는 django-http-compression 와 같이 여러 알고리즘을 같이 적용할 수 있는 미들웨어를 선택하는 것이 현명할 것으로 보입니다.

brotli 압축방식은 전반적으로 지원됩니다.

참고

zstd asgi: https://github.com/tuffnatty/zstd-asgi

zstd starlette: https://github.com/developmentseed/starlette-cramjam

zstd django: https://github.com/adamchainz/django-http-compression

zstd 지원 브라우저 정보: https://caniuse.com/zstd

cloudflare blog: https://blog.cloudflare.com/new-standards/#introducing-zstandard-compression

Python 과 zstd - LZ77 과 허프만 코딩

개발프로브 — Sun, 12 Oct 2025 18:24:11 +0900

25년 10월 7일, 추석 연휴가 한창일때, Python 3.14 정식 버전 (3.14.0) 이 배포되었습니다. 많은 Python 사용자들이 Free-Threaded 에 대해 이야기했습니다. 하지만 저는 Python Native zstd 압축이 지원된다는 사실에 더 관심이 갔습니다. 최근 I/O Bounded API Server 의 응답속도 개선에 관심을 기울이고 있었기 때문입니다.

이번 글에서는 본격적으로 zstd 압축 알고리즘을 알아보고 활용법을 탐구하기 전에 대표적인 무손실 압축 알고리즘인 LZ77과 허프만 코딩을 알아보겠습니다.

대표적인 무손실 압축 알고리즘

zstd 압축에 대해서 이야기하기에 앞서 현대 컴퓨터 시스템에서 압축 알고리즘의 근간이 되는 두 알고리즘을 살펴보겠습니다. 앞으로 설명할 gzip, brotli 그리고 zstd 까지 모두 이 두 알고리즘을 적절히 적용한 사례입니다.

LZ77

대표적인 사전기반 (dictionary based) 압축 기법의 한 종류로 데이터 스트림(인풋 데이터)에서 반복적인 시퀀스를 처리하는 알고리즘입니다.

데이터 스트림내에서 반복적으로 나타는 바이트 시퀀스를 찾아내어 사전(dictionary)을 만들고 두 번째 등장부터는 해당 시퀀스가 처음 나타났던 위치에 대한 참조(reference)로 바이트 시퀀스를 교체하는 식으로 동작합니다. 즉, 반복적으로 등장하는 원본데이터를 작은 크기의 포인터로 표현하는 것이죠.

슬라이딩 윈도우

LZ77 알고리즘은 일정한 크기의 데이터 스트림을 읽는데 이를 슬라이딩 윈도우라고 합니다. 이 슬라이딩 윈도우는 다시 2개로 나뉘는데요, 이미 인코딩된 데이터로 구성되며, 이후에 읽어들일 데이터에 사전 역할을 하는 서치 버퍼(Search Buffer)와 이제 읽어들여서 인코딩될 대상인 룩어헤드 버퍼(Look ahead Bugger) 입니다.

슬라이딩 윈도우 구조(https://www.youtube.com/watch?v=yTQIONTE3Y8)

(Distance, Length) 쌍으로 인코딩

룩어헤드 버퍼의 시작 부분과 일치하는 가장 긴 시퀀스를 서치버퍼에서 발견하면, 알고리즘은 이 반복되는 시퀀스를 (Distance, Length) 쌍으로 인코딩합니다.

- Distance: 슬라이딩 윈도우의 시퀀스와 룩어헤드 버퍼의 시퀀스가 일치하는 시작점까지의 거리

- Length: 일치하는 시퀀스가 몇 바이트로 구성되어 있는지

위의 예시에서 룩어헤드 버퍼 부분이 인코딩 된 결과를 보자면 아래와 같습니다.

- Step1: 처음 데이터를 읽었을때 서치버퍼의 시작부분과 룩어헤드 버퍼와 매치되는 시퀀스가 없습니다. 그래서 슬라이딩 윈도우가 한칸 이동했습니다.

- Step2: 이제 서치버퍼와 룩어헤드 버퍼가 일치하는 시퀀스를 찾았습니다. 두 시퀀스의 시작점간의 거리(DIstance)가 7칸, 그리고 일치되는 시퀀스의 길이(Length)가 4칸, 그리고 다음 문자가 r 이어서 (7,4,'r') 로 데이터가 인코딩 됩니다.

첫번째 데이터와 c 와 같이 인코딩 되지 않은 데이터를 리터럴이라고 합니다.

인코딩 결과 (https://www.youtube.com/watch?v=yTQIONTE3Y8)

LZ77 은 LZ78 그리고 LZW 등 다양한 변형 알고리즘이 존재하지만 기본적인 프레임워크는 동일합니다.

허프만 코딩

데이터의 통계적인 중복성을 제거하는 알고리즘입니다.

더 자주 나타나는 심볼에는 더 짧은 길이의 이진 코드를 할당하고, 드물게 나타나는 심볼에는 더 긴 길이의 이진 코드를 할당하여 전체 데이터 비트수를 줄이는 방식입니다.

허프만 트리

정말 직관적인 설명이죠? 위의 설명은 Spec 으로 본다면 이제는 구현 세부사항을 알아볼 차례입니다. 빈도 기반 이진코드를 만들기 위해 허프만 트리라는 이진트리를 활용합니다.

이진트리는 이런 순서로 만들 수 있는데요.

데이터에서 각 심볼이 나타나는 빈도를 계산하고 각 빈도를 가중치(weight)로 갖는 리프 노드(leaf node)를 생성합니다.
생성된 모든 리프 노드를 우선순위 큐(priority queue)에 넣습니다. 큐의 head 부분에는 가중치가 낮은 노드가 위치합니다.
큐에 노드가 하나 남을때까지 두 노드를 꺼내고 이 두 노드를 자식으로 하는 부모 노드를 생성합니다. 이때 부모 노드의 가중치는 두 자식 도으 가중치의 합으로 합니다. 새로 생성된 부모 노드를 다시 우선순위 큐에 넣습니다.
마지막으로 하나 남은 노드가 바로 허프만 트리의 루트 노드(root node)가 됩니다.

"this is an example of a huffman tree". 라는 데이터를 대상으로 허프만 트리를 만들면 아래와 같이 구성됩니다.

(https://en.wikipedia.org/wiki/Huffman_coding)

이진코드 부여

이렇게 만들어진 허프만 트리를 기반으로 드디어 심볼에 대한 이진코드를 부여합니다. 이진 코드는 루트 노드에서 해당 심볼의 리프 노드까지의 경로로 결정되는데요. 일반적으로 왼쪽 가지로 이동하는 것을 '0'으로 오른쪽 가지로 이동하는 것을 '1'로 표현합니다.

이 과정을 통해 빈도가 높은 심볼은 루트에 가까운, 즉 경로가 짧은 위치에 배치되어 짧은 코드를 할당받고, 빈도가 낮은 심볼은 루트에서 멀리 떨어진, 즉 경로가 긴 위치에 배치되어 긴 코드를 할당받게 됩니다. 그리고 이런 과정을 통해 이진코드를 부여하면 놀랍게도 어떤 심볼의 코드도 다른 심볼 코드의 접두사(prefix)가 되지 않는다는 특징을 갖게됩니다. 예를 들어, 'A'의 코드가 01이라면, 다른 어떤 심볼의 코드도 01로 시작할 수 없습니다.

이러한 접두사 없는 코드(Prefix-Free Code)라는 특징은 압축 해제 과정에서 해당 심볼이 무엇을 의미하는지 모호함이 없도록 만들고 결국 더 효율적이고 정확한 데이터 복원을 가능하게 만듭니다.

참고

Python 3.14 신기능: https://docs.python.org/3.14/whatsnew/3.14.html

Python Free-Threded: https://docs.python.org/3.14/whatsnew/3.14.html#whatsnew314-free-threaded-cpython

Python zstd: https://docs.python.org/3/library/compression.zstd.html

LZ77 알고리즘 예시: https://www.youtube.com/watch?v=yTQIONTE3Y8

허프만 코딩: https://en.wikipedia.org/wiki/Huffman_coding

하나의 컨테이너에 하나의 프로세스

개발프로브 — Wed, 9 Jul 2025 10:04:17 +0900

종종 하나의 Docker 컨테이너에 2개 이상의 프로세스를 Entrypoint의 Script 를 통해 실행하는 경우를 봅니다. 그리고 이러한 행태가 "전혀 문제 없는 방식" 이라고 말하는 사람도 만납니다. 이런 방식이 본질적으로 잘못된게 맞습니다. 어떤 점에서 잘못됐는지 알아보겠습니다.

문제점

gRPC 와 FastAPI 를 하나의 컨테이너에서 운영하는 경우를 예시로 들겠습니다.

1. 운영 리스크를 키운다.

서로 다른 프로세스 두 개를 하나의 컨테이너에서 운영하는 것은 운영 측면에서 리스크를 키웁니다.

프로세스 생명주기: Docker는 PID 1 하나만 관리합니다. 추가로 띄운 자식 프로세스가 신호(SIGTERM/SIGINT)를 못 받아 좀비 프로세스가 남거나, graceful-shutdown 없이 강제 종료될 수 있습니다.
장애의 전체 전파: 하나의 컨테이너에서 gRPC 와 FastAPI 를 모두 구동한다면 gRPC 서버만 죽어도 FastAPI까지 함께 재시작하는 현상이 일어납니다. 각각 내부/외부 담당하는 소통 영역이 다르지만 같은 생명주기를 갖게 되므로 부분 장애가 전체 전파로 이어지게 됩니다.
헬스체크 불가분성: 서로 다른 2개 프로세스에 대해 Liveness/Readiness probe 를 설정해야 하므로 설정이 복잡해지고 실제 K8s 에서 probe 를 설정할때 하나의 Pod에 대해서 gRPC HealthCheck 와 HTTP HealthCheck 를 함께 설정할 수 없어서 서비스 품질 관리에 문제가 발생합니다.
로그/모니터링 혼선: 두 프로세스의 STDOUT/STDERR 스트림이 섞여서 수집되므로 로그스트림이 일관된 정보를 담기 어렵습니다.
리소스 경합: CPU/메모리 제한을 하나로 묶으므로, 트래픽 패턴이 다른 두 서비스가 서로 스로틀링을 일으킬 수 있습니다.

2. 컨테이너의 철학에 위배된다.

기본적으로 컨테이너라는 개념이 왜 등장했는지 그리고 무엇을 추구하며 발전해왔는지 다시 생각해볼 필요가 있습니다.

Single Responsibility: Docker 공식 가이드에 따르면 “한 컨테이너에는 한 서비스를 넣어 관심사를 분리하라” 라고 합니다. 이 지침에 따라 컨테이너를 작고 예측 가능하게 유지해야 이식성과 디버깅, 배포 이점이 극대화됩니다.
변경 단위 최소화: 컨테이너 이미지는 불변(immutable) 아티팩트여야 합니다. 하나의 이미지에 여러 바이너리를 번들하면, 한 컴포넌트 수정이 있을 때마다 전체 이미지를 재빌드, 재배포해야 합니다.

3. DevOps 를 복잡하게 만든다.

클라우드 환경에서 컨테이너를 활용한 CI/CD 그리고 가시성확보가 보편화되었습니다. 그런데 기본적인 컨테이너의 철학을 깨면 암묵적인 룰을 깨트리는 것이죠.

독립 스케일링 불가: HPA(Kubernetes Horizontal Pod Autoscaler)를 프로메트릭스(QPS, CPU) 기준으로 튜닝할 때, FastAPI CPU 스파이크가 gRPC 컨테이너 증설을 강제하여 비용 상승을 초래합니다.
배포 전략 제약: Blue/Green 배포, Canary 배포와 같이 군집마다 두 서비스가 동시에 교체하는 전략은 절반만 새 버전으로 돌려서 A/B 테스트하기 어렵습니다.
관측 스택 복잡화: OpenTelemetry, Prometheus exporter를 둘 다 탑재하면 스크래핑 엔드포인트가 겹치거나 포트 충돌 위험이 있습니다. 이를 회피하기 위해서는 사이드카 컨테이너를 이용할 수 있는데, 굳이 그렇게까지 해야할까요?

몇가지 추가적인 이야기들

이러한 문제점을 이야기를 했을때 들었던 이야기도 공유할까 합니다.

그럼 Sidecar Container 로 빼면 되는 건가요?

결국 하나의 컨테이너를 공유하고 있던 여러 프로세스들은 많은 경우 개념적으로 공통적이 많은 프로세스들입니다. 그러다보니 해당 프로세스를 개별 컨테이너로 분리하는것에 대해 이야기할때 "아 그럼 Sidecar 로 분리하면 되는건가" 라는 말을 들을 때가 있습니다. 둘을 완전히 분리하고 싶지 않은 것이지요.

이건 경우에 따라 다릅니다. 우선 K8s 의 Sidecar 란 주된 프로세스(Primary App)에 기능을 추가하거나 확장할때 사용되는 기능입니다. 그렇다면 하나의 컨테이너에서 돌아가던 프로세스가 로깅, 보안, 모니터링 등을 위한 장치였다면 Sidecar 로 분리하는게 합리적일 것입니다. 하지만 그냥 다른 서비스라면 Sidecar 로 분리하는것은 설계 철학에 위배되는 행위입니다. 그리고 설계 철학을 따르지 않으면 실질적인 문제가 따르게 되어 있습니다.

Sidecar 로 별도 서비스(Secondary App)를 배포하면 독립적인 스케일링이 안되며, 주된 프로세스(Primary App)과 Lifecycle 이 연동되어 버리고 보안경계가 흐려진다는 문제가 있습니다.

어차피 동일한 로직, DB 접근을 공유하는데 코드는 어떡하죠?

이런 질문은 아직 모듈화의 개념이 잡히지 않은 개발자에게 주로 듣게되는 것 같습니다. 아직은 Python 진영의 특성상 모듈화를 강조하지 않아서 그런지 Java 진영보다 Python 진영 개발자로부터 더 자주 듣게됩니다.

동일한 로직, DB 접근을 공유하는데 서비스가 나눠져있다면 로직과 DB 접근을 core 모듈(예를들어)로 분리하고 Application 혹은 Service 계층을 분리하여 2개의 서로다른 컨테이너로 말아올릴 수 있습니다.

디렉터리 구조로 보자면 이런 식이죠. 이 코드는 core 에 있는 주요 로직을 apps 의 fastapi_app 과 grpc_app 이 공유하는 형태입니다.

├── apps
│   ├── fastapi_app
│   │   └── pyproject.toml
│   └── grpc_app
│       └── pyproject.toml
├── core
│   ├── pyproject.toml
│   └── src
│       └── core
├── Dockerfile.fastapi
├── Dockerfile.grpc
├── pyproject.toml
└── uv.lock

현실적인 회색지대

위의 문제점에도 불구하고 여러 프로세스를 하나의 컨테이너에서 운영하는 상황이 이해되는 경우가 있습니다. 바로 초기 PoC 단계의 비용 압박인데요. 여러 컨테이너를 돌릴 컴퓨팅 리소스는 제한적인 상황에서 빠르게 아이디어를 검증해봐야 한다면 하나의 컨테이너에서 여러 프로세스를 운용해볼 수 있을 것입니다.

실제 Docker 진영에서도 하나의 컨테이너에서 여러개의 프로세스를 구동하는 방법을 소개하고 있습니다. 하지만 해당 문서에서도 하나의 서비스가 하나의 컨테이너에 대응 되어야 한다는 것을 명확히 하고 있습니다. 즉, 가능하다는 거지 절대 위의 문제가 해소된다는 것이 아닙니다.

It's ok to have multiple processes, but to get the most benefit out of Docker, avoid one container being responsible for multiple aspects of your overall application.

참고

Baeldung, Why Is It Recommended to Run One Process per Container?

Couchbase, Docker Container Anti Pattern

K8s, Sidecar Containers
Docker Docs, Run multiple processes in a container

가시성 (1) - 그 개념에 대하여

개발프로브 — Sun, 6 Jul 2025 14:28:47 +0900

백엔드 개발자들끼리 이야기하다보면 "어떻게 모니터링하냐"는 주제는 반드시 등장하는 것 같습니다. 특정 기능을 만들어서 배포하면 마치 자식을 학교에 보내놓은 부모의 마음처럼 가서 친구들하고 잘 지내는지, 급식은 잘 먹었는지 궁금하지 않을 수 없기 때문입니다. 결국 대화는 가시성에 대한 내용으로 옮겨갑니다.

그러다 문득 내가 가시성을 과연 제대로 이해하고 있는게 맞나 궁금해졌습니다. 호기심이 동한김에 가시성에 대한 시리즈를 시작합니다.

가시성

가시성(observability)이란?

가시성(Observability) 은 시스템이 스스로 내보내는 신호만으로 내부 상태를 재구성하고 특정 현상의 원인을 추론할 수 있는 능력을 뜻합니다. 처음엔 제어공학 용어였지만, 오늘날 소프트웨어, 클라우드 세계에서는 그 아래와 같은 특징이 나타났습니다.

특징	설명
출력 기반 진단	로그, 메트릭, 트레이스, 이벤트, 프로파일링 등 외부 출력 만 보고 내부를 추적할 수 있음.
액션 가능성 (Actionability)	데이터를 단순히 모아서 리포팅하는게 목적이 아니라 쿼리, 시각화, 알림을 통해 문제를 신속히 파악하고 조치할 수 있도록 함.
미지의 질문(Unknown-Unknowns) 대응	미리 정의된 대시보드, 경보만으로는 알 수 없는 새로운 현상을 탐지, 분석할 수 있어야함
시스템 내재적 품질	가시성은 시스탬에 내재된 특성이므로 설계 단계부터 풍부한 외부 출력을 내보내도록 만들어야함

가시성은 모니터링과 다른 개념이다.

가시성과 모니터링은 미지의 질문에 대응할 수 있도록 해주느냐, 그리고 그 목표가 무엇이냐 즉, 요구되는 내용이 근본적으로 다릅니다.

구분	모니터링	가시성
원하는 것	문제가 발생했는지 파악하는것, 즉 알려진 미지(Known Unkowns)를 기록하고 리포팅하는 것	알려지지 않은 미지(Unkown Unkowns)에 대응해서 왜 문제가 발생했는지, 다른 이상 징후는 없는지 알아내는 것
목표	SLA 준수, 빠른 감지	근본 원인 분석(RCA), MTTR 단축, 시스템 개선
데이터 수집 방식	사전 정의된 메트릭 위주	보다 포괄적인 데이터 스트림, 로그, 트레이스, 이벤트
세분화	일반적으로 호스트와 에이전트를 설치하고 외부 관점에서 메트릭을 캡쳐	일반적으로 코드 수준에서 측정되어 모니터링이 달성하기 어려운 세분화 수준을 제공

엄밀하게 따지자면 모니터링과 가시성은 다른 개념입니다. 예를 들어 AWS에서 기본적으로 제공하는 EC2, RDS 등의 모니터링 화면은 모니터링의 적절한 예시일 것입니다. 반면 데이터독과 같은 플랫폼은 RCA 까지 제공하는 가시성의 적절한 예시입니다.

하지만 저는 아직까지 백엔드 개발자 실무에서 이를 엄격하게 구분한적이 없습니다. Goole의 SRE 가이드의 분산 시스템 모니터링 섹터에서 가시성에 대한 엄밀한 정의 없이 Root cause 를 다루고 있는걸 보면 실무자에게 모니터링과 가시성은 굳이 엄밀히 구분지을 필요가 없는 개념일지도 모릅니다. 어쩌면 이미 모니터링툴이라고 사용하고 있는 많은 솔루션들에 가시성의 개념이 녹아있기 때문일지도 모르지요.

정말 가시성이 필요한가?

개발자들과 이야기를 하다보면 지금도 로그로 오류를 잡고 AWS CloudWath 대시보드로 모두 파악이 되는데 굳이 가시성이라는 분야에 투자를 또 해야하나? 이야기가 나옵니다. 그런데 이렇게 생각을 해보면 어떨까요?

시간이 곧 돈이다.

시스템 장애에 따른 비용은 MTTR(Mean Time To Recovery) x SPT(Sales Per Time) + a 를 따를 것입니다.

a 는 시스템 장애에 실망해서 떠나가는 고객들이 만들어냈을 잠재 매출이며 a MTTR에 대한 함수입니다. 즉, 장애복구에 시간이 길어지면 길어질 수록 이탈 고객도 많아지는 것이지요.

모니터링만으로는 장애발생 근본 원인(Root Cause)를 빠르게 밝히기 어렵습니다. 로그를 뒤져서 밝혀내는 것보다 한번에 파악이 가능한 경우가 MTTR을 줄일 수 있겠죠? 가시성을 확보한다면 MTTR을 줄이는 것은 물론이고 잠재적인 오류 발생 가능성도 파악할 수 있습니다.

복잡성의 기울기

단일 시스템을 다룰때는 로그만으로 대응이 가능해집니다. 하지만 마이크로서비스로 구축되었고 심지어 이벤트 기반 아키텍처라면 단일 로그 스트림으로는 오류 원인을 찾기 굉장히 힘들어집니다.

서비스가 하나씩 추가되어 시스템 토폴로지가 계단식으로 복잡해질 때 가시성에 대한 투자는 선형이 아니 지수적인 가치를 만들어낼것입니다.

조직의 속도와 개발자 경험

릴리스 주기가 짧아질수록 신규 코드, 인프라가 무슨 부작용을 일으키는지 빠르게 파악해야합니다. 그래야 배포 속도를 유지하고 개발자들도 용기를 가질 수 있습니다. 또한 가시성 없이 계속 시스템이 복잡해진다면 디버깅 -> 야근 -> 이직률 상승이라는 악순환이 발생할 수 있습니다.

결국 가시성이란 장애에 대응하는 속도(MTTR)를 줄임으로써 서비스 품질 유지(매출), 개발 조직의 안정성 향상까지 기여할 수 있는 개념입니다.

가시성을 확보하는 방법

가시성이 중요하다는 건 알겠는데, 실제로 어떤 신호(signal)를 모아야 MTTR을 줄일 수 있는 걸까요?

현대적인 가시성은 보통 3대 시그널과 +a 를 많이 이야기합니다. Logs ,Metrics, Traces 그리고 Profiling이 그것입니다.

시그널	From	What
Logs	어플리케이션 라이브러리	상태 변화, 예외 스택 수집
Metrics	라이브러리 Exprter 가 주기적으로 전송	수량, 속도(QPS, CPU, P99 지연) 등, 이를 통해 알림과 대시보드를 만듦
Traces	요청-응답 체인에 따라 자동 삽입된 스캔	분산 호출 순서, 지연 구간, 오류 지점 파악
Profiling	커널 이벤트와 애플리케이션 스택	함수, 메서드 라인 단위 CPU 메모리, I/O Hotspot 파악

이상의 시그널을 이용해서 “에러가 났다(Logs) → 어느 구간이 느렸다(Metrics) → 어떤 호출 체인에서 지연이 컸다(Traces) → 해당 함수가 CPU를 먹었다(Profiling)” 식의 원인 추적 체인이 완성됩니다.

참고

- CNCF, Observability: https://glossary.cncf.io/observability/?utm_source=chatgpt.com

- Wikipedia, Observability: https://en.wikipedia.org/wiki/Observability_%28software%29?utm_source=chatgpt.com

- Splunk, Observability: https://www.splunk.com/en_us/blog/learn/observability.html?utm_source=chatgpt.com

Python Monorepo - uv Docker 다이어트하기

개발프로브 — Sun, 29 Jun 2025 18:13:32 +0900

문제 제기

교적 간단한 기능만 하는 마이크로서비스의 Docker 이미지가 180MB에 달하고 Runtime 에는 Idle 상태에서 메모리를 120MB 를 사용하고 있었습니다. Python alpine 도 아니고 slim 이미지 기반인데 왜 이렇게 메모리를 비효율적으로 쓸까? 호기심이 생겼고 문제를 분석했습니다.

맥락 요약 (이전 글 안본 분들을 위해)

프로젝트 구조

현재 프로젝트의 디렉터리 구조는 아래와 같이 packages 에 공통모듈을 정의하고 services 에서는 해당 공통모듈을 끌어다가 FastAPI 와 gRPC 서버를 돌리는 코드가 위치해 있습니다. 그리고 프로젝트 root 에 pyproject.toml, packges 안의 모든 모듈에 pyproject.toml 이, services 안의 모든 서비스에 pyproject.toml 이 위치해 있습니다.

Dockerfile

개별 서비스마다 하나의 Dockerfile 이 존재하며 하나의 Dockerfile 은 아래의 형태를 따르고 있습니다.

FROM python:3.12-slim
COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv

# 작업 디렉토리
WORKDIR /app

# 필요한 파일들만 복사
ADD pyproject.toml /app/pyproject.toml
ADD uv.lock /app/uv.lock
ADD packages /app/packages
ADD services/a_service /app/services/a_service

RUN uv sync --all-packages

WORKDIR /app/services/a_service

ENV PYTHONPATH=/app:/app/services/a_service

EXPOSE 8000
CMD ["uv", "run", "uvicorn", "app.main:app", "--workers 2"]

원인 분석

1. Entrypoint 에서 uv run 재호출

uv 를 이용해서 sync 한 상태에서 다시 Docker Entrypoint 에서 uv 를 호출하고 있습니다. uv run 명령어는 "어떤 Python 명령이나 스크립트를 실행할 때, 그 실행이 항상 알맞은 Python 가상환경 안에서 이뤄지도록 보장" 해줍니다. 즉 단순히 Python 코드 실행보다 더 많은 일을 하게 됩니다. 예를들어 필요한 라이브러리 설치와 같은 것입니다.

결국 Entrypoint 에서 uv run 을 시행하면 기존 package 를 remove 하고 다시 add 하는 동작이 일어납니다. 이러한 행위는 예상치 못한 결과를 만들 수 있습니다.

게다가 uv sync 에서 --frozen 옵션을 이용한 뒤 다시 uv run 을 호출하면 어떤 이유에선지는 모르지만, Docker 컨테이너 Idel 상태에서의 메모리 사용량이 증가하는 현상이 나타납니다.

2. Build vs Run 경계 모호

uv 는 Python 실행 도구가 아니라 패키지 관리 도구 입니다. 그런데 uv sync 를 통해서 이미 프로젝트 환경에 필요한 의존성을 모두 설치한 뒤에도 uv 를 계속 들고 있습니다. 굳이 그럴 필요가 있을까요?

Build (Python 에서 Build 는 의존성 설치 과정) 를 끝마치면 uv 를 없애는게 Docker 이미지 크기를 줄이는 방법일 것입니다.

해결전략

1. `.venv` PATH 주입

아래와 같이 Docker 내부 SYSTEM PATH 에 .venv 를 지정함으로써 uv run 을 사용하지 않아도 직접 uvicorn 을 호출할 수 있습니다. 이를 이용하면 Entrypoint 에서 굳이 uv run 을 호출하지 않아도 됩니다.

# .venv PATH 주입
ENV PATH="/app/.venv/bin:$PATH"

2. Multi-stage Build

Builder Stage 와 Runtime Stage 를 나누면 uv 를 없앤 Docker 이미지를 만들 수 있습니다.

Builder Stage: uv 로 .venv 완성 후 /app 복사
Runtime Stage: 슬림 이미지 + /venv 만 사용, uv 삭제

3. 최종 Dockerfile

# Builder stage
FROM python:3.12-slim AS builder
COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv

ENV UV_COMPILE_BYTECODE=1 UV_LINK_MODE=copy
ENV UV_NO_PYTHON_DOWNLOADS=1

WORKDIR /app

ADD pyproject.toml /app/pyproject.toml
ADD packages /app/packages
ADD services/a_service services/a_service

RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --all-packages --no-install-project --no-dev

# Runtime stage
FROM python:3.12-slim

RUN groupadd -r app && useradd -r -g app app

COPY --from=builder --chown=app:app /app /app

ENV PATH="/app/.venv/bin:$PATH"

ENV PYTHONPATH=/app:/app/services/a_service

USER app
WORKDIR /app/services/a_service

EXPOSE 8000 50051
CMD ["uvicorn", "app.main:app", "--workers 2"]

결과적으로 Docker 이미지 크기를 20%~30%정도 줄일 수 있었고, Idle 상태의 Docker 컨테이너의 메모리 사용량도 50%가량 줄일 수 있었습니다.

삽질: uv sync --all-packages 를 사용한게 문제는 아닌가?

가설

"모든 workspace 를 설치하니 이미지가 커지나?"

"`uv sync --all-packages` 를 호출하면 Workspace 의 모든 가상환경에서 해당 프로젝트의 모든 라이브러리를 '프로젝트 환경'에 설치하고 Monorepo 사이즈가 커짐에 따라 자연스럽게 Docker 이미지와 컨테이너의 메모리가 사용량도 커질 수 있다" 는 가설이 있었습니다.

증명

이 가설은 틀렸는데, 그 이유는 uv sync 의 동작 방식 때문입니다.

공식문서에는 Syncing은 lockfile(uv.lock) 에 근거하여 packages 일부를 프로젝트 환경에 설치한다고 합니다. (Syncing is the process of installing a subset of packages from the lockfile into the project environment)
그리고 또 다른 공식문서를 통해는 uv sync 명령어를 실행하는 동안 lockfile 이 만들어진다는 것을 알 수 있습니다. (The lockfile is automatically created and updated during uv invocations that use the project environment, i.e., uv sync and uv run.)

즉 uv sync --all-packages 를 통해 프로젝트 환경에 라이브러리를 만든다면 아래의 동작이 일어나는 것입니다.

uv sync --all-packages 를 입력한다.
모든 Workspace의 pyproject.toml을 돌아다니며 uv.lock 파일과 비교하여 uv.lock 파일을 업데이트.
만약 uv.lock 파일이 없다면 현재 소스코드에 근거하여 새롭게 uv.lock 파일을 만든다.
uv.lock 파일에 따라서 프로젝트 환경에 필요한 라이브러리를 설치한다.

제가 실행한 테스트에서 uv.lock 을 포함한 상태에서 Dockerfile 을 빌드했을때와 uv.lock을 포함하지 않고 Dockerfile 을 빌드했을때의 사이즈가 동일했기 때문에 2번의 소스코드와 비교하여 uv.lock 파일을 "업데이트"하는 과정에는 존재하지 않는 내용은 삭제하는 과정을 포함하는 것으로 보입니다.

이러한 과정 때문에 uv.lock 파일이 있는 경우와 없는 경우에 최종 Dockerfile 의 크기에 유의미한 차이가 없으며 결과적으로 Runtime(Docker 컨테이너)에서도 메모리 사용량에 차이가 없는 것으로 보입니다.

차차리 다른 관점에서 uv.lock 파일이 없을때 비교, 업데이트하는 과정이 없어서 이미지 빌드 속도가 조금 더 빠를 수 있겠다는 생각은 듭니다.

Python Monorepo - namespace 활용하기

개발프로브 — Sat, 14 Jun 2025 12:47:27 +0900

문제점: 잘못된 이름으로 만들어진 공통모듈

직전 글에서 uv 를 이용해서 Python Monorepo 를 구성하였습니다. 대략 이런 모습이었죠. shared 에 있는 모듈을 services 에서 끌어다 쓰는 구조입니다.

이 구조 자체는 괜찮은데, 저의 미숙함때문에 치명적인 문제가 생겼습니다. 바로 너무 일반적인 이름을 사용했다는 점입니다.

services 하위의 app에서도 언제든지 exception, logger 와 같은 파일을 정의해서 사용할 수 있기에 충돌 가능성이 있습니다. 즉, 공통모듈을 사용하는 개발자 개개인이 조심해야하는 문제점이 생깁니다. 실무에 집중해야하는 개발자에게 큰 스트레스겠죠?

이 문제를 해결했던 과정을 공유하겠습니다.

원하는 결과물

가장 일반적으로 문제를 해결하는 방식은 shared 밑에 각각의 모듈을 두는 것입니다. 현재 디렉터리 구조상으로만 그런게 아니라 실제 Python 가상환경 안에 설치된 패키지의 구조가 그렇게 인식되어야 하는 것입니다.

그렇게 된다면 IDE가 아래와 같은 가이드라인을 제공해줄 수 있겠죠.

shared 밑에 공통 모듈들이 있습니다.

패키지 자체를 계층화하는 방법

어떻게 이런 결과를 얻을 수 있을까요? 아래와 같이 shared 라는 디렉터리 자체를 패키지로 만들고 exception, logger 를 내부 패키지로 만들어야 하는 걸까요? 물론 유효한 접근입니다.

.shared
├── __init__.py
│   ├── config
│   └── proto
├── exception
│   ├── __init__.py
│   └── ...
├── logger
│   ├── __init__.py
│   └── ...
...

하지만 이렇게 된다면 실제로는 모든 서비스가 공통으로 사용하지 않는 기능이 공통 모듈에 포함되어 공통 모듈이 불필요하게 커질 우려가 있습니다. 그리고 개별 단위 모듈을 분리해서 관리하고자하는 monorepo 의 철학과도 맞지 않습니다.

Build Target을 이용한 패키지 빌드

이전 글에서 Python 패키지 관리에서 사용되는 빌드라는 용어를 아래와 같이 설명했습니다.

Python 코드를 가진 소스 디렉터리를 다른 환경에서 설치가 가능한 아카이브(.whl, .tar.gz)로 변환하는 과정을 말합니다.

그렇다면 코드는 따로따로 작성하지만 그들을 빌드하는 과정에서 하나의 아카이브로 모을 수 있다면, 그리고 그 아카이브의 최상위 모듈이 shared 라면 우리가 원하는 형태의 결과물을 만들 수 있지 않을까요?

다행히도 Python build-backend 는 build target 이라는 spec으로 이러한 기능을 지원해야함을 명시하였고, hatchling은 이 spec을 따르기 때문에 [tool.hatch.build.targets.<TARGET_NAME>] 테이블을 통해 이러한 기능을 제공하고 있습니다.

Target Wheel 을 이용하기 위한 디렉터리 구조

hatcgling 자체가 src 디렉터리를 요구하는 등 디렉터리 구조에 영향을 받습니다. 그러다보니까 사용하고자 하는 namespace 를 {module_name}/src/{namespace}/{module_name} 식으로 구성해 줘야합니다. 그 예시는 아래와 같습니다.

shared 가 namespace 로 빠지면서 packages라는 이름을 최상단으로 만들었습니다. 이러한 이름은 프론트엔드 진영의 예시를 따른 것으로 백엔드에서는 최적의 네이밍이 아닐 수 있습니다.

여기서 중요한 사실이 있습니다. 바로 각 shared namespace 를 공유할 모듈들이 /src/shared/__init__.py 를 만들지 않는다는 것입니다. 그 이유는 PEP 420, Implicit Namespace 와 깊은 관계가 있습니다. 암묵적 네임스페이스(Implicit Namespace)로 인해 디렉터리만 있으면 패키지로 인식되게 되었습니다. 따라서 일반 패키지는 하나의 디렉터리와 하나의 __init__.py 만 가질 수 있습니다.

따라서 만약 모든 shared namespace 를 공유하는 상황이 온다면 N 개의 wheel 안에 동일 경로 + 동일 파일명이 중복되고, 실제 서비스 코드에서는 shared.logger, shared.middleware 를 통한 import 가 ModuleNotFoundError 를 발생시키게 됩니다.

Target Wheel 을 이용하기 위한 pyproject.toml

이제 디렉터리 구성을 맞췄다면 해당 공통 모듈의 pyproject.toml 이 아래와 같이 세팅되어야 합니다.

[project]
name = "shared.middleware"
version = "0.1.0"
description = "Add your description here"
requires-python = ">=3.12"
dependencies = [
    "asgiref>=3.8.1",
    "shared.logger",
]

[tool.uv.sources]
"shared.logger" = { workspace = true }


[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.hatch.build.targets.wheel]
packages = ["src/shared"]

다소 낯설어졌습니다. middleware 라는 공통 모듈은 앞에 shared. prefix 가 붙었으며 심지어 동일한 workspace 에 있는 다른 모듈을 참고할때도 해당 모듈의 prefix 인 shared 를 명시해줬습니다.

이러한 세팅을 통해 이제 동일한 packages 안에 있는 모듈이라고 할지라도 어떤 모듈은 shared namespace 를 공유하며, 어떤 모듈은 grpc_client 라는 모듈을 공유할 수 있게 되었습니다. 덕분에 packages 를 끌어다 쓰는 다른 개발자들도 더 명시적으로 자신이 끌어다 쓰는 모듈이 어떤것인지 파악할 수 있게되어 불편이 해소되었습니다.

Python MSA를 위한 Monorepo 구성기 — 왜 uv를 선택했는가

개발프로브 — Sun, 1 Jun 2025 12:01:00 +0900

Python&FastAPI 위주로 MSA 를 구성하면서 codebase 는 monorepo 형태를 차용했습니다. 이 글에서는 Python으로 MSA를 만들 때 uv를 통해 어떻게 monorepo 형태로 구성할 수 있는지 경험을 공유하고자 합니다.

monorepo 란?

monorepo 는 polyrepos(혹은 multi-project)에 대응되는 개념으로, 하나의 Git 저장소에서 여러 모듈(서비스‧라이브러리)을 함께 관리하는 전략을 말합니다. 동일한 논리적 변경을 하나의 Commit 또는 PR(Review)로 묶을 수 있고, 저장소별 권한·CI/CD 파이프라인을 중복 정의할 필요가 없다는 점이 가장 큰 장점입니다.

반면 “거대한 모놀리식 시스템(모놀리식 코드베이스)과 같다”는 오해도 있지만, 코드 관리 방식과 런타임 아키텍처는 분리해서 봐야 합니다. 모놀리스는 배포 단위가 하나지만, monorepo는 여러 독립 실행 단위(컨테이너·람다·패키지)를 한 저장소에 둘 뿐입니다.

https://monorepo.tools/#what-is-a-monorepo

CircleCI의 글에서는 monorepo 채택에 따른 이점을 다음과 같이 제시합니다.

원자적 변경(Atomic change): API 스펙 변경과 각 서비스 클라이언트 수정이 한 커밋에 들어가므로 깨지는 중간 단계가 사라짐
일관된 개발 경험: 공통 린터, 테스트, 릴리스 스크립트를 한곳에 유지
쉬운 코드 리팩터링: 대규모 네임스페이스 변경·공통 모듈 추출을 한 PR에서 끝낼 수 있음

실제 우리 팀은 monorepo 를 도입했을때 위의 이유로 개발 편의성이 향상되고 이로인해 human error 발생 빈도를 줄일 수 있었습니다.

monorepo 와 multi-module
Gradle 기반 SpringBoot를 쓰던 저에게는 multi-module이 더 익숙한 개념이었고 monorepo 라는 개념을 받아들일때 도대체 multi-module과 다를게 뭔가 궁금했습니다. 결국 저는 “단일 코드베이스에 여러 모듈”이라는 점은 동일하지만, • multi-module은 빌드 시스템(Gradle) 관점, • monorepo는 저장소‧협업 관점의 용어라는 차이가 있을 뿐이라고 결론을 내렸습니다. 이 글에서는 통일하여 monorepo라 부르겠습니다.

패키지, 프로젝트 관리의 필요성

monorepo 구조까지는 좋았습니다. 하지만 우리 팀은 { polyrepo, Monolithic, Java&SpringBoot }에서 { monorepo, MSA, Python&FastAPI }로 전환을 하였고 대대적인 패러다임·언어·아키텍처 변화를 겪다보니 제대로된 “패키지 관리와 프로젝트 관리”를 하지 못하고 있었습니다.

처음에는 pip-tools 를 이용해 개별 서비스마다 별도의 requirements.in 과 requirement.txt 파일을 두고 local 개발환경에서 개별 서비스마다 가상환경(venv)을 별도로 지정하게 되었습니다. 처음 두세번의 배포까지는 아무런 문제가 없었습니다. 그런데 점점 서비스간 패키지 버전이 불일치하는 일이 발생했습니다. 서비스간 패키지 버전이 불일치한다는 것은 A 서비스에서는 제공되는 기능이 B 서비스에서는 제대로 동작하지 않는문제가 발생할 수 있다는 것입니다.

개별 서비스마다 별도의 가상환경을 두는 선택이 문제를 더욱 심각하게 만들었습니다. local 개발환경에서 A 서비스의 가상환경을 환경을 활성화해놓고 B 서비스의 코드를 수정, 테스트하면 분명 문제없이 동작하던 기능이 (A 가상환경이었기 때문에) 컨테이너화하여 Pod 에 올라가면 K8s의 Liveness probe 에서 막히는 일이 발생했으며, 더 심각하게는 전혀 예상치 못한 RuntimeException 이 발생하게 되었습니다.

물론 컨테이너화해서 테스트하는 절차를 철저하게 지킨다면 위의 문제가 발생하기 전에 알아차릴 수 있었겠지만 Test Coverage 를 적정 수준으로 유지해야하므로 현실적으로 이런 상황에서 모든 RuntimeException을 막기는 불가능합니다.

따라서 패키지간 버전 불일치 문제를 해결하고 local 환경에서 하나의 가상환경에서 여러 서비스를 개발할 수 있는 패키지, 프로젝트관리 체계가 필요해졌습니다.

uv 로 monorepo 만들기

왜 uv인가?

결과적으로 우리 팀은 uv 와 workspace, build-system을 활용하여 이러한 문제를 해결했습니다. 그런데 Python 생태계에는 많은 패키지 관리 툴이 존재합니다. 그 중에서 왜 uv 를 선택했을까요? 저희는 제대로된 패키지 관리 체계를 도입하기 위해 아래의 요구사항을 세웠습니다.

우리가 세운 최소 요구사항

요구사항을 만들다보니 "공통 모듈" 이라는 개념이 추가 되었는데 이것 역시 MSA를 운용하다보면 필요성이 절실해지는 부분입니다.

아키텍처(arm64/amd64)·OS·Python 버전별 재현 가능한(Immutable) Lockfile
모든 마이크로서비스가 단일 Lockfile을 공유해 버전 불일치를 막을 것
공통 모듈을 shared/ 하위 패키지로 두고 필요한 서비스가 “로컬(Editable) 의존성”으로 끌어다 쓸 것
의존성 해석과 설치 속도가 빠를 것(로컬 캐시·병렬 빌드 지원)
Docker나 CI 환경에서 pip만큼 가볍게 쓸 수 있을 것(curl /uv 한 줄 설치)

패키지 관리툴 간단 비교

이러한 기준을 바탕으로 알려져있는 몇몇 패키지 관리툴을 비교하였습니다.

툴	Lockfile	Workspace/Monorepo	패키지 설치속도
pipenv	pipfile.lock	미지원	느림
Poetry	poetry.lock	Partial(패키지 경로)	보통
PDM	pdm.lock	PEP 582 기반 (글로벌 Cache)	빠름
Hatch	hatch.lock	플로그인으로 지원	보통
uv	uv.lock	Cargo Workspace 개념 지원	매우 빠름

uv는 Rust로 작성되어 pip 대비 8~10배, Poetry 대비 4~5배 빠른 의존성 해석·설치 속도를 보여줍니다. 또한 Cargo와 같은 workspace 기능을 제공해, 여러 패키지가 하나의 uv.lock을 공유하도록 강제합니다.

Reddit 등 커뮤니티 피드백에서도 “Poetry와 기능 동등성(parity)을 달성했고, monorepo 이동 시 버전 지옥을 해소했다”는 후기가 많았으며, 한국의 Python 사용자들도 uv 를 적극권장한다는 이야기를 전했습니다.

우리가 원하는 요구사항을 모두 충족하면서, 속도도 빠르고, 국내외 사용자들의 후기도 좋았기에 uv를 제외한 다른 툴을 선택할 이유가 없었습니다.

uv 의 주요 개념

1. pyproject.toml, uv.lock 파일

사실 pyproejct.toml 파일과 lock 파일은 uv 만의 개념은 아닙니다. 하지만 Python 패키지 관리 툴을 처음 접하는 사람에게는 둘다 생소한 개념이므로 이 글에서 설명합니다.

pyproject.toml 파일은 개념적으로 이해하자면 개발자가 원하는 명세를 작성하는 파일입니다. 이 프로젝트의 이름과 설명, 상황별로 원하는 라이브러리와 그 버전을 명시합니다. 필요하다면 Lint 설정도 가능합니다. 그리고 이러한 개발자가 작성한 명세에 따라 실제 원하는 것들을 모아서 그 상태를 저장한 파일이 uv.lock 파일입니다.

실제 Python 어플리케이션이 구동하기 위한 가상환경의 구성은 1차적으로 uv.lock 파일에 의존합니다. 만약 uv.lock 파일이 없다면 pyproject.toml 파일을 통해 바로 uv.lock 파일을 생성할 수 있습니다.

이 글에서는 개념정도만 잡고 두 파일에 대한 구체적인 설명은 pyproject.toml 공식문서, uv.lock 공식문서를 참조하시는걸 추천드립니다.

2. workspace

uv에는 Rust Cargo Workspace 개념이 적용되었습니다. Rust의 패키지관리 툴인 Cargo에서 Workspace란 크기가 커진 Rust 라이브러리를 잘게 쪼개서 관리할 수 있도록, 즉 크기가 작아진 개별 라이브러리간 상호 참조를 손쉽게 할 수 있도록 도와주는 장치입니다.

uv에서 동일한 workspace에 '공통 모듈'과 '마이크로서비스'들이 등록된다면 동일한 uv.lock 파일을 공유하게되고 마이크로서비스들이 공통 모듈을 손쉽게 참조할 수 있는 관계를 만들 수 있게 됩니다. 이러한 참조 관계는 path 참조를 통해서도 이뤄질 수 있으며 혹은 가상환경안에 해당 공통모듈을 설치하여 참조할 수도 있습니다.

3. build-backend

build-backend 역시 대부분의 Python 패키지 관리 툴이 공유하는 개념으로 어떤 방식으로 해당 패키지를 빌드해서 가상환경에 추가할지를 지정하는 것입니다. 그런데 설명이 좀 이상합니다. Python은 인터프리터 언어이므로 빌드라는 과정이 없는데 도대체 뭘 빌드한다는 걸까요?

더 엄밀하게 설명하자면 build-backend 들은 Python 코드를 가진 소스 디렉터리를 다른 환경에서 설치가 가능한 아카이브(.whl, .tar.gz)로 변환하는 과정을 빌드라고 말합니다. 이렇게 아카이브로 변환하는 과정을 거쳐야 패키지 설치 속도와 운영체제 호환성이 확보됩니다.

uv 를 이용한 MSA monorepo 예시

예시 코드는 깃헙에서 확인하실 수 있습니다.

핵심은 공통모듈은 모두 build-backend 를 활용하여 아카이브 파일 형태로 가상환경에 포함된다는 것입니다. 이러한 조치를 통해 각 서비스가 배포되는 환경이 변화되어도 안정한 동작을 보장할 수 있고, 무엇보다 IDE가 해당 패키지의 존재 여부를 명확하게 파악할 수 있습니다.

필요하다면 마이크로서비스로 아카이브파일로 바꿔서 사용하는 방법을 구현할 수도 있겠으나, 현재는 Dockerfile 에서 해당 파일을 직접 호출하는 형태이므로 불필요하다고 판단했습니다.

참고

https://monorepo.tools

https://blog.nrwl.io/misconceptions-about-monorepos-monorepo-monolith-df1250d4b03c

https://engineering.linecorp.com/ko/blog/mono-repo-multi-project-gradle-plugin

https://techblog.lycorp.co.jp/ko/python-multi-project-application-with-poetry

Python gRPC (4) - gRPC gateway 에 대한 탐구

개발프로브 — Sun, 27 Apr 2025 14:53:38 +0900

서비스 하나에 대해서 REST 서버와 gRPC 서버를 따로 운영하면서 재밌지만 다소 버겁다고 생각하고 있었습니다. 그러던중 GraphQL까지 추가되었지요. 내부 비지니스 로직은 통합했더라도 여러 프로토콜을 운영하는건 공부할 내용도 많고 어떤일이 발생할지 불명확하여 두려운 일입니다.

REST, gRPC, GraphQL 이 셋을 하나로 혹은 둘로만 줄일 수 있어도 참 좋겠다고 생각하고 찾아보던중 gRPC Gateway 라는 개념을 발견했고 이를 공부해보았습니다. 과연 현실적으로 개발 공수를 줄일 수 있을지, 그리고 운영하면서 추가적인 이슈를 만들어내지는 않을지 알아보았습니다.

gRPC gateway

개념

gRPC Gateway는 gRPC 서버를 HTTP/JSON API처럼 사용할 수 있게 중간에서 변환해주는 서버입니다.

클라이언트가 REST API처럼 HTTP 요청 (GET, POST 등)을 보내면 gRPC-Gateway가 이 요청을 받아서 내부적으로 gRPC 호출로 변환하고 최종적으로 gRPC 서버에 요청을 전달합니다.

즉, gRPC 서버를 REST API처럼 외부에 노출할 수 있게 해주는 '다리(리버스 프록시 서버)' 역할을 합니다.

구성

https://grpc-ecosystem.github.io/grpc-gateway/

위의 개념에서도 이야기했지만 gRPC gateway는 리버스 프록시 서버를 만들어주는게 핵심입니다.

구현

준비사항

기본적인 gRPC 구성을 위한 지식이 필요합니다.
gRPC gateway의 핵심인 reverse proxy는 go언어로만 구현이 됩니다. 따라서 해당 머신에 go를 설치해야합니다.

설치와 실행

기본적인 gRPC 구성에 대한 지식과 go 튜토리얼 정도를 맞췄다면 github readme 에 있는 설치 방법을 통해 gRPC gateway 구성을 위한 go 패키지를 설치하고, 사용 방법을 통해 직접 테스트해볼 수 있을 겁니다.

만약 이러한 작업을 직접하기 귀찮다면 이 모든것을 shell script 로 만들어둔 프로젝트를 이용할 수 있습니다. 간단하게 한번 해보려는거라면 개인적으로 shell script를 이용하시는걸 추천드립니다.

gRPC gateway에 대한 의문점

HTTP/2 에 따른 성능상 이점을 포기하는 걸까?

이전 글에서도 다뤘지만, gRPC는 HTTP/2에 기반하기 때문에 멀티플렉싱과 헤더압축를 활용할 수 있고, 일반적으로 HTTP/1.x 에 기반한 REST 보다 성능상 이득이 있다고 하였습니다. 물론 proto buffer를 사용함으로써 얻는 더 작은 Payload 사이즈에 따른 이득도 있지만 gRPC gateway를 이용하면 순수 gRPC를 썼을 때보다 성능상 불이익이 예상되는 것도 사실입니다.

JSON <-> Binary 변화에 따른 오버헤드가 존재하진 않을까?

gRPC Stub 과 gRPC Server 가 통신할때는 이진화된 데이터를 주고 받기 때문에 이진화된 데이터를 처리하는데 따른 오버헤드를 크게 걱정하지 않았습니다. 하지만 gRPC gateway를 적용하면 조금 달라집니다. 최초 JSON 요청이 넘어오고 그 이진화 한 다음, 다시 이진화된 데이터는 JSON 으로 바꿔야합니다.

도표화 하자면 아래와 같습니다:

REST, 클라이언트 서버 처리과정

gRPC-gateway, 클라이언트 서버 처리과정

이러한 과정에서 오버헤드가 존재한다면 역시 순수 gRPC 를 쓰는것보다도 성능상 이점을 찾기 어려울 것이며, 심지어 순수 REST 보다 성능이 떨어지는게 아닐까? 하는 생각이 듭니다. 이상의 두 의문점을 해소하기 위해 벤치마크 테스트를 시행했습니다.

**gRPC 러닝커브 * google.api 러닝커브를 줄일만한 방법이 있을까?**

성능과는 다른 관점에서의 의문이 들기도 했습니다. SpringBoot, Django, FastAPI 등 Web Server Framework 들은 웹 표준에 맞춰서 서버를 개발할 수 있는 많은 편의 기능을 제공해주고 있습니다. 덕분에 RESTful API 등을 개발하는 백엔드 개발자 입장에서는 생산성이 많이 올라갔지요, 하지만 지금의 protoc를 통해 코드들이 이러한 편의 기능을 잘 제공해주는지는 의문입니다.

AIP 스펙문서를 보면 gRPC를 RESTful하게 제공하기 위해 proto 파일을 작성하는 순간부터 지켜야할 표준들이 엄청 많아지는것이 보입니다. gRPC 자체도 러닝커브가 존재하는데 googe.api.* 의 proto 를 어떻게 사용해야하는지를 익히는 것도 개발자 입장에서는 부담으로 작용합니다.

아직은 Web Server Framework 수준으로 편하게 개발할 수 있는 환경이 갖춰지지 않은 것으로 보입니다.

벤치마크

그렇다면 얼마나 성능을 희생하는건지 벤치마크 테스트를 통해 확인할 수 있을 것입니다. 순수 gRPC에 비해서 gRPC gateway는 성능을 얼마나 희생하는 걸까요? 기존에 벤치마크를 진행했던 히스토리가 있기 때문에 동일한 조건을 유지하기 위해 gRPC server 자체는 Python으로 구성하고, go를 이용해 gRPC gateway를 만들어서 진행했습니다. (github 에서 코드 확인 가능)

평소에 사용하는 Macbook Air 환경에서 실험하기 때문에 완벽히 통제된 결과를 얻기는 힘듭니다. 따라서 이전의 테스트 결과를 그대로 사용하지 않았고 벤치마크 테스트 스크립트는 다시 시행해서 새로운 결과를 얻어냈습니다. 이러한 이유로 이전 히스토리와는 세부적인 숫자가 다를 수 있습니다.

벤치마크 결과를 그래프로 정리하겠습니다.

	평균 지연시간(ms)	Requests/sec	가장느린 응답	가장 빠른 응답	지연시간 중앙값	99% 지연시간
gRPC aio	13.02	7600.1	21.09	0.32	12.8	19.5
gRPC	15.16	6510.8	42.38	0.75	14.6	23.9
REST	20.8	4241.8	567.3	0.5	20.4	39.8
gRPC gateway	24.5	3991.1	113	0.7	23.5	42.2
gRPC gateway aio	29.3	3378.8	77.4	1.4	28.3	49.2

예상한 대로, gRPC Gateway를 이용한 HTTP 요청은 worker 2개를 사용한 Starlette 기반 REST 서버에 비해 성능 면에서 다소 부족한 모습을 보였습니다.

특히 이번 테스트는 localhost 환경에서 진행되었기 때문에, HTTP/1.1과 HTTP/2 프로토콜 차이보다는, 이진 데이터(Protobuf)를 JSON으로 변환하는 과정에서 발생하는 오버헤드가 추가 지연시간의 주요 원인으로 작용했을 것으로 추정됩니다.

예상에 부합하는 결과가 나왔다는 것과는 별개로 2가지 흥미로운 점이 있습니다.

첫번째는 REST 와 gRPC gateway의 Tail Case를 비교하면 REST 가 가장 안좋은 모습을 보였으며, 여기서도 gRPC aio 가 가장 안정적인 결과를 보여였다는 것입니다.

또 하나는 순수 gRPC 서버에서는 grpc.aio를 이용해 asyncio 기반 비동기 처리를 적극 적용할 경우 가장 뛰어난 성능을 보였지만, gRPC Gateway 환경에서는 오히려 grpc.aio를 사용한 서버가 성능 저하를 일으킨다는 사실입니다.

Tail Case 관리 측면에서 Python의 asyncio 를 사용하는 것이 유리한 이유와 gRPC Gateway에서 grpc.aio 가 더 느린 이유를 알아보는 것도 흥미로운 주제가 될 것 같습니다.

gRPC gateway 활용 사례

etcd

유명한 분산 Key-Value 저장소중 하나인 etcd는 공식문서에서 gRPC gateway를 사용중임을 밝히고 있습니다. 특히 etcd 는 K8s환경에서 클러스터 상태 저장 (Pod, Service, ConfigMap, Secret 등)에서 활용중이기 때문에 백엔드 개발자라면 생각지도 못한 순간에 gRPC gateway를 간접적으로 이용중이었던 셈입니다.

동일한 문서에서 etcd는 gRPC gateway를 도입한 이유에 대해서 밝히고 있습니다.

etcd v3는 클러스터 내부 통신을 gRPC 프로토콜로 처리합니다. Go 언어용 gRPC 클라이언트와 etcdctl CLI를 기본 제공하며,
gRPC를 직접 사용할 수 없는 환경을 위해 HTTP/JSON 요청을 gRPC 메시지로 변환하는 RESTful 프록시(gRPC Gateway) 도 함께 제공합니다.

즉, 더 많은 클라이언트가 이용할 수 있는 범용성 있는 솔루션을 만들기 위해 gRPC gateway를 사용할 수 있는 셈입니다. 이런 경우 gRPC gateway로 인한 성능 저하는 일부 클라이언트들에게 나타나는 문제이지, 정상적으로 etcdctl 을 이용하는 클라이언트들은 별도 성능 저하를 경험하지 않을 것입니다.

gRPC Gateway 활용에 대한 중간 결론

MSA 환경에서 특정 서비스가 RESTful API와 gRPC 를 모두 제공하고 있기 때문에 이를 통합하기 위한 방법으로 gRPC gateway에 대해서 알아봤습니다. 그리고 지금까지 알아본 결론은 etcd 처럼 특정 사용자의 행위를 정확히 규정하는 솔루션의 경우 서비스 제공 범위를 넓히기 위해 gRPC Gateway는 유용하게 사용될 수 있겠지만 일반 유저가 직접 사용하는 프로덕트 서버의 경우 섣불리 gRPC gateway를 도입하기는 어렵다는 것입니다.

아직까지는 일반 유적 직접 사용하는 프로덕트는 HTTP/1.1 웹 기반인 경우가 많으며 이런 경우에는 gRPC Gateway도입이 오히려 성능 저하를 불러일으킬 것이며 또한 대고객 서비스의 업데이트가 잦다고 할때 아직까지는 gRPC gateway를 구성하는 도구가 제공하는 생산성이 Web Server Framework 가 제공하는 생산성보다 떨어지기 때문입니다.

참고

- gRPC gateway: https://grpc-ecosystem.github.io/grpc-gateway/

- HTTP and gRPC Transcoding Spec: https://google.aip.dev/127

- etch gRPC gateway: https://etcd.io/docs/v3.5/dev-guide/api_grpc_gateway/

RDB에서 계층형 데이터를 관리하는 방법

개발프로브 — Sun, 13 Apr 2025 16:07:14 +0900

모놀리식으로 개발했던 시스템들을 MSA로 전환하면서 실수를 보완하고 변경된 요구사항에 맞춰서 많은 것들을 바꾸고 있습니다. 특히 부동산 프로젝트 관리 도메인을 마이크로 서비스로 만들때는 다양한 프로젝트 관련 메타데이터들을 RDB에서 어떻게 관리할지 고민이 되었습니다. 어떤 문제를 인지했는지, 어떻게 해결했는지 공유하겠습니다.

문제인지

프로젝트 관리를 위해서는 프로젝트에 적절히 메타데이터를 부여해야했습니다. 이러한 메타데이터는 N 개로 늘어날수도 있으며, 심지어 하나의 메타데이터 카테고리 안에서 위계가 생겨나는 중이었죠.

처음에는 가볍게 생각했습니다. "000 이라는 카테고리에 하위 개념이 생기면 테이블 하나 더 만들지 뭐!" 하지만 얼마 지나지않아 그렇게 풀면 안되는 문제라는 것을 깨달았습니다.

매번 위계가 생길때마가 테이블을 만드는 것은 비효율적이며
FrontEnd 개발자와 약속했던 API Interface가 바뀌어야 했습니다.

쿠팡 등 커머스 서비스를 보면 다양한 카테고리가 있는데 그들이 이렇게 비효율적으로 일할것같지 않을것 같다는 생각을 쭉 해오고 해결법을 찾았다가 MSA로 변경하는 김에 같이 바꿨습니다.

해결방법들

당연하게도 이러한 문제 의식을 가진건 제가 처음이 아니었고, 2010년대 초반을 기점으로 다양한 레퍼런스를 찾을 수 있었습니다. RDB는 데이터 자체를 Flat하게 다루는데 최적화 되어 있기 때문에 위계가 있는 데이터를 어떻게 Flat하게 다룰지가 포인트였습니다. 그리고 선배 개발자분들이 고안한 해결책은 다음과 같습니다

Adjacency List Model

각 행이 자신의 부모 노드 식별자(parent id)를 저장하는 구조입니다. 예를 들어, 아래와 같이 간단한 테이블을 구성할 수 있습니다.

+-------------+----------------------+--------+
| category_id | name                 | parent |
+-------------+----------------------+--------+
|           1 | ELECTRONICS          |   NULL |
|           2 | TELEVISIONS          |      1 |
|           3 | TUBE                 |      2 |
|           4 | LCD                  |      2 |
|           5 | PLASMA               |      2 |
|           6 | PORTABLE ELECTRONICS |      1 |
|           7 | MP3 PLAYERS          |      6 |
|           8 | FLASH                |      7 |
|           9 | CD PLAYERS           |      6 |
|          10 | 2 WAY RADIOS         |      6 |
+-------------+----------------------+--------+

상당히 직관적이고 구현도 쉬울것 같습니다. 하지만 다음의 기준으로 살펴볼 필요가 있습니다.

전체 Hierarchy 조회:

각 노드가 단일 부모를 가리키므로, 전체 트리를 조회하기 위해 재귀적 탐색(예: WITH RECURSIVE 쿼리)을 사용해야 합니다, 시간복잡도: 최악 O(n)

단일 Hierarchy Path 조회:

단일 경로는 부모를 재귀적으로 따라가므로 데이터 양이 적으면 문제가 없음, 시간복잡도: O(depth)

종말 Node(Leaf) 조회:

설명: LEFT JOIN이나 서브쿼리로 자식이 없는 노드를 찾을 수 있으나, 전체 데이터 스캔 필요, 시간복잡도: O(n)

Hierarchy Node 추가/삭제:

단일 INSERT 또는 DELETE 쿼리로 노드 추가/삭제 가능 (부모 ID만 처리하면 됨), 시간복잡도: O(1)

Nested Set Model

이 해법은 테이블로 보면 다소 난해해집니다. 그래서 아래의 그림을 보는게 가장 직관적입니다:

https://mikehillyer.com/articles/managing-hierarchical-data-in-mysql/

ELECTRONICS 라는 대분류 안에 TELEVISIONS, PORTABLE ELECTROFICS 가 나뉘고 그 이하에 다른 카테고리들이 있습니다.

이제 이 그림을 X 좌표계에 올리고 좌우 양끝점을 통해 범주를 계산한다고 생각해보겠습니다. 그렇다면 ELECTRONICS의 시작 x 값이 가장 작고 종료 x 값이 제일 커야겠죠? 반대로 TELEVISIONS, PORTABLE ELECTROFICS 의 범위 값은 ELECTRONICS 보다 작아야하고 서로 겹치지 않아야합니다. 이렇한 개념을 RDB 테이블에서 표현하면 다음과 같습니다:

+-------------+----------------------+-----+-----+
| category_id | name                 | lft | rgt |
+-------------+----------------------+-----+-----+
|           1 | ELECTRONICS          |   1 |  20 |
|           2 | TELEVISIONS          |   2 |   9 |
|           3 | TUBE                 |   3 |   4 |
|           4 | LCD                  |   5 |   6 |
|           5 | PLASMA               |   7 |   8 |
|           6 | PORTABLE ELECTRONICS |  10 |  19 |
|           7 | MP3 PLAYERS          |  11 |  14 |
|           8 | FLASH                |  12 |  13 |
|           9 | CD PLAYERS           |  15 |  16 |
|          10 | 2 WAY RADIOS         |  17 |  18 |
+-------------+----------------------+-----+-----+

다시 공통 기준에서 살펴보겠습니다.

전체 Hierarchy 조회:

각 노드에 미리 계산된 lft와 rgt 값을 이용하여, 단일 범위(BETWEEN) 쿼리로 전체 서브트리를 빠르게 조회할 수 있습니다, 시간복잡도: O(1) ~ O(log n)

단일 Hierarchy Path 조회:

특정 노드에 대한 전체 경로는 해당 노드의 lft/rgt 값 범위를 활용하여 즉시 조회할 수 있습니다, 시간복잡도: O(1) ~ O(log n)

종말 Node(Leaf) 조회:

설명: Leaf 노드는 일반적으로 rgt = lft + 1 조건을 만족하므로, 이를 통해 빠르게 조회할 수 있습니다, 시간복잡도: O(1)

Hierarchy Node 추가/삭제:

노드 삽입이나 삭제 시, 전체 트리에서 영향을 받는 left/right 값들을 재계산하고 업데이트해야 하므로, 작업 비용이 많이 듭니다, 시간복잡도: O(n)

Closure Table

개인적으로 RDB에서 계층형 데이터를 다룰때 가장 RDB스럽게 풀어낸 방법이라고 생각합니다. 바로 데이터 테이블과 계층정보를 다루는 테이블을 분리하는 것입니다. 위의 해법들과는 다르게 테이블이 2개 생긴다는(따라서 공간복잡도가 커지는) 특징이 있습니다.

https://kntmr.hatenablog.com/entry/2020/08/14/080000

다시 공통기준에서 살펴보자면

전체 Hierarchy 조회:

모든 조상–자손 관계가 별도의 테이블에 저장되어 있으므로, 단일 JOIN으로 전체 서브트리를 빠르게 조회할 수 있습니다, 시간복잡도: O(1) ~ O(log n)

단일 Hierarchy Path 조회:

Closure Table에 미리 계산된 경로 정보를 통해 특정 노드의 전체 경로를 단순 JOIN이나 WHERE 조건으로 조회할 수 있습니다, 시간복잡도: O(1) ~ O(log n)

종말 Node(Leaf) 조회:

자식이 없는 노드의 경우, Closure Table에서 관련 조상–자손 관계가 없음을 조건으로 빠르게 필터링할 수 있습니다, 시간복잡도: O(1) ~ O(log n)

Hierarchy Node 추가/삭제:

노드 추가 시, 부모의 모든 조상 관계를 새로운 노드와 연결하는 다수의 INSERT가 필요하며, 삭제 시에도 관련된 모든 관계를 제거해야 합니다, 시간복잡도: O(a) 또는 O(r) (여기서 a는 추가할 조상 수, r은 삭제할 관련 관계 수; 일반적으로 트리 깊이에 비례)

postgresql의 ltree

ltree는 PostgreSQL의 확장(extension) 기능 중 하나로, 계층적(트리형) 데이터 구조를 문자열(경로)의 형태로 저장하고, 이 경로를 기준으로 효율적으로 검색할 수 있는 데이터 타입을 제공합니다. 각 노드의 위치는 루트에서 해당 노드까지의 “경로”를 나타내는 문자열로 저장됩니다. 예를 들어, 파일 시스템의 경로처럼 'Top.Middle.Bottom'으로 표현할 수 있습니다. ltree 만을 위한 @> 연산자, <@ 연산자와 기타 함수(예: nlevel(), subpath()) 들이 제공됩니다.

https://dba.stackexchange.com/questions/90797/how-to-update-the-parent-child-of-all-rows-in-the-tree-ltree

전체 Hierarchy 조회:

ltree 전용 인덱스와 <@ 연산자 등으로 경로 기반 조회를 수행할 수 있어, 전체 서브트리를 매우 빠르게 조회할 수 있습니다, 시간복잡도: O(1) ~ O(log n)

단일 Hierarchy Path 조회:

경로 문자열을 기반으로 접두사 매칭 연산을 사용하여, 특정 노드까지의 경로를 즉시 추출할 수 있습니다, 시간복잡도: O(1) ~ O(log n)

종말 Node(Leaf) 조회:

ltree는 기본적으로 경로 정보만 저장하므로, Leaf 여부 판별을 위해 경로 길이 등의 추가 계산이 필요할 수 있지만, 적절히 최적화하면 빠르게 조회할 수 있습니다, 시간복잡도: 보통 (약간의 추가 계산 필요)

Hierarchy Node 추가/삭제:

노드 추가나 이동 시, 해당 노드의 경로 문자열을 계산하여 업데이트해야 합니다. 인덱스 재구성이 필요하므로 비용이 들 수 있으나, 데이터 규모가 작다면 큰 부담은 없습니다, 시간복잡도: O(1) ~ O(log n) (경로 재계산 비용 포함)

효율성 종합

모델	노드 추가	노드 삭제	전체 조회	단일 Path 조회	종말 Node(Leaf) 조회
Adjacency List	시간복잡도: O(1)	시간복잡도: O(1)	시간복잡도: 최악 O(n)	시간복잡도: O(depth) (depth는 보통 작음)	시간복잡도: O(n)
Nested Set	시간복잡도: O(n)	시간복잡도: O(n)	시간복잡도: O(1) ~ O(log n)	시간복잡도: O(1) ~ O(log n)	시간복잡도: O(1)
Closure Table	시간복잡도: O(a), a는 조상 수 (최악 O(n))	시간복잡도: O(r), r은 관련 관계 수 (최악 O(n))	시간복잡도: O(1) ~ O(log n)	시간복잡도: O(1) ~ O(log n)	시간복잡도: O(1) ~ O(log n)
PostgreSQL ltree	시간복잡도: O(1) ~ O(log n) (데이터량이 작으면 거의 O(1))	시간복잡도: O(1) ~ O(log n)	시간복잡도: O(1) ~ O(log n)	시간복잡도: O(1) ~ O(log n)	시간복잡도: O(1) ~ O(log n)

해결방법 선택

데이터의 전체 건수(N)가 많을수록, 그리고 위계 깊이가 깊을수록 각각의 알고리즘이 가진 시간복잡도와 공간 복잡도가 중요한 고려 대상이 됩니다. 또한 읽기(READ) 연산이 압도적으로 많은 경우, Insert/Update 비용보다는 조회 성능이 우선되기 때문에 전체 Hierarchy 조회 및 특정 경로 조회의 효율성이 결정적인 요소가 됩니다. 이러한 기준에서 주관적으로 평가를 해보자면:

Adjacency List Model

구조가 간단하여 구현이 쉽고, 단일 노드의 추가/삭제는 매우 빠르지만, 읽기 성능이 좋지 않기 때문에 소규모 프로젝트에 적합하다고 판단됩니다.

Nested Set Model

lft/rgt 값을 이용한 범위 쿼리로 전체 서브트리 조회 및 특정 경로 조회가 매우 빠르며, 인덱스가 잘 구성되면 조회 성능이 뛰어납니다. 다만 노드 추가/삭제시 전체 트리의 lft/rgt 를 계산해야하므로 업데이트 비용이 매우 높아집니다.

다양한 위계를 가진 다수의 데이터를 다루며, 읽기 연산이 압도적으로 많은 경우에 적합합니다.

Closure Table

각 노드의 모든 조상–자손 관계를 별도 테이블에 미리 저장하기 때문에, 전체 조회나 특정 경로 조회가 단순 JOIN이나 WHERE 조건으로 빠르게 수행됩니다. 노드 추가/삭제시 처리해야 할 작업은 있지만, 구현 복잡도 측면에서는 비교적 간단합니다. 다만 대량의 데이터에 대해서 공간복잡도가 크게 증가되는 문제가 있습니다.

하지만 일반적으로 계층형 데이터가 대량이기는 어렵기에 공간복잡도는 큰 문제가 되지 않을 것으로 보이며, 오히려 가장 RDB다운 해법이라고 판단됩니다.

PostgreSQL ltree

성능측면에서 나무랄데가 없습니다. 다만 특정 RDBMS에 종속성이 생긴다는 점, 그리고 특정 러닝커브가 생긴다는 점에서 부정적입니다.

최종 결론

저의 주관을 종합해보면 읽기 연산이 압도적으로 많은 환경에서는:

Nested Set Model과 Closure Table이 조회 성능 면에서 우수합니다.
Nested Set Model은 조회 쿼리가 매우 빠르지만, 노드 추가/삭제 시 전체 트리 재계산 등 업데이트 비용이 높습니다.
Closure Table은 조회 성능도 뛰어나면서, 노드 추가/삭제 작업에 있어서도 구현이 비교적 간단하며, RDB를 이용한 해결책이라는 점이 더 잘 와닿습니다.

PostgreSQL ltree는 기능적으로 매우 매력적이지만, 특정 RDBMS(즉, PostgreSQL)에 종속성이 생긴다는 점에서 범용성이 떨어진다고 생각합니다.
Adjacency List Model은 구현이 간단하고 단순한 수정 작업에는 효과적이지만, 조회 연산이 많은 경우에는 재귀 탐색 비용 때문에 효율성이 떨어집니다.

따라서, 전체 Record 수(N)가 상대적으로 적고, 위계 깊이(Depth)가 2~5 정도인 환경에서, READ 연산이 주를 이루는 상황이라면, 공간 복잡도만 감수할 수 있다면 Closure Table 방식이 Nested Set 방식보다 구현 복잡도 면에서 우수하며, RDB 기반 해법으로서도 더 직관적이라고 판단됩니다.

Response Interface는?

백엔드 개발자로서 또 하나의 고민은 DB는 저렇게 해결한다고 하는데 "프론트에게 내려주는 데이터 구조는 어떻게 가야하는걸까?" 입니다. 이러한 고민은 백엔드 뿐만 아니라 프론트도 많이 해왔고, React 진영에는 관련 라이브러리가 있는것을 확인했습니다.

그 결과 다음과 같이 데이터를 내려주는 것으로 합의가 되었습니다.

{
    "id": 1,
    "name": "item1",
    "parentId": null,
    "depth": 0
},
{
    "id": 2,
    "name": "item1.1",
    "parentId": 1,
    "depth": 1
},
{
    "id": 3,
    "name": "item1.2",
    "parentId": 1,
    "depth": 1
},
{
    "id": 4,
    "name": "item2",
    "parentId": null,
    "depth": 0
}

참고

managing-hierarchical-data-in-mysql: https://mikehillyer.com/articles/managing-hierarchical-data-in-mysql/

closure table: https://fueled.com/the-cache/posts/backend/closure-table/

closure talbe: https://kntmr.hatenablog.com/entry/2020/08/14/080000

postgresql ltree: https://www.postgresql.org/docs/16/ltree.html

postgresql ltree: https://patshaughnessy.net/2017/12/13/saving-a-tree-in-postgres-using-ltree

Python gRPC (3) - gRPC가 빠른 이유와 벤치마크

개발프로브 — Sun, 13 Apr 2025 14:28:53 +0900

gRPC를 왜 써야했는지, 그리고 어떻게 구현해야하는지 알아봤습니다. 이제는 그래서 도대체 왜 gRPC가 빠른건지 이론적인 배경을 정리하겠습니다.

gRPC 성능의 핵심 이론

gRPC가 빠른 가장 큰 이유는 통신 계층의 개선(HTTP/2)과 데이터 표현 방식의 개선(Protocol Buffers)에 있습니다. HTTP/2가 제공하는 멀티플렉싱, 헤더 압축 등의 기능과, 프로토콜 버퍼를 통한 바이너리 데이터 직렬화가 결합되어 지연을 줄이고 처리량을 높입니다. 주요 이론적 요소를 정리하면 다음과 같습니다.

HTTP/2 멀티플렉싱

오늘날에 일반적인 웹 통신은 HTTP/1.1 버전을 따릅니다. 하지만 gRPC는 HTTP/2를 따르도록 되어 있으며, HTTP/2는 하나의 TCP 연결에서 동시에 여러 요청과 응답을 주고받을 수 있는 멀티플렉싱을 지원합니다.

https://blog.cloudflare.com/http-2-for-web-developers

이에 따라 이전 HTTP/1.1처럼 요청-응답을 순차적으로 처리하지 않아도 되므로 지연 시간이 크게 감소합니다. 즉, 클라이언트는 단일 연결로 다수의 요청을 병렬 전송하고 서버로부터 병렬 응답을 받아볼 수 있어 대기 시간이 줄어듭니다.

물론 HTTP/1.1 에서도 요청-응답을 비동기적으로 처리할 수 있도록, 즉 한번에 여러 요청을 처리할 수 있도록 Keep-Alive, pipelining 을 지원했지만 근본적은 해결책은 아니었기 때문에 HOL 블로킹(Head of line blocking)문제가 발생할 수 있으며, 다수의 proxy 서버들은 이 spec에 대응하지 못했습니다. 그에비해 HTTP/2 의 멀티플렉싱은 이러한 문제를 더 본질적으로 해결한 접근입니다.

HTTP/2 헤더 압축(HPACK)

https://cheapsslsecurity.com/p/http-2-header-compression/

HTTP/1.1에서는 매 요청마다 쿠키 등 반복적인 헤더들이 전송되어 불필요한 오버헤드가 많았습니다. HTTP/2에서는 헤더를 압축하고 중복을 제거하여 전송하기 때문에 대역폭 사용이 효율적이고 응답 속도가 개선됩니다. 예를 들어 gRPC는 HTTP/2 기반이므로 content-type, 권한 토큰 등의 헤더를 한 번만 보내거나 압축하여 반복 전송하지 않으므로, REST API 대비 패킷 크기가 줄고 처리 효율이 높아집니다.

Protocol Buffers 바이너리 직렬화

지금까지의 특성은 사실 HTTP/2를 이용하기 때문에 얻을 수 있는 이득이지 gRPC를 사용하기 때문에 얻는 이득이라고 보기 어렵습니다. 위의 성능상 이점은 클라이언트와 서버가 HTTP/2 위에서 REST로 통신을 해도 똑같으니까요. 하지만 gRPC는 proto buffer를 이용하여 바이너리 직렬화/역직렬화라는 추가적인 성능상 이득을 줍니다.

gRPC는 데이터 교환에 JSON 대신 Protocol Buffers(이하 ProtoBuf)를 사용합니다. ProtoBuf는 이진(binary) 포맷으로 데이터를 직렬화하기 때문에 JSON처럼 사람이 읽을 수 있는 텍스트 표현에 비해 데이터 크기가 작고 파싱 속도가 빠릅니다. ProtoBuf에서는 각 필드를 번호(Tag)로 식별하고 타입을 미리 정의하여 변환하므로, 키 이름과 구조를 일일이 문자열로 보내는 JSON에 비해 효율적인 인코딩/디코딩이 가능합니다.

데이터 중심 어플리케이션 설계의 저자 Martin Kleppmann는 자신의 블로그에서 이 부분을 정확히 설명했습니다.

# json 으로 이 데이터를 표현하면 82byte 지만
{
    "userName": "Martin",
    "favouriteNumber": 1337,
    "interests": ["daydreaming", "hacking"]
}

# proto 파일을 에서 메시지 포맷을 이렇게 정의하면 33byte 가 됩니다.
message Person {
    required string user_name        = 1;
    optional int64  favourite_number = 2;
    repeated string interests        = 3;
}

python code로 보자면, message/person.proto 파일을 기반으로 만들어진 pb2.py 파일에서 이진 포맷 데이터를 확인할 수 있습니다.

# pb/message/person.pb2.py
from google.protobuf import descriptor_pool as _descriptor_pool
... 
# DESCRIPTOR 에 할당된 이진 데이터를 확인할 수 있습니다.
DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x14message/person.proto\x12\x06member\"H\n\x06Person\x12\x11\n\tuser_name\x18\x01 \x01(\t\x12\x18\n\x10\x66\x61vourite_number\x18\x02 \x01(\x03\x12\x11\n\tinterests\x18\x03 \x03(\tb\x06proto3')

...

실험 결과: REST vs gRPC 성능 비교

공식 벤치마크

gRPC 공식문서에서는 Benchmark 에 대한 정보를 제공하고 있습니다. 심지어 Grafana로 만든 대시보드도 제공하고 있어서 정보를 얻기 정말 편합니다. 다만, REST 와 gRPC의 비교가 아니라 각 언어간 gRPC의 Latency 와 throughput 을 비교하는 자료여서 지금 알아보고자 하는 내용과는 달라서 깊이 알아보진 않겠습니다.

Payload 에 따른 비교

gRPC 특성상 다양한 클라이언트(언어)가 고려되어야 할것입니다. 다양한 벤치마크들 중 KTH의 학사학위 프로젝트에서 적절한 레퍼런스를 찾은듯 합니다.

table 4.2, data size

Java, Python, Rust 언어에 대해서 요청횟수는 고정하고, payload 크기를 XS, S, M, L 으로 바꿔가며 실험한 결과를 발견했습니다. 초록부터 Appendix 이전가지 44 페이지 정도 되는 짧은 보고서이므로 다 읽어보는게 좋겠지만, 실험결과만 요역하자면 다음과 같습니다:

java, Python, Rust 결과 그래프

실험 결과에 따르면, Payload 크기가 클수록 gRPC의 성능이 REST 대비 일관되게 우수한 것으로 나타났습니다. Java, Python, Rust 세 언어 모두에서 동일한 경향이 확인되었으며, 특히 중간(M) 이상 크기의 메시지에서 gRPC가 확실한 우위를 보였습니다. 예를 들어 Java 환경에서는 protobuf로 인코딩된 메시지는 JSON 대비 56% 더 작은 크기를 가졌고, gRPC 서버는 REST보다 52% 더 높은 throughput 을 달성했습니다.

프로그래밍 언어에 따라 gRPC의 효율성은 다소 차이가 있었습니다. 실험에서는 Payload가 아주 커지는 경우(예: L)에는 Python의 gRPC 성능 향상폭이 다른 두 언어의 성능 향상 폭보다 굉장히 컸습니다. 반면 Payload가 작은 경우 RUST는 명확하게 REST 를 이용하는게 gRPC 보다 340% 더 높은 throughput을 보여주었습니다.

이러한 실험결과를 통해 얻을 수 있는 인사이트 아래와 같습니다:

항상 gRPC가 REST보다 나은것은 아니다. 전달하는 데이터 payload가 작다면 REST를 고려할수도 있다.
언어에따라 REST 대비 gRPC의 성능이 차이가 있다. 만약 성능상 차이가 크지 않다면 운영이 더 복잡해지는 gRPC를 굳이 도입하지 않을 수도 있다.

직접 실험하기

위의 실험도 충분히 재미있고 유용한 결과를 주지만 요청횟수에 따른 비교가 아쉽습니다. 더 오피셜하고 명확한 레퍼런스로는 "2021년에 작성된 관련 보고서" 가 있지만, 저는 접근할 수 없어서 직접 테스트하게 되었습니다.

원래는 더 현실적인 테스트를 위해 EC2 에 gRPC, REST 서버를 올리고 부하 테스트를 진행했지만, 제가 이용하는 네트워크망이 일반 가정용이어서 너무 느린 문제로 결국 localhost 테스트로 대체되었습니다.

이하의 내용은 github에서 코드를 내려받으셔서 직접 재현할 수 있습니다.

테스트 환경

서버 환경: MacBook Air 15, M3, 2024, RAM 24GB
REST 서버: Starlette + Uvicorn (--workers=2)
gRPC 서버: Python grpc.server(ThreadPoolExecutor(max_workers=10)), grpc.aio.server(...)
클라이언트: go ghz, hey
Response Payload 크기: 14KB, 256KB (REST는 JSON, gRPC는 Protobuf)
부하 조건: 클라이언트: 50, 100개, 요청: 2000, 5000, 10,000

테스트 결과

부하조건을 다르게 줬지만, 결과적으로 저정도 부하 조건에는 각 프로토콜별로 유의미한 차이를 찾을 수 없습니다. raw 데이터는 구글 스프레드시트에 열어두었습니다.(raw data)

그래서 Payload 크기를 14KB, 256KB 로 고정했을때 클라이언트 100개가가 총 10,000개의 요청을 전달하는 케이스만 요약하였습니다.

14KB 조건:

위의 "Payload에 다른 비교"와 같은 결과가 나왔습니다. REST 가 전반적으로 gRPC, gRPC_aio 보다 적은 Latency 를 보여주 고 있습니다.

14KB 조건에서 Latency Distribution

실제 median latency 로 비교를 해보자면 REST(3.4ms), gRPC(5.66ms), gRPC_aio(4.09ms) 로, REST 가 gRPC 보다 40%, gRPC_aio 보다는 16% 더 나은 성능을 보여주고 있습니다.

다만 99% percentile 에서의 안정성은 gRPC 가 REST 보다 뛰어났으며, 특히 aio 를 이용한 gRPC가 더 안정적인 모습을 보여주었습니다.

256KB 조건:

Payload 크기가 커지자 gRPC의 성능이 REST보다 나아지기 시작했습니다. 역시 aio를 이용한 gRPC 가 gRPC 보다 더 안정적이고 더 나은 성능을 보여주는 것이 확인되었습니다.

256KB 조건에서 Latency Distribution

실제 median latency 로 비교를 해보자면 REST(22ms), gRPC(14.19ms), gRPC_aio(12.33ms) 로, REST 가 gRPC 보다 55%, gRPC_aio 보다는 78% 더 안좋은 성능을 보여주고 있습니다.

gRPC vs gRPC_aio

직접 벤치마크 테스트를 해보고는 스웨덴 학부생들이 했던 실험결과를 재확인하였습니다. 그런데 거기서 그치지 않고 추가로 흥미로운 결과과를 하나 확인했습니다. aio 를 이용한 gRPC가 일반 gRPC보다 단순 I/O 작업에서 더 좋은 성능(낮은 Latency)를 보여주고 있다는 것입니다.

gRPC는 Python Thread에 기반하여 동시성을 구현하고 있는것으로 추측됩니다. 그렇다면 Python Asyncio를 추가로 이용하는 grpc.aio 가 단순 I/O 작업에서는 더 나은 성능을 보여주는것은 당연할 것입니다.

따라서 일반적으로 I/O 가 중요한 작업이라면 gpc 보다는 grpc.aio 를 이용하는게 더 나은 선택일 것입니다. 다만 아직은 Python GIL을 이용하는게 기본 사양이므로 gRPC를 통해 일어나는 작업이 CPU Bound 하다면 무작정 grpc.aio를 이용하는건 지양해야할것입니다.

종합 결론

모두 Python에 대한 이야기입니다.

localhost 환경에서 REST의 병렬처리 정도를 (warker)를 높인다면 요청 처리량에 있어서는 gRPC 와 유의미한 차이가 없음
Payload가 일정수준 커질경우 gRPC가 REST 보다 더 나은 성능을 보여줌
Payload 크기와 관계없이 항상 gRPC가 REST보다 더 안정적인 성능(저 낮은 Latency 편차)을 보여줌

실험 한계

테스트는 모두 localhost에서 진행되어 HTTP/2의 장점(멀티플렉싱, RTT 감소 등)은 반영되지 않음
CPU 사용률, 메모리 프로파일링은 포함하지 않음 (추가 실험 대상)

참고

- gRPC 깊게 파고들기 #1, 네이버클라우드

- gRPC 깊게 파고들기 #2, 네이버클라우드

- gRPC Introduction, google

- What does multiplexing mean in HTTP/2, stackoverflow

- HTTP/1.x connection management, MDN

- http2 for web developers, cloudflare

- HPACK, cloudflare

- gRPC Benchmark

- gRPC vs REST, .NET Benchmakr

- gRPC vs REST, SpringBoot

- gRPC vs REST, A Comparative Study of REST and gRPC

- gRPC vs REST, Using Locust

Strawberry 선택 이유와 타 라이브러리와의 비교 분석

개발프로브 — Sat, 29 Mar 2025 13:52:56 +0900

https://pypi.org/project/strawberry-graphql/

이전글에서 REST, gRPC 그리고 GraphQL를 비교해봤습니다. 이번에는 Python의 GraphQL 사용을 돕는 라이브러리를 비교해보려고 합니다. 솔직히 말하자면 FastAPI 유저인 저에게는 FastAPI가 공식문서에서 추천한 Strawberry가 정답으로 자리잡고 있고, 이미 Strawberry를 이용해서 구현했지만 공부하는 차원에서 각 라이브러리의 사용성, 문서화와 개발자 경험(DX), 타입 지원, 웹 프레임워크 통합성, 프로젝트 유지보수 및 커뮤니티 현황을 살펴보겠습니다.

왜 라이브러리 비교기준에서 성능이 빠졌을지 의문을 가질 수 있습니다. 하지만 물론 저도 처음에는 알아봤지만 GraphQL 서버 성능은 주로 쿼리 실행 엔진의 효율과 리졸버에서의 I/O 처리 방식에 따라 좌우되며, 세 라이브러리 모두 Python용 GraphQL 코어 라이브러리를 기반으로 하고 있어, 기본적인 쿼리 파싱/실행 성능은 큰 차이가 없다고 판단되어 비교기준에서 제외했습니다.

Python & GraphQL 라이브러리들

Python에서 GraphQL API를 구현하기 위해 많이 사용되는 라이브러리로 Strawberry, Graphene, Ariadne 세 가지가 있습니다.

우선 Graphene 프로젝트는 가장 역사가 오래되었지만 최근에 유지보수나 업데이트가 활발하지 않은것으로 확인되었습니다.
Strawberry는 보다는 최근에 만들어졌으며 github에서 활발히 논의가 이뤄지는게 확인이 되었습니다.
Ariadne 는 코드우선방식을 채택한 Graphene나 Strawberry와 다르게 스키마 우선 방식을 채택하여 비교할 가치가 있다고 생각했습니다.

각 주제별로 세 라이브러리를 비교하겠습니다.

사용성: Pythonic한 코드 작성의 간결함

GraphQL 라이브러리의 사용성은 얼마나 간결하고 Pythonic하게 스키마와 리졸버를 작성할 수 있는지를 의미합니다. 각 라이브러리는 스키마 정의 방식부터 차이가 있습니다.

Graphene

코드 우선(code-first) 접근 방식의 대표격입니다. Django ORM 스타일과 비슷하게 Python 클래스를 정의하여 GraphQL 스키마를 만듭니다. Django 개발자에게 친숙할 수 있지만, 작은 스키마에도 많은 보일러플레이트(boilerplate) 코드와 규칙이 필요할 수 있습니다.

import graphene

class User(graphene.ObjectType):
    name = graphene.String()
    age = graphene.Int()

class Query(graphene.ObjectType):
    user = graphene.Field(User)

    def resolve_user(self, info):
        return User(name="Patrick", age=100)

schema = graphene.Schema(query=Query)

Strawberry

Graphene과 마찬가지로 코드 우선 접근이지만, 최신 Python 기능인 타입 힌트와 데이터클래스를 적극 활용하여 보다 간결하고 Pythonic한 인터페이스를 제공합니다.

import strawberry


@strawberry.type
class User:
    name: str
    age: int

@strawberry.type
class Query:
    @strawberry.field
    def user(self) -> User:
        return User(name="Patrick", age=100)


schema = strawberry.Schema(query=Query)

Ariadne

스키마 우선(schema-first) 접근 방식을 취합니다. 즉, GraphQL의 SDL(schema definition language) 문법으로 스키마를 문자열이나 파일로 작성하고, 해당 스키마의 각 타입과 필드에 대응하는 리졸버 함수를 Python 코드로 연결합니다.

from ariadne import gql, QueryType, make_executable_schema

# GraphQL 스키마 정의 (SDL)
type_defs = gql("""
    type User {
        name: String!
        age: Int!
    }

    type Query {
        user: User!
    }
""")

# 리졸버 객체 생성
query = QueryType()

@query.field("user")
def resolve_user(_, info):
    return {"name": "Patrick", "age": 100}

schema = make_executable_schema(type_defs, query)

Ariadne을 쓰면 GraphQL 자체의 표준 문법으로 API를 명세하고, 비즈니스 로직 연결은 @query.field("fieldName") 같은 데코레이터나 ObjectType("TypeName") 객체를 통해 매핑합니다. 이 방식은 GraphQL을 잘 아는 개발자에게는 명확하고 직관적입니다.

Graphene처럼 복잡한 Python 클래스 계층을 만들 필요 없이 스키마는 스키마대로, 코드 로직은 코드대로 분리할 수 있어 단순합니다. 반면 Python 타입 힌트를 이용해 자동으로 스키마를 생성해주진 않기에, GraphQL SDL 문법을 별도로 작성해야 하는 부담이 있습니다.

개인적인 평가

제 개인적인 견해로는 Strawberry의 방식이 가장 Pythonic 한것 같습니다. Django처럼 python type과 별도 호환이 필요한것도 아니고, Ariadne처럼 type_defs SDL을 별도로 관리해줄 필요도 없습니다.

문서화 수준과 개발자 경험 (DX)

개발자 경험(DX)은 학습 곡선, 문서의 친절함, 사용 시 장애 요소 등을 포함합니다. 세 라이브러리는 이 부분에서 다음과 같은 장단점을 보입니다.

Graphene

오랜 기간 사용되었지만 공식 문서화가 다소 빈약하고 최신 업데이트를 충분히 반영하지 못한 면이 있습니다. (개인적으로 ASGI의 공식문서를 보는 느낌이 들었을 정도로 재미없는 공식문서입니다.) 특히 Graphene v3로 업그레이드되는 동안 문서와 주변 도구들이 늦게 따라와 혼란이 있었고, 예를 들어 DataLoader 문서가 깨져 한동안 제대로 안내되지 않았다는 지적도 있었습니다.

그럼에도 Graphene은 성숙한 생태계를 갖추고 있어, Stack Overflow 등 Q&A나 블로그 게시물이 풍부한 편입니다. 다만 2020~2021년 경 프로젝트가 잠시 정체되면서 유지보수 부재 논란이 있었고, 실제로 2021년에는 maintainer를 모집하는 공지가 올라오기도 했습니다. 이후 다행히 새로운 기여자들이 참여하여 현재는 릴리스가 이어지고 있지만, 이러한 과거 때문에 미래 지원에 대한 우려가 있는것도 사실입니다.

Strawberry

비교적 신생 프로젝트지만 문서가 잘 정비되어 있고, 예제와 API 레퍼런스가 명확합니다. FastAPI 등 최신 프레임워크 철학과 맞닿아 있어 학습 개념도 쉽게 와닿으며, 공식 문서도 타입 힌트의 활용, Pydantic 통합 등 실용적인 내용을 담고 있습니다. 실제로 Graphene 사용 중 겪었던 서드파티 라이브러리 호환성 문제(예: 구독 프로토콜, 오래된 의존성 등)들이 Strawberry에서는 비교적 원활하게 해결되었고, Async 지원이나 최신 GraphQL 기능(예: 서브스크립션, 데이터로더)도 기본 제공 또는 쉽게 사용할 수 있도록 되어 있습니다.

다만 Strawberry는 아직 버전 1.0 이전(현재 0.x대)이라 API가 완전히 안정된 상태는 아니며 종종 breaking change가 발생할 수 있습니다. 그럼에도 활발한 개발과 빈번한 릴리스로 이슈 해결이 빠르고, Discord 등지에서 활발한 커뮤니티 지원을 받을 수 있습니다.

Ariadne

문서와 예제가 잘 제공되어 있고, 개념이 단순하여 진입 장벽이 높지 않습니다. 공식 사이트의 튜토리얼이나 블로그 글을 통해 SDL 작성부터 ASGI 앱 구동까지 간단한 예제로 쉽게 따라할 수 있습니다. Ariadne의 철학이 "작고 기억하기 쉬운 API"를 지향하여, 실제 사용해보면 필요한 기능만 최소한의 API로 제공해 직관적입니다.

예를 들어 make_executable_schema로 스키마 문자열과 리졸버를 연결하고, GraphQL ASGI 앱으로 서비스하는 흐름이 명쾌합니다:

import os

from ariadne import make_executable_schema
from ariadne.asgi import GraphQL
from mygraphql import type_defs, resolvers

schema = make_executable_schema(type_defs, resolvers)
application = GraphQL(schema)

개발자 경험 측면에서 GraphQL 스키마 설계와 Python 코드를 분리하는 것을 선호하는 경우 Ariadne이 만족도를 줄것으로 보입니다. 반면, 대규모 프로젝트에서 Python 타입 시스템과 연계된 도구(Mypy, Pydantic 등)를 활용한 개발 편의는 Ariadne에서 자동으로 얻기 어렵습니다. 모든 타입 정의를 GraphQL SDL로 수동 관리해야 하므로, 코드 상에서 타입참조 추적이나 에디터 자동완성 같은 부분은 Strawberry보다 부족할 수 있습니다. 요약하면 Ariadne은 심플함이 강점이지만, Python 도구들과의 통합된 DX는 상대적으로 단순한 편입니다.

타입 지원: Python 타입 힌트 및 Pydantic 통합

Python 백엔드 개발자에게 타입 시스템과의 통합은 매우 중요한 요소입니다. 각 라이브러리가 Python의 타입 힌트나 데이터 검증 라이브러리(Pydantic 등)와 어떻게 호환되는지 살펴보겠습니다.

Graphene

등장 시기가 Python 타입 힌트가 도입되던 무렵이라, Graphene 자체는 타입 힌트를 활용한 설계는 아닙니다. 스키마 정의에 별도의 graphene 타입 클래스를 사용하기 때문에, IDE 상에서 Python 타입 체크를 해주진 않습니다. 예를 들어 age = graphene.Int()로 필드를 정의해도 해당 클래스의 age 속성은 단순히 GraphQL 필드이지, Python 정수형이라는 힌트를 갖지 않습니다.

따라서 Graphene은 정적 타입 체크 도구(mypy)와의 연계는 부족합니다. 한편 Graphene은 Django 모델이나 SQLAlchemy 모델과의 통합을 통해 모델 필드로부터 GraphQL 필드를 생성하는 기능을 제공하지만, Pydantic 같은 독립적인 검증 모델과의 공식 통합은 없습니다. Pydantic 모델을 GraphQL 스키마로 이용하려면 수동으로 Graphene 타입을 만들어 매핑해야 합니다.

Strawberry

타입 힌트 우선 디자인을 내세운 라이브러리답게, 모든 GraphQL 타입 정의와 필드에 Python 타입 힌트를 사용합니다. 덕분에 개발자는 자연스러운 Python 데이터클래스를 작성하듯이 GraphQL 타입을 정의할 수 있고, IDE 자동완성이나 mypy 같은 도구의 혜택을 누릴 수 있습니다. 또한 Strawberry는 Pydantic과의 통합을 실험적으로 지원하여, 기존 Pydantic 모델을 재사용해 GraphQL 타입을 만들 수 있습니다. 공식 문서에 따르면 "Strawberry는 Pydantic을 지원하며, Pydantic 모델로부터 Strawberry 타입을 생성해 코드를 두 번 작성할 필요를 없애준다"고 합니다. (하지만 저는 아직 experimental 단계의 기능이어서 실제 회사에서는 사용하지 못했습니다.)

strawberry.experimental.pydantic.type 데코레이터를 활용하여... Pydantic의 필드 정의를 읽어들여 자동으로 해당 GraphQL 타입을 생성합니다. 예를 들어, Pydantic 모델 User(BaseModel)이 있을 때:

@strawberry.experimental.pydantic.type(model=User)
class UserType:
    id: strawberry.auto
    name: strawberry.auto

이렇게 하면 UserType GraphQL 객체 타입이 Pydantic User의 id, name 필드를 그대로 갖게 됩니다. 이 기능 덕분에 데이터 검증(Pydantic)과 GraphQL 스키마 정의를 한 번에 관리할 수 있으며, 중복 모델 정의를 줄일 수 있습니다.

Ariadne

Ariadne은 GraphQL 스키마를 SDL로 정의하므로 Python의 타입 힌트 시스템과 직접적인 연계는 없습니다. GraphQL 스키마 자체의 타입(예: String, Int, 커스텀 타입 등)을 사용하고, 리졸버 함수의 시그니처에는 자유롭게 Python 타입 힌트를 달 수 있지만 그것이 GraphQL 스키마에 반영되진 않습니다. 따라서 정적 타입 체크나 에디터 지원 측면에서는 Ariadne이 특별한 도움을 주지 않습니다. Pydantic과의 통합도 별도로 제공되지 않습니다.

하지만, 필요하다면 리졸버 구현 내에서 Pydantic 모델을 활용할 수는 있습니다. 예를 들어, 뮤테이션 인자로 받은 딕셔너리를 Pydantic 모델로 파싱하여 검증하거나, 반대로 반환할 객체를 Pydantic 모델로 생성한 뒤 .dict()로 직렬화해 돌려주는 식으로 수작업 통합은 가능합니다. 이것은 순전히 개발자 몫이며, 프레임워크 차원의 지원은 아니죠. 정리하면 Ariadne은 타입 힌트/모델 통합보다는 GraphQL 스키마 자체에 집중한 라이브러리입니다.

주요 웹 프레임워크와의 통합성

GraphQL 라이브러리 선택 시, 사용 중인 웹 프레임워크와 쉽게 통합되는지도 고려해야 합니다. FastAPI, Django 같은 인기 프레임워크와의 통합 현황을 비교해보겠습니다.

FastAPI와 ASGI 프레임워크

FastAPI는 공식 문서에서 Strawberry를 권장할 정도로 Strawberry와의 궁합이 뛰어납니다.

Strawberry는 strawberry.fastapi.GraphQLRouter를 제공하여 FastAPI 애플리케이션에 손쉽게 GraphQL 엔드포인트를 추가할 수 있습니다. app.include_router(GraphQLRouter(schema), prefix="/graphql") 한 줄로 통합이 가능합니다

import strawberry
from fastapi import FastAPI
from strawberry.fastapi import GraphQLRouter


@strawberry.type
class User:
	pass

@strawberry.type
class Query:
	pass

schema = strawberry.Schema(query=Query)

graphql_app = GraphQLRouter(schema)

app = FastAPI()
app.include_router(graphql_app, prefix="/graphql")

Graphene의 경우, Starlette(및 FastAPI)에서 GraphQL을 쓰려면 별도의 어댑터가 필요했습니다. 예전에는 Starlette의 GraphQLApp 클래스를 사용했으나 deprecated 되었고, 현재는 타사 라이브러리인 starlette-graphene3를 이용해 FastAPI에 Graphene을 붙일 수 있습니다. 이는 동작은 하지만 공식 지원이 아닙니다.

Ariadne은 ASGI 앱 자체로 동작하므로 FastAPI에 손쉽게 mount할 수 있습니다. app.mount("/graphql", GraphQL(schema)) 형태로 서브 애플리케이션으로 붙이거나, FastAPI 라우터 내부에서 GraphQL(schema).handle_http 등을 직접 endpoint로 사용하는 방식도 가능합니다. 실제로 Starlette, FastAPI, Flask 등과의 통합 예제가 문서에 제공됩니다.

from ariadne import QueryType, make_executable_schema
from ariadne.asgi import GraphQL
from fastapi import FastAPI

type_defs = """
    type Query {
        hello: String!
    }
"""

query = QueryType()


@query.field("hello")
def resolve_hello(*_):
    return "Hello world!"


# Create executable schema instance
schema = make_executable_schema(type_defs, query)

# Mount Ariadne GraphQL as sub-application for FastAPI
app = FastAPI()

app.mount("/graphql/", GraphQL(schema, debug=True))

Django

Graphene은 Django 환경에서 가장 오래 사용된 GraphQL 솔루션입니다. graphene-django 패키지를 통해 Django의 ORM 모델을 Graphene 타입으로 쉽게 변환하고, Django view로 GraphQL 엔드포인트(/graphql)를 제공할 수 있습니다. Graphene-Django는 Django의 권한 체계나 필터 셋과 연동하는 등 편의 기능도 많아 성숙한 상태입니다.

Strawberry도 최근 strawberry-graphql-django패키지를 통해 Django 통합을 제공하고 있습니다. Django 모델로부터 Strawberry 타입을 생성하거나, Django의 urlpatterns에 GraphQL view를 추가하는 기능을 갖추고 있지만, 성숙도는 이제 올라오는 단계입니다. Graphene-Django가 수년간 다듬어져 온 것에 비해 Strawberry-Django는 비교적 새롭지만, 활발한 개발이 이루어지고 있rh 점차 안정화되고 있습니다.

Ariadne도 Django 통합을 지원하는 별도 패키지(ariadne_django)가 있어서, GraphQLView.as_view()를 통해 Django의 URL 패턴에 GraphQL 엔드포인트를 등록할 수 있습니다.
Django에서 Ariadne를 사용하면 GraphQL 스키마는 SDL로 정의하고, 각 앱별로 SDL 조각과 resolver 함수를 모듈화하여 구성하는 패턴을 취할 수 있습니다. Django 환경에서는 Graphene과 Ariadne 둘 다 많이 사용되고 있고, Strawberry는 신흥 대안으로 자리잡는 추세입니다.

프로젝트 유지보수 상태 및 커뮤니티 활동

오픈소스 라이브러리의 유지보수 현황과 커뮤니티 규모도 무시할 수 없는 요소입니다. 장기적으로 사용할 기술이라면 업데이트 주기나 이슈 대응 속도, 사용자 풀 등을 봐야 합니다.

Graphene

2015년경부터 개발되어 가장 역사가 오래된 Python GraphQL 라이브러리 중 하나입니다. 스타 수, 다운로드 수 등 인지도나 사용자 기반이 가장 크다고 볼 수 있습니다. 다만 앞서 언급했듯 한때 주요 유지관리자들의 손이 떠나 프로젝트가 정체되었던 시기가 있었습니다.

현재는 여러 기여자의 참여로 다시 활기를 찾았고, 2022년 Graphene 3.x 정식 버전이 나오면서 꾸준한 릴리스가 이뤄지고 있습니다. Graphene-Django나 Graphene-SQLAlchemy 같은 서브 프로젝트들도 커뮤니티 주도로 관리되고 있습니다. 커뮤니티 Q&A는 많지만, 오래된 이슈나 v2 기준의 답변도 많아 정보를 걸러볼 필요는 있습니다.

Strawberry

2019년경 등장하여 빠르게 성장한 프로젝트입니다. 아직 버전 1.0은 아니지만 0.x 버전대에서 거의 매주 단위의 빈번한 업데이트가 진행되고 있습니다. Graphene 핵심 개발자 출신 등이 참여해 만들었기 때문에 Graphene의 단점을 보완하려 노력하고 있으며, 커뮤니티도 Discord, GitHub Discussions 등을 통해 활발합니다.

Ariadne

2018년경부터 시작되어 현재까지 꾸준히 유지보수되고 있습니다. 주로 Django 기반 커머스 플랫폼 Saleor를 만든 Mirumee사가 중심이 되어 개발한 것으로 알려져 있으며, 해당 회사 프로젝트에서 활용하면서 안정성을 높여온 케이스입니다.

현재 버전도 0.x이지만 (최근 2025년 2월에 0.26 버전 릴리스), 이는 Semantic versioning을 엄격히 따르는 것일 뿐 기능은 충분히 안정적입니다. 커뮤니티 규모는 Graphene이나 Strawberry보다 작아 보이지만, GraphQL을 선호하는 Python 개발자들 사이에서는 평판이 좋은 편입니다. Slack/Discord 같은 공식 커뮤니티와 GitHub 이슈를 통해 질문을 해결할 수 있고, GraphQL 표준에 맞춰 돌아가는 만큼 일반 GraphQL 자료들도 참고 가능합니다.

Strawberry를 선택할 만한 이유

위의 비교 요소들을 종합해보면, Strawberry를 선택하는것은 타입힌트를 선호하는 Python 개발자에게는 좋은 선택일 것이며, 특히 FastAPI를 이용중인 팀에게는 가장 나은 대안이 될 것으로 보입니다.

실제로 몇 줄의 코드만으로 GraphQL 라우트를 추가할 수 있었고, FastAPI의 의존성 주입이나 보안 처리도 Strawberry의 컨텍스트 기능과 잘 연계되었습니다.

저는 Strawberry로 GraphQL을 구현할 때 Python 코드와 GraphQL 스키마 사이의 갭이 느껴지지 않았고 자연스러웠습니다. 반면 Graphene은 Django 스타일이라 호불호가 있었고 (우리 팀에는 Django 경험이 적은 인원도 있어 학습이 필요해 보였습니다.), Ariadne은 SDL 작성에 익숙하지 않은 몇몇에게 초기 진입장벽이 존재했습니다.

유지보수와 향후 전망도 선택에 영향을 줄것입니다. 물론 미래일은 알 수 없지만, 최근의 모멘텀만 보자면 Strawberry는 적극적으로 개선되고 있어 새로운 GraphQL 기능이나 버그 수정이 빠른것으로 파악되었스빈다. Graphene은 현재도 사용자가 많지만 만약 메인테이너 이탈이 다시 생긴다면 대응이 느려질 수 있다는 걱정이 있었죠. Ariadne도 안정적이지만 개발 커뮤니티의 규모가 Strawberry만큼 크진 않아 정보 구하기 측면에서는 Strawberry 쪽이 나았습니다.

마지막으로, 기능성 측면도 Strawberry는 부족함이 없었습니다. GraphQL 서브스크립션, 파일 업로드, 권한 제어 등 필요한 기능을 플러그인이나 내장 기능으로 지원했고, Graphene에서 쓰던 방식을 거의 대등하거나 더 편리한 방법으로 대체할 수 있었습니다. 예컨대 Graphene-Django에서 쓰던 JWT 인증 미들웨어를 Strawberry의 dependencies로 손쉽게 재구현하거나, DataLoader를 활용해 N+1 문제를 해결하는 것도 Strawberry가 잘 지원했습니다.

이러한 이유들로, Python을 이용하는 팀이 Strawberry를 GraphQL 개발에 사용하는 것은 좋은 선택이 될 것입니다. 개발 속도 뿐만 아니라 개발자 경험 측면에서도 좋은 선택으로 보입니다.

GraphQL vs REST vs gRPC: 개념과 설계 철학, 성능 특성 비교

개발프로브 — Sat, 29 Mar 2025 13:52:43 +0900

https://pradeepl.com/blog/api/rest-vs-graphql-vs-grpc/

기존에 REST 와 gRPC로 데이터를 서빙하던 FastAPI 서버에 GraphQL을 도입하게 되었습니다. 필드가 많은 데이터를 서빙하는 서버였는데, 다수의 클라이언트에 서로 다른 인터페이스의 API를 서빙해야 했습니다. 그렇다면 REST 보다는 데이터 질의가 유연한 GraphQL을 도입하는게 좋겠다는 결론을 내렸고, 이미 잘 만들어진 라이브러리와 공식문서 덕분에 3일만에 배포할 수 있었습니다. 일단 구현은 했고, 이제는 블로그에 글을 연재하면서 관련 이론과 케이스 스터디를 진행해보려고 합니다.

이번 글에서는 REST와 gRPC 그리고 GraphQL의 개념, 설계철학을 알아보고 성능 특성을 비교하여 향후 프로젝트를 진행할때 적절한 기술을 선택할 수 있는 기반을 다지고자합니다.

REST: 리소스 중심의 API 아키텍처

REST(Representational State Transfer)는 Roy Fielding의 논문에서 정립된 아키텍처 스타일로, HTTP 프로토콜을 기반으로 클라이언트와 서버가 상호 작용하는 가장 전통적인 방식입니다. RESTful API에서는 리소스(자원)를 중심으로 URL 엔드포인트를 설계하고, HTTP의 표준 메서드를 통해 해당 자원에 대한 생성, 조회, 갱신, 삭제(CRUD) 작업을 수행합니다. REST의 중요한 특징은 무상태성(stateless)으로, 각 요청이 이전 요청의 상태에 영향받지 않고 독립적으로 처리됩니다. 또한 균일 인터페이스(uniform interface)를 지향하여, 일관된 방식으로 자원에 접근하고 표현하도록 규약합니다.

REST의 장점과 단점

대다수의 사람들에게 익숙한 개념이기 때문에 추가로 정리할 내용은 없는것 같습니다. 다른 기술들과 비교를 위해 장점, 단점만 정리하겠습니다.

REST의 장점:

단순성: HTTP 기반으로 동작하므로 이해하기 쉽고 구현이 용이합니다. 클라이언트에서 curl이나 브라우저로도 테스트할 수 있고, 기존 웹 기술 스택을 그대로 활용합니다.
광범위한 호환성: JSON, XML 등 여러 포맷을 주고받을 수 있고, 언어나 플랫폼과 무관하게 모든 HTTP 클라이언트가 이용 가능하여 범용성이 높습니다
캐싱 등 웹 인프라 활용: HTTP 프로토콜의 캐시 제어 등을 활용하여 성능 개선이 가능하고, 로드 밸런서나 게이트웨이 등 기존 인프라와 쉽게 연동됩니다.
성숙한 생태계: 오랜 기간 사용되어 온 만큼 문서화, 모니터링, 테스트를 위한 풍부한 도구와 커뮤니티 지식이 축적되어 있습니다.

REST의 단점:

과/미페치 문제: 고정된 응답 구조로 인해 필요 이상의 데이터를 받거나 필요한 데이터를 한 번에 못 받아 여러 호출이 필요한 문제가 흔합니다.
성능 한계: 텍스트 기반 통신으로 이진 프로토콜에 비해 메시지 크기, 처리에서 불이익이 있으며 HTTP/1.x 오버헤드로 인해 고성능이 요구되는 환경에서는 비효율적일 수 있습니다. 대용량 데이터 전송이나 실시간 상호작용에는 부적합합니다.
버전 관리 부담: 클라이언트 호환성을 유지하면서 API를 발전시키기 어려워, 새로운 기능 추가 시 종종 API 버전을 올려야 합니다. 이는 API 소비자와 제공자 모두에게 부담이 됩니다.
실시간 기능의 부재: 표준 REST에는 서버->클라이언트 푸시나 실시간 스트리밍 기능이 없어, 실시간 업데이트가 필요할 경우 WebSocket이나 Server-Sent Events 등을 별도로 구현해야 합니다.

gRPC: 고성능 RPC 프레임워크

gRPC는 Google이 개발하여 2015년에 오픈 소스로 공개한 고성능 RPC(Remote Procedure Call) 프레임워크입니다. gRPC에서는 서비스와 메서드를 정의한 프로토콜 버퍼(Protocol Buffers) 기반의 인터페이스 정의서(IDL)를 토대로, 클라이언트와 서버가 강력한 타입의 Stub 코드를 생성하여 사용합니다. 쉽게 말해, 원격 서버의 함수를 로컬에서 호출하듯이 사용할 수 있게 해주는 기술입니다. HTTP/2 프로토콜을 전송 계층으로 사용하며, 요청과 응답 데이터는 프로토콜 버퍼 형식으로 바이너리 직렬화되어 교환됩니다. 이러한 구조 덕분에 gRPC는 빠르고 효율적인 통신을 지원하며, 다양한 프로그래밍 언어에서 생성된 코드로 상호 운용이 가능합니다.

gRPC의 설계 철학은 계약 우선(contract-first), 엄격한 스키마 및 효율성으로 요약됩니다. API의 인터페이스를 먼저 .proto 파일로 정의하고, 이 계약에 맞춰 양측 코드가 생성되므로 개발자간 명세 불일치가 적고 안정성이 높습니다. 또한 메시지 형식을 바이너리로 엄격히 정의하기 때문에, REST나 GraphQL처럼 각 요청마다 데이터를 해석하고 검증하는 오버헤드가 줄어듭니다. gRPC는 데이터보다는 동작(원격 함수 호출)에 초점을 맞추고 있어서, 마치 객체의 메서드를 호출하듯 서비스를 사용하게 해줍니다. 그 대신 REST처럼 리소스 경로만 알면 되는 것이 아니라, 사전에 컴파일된 클라이언트 코드(Stub)를 사용해야 한다는 차이가 있습니다.

gRPC를 구성하는 요소

이미 python gRPC 시리즈에서 다룬 내용이지만, 이 글만 읽어서 gRPC가 낯선 사람들을 위해 간단히 gRPC를 구성하는 요소들을 정리해보자면 다음과 같습니다

.proto 파일에 의해 정의된 Proto Request, Proto Response가 각 서비스에 정의된 gRPC Stub, gRPC Server에 의해 통신되는 구조입니다. 이때 각 연결된 서비스들은 엄격히 정의된 .proto 파일의 제한을 받는것으로 안정성을 향상시킵니다.

gRPC의 활용

gRPC는 웹 브라우저 환경에서 바로 사용하기 어려운데, 브라우저가 HTTP/2 상의 임의의 바이너리 프로토콜 호출을 직접 수행할 수 없기 때문입니다. 이를 해결하기 위해 gRPC-Web이라는 별도 기술이 존재하지만, 순수 웹 클라이언트만 대상으로 하는 공개 API라면 REST나 GraphQL 대비 구현이 복잡해질 수 있습니다. 그럼에도 불구하고 서버-서버 통신이나 모바일 앱과 백엔드 간 통신 등 통제된 환경에서는 gRPC의 이점이 커서, 강력한 타입 안전성과 성능 때문에 선호됩니다.

gRPC는 주로 내부 시스템이나 마이크로서비스 아키텍처에서 서비스 간 통신에 많이 쓰이며, 외부 개발자에게 공개하는 API보다는 사내 API 용도에 적합하다는 평가를 받습니다. 대표적인 도입 사례로는 Google, Netflix 외에도 Uber가 대규모 실시간 플랫폼에 gRPC를 활용하고 있는것으로 알려져있으며, Red Hat Blog에서는 gRPC의 활용에 대한 사례를 다루고 있어서 참고할만 합니다.

gRPC의 장점과 단점

gRPC의 가장 큰 강점은 성능과 네트워크 효율입니다. HTTP/2의 멀티플렉싱과 헤더 압축, 프로토콜 버퍼의 바이너리 직렬화를 결합하여 매우 낮은 대기 시간(latency)과 높은 처리량(throughput)을 보여줍니다. 실제로 동일한 API를 gRPC로 구현하면 REST 대비 응답 속도가 크게 향상될 수 있는데, 이는 HTTP/2의 스트림 기능으로 다중 요청을 단일 연결에서 병렬 처리하고, 이진 데이터로 데이터 크기를 최소화하기 때문입니다.

또한 gRPC는 서버->클라이언트 스트림, 클라이언트->서버 스트림, 양방향 스트림 등의 통신 패턴을 제공하기 때문에 실시간 양방향 통신이나 대용량 데이터 스트림 전송에 매우 유리합니다. 예를 들어 채팅, 화상통화, 실시간 데이터 피드 등은 gRPC의 스트리밍을 활용해 구현할 수 있습니다.

한편, gRPC를 사용하려면 초기 설정과 학습 부담이 다소 있습니다. 프로토콜 버퍼 IDL 문법을 익히고 .proto 파일을 작성해야 하며, 이를 기반으로 서버와 클라이언트 코드를 생성하는 빌드 과정을 거쳐야 합니다. REST나 GraphQL처럼 인간이 읽을 수 있는 JSON을 주고받는 것이 아니므로, 디버깅이나 테스트 시 일반적인 HTTP 툴로는 내부 내용을 직접 확인하기 어렵습니다. 대신 grpcurl과 같은 전용 도구나 로깅을 통해 디버깅을 해야 합니다.

gRPC의 장점:

우수한 성능: 이진 프로토콜과 HTTP/2 기반으로 매우 빠른 응답 시간과 높은 처리량을 보입니다. 동일 환경에서 REST 대비 지연 시간이 현저히 낮고 효율적이라는 것이 입증되었습니다.
스트리밍 지원: 요청-응답 외에 스트리밍 방식 통신을 기본으로 지원하여, 실시간 양방향 데이터 송수신이나 스트림 전송에 용이합니다. 별도의 프로토콜 없이도 스트리밍 API를 구현할 수 있습니다.
엄격한 스키마와 타입: 프로토콜 버퍼 IDL로 메시지 구조와 서비스를 명시적으로 정의하므로, 클라이언트-서버 간 인터페이스가 명확하고 타입 안정성이 높습니다. 컴파일 타임에 검증되므로 런타임 오류가 줄어듭니다.
다중 언어 및 플랫폼 지원: 공식 툴체인이 다양한 언어를 지원하여(예: C++, Java, Python, Go 등), 서로 다른 기술 스택 사이의 통신도 통합된 방식으로 처리할 수 있습니다. 한 번 IDL을 작성하면 여러 언어의 클라이언트/서버 코드를 생성해 사용할 수 있습니다.
효율적인 데이터 전송: 프로토콜 버퍼는 JSON 대비 데이터 크기가 작고 파싱 속도가 빠르며, 필드가 정의된 것만 전송하므로 불필요한 데이터가 오가지 않습니다. 네트워크 대역폭이 제한적인 환경에서도 유리합니다.

gRPC의 단점:

브라우저 미지원: 웹 브라우저에서는 gRPC 호출을 직접 할 수 없어 별도의 프록시(gRPC-Web) 또는 폴백이 필요합니다. 따라서 웹 프런트엔드 대상의 공개 API에는 추가 작업이 요구됩니다.
학습 곡선: 새로운 IDL 문법과 RPC 개념에 익숙해져야 하고, 빌드/코드생성 파이프라인을 구축해야 하므로 초기 진입 장벽이 있습니다. 작은 팀이나 단순 서비스에는 설정 부담이 큽니다.
디버깅 어려움: 메시지가 바이너리라 사람이 읽기 어려워, 문제 발생 시 HTTP 기반 API만큼 직관적으로 디버깅하기 힘듭니다. 전용 도구가 필요하며, 로그 분석 등으로 추상화된 호출을 추적해야 합니다.
유연성 감소: 클라이언트가 고정된 stub와 메시지 형식에 의존하므로, GraphQL처럼 요청마다 필드를 가감할 유연성은 없습니다. 계약을 변경하려면 양측 코드를 재생성 및 배포해야 하므로, 빈번한 요구사항 변경이 있는 경우 대응이 번거로울 수 있습니다.
서비스 공개 어려움: 주로 내부 통신용으로 설계되어 외부 공개 API로 사용할 때는 REST만큼 친숙한 표준이 아니며, 서드파티가 쉽게 호출하기 어렵습니다. 따라서 파트너나 공개 API에는 부적합할 수 있고 (대신 SDK 배포 필요), 이러한 경우 보통 REST나 GraphQL로 게이트웨이를 마련해 공개합니다.

GraphQL: 유연한 데이터 질의 언어

https://hasura.io/learn/graphql/intro-graphql/what-is-graphql/

GraphQL은 Facebook(메타)이 2012년 개발하여 2015년 공개한 API 질의 언어(query language)입니다. 일반적인 REST API와 달리 단일 엔드포인트에 요청을 보내서, 클라이언트가 필요한 데이터 필드를 선택하여 질의할 수 있다는 점이 가장 큰 특징입니다. GraphQL 서버는 사전에 정의된 스키마(schema)를 기반으로 클라이언트의 질의(query)를 해석하고 적절한 데이터를 모아 응답합니다. 클라이언트는 한 번의 요청으로 필요한 데이터만 정확히 받아올 수 있으므로, 다수의 REST호출을 대체하여 네트워크 효율을 높일 수 있습니다.

GraphQL의 설계 철학은 데이터 중심의 유연성에 있습니다. 클라이언트가 데이터 형태를 지정해서 요청할 수 있으므로, API 설계자는 다양한 클라이언트 요구사항을 하나의 통합된 그래프형태로 충족시킬 수 있습니다. GraphQL 스키마는 타입 시스템으로 모델링된 도메인 객체와 그 관계(예: User 타입이 Post 타입 목록을 가질 수 있음)를 정의하며, 이를 통해 API는 자체 자가문서화(self-documenting) 특성을 갖게 됩니다. 클라이언트는 스키마를 인스펙션하여 어떤 쿼리와 필드가 존재하는지 알 수 있고, 필요에 따라 조합하여 사용할 수 있습니다. REST가 URL 단위의 리소스 표현에 초점을 맞춘 반면, GraphQL은 전체 데이터 모델을 하나의 그래프로 파악하고 필요한 부분집합을 질의하는 접근을 취합니다.

GraphQL을 구성하는 요소

GraphQL의 개념을 살펴본것만으로도 GraphQL Server, Query, Schema, Self-Documenting 와 같은 새로운 개념이 등장했습니다. 사실은 여기에 더해서 Mutation 이라는 개념도 있어서 이를 간단히 다뤄보겠습니다.

1. GraphQL Server

GraphQL 서버는 클라이언트의 요청을 받아서, 사전에 정의된 스키마에 따라 해당 요청을 처리합니다. 서버는 Query, Mutation, 그리고 (옵션으로) Subscription 요청을 처리하며, 각 요청에 대해 적절한 리졸버(resolver)함수를 호출합니다. 이 리졸버 함수는 실제 데이터 소스(데이터베이스, 외부 API 등)와 연동되어 데이터를 가져오거나 수정하는 역할을 수행합니다.

2. Schema

스키마는 GraphQL API의 계약(contract)을 정의하는 역할을 합니다. 여기에는 어떤 타입의 데이터가 존재하는지, 그리고 클라이언트가 어떤 Query와 Mutation을 수행할 수 있는지가 명시되어 있습니다. 스키마는 GraphQL SDL(Schema Definition Language)로 작성되며, 이를 통해 API의 모든 구성 요소를 명확하게 표현하고, 클라이언트는 스키마를 통해 API의 사용법을 쉽게 이해할 수 있습니다.

3. Query

쿼리는 클라이언트가 서버에 데이터 요청을 보낼 때 사용하는 명령어입니다. 쿼리 문법을 통해 클라이언트는 어떤 데이터가 필요한지, 그리고 그 데이터의 구조를 명시할 수 있습니다. 이로 인해 한 번의 요청으로 여러 종류의 관련 데이터를 효율적으로 조회할 수 있게 됩니다.

4. Mutation

Mutation은 데이터의 변경(생성, 수정, 삭제)을 담당하는 명령어입니다. REST API에서 POST, PUT, DELETE 요청과 유사하지만, GraphQL에서는 Mutation을 통해 요청에 대한 인자와 반환 필드를 구체적으로 지정할 수 있습니다. 이를 통해 클라이언트는 변경된 데이터의 상태를 정확하게 확인할 수 있습니다.

5. Resolver

각 쿼리나 Mutation이 호출되면, 해당 요청은 리졸버(resolver)함수로 전달됩니다. 리졸버는 스키마의 각 필드와 매핑되어 있으며, 데이터 소스에 접근해 실제 데이터를 가져오거나 변경하는 핵심 로직을 수행합니다. 이 과정에서 데이터베이스 호출, 캐싱, 또는 외부 API 호출 등의 다양한 작업이 이루어집니다.

6. Subscription

Subscription은 실시간 데이터 업데이트를 위한 메커니즘입니다. 클라이언트는 특정 이벤트나 데이터 변경 사항을 구독(subscription)하고, 서버는 변경 사항이 발생할 때마다 이를 실시간으로 클라이언트에 전송합니다. 이 기능은 실시간 채팅, 알림, 스트리밍 데이터 등 동적 데이터 전송에 매우 유용합니다.

7. Self-Documentation

GraphQL은 스키마를 기반으로 자동 문서화(Self-Documenting)가 가능합니다. GraphiQL 같은 도구를 사용하면, 클라이언트 개발자는 인터랙티브하게 API를 탐색하고 테스트할 수 있으며, 스키마에 정의된 모든 타입과 필드를 쉽게 확인할 수 있습니다. 이는 개발자 경험을 크게 향상시킵니다.

GraphQL의 활용

GraphQL은 복잡한 도메인이나 다양한 요구 사항이 있는 서비스에 특히 잘 맞습니다. 예를 들어, 전자상거래 애플리케이션에서 제품 정보, 재고, 사용자 리뷰를 각각 다른 마이크로서비스나 데이터베이스에서 가져와야 한다면 GraphQL 게이트웨이가 이를 한 번에 조합하여 제공할 수 있습니다. 이러한 이유로 다수의 기업들이 GraphQL을 도입하고 있는데, GitHub는 REST API에 이어 GraphQL 기반 API를 제공하고 있으며, Shopify, PayPal, Netflix, Facebook 등에서도 GraphQL을 통해 클라이언트에게 유연한 API를 제공합니다. 내부 시스템을 통합하여 단일 API로 노출해야 하는 BFF(Backend for Frontend) 패턴이나, 모바일/웹 클라이언트마다 데이터 요구 사항이 상이한 경우에 GraphQL은 유용한 선택입니다.

GraphQL의 장점과 단점

GraphQL을 사용하면 클라이언트는 오직 필요한 데이터만 받으므로 네트워크 효율성 측면에서 유리합니다. 특히 모바일이나 저대역폭 환경에서는 다수의 REST 호출을 한 번의 GraphQL 호출로 대체함으로써 응답 속도를 향상시킬 수 있습니다. Facebook이 초기 GraphQL을 도입한 계기도 모바일 앱에서 뉴스피드 데이터를 가져올 때 여러 REST API 호출을 하나로 통합하기 위함이었습니다. 또한 GraphQL은 구독(subscription) 기능을 통해 서버가 실시간으로 데이터 변경 사항을 푸시할 수 있는 메커니즘을 제공합니다. 이를 활용하면 실시간 피드나 알림과 같은 기능도 GraphQL 안에서 구현이 가능합니다.

그러나 GraphQL은 서버 측 구현의 복잡도가 높을 수 있습니다. 클라이언트가 임의의 질의를 보낼 수 있기 때문에, 서버는 각 질의에 맞춰 데이터를 조합하는 리졸버(resolver) 로직을 잘 최적화해야 합니다. 복잡한 질의의 경우 서버 부하가 급증할 우려가 있고, N+1 쿼리 문제 등 효율적인 데이터 로딩을 위한 추가 구현이 필요합니다. 또한 대부분의 GraphQL 질의는 POST 요청으로 이루어지므로, HTTP 레벨 캐싱이 바로 적용되지 않아 별도의 캐시 계층이나 Persisted Query 등을 설계해야 할 수 있습니다. 클라이언트가 자유롭게 질의하는 만큼, 쿼리 복잡도나 요청 빈도를 제어하기 위한 쿼리 제한(rate limiting)도 어렵습니다. 마지막으로, REST만 사용해 온 개발자들에게는 GraphQL의 스키마 정의 언어, GraphiQL 등 새로운 도구와 개념을 학습해야 하는 학습 곡선이 존재합니다. 반면 일단 스키마가 구축되고 나면, 프런트엔드 개발자는 백엔드 변경을 기다리지 않고도 필요한 데이터를 조합해 쓸 수 있어 개발 속도가 빨라지는 장점이 있습니다.

GraphQL의 장점:

필요한 데이터만 조회: 클라이언트가 요청한 정확한 데이터만 응답하여 불필요한 전송을 줄입니다. 이로써 오버페칭을 피하고 네트워크 효율을 높입니다.
버전관리 부담 경감: 스키마에 필드를 추가하더라도 기존 질의에는 영향이 없으므로 API 버전 관리 없이도 확장이 용이합니다. 새로운 기능을 추가할 때도 구버전 유지 부담이 적습니다.
강력한 타입 시스템: GraphQL 스키마는 엄격한 타입 정의를 가지므로, 클라이언트-서버 간 데이터 계약이 명확하고 오류를 사전에 방지할 수 있습니다. 또한 스키마를 통한 자동 문서화 및 도구 지원(GraphiQL 등)이 뛰어납니다.
클라이언트 주도형 설계: 프론트엔드가 자신에게 최적화된 데이터 구조를 직접 선택할 수 있어, 다양한 화면이나 디바이스별로 효율적인 데이터 활용이 가능합니다. 하나의 요청으로 복수의 관련 데이터를 가져올 수 있어 복잡한 화면의 데이터를 일괄 조회하기에 좋습니다.
실시간 기능: GraphQL의 구독(subscription)을 사용하면 데이터 변경 시 실시간으로 업데이트를 푸시 받을 수 있어, 별도 소켓 프로토콜 없이도 기본적인 실시간 통신이 가능합니다.

GraphQL의 단점:

서버 부하 및 복잡성: 유연성의 대가로 서버 구현이 복잡해질 수 있고, 잘못된 질의나 비효율적인 리졸버 구현은 서버 부하로 이어질 수 있습니다. 특히 많은 관계를 한꺼번에 요청하는 복잡한 질의는 처리 비용이 큽니다.
캐싱 어려움: GraphQL 응답은 일반적으로 HTTP 레이어에서 캐싱하기 어려워, REST처럼 브라우저나 CDN 캐시를 자동 활용할 수 없습니다. 개발자가 응답 캐싱 전략을 별도로 마련해야 할 수 있습니다.
권한 및 제한 관리: 엔드포인트가 하나로 통합되어 있고 질의 내용이 동적으로 변하므로, 요청별 권한 제어나 Rate Limit 정책 수립이 까다롭습니다. 쿼리 깊이 제한, 시간 제한 등 별도 대책이 필요합니다.
초기 학습 비용: GraphQL 고유의 스키마 정의 문법, 쿼리 언어, 그리고 서버/클라이언트 라이브러리에 대한 학습이 필요하여 익숙해지기까지 시간이 걸립니다. 소규모 프로젝트나 단순한 API에는 다소 과설계(Overengineering)가 될 수 있습니다.
도구 및 생태계 제약: REST만큼 범용적인 표준은 아니므로 일부 모니터링/디버깅 툴이나 기존 인프라와의 통합에서 제약이 있을 수 있습니다. 또한 HTTP가 아닌 별도 프로토콜을 사용하는 것이 아니기 때문에, HTTP/2 기반의 전송 최적화나 바이너리 메시지 압축 측면에서는 gRPC보다 불리합니다.

기술 비교: GraphQL vs REST vs gRPC

앞서 살펴본 바와 같이, GraphQL, REST, gRPC는 개념적인 접근 방식부터 장단점까지 여러 측면에서 뚜렷이 대비됩니다.

특징 RESTgRPCGraphQL: 표로 요약

특징	REST	gRPC	GraphQL
설계 철학	리소스 중심 (URL 및 HTTP 메서드로 자원 표현). 클라이언트가 정해진 엔드포인트에 요청.	RPC 중심 (함수 호출 형태) 및 계약 기반 인터페이스 정의. 프로토콜에 명시된 메서드 호출.	데이터 질의 중심으로 유연한 그래프 모델i. 단일 엔드포인트에서 필요한 데이터 필드 질의.
데이터 포맷	텍스트 (주로 JSON 또는 XML). 사람이 읽을 수 있어 디버깅 용이.	바이너리 (프로토콜 버퍼 등). 효율적이지만 사람이 읽기 어려움.	텍스트 (일반적으로 JSON). 요청은 전용 질의 언어 문법 사용.
통신 프로토콜	HTTP 1.1 (전통적인 요청/응답).	HTTP/2 (멀티플렉싱, 헤더 압축 지원). gRPC-Web 사용 시 HTTP/1.1 업그레이드.	주로 HTTP (HTTP/1.1 또는 HTTP/2 모두 가능).
요청-응답 패턴	단순 요청/응답. 서버 푸시나 스트리밍은 별도 구현 필요.	다양한 RPC 패턴: 단일 요청-응답, 서버 스트림, 클라이언트 스트림, 양방향 스트림 지원.	질의(Query)와 변경(Mutation), 구독(Subscription) 패턴 제공. 구독을 통해 실시간 업데이트 가능.
스키마/타입 체계	공식 스키마 없음 . 유연하지만 타입 불일치 가능.	프로토콜 버퍼 (.proto)로 엄격한 스키마 정의. 컴파일 시 검증되어 타입 안전성 보장.	GraphQL SDL로 스키마 정의. 스키마를 통해 질의 구조와 타입 검증, 자체 문서화 제공.
성능 및 효율	요청 당 오버헤드가 비교적 크고 (다중 요청 시 지연 증가), 텍스트 파싱 부담. 캐싱으로 완화 가능.	이진 프로토콜과 HTTP/2로 고성능, 저지연. 다수 호출도 단일 연결로 효율적 처리.	필요한 데이터만 전송하여 불필요 트래픽 없음. 단일 엔드포인트 처리로 서버 부하 증가 가능, JSON 기반이라 gRPC보다는 비효율.
클라이언트 지원	폭넓음: 브라우저, 모바일, 임베디드 등 HTTP 가능한 어디서나 사용.	제한적: 서버 및 네이티브 앱에서는 좋으나, 브라우저에서는 직접 호출 불가 (gRPC-Web 필요).	폭넓음: HTTP 사용으로 REST와 유사하게 동작하며, 전용 클라이언트 라이브러리로 생산성 향상.
개발 생산성	단순하고 바로 활용 가능. 방대한 문서/툴 지원. 변경 시 클라이언트 영향 커 버전 관리 필요.	초기 설정 복잡하지만, 일단 구축 후에는 자동 생성 코드로 개발 편의 높음.양측 강제 계약으로 오류 감소. 디버깅은 어려움.	초기 학습 필요하지만, 스키마 인트로스펙션 등으로 프론트엔드 개발 편의 높음. API 진화가 쉬워 빈번한 변경에 유연.
주요 사용 사례	공개 웹 API, 단순 CRUD 서비스, 광범위한 클라이언트 대상 서비스. 브라우저 캐싱 활용이 중요한 경우.	마이크로서비스 내부 통신, 고성능 요구 시스템, 실시간 통신 (예: 스트리밍, 채팅). 클라이언트-서버가 통제된 환경.	다양한 데이터를 통합하는 게이트웨이, 복잡한 도메인의 API, 모바일 최적화 API. 클라이언트별 요구사항이 다양한 서비스.

언제 어떤 기술을 선택해야 할까?

지금까지 알아본 내용을 바탕으로, 프로젝트의 요구사항에 따라 세 가지 기술 중 무엇을 선택할지 간략히 정리해봅닌다.

REST를 선택: 클라이언트 종류가 많고 범용적인 공개 API를 제공하거나, 간단한 CRUD 위주의 서비스를 신속하게 구축해야 할 때는 REST가 적합해보입니다. REST는 브라우저를 포함한 모든 환경에서 호환되고, 학습 부담이 낮아 팀원 대부분이 익숙하며, HTTP 캐싱 등 웹 표준의 이점을 쉽게 활용할 수 있습니다. 예를 들어 블로그나 뉴스 사이트처럼 데이터 변경 빈도가 낮고 캐싱을 극대화하고 싶은 경우, REST의 단순함과 캐시 제어 기능이 유용합니다.
GraphQL을 선택: 클라이언트별로 필요한 데이터가 천차만별이고, 한 번의 요청으로 여러 종류의 데이터를 연관지어 가져와야 하는 경우 GraphQL이 빛을 발합니다. 모바일 앱처럼 네트워크 환경이 제한적이거나, 다양한 화면에 맞춰 유연하게 데이터를 공급해야 한다면 GraphQL의 이점이 큽니다. 또한 서비스 기능을 빠르게 확장하면서도 기존 API 버전을 늘리지 않고 유연하게 진화시키고 싶을 때 GraphQL을 고려할 수 있습니다. 단, 팀에 GraphQL 경험이 충분하고, 캐싱/모니터링 등 운영 상의 복잡성을 감당할 수 있다는 전제가 필요합니다.
gRPC를 선택: 내부 시스템 간의 통신이나, 엔드투엔드 성능이 중요한 마이크로서비스 아키텍처에서는 gRPC가 최상의 성능을 제공할 수 있습니다. 예를 들어 실시간 처리가 핵심인 광고 경매 시스템이나, 다수의 마이크로서비스가 밀접하게 상호 작용하는 환경에서는 gRPC의 낮은 지연 시간과 스트리밍 기능이 큰 강점입니다. 서버와 클라이언트를 모두 제어할 수 있고, 여러 언어로 구축된 서비스 간에 효율적이고 타입 안전한 통신이 필요하다면 gRPC가 적합합니다. 다만 브라우저 클라이언트가 직접 호출해야 하는 공개 API라면 gRPC는 권장되지 않으며, 이 경우 REST나 GraphQL 위에 별도 게이트웨이를 두어 변환하여 제공하는 방안도 고려됩니다.

요약하면, REST는 단순성과 호환성 면에서 기본값에 가까운 선택이고, GraphQL은 유연한 데이터 질의와 클라이언트 최적화에 강점이 있으며, gRPC는 성능과 효율을 극대화해야 하는 환경에서 돋보입니다. 각 기술은 상호 배타적이라기보다는 상황에 따라 병행 활용되기도 합니다. 예를 들어, 마이크로서비스 내부 통신에는 gRPC를 사용하면서, 외부 공개 API 계층에는 GraphQL이나 REST로 변환해 제공하는 아키텍처도 가능합니다. 궁극적으로는 애플리케이션의 특성과 요구사항을 고려하여 가장 적합한 통신 방식을 선택하거나, 필요하다면 적절히 조합하여 사용하는 것이 중요합니다.

참고

Introduction to GraphQL: https://graphql.org/learn/

PostMan, gRPC vs GrpahQL: https://blog.postman.com/grpc-vs-graphql/

Comparing REST, gRPC, and GraphQL: https://systemdesignschool.io/blog/rest-grpc-graphql

kong, What is GraphQL: https://konghq.com/blog/learning-center/graphql

gatsby, GraphiQL: https://www.gatsbyjs.com/docs/how-to/querying-data/running-queries-with-graphiql/

rest arch style: https://ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

Python asyncio에 대한 탐구

개발프로브 — Sun, 23 Mar 2025 18:57:05 +0900

https://medium.com/@yashwanthnandam/a-beginners-guide-to-python-s-asyncio-lets-get-async-ing-b2c9c81557cd

Python Web 개발을 FastAPI로 시작하다보니 비동기 상태에서 Python을 다루는게 너무나 당연했습니다. 그동안 막연히 Python을 비동기적으로 쓰려면 asnyc 를 써야지 생각만해왔습니다. 주말을 맞이해서 이번에 그 기반을 닦아보려고 합니다. 오늘은 그래서 asyncio 는 무엇인지 그리고 왜 필요한지, node.js와의 차이점은 무엇인지 등을 알아보고 정리하려 합니다.

asyncio란 무엇인가?

공식 문서에서는 asyncio를 “async/await 문법을 이용하는 동시성(concurrent)처리를 위한 라이브러리" 라고 소개하고 있습니다. 이러한 asyncio 라이브러리를 이용하여 IO bound 되어있는 작업을 효율적으로 처리할 수 있고, 이러한 이유로 고성능 웹 프라임워크, 네트워크 연결, 데이터베이스 연결등의 다른 라이브러리의 근간이 됩니다.

asyncio는 Python에서 비동기 I/O를 지원하기 위한 라이브러리로, async/await 구문을 사용하여 동시성 있는 코드를 작성할 수 있게 해줍니다, 즉 Python 코드에서 동시성을 구현하기 위한 내장 도구입니다.

asyncio를 사용하면 한 번에 여러 작업을 동시에 수행하는 듯한 코드를 작성할 수 있지만, 실제로는 단일 스레드 상에서 비동기적으로 실행됩니다. 이러한 비동기 프로그래밍은 주로 I/O-bound 작업(입출력 대기 시간이 많은 작업)에 적합합니다. 예를 들어 파일 읽기/쓰기, 네트워크 요청 처리, DB 쿼리 등에서 asyncio를 사용하면 한 작업이 I/O를 기다리는 동안 다른 작업을 수행함으로써 효율을 높일 수 있습니다. 실제로 공식 문서에서도 asyncio는 I/O-bound와 고수준 네트워크 코드에 이상적으로 맞는다고 언급합니다. 반면 CPU 연산 위주의 작업에는 asyncio가 적합하지 않을 수 있는데, 이는 뒤에서 자세히 다루겠습니다. 정리하자면 asyncio는 Python에 내장된 “이벤트 루프 기반 비동기 I/O 라이브러리”입니다.

asyncio를 사용하면 개발자가 명시적으로 코루틴(coroutine)을 정의하고, 이벤트 루프를 통해 이들을 동시 실행하여 동시성을 달성할 수 있습니다. 이러한 디자인은 전통적인 스레드 기반 접근과 달리 협력적 멀티태스킹(cooperative multitasking)으로 이루어지며, 하나의 스레드안에서 여러 작업이 교대로 실행되는 방식입니다.

asnycio 가 Python 공식 라이브러리로 등장하기 전에는 Twisted, Gevent 같은 서드파티 비동기 라이브러리가 있었습니다.

Python에서 asyncio가 등장한 배경

Python에서 asyncio가 등장한 배경에는 언어 자체의 실행 모델과 I/O 병목 문제, 그리고 기존 스레드 모델의 한계 등이 있습니다. Python은 전통적으로 동시성 처리를 위한 기본 수단으로 멀티스레딩(threading)과 멀티프로세싱(multiprocessing)을 제공해 왔습니다. 그러나 두 접근법 모두 장단점이 있고, Python만의 제약도 존재합니다.

GIL과 싱글 스레드 중심 구조

Python 인터프리터(CPython 구현)에는 GIL(Global Interpreter Lock)이라는 락이 있습니다. GIL 때문에 한 시점에 하나의 스레드만 Python 바이트코드를 실행할 수 있게됩니다. 그 결과, 멀티스레드를 사용해도 CPU-bound 작업(순수 파이썬 연산이 많은 작업)의 경우 동시에 여러 스레드가 실행되지 못하고 하나씩 실행됩니다. 즉, CPU를 많이 쓰는 작업에서는 스레드를 늘려도 성능 향상이 거의 없고, 오히려 컨텍스트 스위칭 오버헤드로 약간 느려질 수도 있습니다.

Python 3.13 부터는 GIL 제약조건이 약화되었습니다. 하지만 이러한 변화가 바로 asyncio의 장점을 퇴색시키기는 어려울것으로 보입니다. 아래에도 나오지만 CPU 스케줄링의 원리에 따라 스레드가 I/O 작업을 처리할때 다른 스레드가 실행되기 때문에 GIL을 없애는 것이 Python 스레드의 I/O를 크게 개선시키는 것은 아닙니다. 다만 Python의 CPU Bound 작업 성능이 크게 개선될것으로 기대됩니다.

I/O-bound 작업의 병목

반면 I/O-bound 작업(파일/네트워크 입출력처럼 대기 시간이 큰 작업)의 경우, GIL 하에서도 스레드가 유용하긴 합니다. 예를 들어 하나의 스레드가 네트워크 응답을 기다리는 동안 GIL을 놓고 다른 스레드가 실행될 수 있기 때문입니다. 하지만 전통적인 스레드 기반 I/O 처리에는 다른 문제가 있습니다. 만약 수천 개의 동시 연결을 처리해야 한다면, 수천 개의 스레드를 생성하는 것은 큰 메모리 소모와 문맥 전환 비용을 초래합니다. Python 스레드는 운영체제 스레드로 구현되므로, 많은 양을 띄우면 OS 스케줄러 부하도 커지고 성능이 떨어집니다.

스레드 기반 모델의 복잡도

스레드를 사용하면 공유 자원 접근 동기화(락 등) 문제, 데드락, 경쟁조건 같은 복잡도가 따라옵니다. 특히 Python에서는 데이터 공유에 대한 동기화를 프로그래머가 신경써야 하고, 디버깅도 어려울 수 있습니다. I/O처리를 위해 단순히 동시성을 얻고 싶었는데, 이러한 부수적인 어려움이 있는 것이죠.

이러한 이유들로, Python 커뮤니티에서는 보다 가벼운 동시성 모델을 필요로 했습니다. 이벤트 루프 기반의 비동기 처리는 이를 해결할 대안으로 떠올랐습니다. 이미 Node.js나 JavaScript 런타임이 이벤트 루프 기반 비동기 처리를 활용하여 높은 동시성을 효율적으로 다루고 있었고, Python 생태계 내에서도 Twisted, Tornado 같은 이벤트 루프 라이브러리가 존재하고 있었습니다. 다만 Python 표준 라이브러리에는 통합된 솔루션이 없었죠. asyncio는 이러한 요구에 따라 Python 3.4 (2014년경)에 도입되었습니다.

Guido van Rossum이 주도한 Tulip프로젝트(PEP 3156)로부터 시작하여 표준화되었으며, 이후 Python 3.5에서 async/await 구문 지원(PEP 492)이 추가되면서 비로소 개발자가 쓰기 편한 형태의 비동기 프로그래밍이 가능해졌습니다. Python 3.7에서 asyncio.run() 함수가 도입되어 이벤트 루프 실행이 더욱 간편해지고, ayncio는 사실상 Python에서 비동기 프로그래밍의 표준이 되었습니다.

Python의 thread와의 차이점

위에서 말한것처럼 Tulip프로젝트 이전에는 Python에서 동시성은 스레드(thread)로 구현되곤 했습니다. asyncio의 코루틴 기반 동시성은 겉보기에는 스레드와 비슷하게 여러 작업을 동시에 처리하지만, 내부 동작과 성능 특성에서 차이가 있습니다. 주요 차이점을 하나씩 살펴보겠습니다.

동시성 구현 방식

스레드(Thread): 하나의 프로세스 내에서 여러 OS 스레드를 실행함으로써 동시성을 얻습니다. 운영체제가 CPU 시간을 여러 스레드에 분배해주므로, 스레드들은 선점형 멀티태스킹(preemptive multitasking)을 합니다. 각 스레드는 독립적인 호출 스택을 갖고 병렬로 실행되지만, Python의 경우 GIL로 인해 동일 시점에 하나의 스레드만 실행된다는 제약이 있습니다. 그래도 I/O 대기 중에는 자연스럽게 다른 스레드로 전환되므로 I/O-bound 작업에서 병렬성이 어느 정도 실현됩니다
asyncio(코루틴): 하나의 스레드 안에서 이벤트 루프(event loop)가 여러 코루틴(coroutine)을 협력적으로 스케줄링합니다. 각 코루틴은 await 키워드를 만나면 자신이 제어권을 양보하여 이벤트 루프가 다른 코루틴을 실행하도록 합니다. 따라서 asyncio의 동시성은 협력적 멀티태스킹(cooperative multitasking)입니다. OS가 강제로 태스크를 바꾸는 것이 아니라, 코루틴들이 스스로 양보하는 것이죠. 이러한 코루틴 전환은 결정적인 시점(주로 I/O 작업 전에 await할 때)에 일어나므로 오버헤드가 적고, 여러 코루틴이 하나의 호출 스택을 공유합니다. 결과적으로, 수천 개의 작업도 단일 스레드에서 효율적으로 관리할 수 있게 됩니다

성능과 리소스 사용

https://www.cs.uic.edu/~jbell/CourseNotes/OperatingSystems/4_Threads.html

스레드의 성능 및 오버헤드: Python에서 스레드는 I/O-bound 작업에 한해 유용하며, 이러한 경우 여러 스레드가 있으면 (GIL로 인해 한 번에 한 스레드씩 실행되지만) 한 스레드가 파일/네트워크 대기 시 다른 스레드가 실행되어 대기 시간을 숨길 수 있습니다. 하지만 스레드를 많이 생성하면 각 스레드는 스택 메모리를 차지하고, 컨텍스트 스위치에 비용이 듭니다.
asyncio의 성능 특성: asyncio는 수많은 작업을 동시 처리할 때도 메모리 오버헤드가 낮고(OS 스레드를 생성하지 않으므로), 컨텍스트 스위치가 필요할 때만 발생하여 매우 효율적입니다, 즉 스레드보다 적은 자원으로 높은 동시성을 달성합니다

GIL때문에 Python MultiThread 환경에서 CPU Bound 작업의 효율성이 낮아지는것은 언급했습니다. 하지만 그렇기 때문에 asyncio 를 이용한 CPU Bound 작업이 효율적이라고 생각하면 안됩니다. 하나의 코루틴이 CPU를 오래 점유하면(예: 복잡한 계산을 계속하면) await로 양보하기 전까지는 다른 코루틴이 실행되지 못하므로 전체 이벤트 루프가 정지된 것처럼 됩니다. 따라서 CPU 집약적인 일은 asyncio 안에서 하지 않고, 별도의 프로세스나 스레드로 offload 하거나(예: run_in_executor), 계산을 적절히 await로 나눠주어야 합니다.

코드 작성 및 구조

쓰레드 코드: 쓰레드를 사용하려면 각 작업을 함수로 만들고 threading.Thread(target=함수) 방식으로 실행합니다. 결과를 모으려면 join()으로 모든 쓰레드가 끝날 때까지 기다려야 하고, 작업 사이에 공유 데이터가 있다면 Lock 같은 동기화 도구도 직접 사용해야 합니다. 예를 들어 여러 URL을 다운로드하는 코드를 스레드로 짜면 다음과 같습니다:

import threading
import requests

urls = [ ... 리스트 ...]
results = []

def download(url):
    resp = requests.get(url)        # 네트워크 I/O (블로킹)
    results.append(resp.text)       # (공유 리스트 접근 - 동기화 필요할 수 있음)

threads = []
for url in urls:
    t = threading.Thread(target=download, args=(url,))
    t.start()
    threads.append(t)
for t in threads:
    t.join()  # 모든 스레드 작업 완료 대기
print(len(results), "개의 응답 수신 완료")

위 코드에서는 requests.get 호출이 블로킹 I/O이지만, 여러 스레드를 통해 동시 요청이 가능합니다. 다만 results.append는 공유 리스트 접근이라 스레드 간 경합이 발생할 수 있어서, 엄격히 따지면 Lock이 필요할 수도 있습니다. 이렇듯 스레드 코드는 동시성 처리를 비교적 자동으로 OS에 맡기지만, 공유상태 관리 등에서 주의가 필요합니다.

asyncio 코드: asyncio를 사용하면 우선 async def로 코루틴 함수를 정의하고, 그 안에서 await으로 비동기 작업을 호출합니다. 그리고 asyncio.run() 또는 이벤트 루프를 통해 이 코루틴들을 실행합니다. 예를 들어 위와 동일한 작업을 asyncio와 aiohttp로 구현하면 다음처럼 작성할 수 있습니다 (requests는 동기 라이브러리라 사용할 수 없고, aiohttp 같은 비동기 HTTP 클라이언트를 사용해야 합니다):

import asyncio
import aiohttp

urls = [ ... 리스트 ...]
results = []

async def download(url, session):
    async with session.get(url) as resp:   # 비동기 HTTP GET
        text = await resp.text()          # 결과 본문 읽기 (비동기 I/O)
        results.append(text)

async def main():
    async with aiohttp.ClientSession() as session:
        tasks = [asyncio.create_task(download(url, session)) for url in urls]
        await asyncio.gather(*tasks)      # 모든 다운로드 코루틴 병행 실행
    print(f"{len(results)}개의 응답 수신 완료")

asyncio.run(main())

위 asyncio 코드는 async with 문으로 HTTP 세션을 관리하고, asyncio.gather로 다수의 다운로드 작업을 동시에 실행합니다. await resp.text() 하는 동안 다른 task들이 실행되므로, 진짜 동시에 네트워크를 기다리고 처리하는 효과를 얻습니다. 또한 코드에서 공유 리스트 results에 append 하는 부분은 한 스레드 내에서 실행되므로 데이터 경합 없이 안전합니다. 전반적으로, asyncio 코드는 동기 코드처럼 순차적 구조를 유지하면서도, await 키워드 덕분에 자연스럽게 동시성을 부여합니다.

상황별 효율성과 선택 기준

I/O-bound 작업이 많은 서버나 애플리케이션에서는 asyncio가 빛을 발합니다. 예를 들어 웹 크롤러, 대용량 API 호출 처리, 채팅 서버 등 동시에 수천 개의 네트워크 I/O를 해야 하는 경우, 쓰레드로 구현하면 수천 스레드를 만들기 어려운 반면 asyncio는 한 이벤트 루프에서 수천 코루틴을 관리해낼 수 있습니다. 이러한 경우 asyncio가 더 가볍고 확장성 있게(scale) 동작합니다
CPU-bound 작업(예: 이미지 처리, 머신러닝 연산 등 계산 위주)은 asyncio로 처리하면 오히려 전체가 느려집니다. 이때는 오히려 멀티스레드보다 멀티프로세싱(또는 C 확장 모듈 활용)이 필요합니다. CPU 작업은 여러 코어에서 병렬로 돌려야 빨라지는데, Python 쓰레드는 GIL로 막혀 있으니, 차라리 멀티프로세싱으로 별도 프로세스를 돌리는것이 권장됩니다. 혹은 Python 3.11 이후 도입된 concurrent.futures.ThreadPoolExecutor/ProcessPoolExecutor를 적절히 쓰는 것이 나을 수 있습니다.

I/O 효율적이라고 알려진 node.js 와의 비교

https://nodejs.org/en/learn/asynchronous-work/event-loop-timers-and-nexttick

Python의 asyncio를 이야기할 때 자주 비교되는 대상이 Node.js입니다. Python은 Node.js의 이벤트 루프에서 영향을 받아 asyncio를 도입했다고 해도 과언이 아닙니다. 두 환경의 공통점과 차이를 살펴보겠습니다.

이벤트 루프와 싱글 스레드 아키텍처

공통점

Node.js와 Python asyncio 모두 이벤트 루프(event loop)가 핵심입니다. 이벤트 루프는 비동기 작업(네트워크 I/O, 타이머 등)의 완료 이벤트를 감지하고 등록된 콜백이나 코루틴을 실행하는 역할을 합니다. 또한 단일 스레드 기반이라는 점도 같습니다. Node.js의 JavaScript 코드 실행은 기본적으로 하나의 쓰레드에서 일어나고, asyncio도 하나의 메인 쓰레드에서 코루틴들을 처리합니다.

따라서 하나의 작업이 CPU를 너무 오래 점유하면 다른 작업이 지연된다는 점도 공통됩니다.

차이점

이벤트 루프의 시작과 관리 방식이 다릅니다. Node.js에서는 이벤트 루프가 런타임 자체에 내장되어 있습니다. 즉, Node.js로 실행되는 스크립트는 기본적으로 이벤트 루프 위에서 동작하며, 모든 I/O API가 비동기(논블로킹)로 설계되어 있습니다. 반면 Python에서는 이벤트 루프가 기본 활성화되어 있지 않고, asyncio를 사용할 때 명시적으로 asyncio.run() 등을 호출하여 이벤트 루프를 돌립니다.

Python은 필요할 때만 이벤트 루프를 “켜는” 온/오프 개념이고, Node.js는 항상 이벤트 루프가 동작하고 있는 형태라고 볼 수 있습니다.

또 다른 차이는 언어와 런타임의 역사에서 비롯됩니다. Node.js (그리고 브라우저의 JS)는 원래부터 비동기 작업을 콜백으로 처리해왔고, 이후 Promise와 async/await을 도입하여 개선했습니다. Python은 전통적으로 동기/블로킹 함수들이 많고, asyncio 도입 후에도 기존 라이브러리 상당수가 동기 방식으로 남아 있습니다. 그래서 Python 개발자는 동기 코드와 비동기 코드의 호환을 고민해야 하는 경우가 많습니다. (예: Django ORM은 동기이기 때문에 asyncio 웹 서버에서 사용할 때 별도의 쓰레드풀로 돌리는 등 추가 작업이 필요함)

성능 및 활용 차이

Node.js와 Python asyncio 중 어떤 것이 성능이 더 좋냐는 단순 비교는 어렵습니다. Node.js는 V8 엔진으로 구동되어 JavaScript가 JIT 컴파일된다는 이점이 있고, Python은 인터프리터라 단순 반복문 같은 CPU 작업은 JS보다 느릴 수 있습니다. 하지만 I/O 처리 성능은 양쪽 다 훌륭하며, 큰 차이가 없습니다. 둘 다 커널 비동기 I/O 기술(epoll 등)을 활용하고 최적화되어 있어 수만 개 소켓 연결 처리도 가능한 수준입니다.

차이가 있다면, Python asyncio는 선택적이므로, 상황에 따라 동기 코드와 혼용이 가능하고 필요시 멀티스레드/멀티프로세스로 전환이 가능합니다. Node.js는 기본적으로 싱글 스레드이므로, CPU-bound 처리에 한계를 느낄 땐 Cluster/fork나 Worker Threads 등을 사용해야 합니다.

결국 Node vs Python asyncio는 동시성 모델의 철학은 비슷하나, Python이 동기와 비동기 모델을 모두 포괄하는 유연함이 있고 Node는 일관되게 비동기라는 차별점이 있습니다.

asyncio 를 이용하는 방법 (기본 사용법 정리)

기본적인 코루틴 정의부터 asyncio.run()으로 실행, 여러 코루틴을 한꺼번에 실행하는 asyncio.gather(), 그리고 비동기 반복문(async for), 컨텍스트 매니저(async with), 마지막으로 코루틴에서의 yield 사용법까지 하나씩 예제 코드와 함께 정리해보겠습니다.

코루틴 정의와 asyncio.run()

코루틴(coroutine)은 Python에서 async/await 기능의 핵심 단위입니다. 코루틴은 async def로 정의된 함수로, 호출 시 즉시 실행되는 것이 아니라 코루틴 객체를 반환합니다. 이 코루틴 객체는 “미래에 실행될 작업”으로 생각하면 됩니다. 아래에 정의된 hello 라는 코루틴을 실제로 실행하려면 이벤트 루프가 필요합니다.

import asyncio

async def hello():
    print("Hello ...")
    await asyncio.sleep(1)       # 1초 비동기 대기 (다른 작업에 양보)
    print("... World!")

# 코루틴 함수를 호출해도 바로 실행되지 않음
coro = hello()  
print(coro)  
# <coroutine object hello at 0x...>

asyncio.run()은 이벤트 루프를 시작하고 주어진 코루틴을 최종 완료까지 실행해주는 편의 함수입니다. 보통 asyncio.run(main()) 형태로, 하나의 메인 코루틴을 실행하는 데 사용합니다. asyncio.run이 내부에서 이벤트 루프를 새로 만들어 main() 코루틴을 실행하고, 끝나면 루프를 정리해줍니다. Python 3.7+에서 권장되는 진입점 실행 방식이죠.

async def main():
    print("작업 시작")
    await hello()            # 위에서 정의한 코루틴을 await로 실행
    print("모든 작업 완료")

asyncio.run(main())         # 이벤트 루프를 열고 main 코루틴 실행

위 코드를 실행하면 main() 코루틴 내부에서 await hello()를 만나 hello() 코루틴으로 들어갔다가, hello가 1초 쉬는 동안 다시 main으로 복귀… 이런 식으로 동작하며, 결과적으로 "Hello ..." (즉시 출력) → 1초 대기 → "... World!" → "모든 작업 완료" 순으로 출력됩니다.

핵심은, await 키워드입니다. await는 코루틴의 실행을 일시 중지하고(await 키워드 뒤의 작업 완료를 기다린 뒤) 다시 재개시킵니다. await를 호출하면 현재 코루틴은 이벤트 루프에게 제어권을 넘기고, 그 사이에 다른 코루틴이 실행될 수 있습니다.

흐름을 정리하면 다음과 같습니다.

async def func(): ... : 코루틴 정의.
await something : 코루틴 내에서 다른 코루틴/작업이 끝날 때까지 non-blocking 대기.
asyncio.run(coro) : 코루틴 실행을 위해 이벤트 루프 생성 및 돌입.

동시에 여러 코루틴 실행: asyncio.gather()와 create_task()

await를 사용하면 순차적으로 코루틴을 실행하게 됩니다. 만약 여러 코루틴을 동시에 실행하고 싶다면 어떻게 해야 할까요? 대표적으로 asyncio.gather()와 asyncio.create_task()를 활용합니다.

asyncio.create_task(coro): 주어진 코루틴을 백그라운드 Task로 스케줄링합니다. 즉, 즉시 해당 코루틴 실행을 시작하고, Task 객체를 반환합니다. Task는 미래에 결과를 담게 되는 Future의 한 종류라고 볼 수 있습니다.
asyncio.gather(*coros): 여러 코루틴들을 동시에 실행하고 모두 완료될 때까지 기다린 뒤 결과를 한꺼번에 반환합니다. 내부적으로 각 코루틴을 Task로 만들고 추적합니다.

3개의 작업을 동시에 실행하여 실행 시간을 단축해보겠습니다. 각 작업은 1초씩 걸린다고 가정합니다:

import asyncio
import time

async def work(id):
    print(f"작업 {id} 시작")
    await asyncio.sleep(1)          # 1초짜리 비동기 작업 (예: 네트워크 요청)
    print(f"작업 {id} 완료")
    return id

async def main():
    start = time.time()
    # 방법 1: asyncio.gather로 동시에 실행
    results = await asyncio.gather(work(1), work(2), work(3))
    end = time.time()
    print("동시 실행 결과:", results)
    print(f"총 실행 시간: {end - start:.2f}초")

asyncio.run(main())

다음과 같은 결과가 출력됩니다.

작업 1 시작
작업 2 시작
작업 3 시작
작업 1 완료
작업 2 완료
작업 3 완료
동시 실행 결과: [1, 2, 3]
총 실행 시간: 1.00초 (내외)

asyncio.gather를 사용하지 않고, create_task를 사용해서 다음과 같이 할 수 있습니다:

async def main():
    start = time.time()
    # 방법 2: create_task를 사용하여 태스크 생성 후 개별 await
    task1 = asyncio.create_task(work(1))
    task2 = asyncio.create_task(work(2))
    task3 = asyncio.create_task(work(3))
    # 이 시점에서 작업들이 백그라운드로 진행 중
    result1 = await task1
    result2 = await task2
    result3 = await task3
    end = time.time()
    print("동시 실행 결과:", [result1, result2, result3])
    print(f"총 실행 시간: {end - start:.2f}초")

create_task로 태스크를 생성하면 즉시 작업이 시작되므로, 바로 await를 하지 않고 있다면 다른 코드도 동시에 실행될 수 있습니다. 위 예에서 task1 생성 후 task2를 생성하는 동안도 task1의 작업은 진행 중입니다. 결국 await task1 등을 통해 결과를 모을 때까지 3개 작업이 병행되는 것이죠. asyncio.gather는 이런 패턴을 한 줄로 축약한 것이라 볼 수 있습니다.

에러 처리

asyncio.gather는 기본적으로 내부 태스크 중 하나에서 예외가 발생하면 즉시 예외를 전파하고 다른 태스크도 취소합니다. 반면 return_exceptions=True 옵션을 주면, 예외도 결과로 모아서 반환해줍니다. 일반적으로는 예외 처리를 개별 코루틴 내에서 하거나, gather 바깥에서 try/except로 묶어 처리합니다.

asyncio.wait

gather와 비슷한 asyncio.wait도 있는데, 이건 태스크 집합을 주면 완료된 것과 안 된 것을 구분해서 돌려주는 저수준 함수입니다. 대부분의 경우 gather가 더 편리하고, Python 공식문서에서도 저수준 API를 직접 다루는 것을 권장하지 않기 때문에 깊이 다루지 않겠습니다.

비동기 이터레이션: async for (비동기 제너레이터)

async for는 비동기 이터레이터/제너레이터와 함께 사용되는 구문입니다. 일반적인 for문은 이터레이터의 __iter__/__next__를 호출해 동작하는데, 비동기 이터레이터는 __anext__라는 비동기(next) 메서드를 가집니다. 그리고 async for 루프는 이 __anext__가 반환하는 코루틴을 await하면서 루프를 돕니다. 말이 어렵지만, 실제로 언제 쓰이냐 하면

파일이나 소켓에서 비동기적으로 한 줄씩 읽어들일 때 (aiofiles나 asyncio.StreamReader 등은 async iterator를 지원하여 async for line in reader 형태로 쓸 수 있음).
대기 시간이 있는 데이터를 스트리밍 받을 때 (예: 비동기 발생 이벤트 소비)

아울러 비동기 제너레이터(async generator)도 있습니다. 이는 async def 함수 안에서 yield 키워드를 써서 비동기적으로 값을 순차 생성하는 함수입니다. PEP 525에 도입된 기능으로, 이러한 함수는 호출 시 AsyncGenerator 객체를 반환하며, 이는 앞서 말한 비동기 이터레이터 프로토콜을 따릅니다. 비동기 제너레이터는 async for로 순회해야 합니다.

간단한 비동기 제너레이터와 async for 사용법을 보겠습니다

# 비동기 제너레이터 함수 정의
async def async_count(stop):
    for i in range(stop):
        await asyncio.sleep(1)   # 매 반복마다 1초 비동기 대기
        yield i                 # 값을 산출 (yield) - async generator

async def main():
    # async for를 사용하여 비동기 제너레이터로부터 값 받기
    async for num in async_count(3):
        print(f"{num} 출력 (시간: {time.time():.0f})")

asyncio.run(main())

각 숫자가 1초 간격으로 출력되는 것을 볼 수 있습니다. async_count 함수는 매 loop마다 await asyncio.sleep(1)으로 1초 쉬고 yield i로 값을 내보냅니다. 이처럼 async def 내에서 yield를 쓰면 일반 함수의 제너레이터와 달리 Async Generator가 됩니다. 그리고 async for num in async_count(3) 구문이 내부적으로 다음과 같이 동작합니다. 개발자는 async for 구문만 써주면 이런 복잡한 처리가 자동으로 이루어집니다.

iterator = async_count(3).__aiter__()
while True:
    try:
        num = await iterator.__anext__()
    except StopAsyncIteration:
        break
    # loop body
    print(num)

비동기 컨텍스트 매니저: async with

async with 구문은 비동기 컨텍스트 매니저를 사용할 때 쓰입니다. 일반적인 with 문은 객체의 __enter__와 __exit__를 호출해서 자원 관리를 하는데, 비동기 상황에서는 __aenter__와 __aexit__라는 비동기 메서드를 사용합니다. 예를 들어, asyncio.Lock은 비동기 락 객체인데, 이것을 async with로 획득/해제할 수 있습니다. 또 aiohttp의 ClientSession이나 데이터베이스의 AsyncSession 등도 async with로 열고 닫는 처리를 합니다.

참고

Python document, asyncio: https://docs.python.org/ko/3/library/asyncio.html

Python document, corruines and task: https://docs.python.org/3/library/asyncio-task.html#coroutine

Python document, eventloop: https://docs.python.org/3/library/asyncio-eventloop.html

Python Asyncio vs Threading: https://www.geeksforgeeks.org/asyncio-vs-threading-in-python/

Async IO in Python: A Complete Walkthrough: https://www.geeksforgeeks.org/asyncio-vs-threading-in-python/

Python의 Type System

개발프로브 — Thu, 20 Mar 2025 14:42:52 +0900

gRPC에 대해서 알아보던중 pyi 파일을 처음 보았고, 이 파일이 Python Type System 중 하나인 stub file 이라는 것을 알게되었습니다. stub file 이 무엇인지 궁금해졌고, 이 궁금증은 Python의 Type System 전체로 확장되었습니다. 전반적인 내용을 정리해보고자 합니다. Python 공식문서중 TypeHint Guide에서 많은 내용을 참고했습니다.

왜 Type System이 필요한가?

우선 프로그래밍 언어를 구분할때 다음과 같은 기준이 있습니다.

타입 캐스팅이 자유로운지에 따라 강 타입/약 타입
컴파일시 타입을 체크하는지에 따라 정적 타입/동적 타입

이러한 기준에서 봤을때 Python은 약 타입이자, 동적 타이핑 언어입니다. 즉 명시적인 타입 캐스팅 없이 타입 변환이 가능하며, JIT 컴파일을 하긴 하지만 기본적으로 Interpreter 를 통해 동작하기 때문에 런타임에 타입을 체크하는 동적 타입 언어인 것입니다.

이러한 Python에게 Type System 이 필요한 이유는 다음의 이점이 있기 때문입니다.

1. 안정성과 버그 조기 발견:
동적 타이핑은 실행 시점에서 타입 에러를 발견하기 때문에, 큰 규모의 프로젝트나 복잡한 코드에서는 예기치 않은 버그가 발생할 위험이 큽니다. 정적 타입 힌트를 도입하면 코드 작성 시점에서 오류를 미리 잡아내어 안정성을 높일 수 있습니다.

2. 코드 가독성과 문서화:
타입 주석은 함수와 클래스의 의도를 명확하게 해 주며, 이를 통해 코드의 이해도가 향상됩니다. 이는 협업 환경에서 특히 중요한 역할을 합니다.

3. 개발 도구와의 시너지 효과:
타입 힌트를 활용하면 IDE 및 정적 분석 도구(예: mypy, Pyright)와의 연동이 원활해져 자동완성, 리팩토링, 코드 탐색 등에서 생산성을 크게 향상시킬 수 있습니다.

그럼에도 불구하고, Python은 정적 타입 검사를 강제하지 않는다.

정적 타입 힌트가 제공하는 여러 이점에도 불구하고, Python은 여전히 약 타입(dynamic typing) 언어로 남아있습니다. Python 공식 문서에서는 다양한 이유를 들고 있지만 짧게 정리하자면 다음과 같습니다:

Python은 처음부터 동적 타이핑 언어였고, 이 언어를 사용하는 개발자에게 정적 타입 검사를 강제할 순 없다. 타입 어노테이션자체가 가독성을 해치는 경우도 존재하며, 동적 프레임워크의 특성상 정적 타입을 지정하기 어려울 수 있다. 또한 Hyrum's Law에 따르면 타입 어노테이션은 복잡해지거나 Any 로 치환될 가능성이 있다.

Type System How to

이제는 왜 Type System이 필요한지, 그럼에도 불구하고 왜 정적 타입을 강제하지 않는지 알게되었습니다. 그렇다면 Python에서는 Type System을 이용하는 방법을 알아보겠습니다.

간단한 Typing

Python의 typing 모듈을 이용하면 함수 인자, 반환값 등 코드의 주요 부분에 타입 정보를 추가할 수 있습니다. 이는 코드의 의도를 명확히 하고, 정적 분석 도구(예: mypy)를 통한 오류 검출에 도움을 줍니다.

def greet(name: str) -> str:
    return f"Hello, {name}!"

# 사용 예시
print(greet("Alice"))

name: str 은 매개변수 name이 문자열임을 명시합니다.
-> str 은 함수가 문자열을 반환함을 나타냅니다.

Generic Type

Generic Type은 여러 타입에 대해 동일한 로직을 재사용할 수 있게 해줍니다.

TypeVar와 Generic을 사용하여 타입을 일반화함으로써, 보다 유연하면서도 타입 안전한 코드를 작성할 수 있습니다.

from typing import TypeVar, Generic, List

T = TypeVar('T')

class Stack(Generic[T]):
    def __init__(self) -> None:
        self._items: List[T] = []
    
    def push(self, item: T) -> None:
        self._items.append(item)
    
    def pop(self) -> T:
        return self._items.pop()

# 정수형 스택 예시
int_stack = Stack[int]()
int_stack.push(10)
print(int_stack.pop())

# 문자열 스택 예시
str_stack = Stack[str]()
str_stack.push("hello")
print(str_stack.pop())

T = TypeVar('T')를 통해 임의의 타입 변수를 선언합니다.
Stack(Generic[T]) 클래스는 다양한 타입의 데이터를 저장할 수 있는 스택을 구현합니다.
각각의 스택 인스턴스는 타입 인자를 통해 정해진 타입만을 다루게 됩니다.

Stub File

Stub File(.pyi 파일)은 기존 코드와 별도로 타입 정보를 제공하는 파일입니다. 이를 통해 라이브러리나 기존 코드베이스에 직접 손대지 않고도 정적 타입 정보를 추가할 수 있어, 점진적 도입에 매우 유용합니다. 특히 외부 라이브러리(external library)의 경우, 원본 코드를 수정할 수 없거나 수정이 어려운 상황에서 Stub File을 이용하여 타입 정보를 보완할 수 있습니다. 이러한 이점 때문에 Python에서 gRPC를 활용할때 사용됩니다.

mylib.py:

def add(a, b):
    return a + b

mylib.pyi:

def add(a: int, b: int) -> int: ...

실제 코드(mylib.py)는 타입 정보 없이 동작하지만, 타입 스텁 파일(mylib.pyi)은 정적 타입 검사기에게 함수 add의 인자와 반환값이 모두 정수임을 알려줍니다.
외부 라이브러리의 경우, 해당 라이브러리가 타입 정보를 포함하고 있지 않다면, 별도의 Stub File을 제공하여 사용자들이 정적 타입 검사 도구를 통해 타입 안전성을 확보할 수 있도록 돕습니다.
예를 들어, typeshed 프로젝트는 Python의 표준 라이브러리와 다양한 외부 라이브러리의 타입 정보를 수집하여 관리하며, 이를 통해 많은 라이브러리들이 정적 타입 검사를 활용할 수 있게 합니다.

참고

Python Document, TypeSystem Guides: https://typing.python.org/en/latest/guides/index.html

Python Docuemnt,Stubfile: https://typing.python.org/en/latest/spec/distributing.html#stub-files

Python Document, Writing and Maintaining: https://typing.python.org/en/latest/guides/writing_stubs.html

pep TypeHints: https://peps.python.org/pep-0484

Python 3.13 JIT: https://docs.python.org/3/whatsnew/3.13.html#an-experimental-just-in-time-jit-compiler

Python gRPC (2) - 기본 구조와 python 구현

개발프로브 — Sat, 8 Mar 2025 22:01:47 +0900

지난글에서 RPC (gRPC) 를 선택한 이유를 알아봤습니다. 이제는 python 에서 어떻게 gRPC 를 사용할 수 있는지 공유하겠습니다.

.proto 파일

RPC는 엄격한 규칙을 따르기 때문에 IDL(Interface Definication Language)이 제공됩니다. 특히 구글에서 만들고 배포하는 gRPC는 관련 문서와 tool이 잘 구비되어 있어서 구현하기 용이합니다. gRPC를 구현하기 위해 가장 먼저 해야할 것은 서버와 메시지 규약을 정하는것입니다. 이러한 규약은 .proto 파일에 정의됩니다.

Service 와 Message

gRPC는 Service를 통해서 호출될 함수를 정의하고, Message 를 통해서 호출 파라미터, 응답 값을 정의합니다.

아래 예제는 protobuf bestpractice 1-1-1 rule 에 따라 message 별로 파일을 나누고, 각 message 파일을 service 파일에서 import 하여 정의하고 있습니다:

syntax = "proto3";

package hello;

import message/hello_request.proto
import message/hello_response.proto

service HelloService {
  rpc SayHello (HelloRequest) returns (HelloResponse);
}

syntax = "proto3";

package hello;

message HelloRequest {
  string greeting = 1;
  // data_type | filed_name | tag_number
}

syntax = "proto3";

package hello;

message HelloResponse {
  string reply = 1;
  // data_type | filed_name | tag_number  
}

위에서 말한걸 다시 정리하자면,

service: 클라이언트가 호출할 수 있는 원격 메서드 집합
message: 클라이언트와 서버 간에 주고받는 데이터 구조를 정의하는 개념

하지만 package, 그리고 field 옆에 있는 숫자는 무엇인지 설명되지 않았습니다. protocol buffers 문서에서 그 답을 얻어보겠습니다.

Protocol buffers

우선 protocol buffer 란 gRPC 에서 활용되는 IDL이면서 하나의 데이터 직렬화 매커니즘입니다. 줄여서 protobuf, 혹은 pb라고도 합니다. 하나의 언어체계인만큼 위에서 언급된 package, tag number(filed 옆 숫자) 는 pb 만의 특수한 약속입니다. pb 를 사용하면서 알아두면 유용한 개념을 정리하겠습니다.

package

namespace 를 정의합니다. 동일한 이름의 Service, Message 일지라도 namespace 가 다르면 gRPC 내부적으로 다르게 취급됩니다.

tag number

필드를 식별하는 고유한 식별자입니다. json 이 데이터 타입을 정의할때 전체 필드이름을 사용하는것과 달리 pb 는 이 tag number 를 이용해서 필드를 특정합니다. 덕분에 json에 비해 더 경량화된 데이터 구조를 가질 수 있게 됩니다.

tag number 를 기준으로 필드를 구분하기 때문에 동일한 tag number 에 대해서 다른 필드를 정의하면 예상치 못한 동작을 초리할 수 있습니다. 즉, 한번 폐기된 tag number 를 재사용하는 것은 엄격히 금지됩니다.

데이터 타입

위의 예제에서는 오로지 string 타입만 나와있지만, gRPC 는 다양한 데이터 타입을 지원합니다. 모든 내용을 블로그로 옮겨오는것은 비효율적이기 때문에 pb의 scala type 에 대한 링크를 남겨두겠습니다.

gRPC 의 구조

위 그림은 구글에서 제공하는 gRPC의 도식입니다. gRPC Server 에서 각 gRPC Stub 과 Proto Request, Response 를 주고 받는것을 알 수 있습니다. 이제 각각이 무엇인지 간단히 정리하겠습니다.

server

gRPC 서버는 클라이언트가 호출할 수 있는 원격 프로시저(RPC)를 정의하고 처리하는 역할을 합니다.
proto 파일에서 정의한 service를 구현하여 요청을 처리하고 응답을 반환합니다.
보통 멀티스레딩을 지원하는 고성능 서버로 동작하며, HTTP/2 기반의 스트리밍을 사용할 수 있습니다.

stub

Stub(스텁)은 클라이언트와 서버 간의 gRPC 요청을 중개하는 역할을 합니다.
server와 stub은 동일한, 혹은 적어도 이전버전과 호환되는(Backwards-compatibility) proto 파일을 기반으로 통신해야합니다.
클라이언트에서 서버를 호출하는 객체이며, 서버의 원격 메서드를 로컬 메서드처럼 호출할 수 있도록 합니다.
Stub에는 Blocking(동기), Non-Blocking(비동기) 두 가지 유형이 있습니다.

channel

Channel(채널)은 클라이언트와 서버 간의 연결을 담당하는 객체입니다.
gRPC는 HTTP/2 기반이므로, 하나의 Channel에서 여러 개의 gRPC 호출을 수행할 수 있습니다.
보통 TLS(보안) 또는 플레인 텍스트(일반 HTTP/2) 연결을 설정할 수 있습니다.

Python과 gRPC

이제 proto 파일의 존재와, server, stub 그리고 channel 의 개념을 알았습니다. 이제는 Python에서 gRPC 서버를 구현하는 방법과 Python만의 특징을 살펴보겠습니다.

Python의 gRPC 특징

Python에서는 grpcio-tools를 사용하여 proto 파일을 컴파일할 필요 없이 런타임에 동적으로 스텁을 생성할 수 있습니다.
Python의 asyncio를 활용한 비동기 gRPC 서버/클라이언트를 쉽게 구현할 수 있습니다. 반면 Stream을 사용하는 것은 권장되지 않습니다.
Python에서는 다른 언어보다 더 간결하게 gRPC를 구현할 수 있으며, 클래스를 직접 상속받아 서비스 구현을 할 수 있습니다. 또한 Reflection API를 지원하기 때문에 gRPC 서비스를 동적으로 사용할 수 있습니다.

요약하자면, Python에서 gRPC를 이용하는 것은 쉽지만 Stream 을 이용하기 보다는 asyncio 를 직접 이용하는 방안을 채택해야합니다.

Python gRPC 서버 구축 (gRPC Tools 활용)

지금까지 정리한 개념을 통해 python 코드에서 gRPC를 세팅하려면 어떻게 해야하는지 명확해진것 같습니다.

proto 파일이 있어야하며
grcpio_tools 을 이용하여 python 에서 gRPC를 구현할떄 필요한 protobuf 파일들을 생성합니다.
protobuf 파일을 기반으로 gRPC server 가 정의되어야 하고
protobuf 파일을 기반으로 gRPC stub 을 클라이언트가 활용해야합니다.

전체 완성 코드는 github 에서 확인할 수 있습니다.

1. proto 파일 작성

첫번째로 proto 파일을 만들어보겠습니다. 아래와 같은 구조로 proto 파일은 service 와 message 를 분리해둘겁니다.

.
├── proto
│   ├── member_service.proto
│   └── message
│       ├── member_request.proto
│       └── member_response.proto

각각의 message 를 먼저 만들고,

syntax = "proto3";

package member;


message MemberRequest {
    string member_id = 1;
}

syntax = "proto3";

package member;


message MemberResponse {
    string member_id = 1;
    string member_name = 2;
}

service 를 정의해줍니다.

syntax = "proto3";

package member;

import "message/member_request.proto";
import "message/member_response.proto";

service MemberService {
    rpc GetMember (MemberRequest) returns (MemberResponse);
}

2. grpcio_tools 활용

grpcio_tools 는 정의해둔 proto 파일을 통해 python에서 활용 가능한 protobuf 파일을 만들어줍니다. 이때 참 주의할 사항이 많습니다.

service 파일이 참조하는 message 파일의 구조가 python 파일 구조에도 그대로 반영되어야 합니다.
생성된 protobuf 파이썬 파일의 위치에 따라 활용 의도가 달라지며, python 실행 컨텍스트로 고려되어야 합니다.

저는 이번 예제에서 app 밑에 pb 를 두는 구조를 선택했습니다.

app 에서 정의한 기능(비즈니스 로직, DB 연결) 을 공유하려면 app 밑에서 grpc 를 정의하는게 유리하다고 생각했습니다.
또한 pb 밑에 message 디렉터리를 두어서 service 가 message 를 참조하는 구조를 그대로 모방하도록 했습니다.

.
├── proto
│   ├── member_service.proto
│   └── message
│       ├── member_request.proto
│       └── member_response.proto
└── services
    ├── board_service
    │   ├── app
    │   │   ├── main.py
    │   │   └── pb
    │   │       └── message
    │   ├── proto.sh
    └── member_service
        ├── app
        │   ├── grpc_server.py
        │   ├── main.py
        │   └── pb
        │       └── message

이제는 grpc_tools 를 이용해보겠습니다. 우선 pip install grpc_tools 를 해주세요.

그리고 각 서비스마다 다음의 스크립트를 만들어두고, 실행하겠습니다. service 와 message 를 따로따로 긁어와줍니다.

#!/bin/bash

set -e

python -m grpc_tools.protoc \
  -I=../../proto \
  --python_out=./app/pb \
  --grpc_python_out=./app/pb \
  --pyi_out=./app/pb \
  ../../proto/member_service.proto

python -m grpc_tools.protoc \
  -I=../../proto \
  --python_out=./app/pb \
  --grpc_python_out=./app/pb \
  --pyi_out=./app/pb \
  ../../proto/message/*.proto

이 스크립트에 대해서 러프하게 설명하자면,

입력 경로 지정(-I):
- -I=../../proto 옵션은 proto 파일들이 위치한 디렉토리를 지정합니다.
Python 메시지 파일 생성(--python_out):
- 이 옵션은 proto 파일의 메시지 정의를 기반으로 Python 코드를 생성하여 지정된 경로(여기서는 ./app/pb)에 <proto파일명>_pb2.py 파일을 생성합니다.
gRPC 관련 파일 생성(--grpc_python_out):
- 이 옵션은 gRPC 서비스 인터페이스에 대한 코드를 생성하여 <proto파일명>_pb2_grpc.py 파일을 같은 출력 경로에 생성합니다.
Python 타입 스텁 생성(--pyi_out):
- 이 옵션은 생성된 메시지에 대한 정적 타입 검사용 stub 파일 (.pyi)을 생성합니다. 이를 통해 Python 코드 작성 시 타입 힌트를 활용할 수 있습니다.
- 개인적으로 이게 정말 중요합니다. gRPC 타입 힌트 유무에 따라 개발 난이도와 런타임 오류 빈도가 많이 달라질겁니다.
마지막 인자로 proto 파일 지정:
- 스크립트의 마지막 부분에서 실제로 컴파일할 proto 파일들을 지정합니다.

더 자세한 설명은 공식문서에서 확인하실 수 있습니다.

이제는 pb 밑에 다양한 파일들이 생성되었지만, 대표적으로 3가지만 살펴보겠습니다.

member_service_pb2.py
member_service_pb2_grpc.py
member_response_pb.pyi

member_service_pb2 와 member_service_pb2_grpc 의 차이는 뭘까요?

직관적으로 pb2는 protocol buffer 를 위한 python 구현체일것이고, grpc는 그러한 pb2를 이용한 grpc 구현체일것이라고 알 수 있을 것입니다. 조금만 더 파고들어서 message 내부를 보면 더 명확해지죠. 이러한 직관 말고 내부 코드를 조금 살펴보겠습니다.

member_service_pb2

# ...

_sym_db = _symbol_database.Default()


from message import member_request_pb2 as message_dot_member__request__pb2
from message import member_response_pb2 as message_dot_member__response__pb2


DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x14member_service.proto\x12\x06member\x1a\x1cmessage/member_request.proto\x1a\x1dmessage/member_response.proto2K\n\rMemberService\x12:\n\tGetMember\x12\x15.member.MemberRequest\x1a\x16.member.MemberResponseb\x06proto3')

_globals = globals()
_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'member_service_pb2', _globals)
if not _descriptor._USE_C_DESCRIPTORS:
  DESCRIPTOR._loaded_options = None
  _globals['_MEMBERSERVICE']._serialized_start=93
  _globals['_MEMBERSERVICE']._serialized_end=168
# @@protoc_insertion_point(module_scope)

다소 생소한 개념이 보입니다. 얼추 보았을떄 pb 파이썬 구현체에서는 descriptor가 중요한것 같습니다. 다소 생소한 개념이기 때문에 엄밀하게 정의하고 세부 동작을 파악하는 일은 다음으로 미루고 우선 직관적으로 이해하고 넘어가겠습니다.

pb에서 descriptior는 pb에서 정의된 데이터 타입에 대한 메타데이터를 설명하는 역할을 합니다.

그리고 member_service_pb2 파일은 descriptor pool 에 정의된 proto를 추가하고 (AddSerializedFile), 이러한 pool 을 전역적으로 build 하는 역할을 한다고 이해할 수 있습니다.

이러한 작업을 통해 proto로 정의된 메타데이터가 python에서 다룰 수 있는 무언가가 되는것이라고 이해하면 되겠습니다.

member_service_pb2_grpc

# ...

class MemberServiceStub(object):
    """Missing associated documentation comment in .proto file."""

    def __init__(self, channel):
        """Constructor.

        Args:
            channel: A grpc.Channel.
        """
        self.GetMember = channel.unary_unary(
                '/member.MemberService/GetMember',
                request_serializer=message_dot_member__request__pb2.MemberRequest.SerializeToString,
                response_deserializer=message_dot_member__response__pb2.MemberResponse.FromString,
                _registered_method=True)


class MemberServiceServicer(object):
    """Missing associated documentation comment in .proto file."""

    def GetMember(self, request, context):
        """Missing associated documentation comment in .proto file."""
        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
        context.set_details('Method not implemented!')
        raise NotImplementedError('Method not implemented!')


def add_MemberServiceServicer_to_server(servicer, server):
    rpc_method_handlers = {
            'GetMember': grpc.unary_unary_rpc_method_handler(
                    servicer.GetMember,
                    request_deserializer=message_dot_member__request__pb2.MemberRequest.FromString,
                    response_serializer=message_dot_member__response__pb2.MemberResponse.SerializeToString,
            ),
    }
    generic_handler = grpc.method_handlers_generic_handler(
            'member.MemberService', rpc_method_handlers)
    server.add_generic_rpc_handlers((generic_handler,))
    server.add_registered_method_handlers('member.MemberService', rpc_method_handlers)

grpc 영역으로 넘어오니 조금 익숙한 개념이 보입니다. servicer, channel, stub 이 그것입니다. 이 글의 목적이 python에서 grpc를 사용하는 기본적인 방법을 공유하는 것이기 때문에 여기서도 직관적으로 이해하고 넘어가겠습니다.

MemberServiceStub은 proto 파일에서 정의한 service를 끌어다 쓰는 클라이언트쪽에서 사용할 것이고, 각 요청을 클래스 수준에서 멤버변수로 갖게 된다는것을 알 수 있습니다.(특히 여기서는 단항요청으로 구성되어 있습니다.)

MemberServiceServicer 는 proto 파일에서 정의한 service 를 정의하는 서버쪽에서 사용할 것이고, 각 요청이 함수로 정의되어 있다는 것을 알 수 있습니다. context 파라미터를 이용하여 마치 HTTP 에서 상태코드를 정의하듯이 활용할 수 있습니다,

add_MemberServiceServicer_to_server 함수를 보면, rpc 핸들러를 정의하고, 이를 등록하는 과정이 있음을 알 수 있습니다. 이상을 통해 gRPC 서버를 정의할때 활용되어야 한다는 것을 알 수 있습니다.

단순히 생각하면 Servicer 에서 해당 함수를 고쳐서 grpc 서버 기능을 구현하고 싶지만 protoc에 의해 생성된 코드를 임의로 고치는 것은 권장되지 않습니다.

member_response_pb.pyi

이 파일은 stub file 이라고 합니다. stub file 덕분에 gRPC Request와 Response 를 일반 Python 클래스를 다루듯이 사용할수 있게 됩니다.

from google.protobuf import descriptor as _descriptor
from google.protobuf import message as _message
from typing import ClassVar as _ClassVar, Optional as _Optional

DESCRIPTOR: _descriptor.FileDescriptor

class MemberResponse(_message.Message):
    __slots__ = ("member_id", "member_name")
    MEMBER_ID_FIELD_NUMBER: _ClassVar[int]
    MEMBER_NAME_FIELD_NUMBER: _ClassVar[int]
    member_id: str
    member_name: str
    def __init__(self, member_id: _Optional[str] = ..., member_name: _Optional[str] = ...) -> None: ...

3. gRPC 서버 정의

이제는 member_service_pb2_grpc 를 활용하여 member_service 에서 grpc_server.py 를 만드는 방법을 공유하겠습니다. MemberServiceServicer 를 확장하는 클래스를 정의하고, GetMember 메서드를 오버라이딩합니다. 이때 serer 를 grpc.aio.server() 로 정의하여 python에서 steram 을 사용할경우 발생하는 성능상 불이익을 완화합니다.

import asyncio
import grpc
import uuid

from sqlalchemy import select

from app.pb import member_service_pb2_grpc
from app.pb.message import member_request_pb2, member_response_pb2
from app.pb.member_service_pb2_grpc import MemberServiceServicer
from app.database.connection import async_session, engine
from app.database.model import MemberModel, BaseModelDeclarative

class MemberServiceServicerImpl(MemberServiceServicer):
    async def GetMember(self, request: member_request_pb2.MemberRequest, context):
        async with async_session() as db:
            result = await db.execute(
                select(MemberModel).where(MemberModel.id == uuid.UUID(request.member_id))
            )
            member = result.scalars().first()

            if not member:
                context.set_code(grpc.StatusCode.NOT_FOUND)
                context.set_details("Member not found")
                return member_response_pb2.MemberResponse()

        return member_response_pb2.MemberResponse(
            member_id=str(member.id),
            member_name=member.name
        )

async def init_db():
    async with engine.begin() as conn:
        await conn.run_sync(BaseModelDeclarative.metadata.create_all)

async def serve():
    await init_db()

    server = grpc.aio.server()
    member_service_pb2_grpc.add_MemberServiceServicer_to_server(MemberServiceServicerImpl(), server)
    listen_addr = "[::]:50051"
    server.add_insecure_port(listen_addr)
    await server.start()
    await server.wait_for_termination()


if __name__ == "__main__":
    asyncio.run(serve())

4. gRPC 클라이언트 정의

client 를 정의하는건 더 간단합니다.

channel 을 만들때에서 grpc.aio 를 이용하여 비동기적으로 grpc 서버를 호출할 수 있도록 하였습니다.

member-service:50051 로 채널의 연결점을 정의한건, github 코드에서 docker-compose 설정에 기반한것으로 언제든 바뀔 수 있습니다.

from uuid import UUID

import grpc
from google.protobuf.json_format import MessageToDict

from app.pb import member_service_pb2_grpc
from app.pb.message import member_request_pb2

channel = grpc.aio.insecure_channel("member-service:50051")
stub = member_service_pb2_grpc.MemberServiceStub(channel)


class MemberServiceClient:
    @staticmethod
    async def get_member_by(member_id: UUID):
        member_response = await stub.GetMember(member_request_pb2.MemberRequest(member_id=str(member_id)))
        return MessageToDict(member_response, preserving_proto_field_name=True)

이상의 작업을 완료한 뒤 테스트를 해보면 gRPC 통신이 잘 동작하는 것을 알 수 있습니다.

참고

gRPC core concepts: https://grpc.io/docs/what-is-grpc/core-concepts/

grpc-tools: https://grpc.io/docs/languages/python/quickstart/#grpc-tools

Protocol buffers overview: https://protobuf.dev/overview/

Protocol buffers dos-donts: https://protobuf.dev/best-practices/dos-donts/

Protocol buffers python generatede code: https://protobuf.dev/reference/python/python-generated/

what is descriptors by buf.build: https://buf.build/docs/reference/descriptors/

Python gRPC (1) - 왜 gRPC 를 선택했나

개발프로브 — Sat, 8 Mar 2025 22:00:33 +0900

MSA를 구현할때 각 서비스별로 분리된 데이터베이스를 관리합니다. 이 상황에서 화면으로 전달될 데이터가 하나의 서비스에 국한될 가능성은 거의 없을 것입니다. 이때 BFF 와 같이 각 서비스와 통신하여 데이터를 모아주는 역할을 하는 서비스가 존재하게 됩니다.

이때 데이터를 동기화하는 다양한 패턴이 있지만, 실시간으로 데이터를 동기화해야하는 경우에는 gRPC 가 적합하다 판단했습니다. 이 글에서는 왜 그렇게 생각했는지 정리했습니다.

MSA 에서 데이터 동기화 패턴

Chris Richardson의 Microservice Pattern에 따르면 <데이터 동기화 패턴> 이라는 용어가 적합하지 않을 수 있습니다. 이 글에서 말하는 데이터 동기화 패턴이란 마이크로 서비스 환경에서 사용자의 요구에 따라 일관성있는 데이터를 전달하기 위한 패턴으로 정의하겠습니다. 그리고 데이터 동기화 패턴에는 다음의 것들이 있습니다:

1. API 기반 동기화

서비스들이 필요한 데이터를 실시간으로 다른 서비스의 API를 통해 요청하여 가져옵니다.

장점

데이터가 필요한 순간에 요청을 통해 실기간으로 데이터를 동기화할 수 있다는 점,
해당 데이터를 획득하기 위한 프로토콜만 맞추면 된다는 점에서 다소 결합도가 낮은 방법이라는 장점이 있습니다.

단점

다만 네트워크 지연 및 호출 빈도에 따라 성능이 영향을 받을 우려가 있어 Loadbalancing 이 주요하며
요청을 받아서 처리하는 서비스의 상태에 따라 데이터 품질이 달라진다는 점에서 Service Discovery 를 고려해야할 뿐만 아니라 SPOF 문제도 내포하고 있습니다.

예시

REST API, Remote Procedure Call 등 각 서비스간 포로토콜에 기반한 통신을 포함합니다.

2. 이벤트 기반 동기화 (메시지 큐 활용)

데이터 변경 시, 변경 이벤트를 메시지 큐를 통해 발행하고, 구독 서비스들이 이를 받아 로컬 데이터를 업데이트합니다. (사가패턴 등)

장점

서비스간 느슨한 결합을 유지할 수 있으며 DLQ를 활용하여 장애허용(fault tolerance)도가 높은 시스템을 기대할 수 있습니다. 또한 polling 방식을 이용하여 더 안전하게 이벤트 동기화를 처리할 수 있습니다.

단점

실시간 데이터 동기화 구현을 위해 pushing 방식을 채택한다면 멱등성(idempotency) 보장을 위해 별도의 설계가 추가되어야하며,
트랜잭션 동기화를 위해 Saga Pattern 을 도입한다면 전체 MSA 설계가 어려워지는 측면이 존재합니다.

예시

메시지 큐(예: Kafka, RabbitMQ)를 이용한 트랜잭션 동기화가 있습니다.

3. Change Data Capture (CDC) / ETL 기반 동기화

CDC는 데이터베이스에서 발생하는 변경 사항(Insert, Update, Delete)을 실시간 또는 준실시간으로 캡처하여 다른 서비스나 데이터 저장소로 전파하는 기술입니다. 주로 데이터 동기화, 실시간 분석, 이벤트 기반 아키텍처 구축 등에서 사용됩니다. ETL(Extract, Transform, Load)은 추출된 데이터를 변환하고 목적지 시스템에 적재하는 일련의 작업을 의미합니다.

아직 직접 해본적이 없어서 다소 이론적인 내용들입니다.

장점

데이터가 변경되는 즉시 이를 캡처하여 동기화하기 때문에 실시간 데이터 일관성 보장에 매우 효과적이라고 알려져있습니다.
분산 데이터베이스 환경에서도 안정적이면서 효율적인 동기화를 지원하는것으로 알려져있습니다.

단점

CDC 프로세스를 관리하기 위한 추가 인프라를 운영해야 하며, 장애 관리 및 모니터링 시스템 구성이 복잡해질 수 있습니다.
CDC 프로세스가 중단될 경우 데이터 유실 또는 데이터 복제 지연 등의 문제가 발생할 수 있어서 역시 설계가 복잡해집니다.

예시

Debezium과 Kafka를 활용한 실시간 데이터 복제, AWS Database Migration Service(DMS) 등이 있습니다.

결국 어떤 동기화 전략을 선택해야하나

결국 실시간으로 데이터를 동기화하는 선택지로는 API 기반 동기화와 CDC 기반 동기화가 있습니다. 그런데 CDC로 접근하는것은 공부가 부족하기도 하지만 관련 유지보수 비용이 높아진다는 부담이 존재했습니다. 그래서 API 기반 동기화를 선택하게 되었습니다.

그렇다면 API 기반 동기화 중 구체적으로 어떤 프로토콜을 이용할것인지 정해야합니다.

1. RPC(gRPC)와 GraphQL 중 어떤 프로토콜을 선택할지에 대한 고민

RPC란?

Remote Procedure Call의 약자로, 원격에서 함수를 호출하는 방식입니다. 대표적으로 gRPC가 있으며, Protocol Buffers를 이용해 데이터 구조를 정의합니다.
주로 서비스 간 빠른 속도와 효율적이고 엄격한 규격이 필요할 때 사용합니다.

GraphQL이란?

Facebook에서 개발된 데이터 쿼리 및 조작을 위한 쿼리 언어입니다.
클라이언트가 데이터를 정확히 원하는 대로 요청하여 받을 수 있고, Subscription을 통해 데이터 변경을 실시간으로 구독할 수 있습니다.

gRPC vs GraphQL 간 주요 비교

	gRPC	GraphQL
데이터 형식	Protocol Buffers	JSON
통신 프로토콜	HTTP/2 (binary)	HTTP (주로 POST 방식)
성능	우수(낮은 지연, 높은 성능)	양호(하지만 데이터 선택성으로 효율성 높음)
실시간성	Streaming 방식 지원	Subscription 지원
데이터 유연성	낮음(정의된 데이터 형식만 가능)	매우 높음(필요한 데이터만 선택 가능)
클라이언트 접근성	낮음(엄격한 정의 필요)	높음(쿼리 유연성, 클라이언트 친화적)
유지보수	schema 관리 부담 존재	schema 진화 용이

2. 기술의 선택

이번 데이터 동기화의 고민은 주로 내부 서비스간 데이터를 동기화하는것이 이슈였습니다. 내부 통신이기에 서비스간 엄밀한 타입 정의가 중요하며, 성능이 가장 우선시 되어야 했습니다.

그런 측면에서 데이터 타입 유연성이 뛰어난 GraphQL을 선택하기보다 RPC가 적합했으며, 특히 gRPC는 HTTP2 를 이용하여 다수의 요청을 비동기적으로 처리할 수 있다는 것도 큰 장점이었습니다. 이러한 이유로 RPC, 그 중에서도 가장 대표적인 gRPC를 선택하게 되었습니다.

참고

- BFF Pattern, Sam Newman: https://samnewman.io/patterns/architectural/bff/

- Microservice Patterns, Chris Richardson: https://microservices.io/patterns/index.html

FastAPI log (4) - 개선하기

개발프로브 — Sun, 2 Mar 2025 15:38:39 +0900

이 시리즈는 AWS EKS & FastAPI 환경에서 로그를 적용하는 과정을 다루고 있습니다. 전체 시리즈는 다음과 같습니다.

- FastAPI log (1) - AWS EKS Fargate 환경에서 log 를 외부시스템에 보내기

- FastAPI log (2) -AWS EKS Fargate, 왜 Fluent Bit 인가?

- FastAPI log (3) - 설계, 구현

- FastAPI log (4) - 개선하기

이전 글에서 FsatAPI 의 request, stacktrace를 logging 하는 Middleware 를 만들었습니다. 하지만 이러한 구현 접근에는 결정적인 오류와 개선사항이 있습니다.

오류

결정적인 오류는 Middleware 에서 Exception 을 catch 하고 있다는 점입니다. FastAPI 의 기본 middleware chain 을 고려하지 않은 접근이기 때문에 문제가 됩니다. 간단히 이야기하자면, FastAPI 에서는 처리 되지 않은 Exception 에 대한 책임을 다른 Middleware 에게 위임하고 있는데, 중간에 Logging 책임을 지는 Middleware 가 Exception 을 처리하고 있는 것이지요.(이에 대해서는 CORS Middleware 에서 발생하는 문제를 분석할때 다뤘습니다.)

따라서 Exception 을 처리하는 부분이 제외되어야 합니다.

개선 사항

BsaeHTTPMiddelware 사용

Starlette 에서 제공하는 BsaeHttpMiddleware 는 성능상 불이익이 있습니다. 대신 Pure ASGI Middleware 로 구현되어야 합니다.

CORSMiddleware 문제를 해결하기 위해 ASGI Spec 을 공부한 저에게는 조금 기대되는 작업입니다.

확장성 부족

이전 글에서는 로깅 라이브러리 레퍼런스를 알아본다고 고작 python-json-logger 정도를 알아봤습니다. 하지만, 엘라스틱 서치에서 공통 로깅사양을 구현한 python 라이브러리가 있다는 것을 이제 막 발견했습니다. 이 코드를 침고하여 더 확장서있는 middleware 를 만들 수 있을 것 같습니다.

결합도가 높음

이전 버전은 middleware 자체의 기능보다는 전체 어플리케이션에서의 사용에 초점을 맞췄습니다. 그러한 이유로 여러 환경변수를 통해 logger 를 가져오고, stack_trace 를 출력하고 등의 행위를 제한했습니다. 그런데 이제보니 이러한 행위는 파이썬답지 못하며 middleware 에 집중된 행위가 아닙니다. 불필요한 외부 참조를 제거하고 middleware 내부에만 집중해야합니다.

개선 적용

전체 코드 결과물은 github 에서 확인할 수 있습니다.

import logging
import time
import uuid
import json

from starlette.types import ASGIApp, Message, Scope, Receive, Send

class JsonRequestLoggerMiddleware:
    def __init__(
        self, app: ASGIApp,
        error_info_name: str = "error_info",
        error_info_mapping: dict[str, str] | None = None,
        event_id_header: str | None = None,
        client_ip_headers: list[str] | None = None,
        logger: logging.Logger | None = None,
    ) -> None:
        """
        Initializes the JSON Request Logger Middleware.

        Args:
            app (ASGIApp): The ASGI application instance to wrap.
            error_info_name (str, optional): The key name in the request state from which to extract error information.
                Defaults to "error_info".
            error_info_mapping (dict[str, str] | None, optional): A dictionary mapping error information keys (from the request
                state) to desired log field names. For example, {"code": "error_code", "message": "error_message"}.
                Defaults to None.
            event_id_header (str | None, optional): The HTTP header name to extract an event ID from. If not provided or if the header
                is missing, a new UUID will be generated. Defaults to None.
            client_ip_headers (list[str] | None, optional): A list of HTTP header names to check for the client IP address,
                in order of priority. If none are provided, the client IP will be obtained from the scope's "client" value.
                Defaults to None.
            logger (logging.Logger | None, optional): A custom logger to use for logging requests. If not provided, a default
                logger with INFO level is created. Defaults to None.
        """
        self.app = app
        self.error_info_name = error_info_name
        self.error_info_mapping = error_info_mapping or {
            "code": "error_code",
            "message": "error_message",
            "stack_trace": "stack_trace",
        }
        self.event_id_header = event_id_header
        self.client_ip_headers = client_ip_headers or ["x-forwarded-for", "x-real-ip"]
        # logger setting
        if logger:
            self.logger = logger
        else:
            logger = logging.getLogger("request-logger")
            logger.setLevel(logging.INFO)
            if logger.hasHandlers():
                logger.handlers.clear()
            stream_handler = logging.StreamHandler()
            stream_handler.setLevel(logging.INFO)
            formatter = logging.Formatter("%(message)s")  
            stream_handler.setFormatter(formatter)
            logger.addHandler(stream_handler)
            logger.propagate = False
            self.logger = logger
            
    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
        if scope["type"] != "http":
            return await self.app(scope, receive, send)

        start_time = time.time()
        
        # parse header
        headers = {k.decode("latin1"): v.decode("latin1") for k, v in scope.get("headers", [])}
        # event_id
        if self.event_id_header and self.event_id_header in headers:
            event_id = headers[self.event_id_header]
        else:
            event_id = str(uuid.uuid4())
            
        # extract client ip from client_ip_headers
        client_ip = None
        for header in self.client_ip_headers:
            if header in headers:
                # X-Forwarded-For case
                client_ip = headers[header].split(",")[0].strip()
                break
        if not client_ip:
            client_ip = scope.get("client", ("unknown",))[0]
                        
        # default log data
        log_data = {
            "timestamp": time.strftime("%Y-%m-%dT%H:%M:%S.%fZ", time.gmtime()),
            "event_id": event_id,
            "method": scope.get("method"),
            "path": scope.get("path"),
            "client_ip": client_ip,
            "user_agent": headers.get("user-agent"),
        }

        response_status_code = None

        async def send_wrapper(message: Message) -> None:
            nonlocal response_status_code
            if message["type"] == "http.response.start":
                response_status_code = message.get("status")
            await send(message)

        await self.app(scope, receive, send_wrapper)
        
        time_taken_ms = int((time.time() - start_time) * 1000)
        
        # based on response status_code
        if response_status_code is None:
            response_status_code = 500
        log_type = "access" if response_status_code < 400 else "error"
        log_level = "ERROR" if response_status_code >= 400 else "INFO"
                
        # error log data
        
        error_info = scope.get("state", {}).get(self.error_info_name, None)
        if not error_info:
            log_data.update({"error": None})
        if error_info:
            log_data.update({"error": {}})
            for src_key, dest_key in self.error_info_mapping.items():
                log_data["error"][dest_key] = error_info.get(src_key)            
        
        # log data update
        log_data.update({
            "time_taken_ms": time_taken_ms,
            "status_code": response_status_code,
            "log_type": log_type,
            "level": log_level,
        })     
        
        log_level_int = logging.getLevelNamesMapping()[log_level]
        self.logger.log(log_level_int, json.dumps(log_data, ensure_ascii=False))

참고

FastAPI Tips: https://github.com/Kludex/fastapi-tips

ecs-logging: https://github.com/elastic/ecs-logging-python

SQLAlchemy read-only session

개발프로브 — Sat, 22 Feb 2025 17:33:24 +0900

SQLAlchemy Readonly 에 대한 질문

SQLAlchemy 도 Spring의 Transaction 처럼 read-only 를 만드는 기능이 있는지 물어보는 질문이 있었습니다. 이 글의 답변에도 작성했지만, 저도 SpringBoot 를 사용할때는 Transaction 격리수준, 전파수준 등을 엄청 신경썼었는데 FastAPI&SQLAlchemy 를 사용하면서 한번도 이런 고민을 안했습니다.

이게 개별 비즈니스 로직을 간단하게 유지할 수밖에 없는 프레임워크의 장점아닌 장점이라고 생각하면서 SQLAlchemy 에서 read-only transaction 을 만드는 방법을 알아보았습니다.

Does SQLAlchemy automatically create a transaction for read-only operations?

I am currently learning backend development using FastAPI + SQLAlchemy, and I have a question regarding transaction handling in SQLAlchemy. While reading the official SQLAlchemy documentation, I came

stackoverflow.com

해결방법

왠만한 고민에 대한 해답은(특히 소프트웨어 개발 영역에서) 인터넷에 있기 마련입니다. 보통 stackoverflow 에 질문을 올리는 사람들은 인터넷에서 답을 찾지 못한 경우가 많은데 이번 질문은 github issue 를 찾아봤다면 답을 알 수 있는 질문이었습니다.

SQLAlchemy issue 에 비슷한 질문이 있었고, maintainer 는 공식적으로 read-only transaction 을 만드는 방법이 제공되진 않지만 SQLAlchemy 에서 제공하는 events 를 이용해서 충분히 구현이 가능합니다.

from sqlalchemy import create_engine, Column, Integer, String, event
from sqlalchemy.orm import Session, sessionmaker, declarative_base

# Define the base and ORM model.
Base = declarative_base()

class User(Base):
    __tablename__ = "users"
    id = Column(Integer, primary_key=True)
    name = Column(String)
    
    def __repr__(self):
        return self.name

# Utility functions to mark a session as read-only.
def set_read_only(session: Session, read_only: bool = True):
    session.info['read_only'] = read_only

def is_read_only(session: Session) -> bool:
    return session.info.get('read_only', False)

# Listen for before_flush event and prevent flushing if session is read-only.
@event.listens_for(Session, "before_flush")
def before_flush(session, flush_context, instances):
    if is_read_only(session):
        raise Exception("Read-only session: flush not allowed")

# Setup the database and create a session.
if __name__ == "__main__":
    engine = create_engine("sqlite:///:memory:")
    SessionLocal = sessionmaker(bind=engine)
    
    # Create tables.
    Base.metadata.create_all(engine)
    
    # Get Session
    session = SessionLocal()
    
    # normal Session ()
    new_user = User(name="Alice")
    session.add(new_user)

    users = session.query(User).all()
    print("Users:", users)    
    session.commit()    
    
    # read-only Session ()
    set_read_only(session, True)  # Mark session as read-only
    
    new_user = User(name="James")
    session.add(new_user)
    
    users = session.query(User).all()
    print("Users:", users)    
    session.commit()

Spring 에서는 read-only Transaction 을 만들어서 약간의 성능상 이점을 얻을 수도 있었지만, SQLAlchemy 에서는 그런 성능상 이점을 기대할 수 있을지는 모르겠습니다.

FastAPI ErrorHandling 과 CORS (3) - 문제 해결

개발프로브 — Sat, 22 Feb 2025 17:08:57 +0900

FastAPI 에서 ErrorHandling 하는 과정에서 CORS 문제가 발생하는 이슈와 그 원인을 그리고 그에 따른 사람들의 대응을 알아봤습니다.

그리고 저는 문제의 원인이 Starlette에 있다고 생각했고, 나름대로 연구하여 Starlette codebase 에 코드 3줄을 추가하여 이러한 문제를 해소할 수 있는 방법을 찾았습니다.

당장이라도 Starlette 에 PR 을 올리고 싶었지만, 의외로 다른 사람들의 더 나은 대안을 가지고 있거나 FastAPI 나 Starlette 에서 이미 관련 이슈를 해소할 계획일 있을지도 모르기 때문에 우선 discussion 을 이용하기로 했습니다.

FastAPI Discussion

[discussion link]

이 문제가 FastAPI 에 문서화 될 계획이 있다면 당장 급한 이슈는 해소될 것으로 보여서 물어봤습니다.

일단 FastAPI 팀은 문서화 계획은 없으며, Starlette 에 관련 제안을 해달라는 답볃을 받았습니다.

Starlette Discussion

[discussion link]

Starlette 에는 codebase 변경과 문서화를 함께 제안해보았습니다.

하지만 제가 문제가 있다고 생각했던 방식이 사실은 Starlette 의 공식적인 접근이라는 답변을 받았습니다. (FastAPI 의 maintainer 와 동일한 사람입니다.)

이미 Starlette 진영에서 해당 문제에 대한 공식적인 접근방법이 있다고 말을 한 이상 내가 코드베이스를 바꾸는것은 어려운일이라고 생각됩니다. 다만 Starlette 공식문서에 해당 내용을 추가할 순 있을 것 같습니다.

문제해결:Starlette 문서추가

결국 Starlette 공식문서에 해당 내용을 추가할 수 있었습니다. RP#2885, 개발자로서 직접 소스코드에 기여하고 싶은 욕심이 있어서 공식문서로만 끝난게 아쉽지만, Starlette 과 FastAPI 생태계를 더 잘 알게된 계기가 된것 같습니다.

공식문서에 추가된 내용

티스토리 스킨 hELLO 에 기여해보기

개발프로브 — Wed, 19 Feb 2025 20:10:02 +0900

이전에 FatAPI 의 문서 번역에 기여한것에 이어서 FastAPI 의 공식문서에 내용을 변경하는 등 기여를 하고 있는중이다.

오픈소스 초보자의 FastAPI 기여하기

회사에서 FastAPI 로 전환을 하기에 FastAPI Document 를 보면서 공부중이었다. 한국어로 번역된 문서도 있는반면 영어 그대로인 문서들도 있었다. 왜일까? 하고 찾아보던중 FastAPI Github 에서 번역활동

probehub.tistory.com

FastAPI 에서 기여하는 흐름은 이런식이다.

[Fork 를 한다] -> [적절한 이름의 Branch 를 만든다] -> [변경하고자하는 사항을 변경하고 PR을 올린다] -> [리뷰를 받는다] -> [머지 혹은 리젝된다]

하지만 이번에 티스토리 hELLO 에 기여했던 흐름은 전혀 달랐다.

우선 hELLO 에 기여하게 된 계기는 완전히 개인적인 이유다. 이 티스토리에 hELLO 스킨을 적용중이다. 그리고 나는 에디터에 쓰여진 글이 적절히 구조화되었는지를 본 후 "완료" 버튼을 누른다.

그런데 ul, ol 태그 요소가 에디터에서는 들여쓰기가 되었지만 실제 발행된 글에서는 들여쓰기가 되지 않는 것을 발견한 것이다. 이 문제를 해결하는건 간단했다. 웹브라우저에서 개발자 도구를 열고 관련 태그를 분석한 후 CSS 요소를 넣으면 해결이다.

/* 글 내용에 포함된 ul의 들여쓰기 적용 */
ul[data-ke-list-type="disc"] {
  list-style-type: disc;
  padding-left: 1.5rem;
}

ol[data-ke-list-type="decimal"] {
  list-style-type: decimal;
  padding-left: 1.5rem;
}

티스토리 스킨 편집에서 이걸 적용하고 만족하던 중 문득 나와 같은 이유로 고생하는 사람이 있지 않을까? 하는 생각이 들었다. 그리고 깃헙을 찾아보니 hELLO 저자분이 운영중인 리포지토리를 발견할 수 있었다.

그리고 엄청 가볍게 해소되었다.

[ISSUE에 글을 쓴다] -> [Discussion 으로 옮겨진다] -> [저자분이 나중에 반영될것이라고 한다]

이렇게 가볍게 반영되는 오픈소스도 있다는 사실이 새로웠다.

하지만 그 과정이 쉽든 어렵든 어떻든 다른 사람들에게 도움이 되었다는 사실은 변함 없으니 오히려 좋다.

FastAPI & Postgres 로 multi-tenancy 구현하기

개발프로브 — Mon, 17 Feb 2025 08:26:51 +0900

stackoverflow 를 돌아다니다가 "FastAPI multi-tenant 를 구현하는데 경쟁조건이 발생한다" 는 내용의 질문을 발견했습니다. 회사에서 FastAPI 에서 PostgreSQL 의 schema 단위로 tenant 를 구분하여 DB 에 연결하는 기능을 구현했는데, 생각보다 여기서 어려움을 겪는 사람이 있는것 같아서 내용을 정리해봤습니다.

문제 분석

우선 저는 질문자가 구현한 middleware 를 살펴봤습니다. 큰 흐름은 다음과 같습니다.

ContextVar 를 이용한다.
Request 가 있을때마다 SessionLocal 에서 session 을 얻어온다.
얻어온 session 에서 switch schema 를 실행하고 request.state 에 db 라는 이름으로 넘겨준다.

일단 주어진 코드로만 보면 왜 ContextVar 로 current_schema 정보를 저장하는지 의문이지만 ContextVar 자체는 비동기 프렘워크에서 로컬 변수를 저장하는데 사용되며, FastAPI 에서는 request 마다 격리되어 있기 때문에 경쟁조건을 만드는 원인이 아닐것으로 보았습니다. 그래서 주목할만한 특이한 사항은 session 을 request.state 로 넘겨준다는 것입니다.

백엔드 어플리케이션에서는 DB와의 연결이 격리되는것이 중요합니다. 그러한 이유로 SpringBoot 도 Transaction 마다 Connection 을 따로 만들고, FastAPI도 공식문서에서 database session 에 대해서는 yield 와 Depends 사용을 권장하고 있지요. 특히 ASGI 를 염두에둔 FastAPI 에서는 DB Session 의 격리는 더 중요한 사항일 것입니다.

그렇다면 middleware 수준에서 생성한 session 을 request.state 에 넘겨주는것이 DB Session 을 각 요청별로 격리할 수 있을지 파악해보면 될것 같습니다.

# ...
from typing import Optional, Callable
from fastapi import Request, Response
from starlette.middleware.base import BaseHTTPMiddleware
from app.db.session import SessionLocal, switch_schema
from contextvars import ContextVar

# Point1: ContextVar 를 이용한다.
current_schema: ContextVar[str] = ContextVar("current_schema", default="public")

class SchemaSwitchMiddleware(BaseHTTPMiddleware):
    async def dispatch(self, request: Request, call_next: Callable) -> Response:
    	# Point2: 모든 요청마다 SessionLocal 에서 Session 을 얻어온다.
        db = SessionLocal()  # Create a session here
        try:
            tenant_id: Optional[str] = request.headers.get("X-Tenant-ID")

            if tenant_id:
                # tenant_id 를 schem_name 으로 변환하는 로직
                except Exception as e:
                # exception 처리
            else:
                schema_name = "public"

            current_schema.set(schema_name)
            # Point3: middleware 수준에서 schema 를 변경하고 session을 request.state 에 넣는다.
            switch_schema(db, schema_name)
            request.state.db = db  # request state 에 session 저장

            response = await call_next(request)
            return response

        except Exception as e:
        	# Exception 처리
        finally:
            switch_schema(db, "public")
            db.close()

문제의 원인

이미 눈치챘겠지만, middleware 수준에서 생성한 session 을 request.state 에 넘겨주는것이 DB Session 을 각 요청별로 격리 할 수 있다는 보장이 없습니다. 특히 위에 구현된 middleware 의 경우에는 middleware 수준에서 commit 을 한번 하여 상태를 변화시키고 있기 때문에 더욱 문제가 됩니다.

기본적으로 SQLAlchemy 를 이용해 Engine 을 만들고 SessionLocal 을 만들때 Connection Pool 을 이용하게 됩니다. 매 요청마다 pool 에서 session 을 얻어올 것이고, 기존 session이 제대로 관리되지 않는다면 이미 schema 변경이 일어난 session 에 대해서 다른 request 가 다시 schema 를 변경시킬 수 있는 가능성이 생깁니다. 명확하지 않지만 그럴 여지는 분명히 있습니다.

middleware 에서 만든 DB session 을 middleware 와 application 모든 곳에서 적절히 관리할 수 있다면 이러한 여지가 없겠지만 인간은 실수하기 나름입니다. Framework 수준에서 제공해주는 Depends 를 이용하는게 더 적절한 선택이 될 것입니다.

해결방법

아래와 같이 FastAPI의 Depends 안에서 Session 의 수명주기를 처리하면 큰 문제가 없을 것입니다:

from sqlalchemy import create_engine, text
from sqlalchemy.orm import sessionmaker, declarative_base, Session
from app.core.logger import logger
from app.core.config import settings
from typing import Annotated
from fastapi import Header

# Base for models
Base = declarative_base()

DATABASE_URL = settings.DATABASE_URL

# SQLAlchemy engine
engine = create_engine(
    DATABASE_URL,
    pool_pre_ping=True,
    pool_size=20,
    max_overflow=30,
)

# Session factory
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)

# TODO: use this get_db_session function in path operation.
def get_db_session(tenant_id: Annotated[str, Header(alias="X-Tenant-ID")]) -> Generator[Session, None, None]:
    session = SessionLocal()
    try:
        # TODO: Implement tenant_id to tenant_schema here
        session.execute(text(f"SET search_path TO {tenant_id};"))
        session.commit()  # Ensure the schema change is applied immediately
        yield session
    finally:
        session.close()

FastAPI ErrorHandling 과 CORS (2) - 대안 파악

개발프로브 — Sat, 15 Feb 2025 18:48:12 +0900

Starlette 와 FastAPI 의 ISSUE(link,link) 에서는 다음의 해결법이 논의 되었습니다.

논의된 해결법

1. FastAPI 앱을 CORSMiddleware로 감싸기

from: thomasleveil

from starlette.applications import Starlette
from starlette.authentication import AuthenticationBackend, AuthenticationError
from starlette.exceptions import HTTPException
from starlette.middleware.authentication import AuthenticationMiddleware
from starlette.middleware.cors import CORSMiddleware
from starlette.responses import JSONResponse

import uvicorn

class DumbAuthBackend(AuthenticationBackend):
    async def authenticate(self, request):
        raise AuthenticationError("You will never be authenticated!")

app = Starlette(debug=True)

# Global authentication
app.add_middleware(AuthenticationMiddleware, backend=DumbAuthBackend())

@app.route('/')
async def index(request):
    return JSONResponse({"hello": "world"})

if __name__ == '__main__':
    uvicorn.run(
        CORSMiddleware(app=app, allow_origins=["*"]),
        host='0.0.0.0',
        port=8000
    )

CORSMiddleware가 자체적으로 ASGI 앱이므로 FastAPI 앱을 감싸도록 구성합니다. 이를 통해 outermost middleware 가 CORSMiddleware 가 되기 때문에 CORS 헤더 문제를 자연스럽게 해결하게 됩니다.

평가

✅ 장점: 비교적 간단하게 적용 가능
⚠️ 단점: 초보자에게는 이러한 wrapping 개념이 이해하기 어려울 수 있습니다.

이렇게 문제를 해결하는 것은 Starlette App 구성이 갖는 문제를 또다른 ASGI App 을 만들어서 해결하는 것으로 뭔가 와닿지 않습니다.

차라리 Starlette 측에서 CORSMiddleware 를 추가하는 새로운 방법을 제공하는게 맞을 것입니다.

2. ExceptionHandler에서 직접 CORS 헤더 추가

from: ddahan

def add_cors(request: Request, response: JSONResponse) -> JSONResponse:
    """
    CORS headers are not automatically added to error handlers with FastAPI
    cf. https://github.com/fastapi/fastapi/discussions/8027
    """
    cors_headers = {
        "Access-Control-Allow-Methods": ", ".join(settings.CORS_ALLOW_METHODS),
        "Access-Control-Allow-Headers": ", ".join(settings.CORS_ALLOW_HEADERS),
        "Access-Control-Allow-Credentials": str(settings.CORS_ALLOW_CREDENTIALS).lower(),
    }

    # If the origin is in the allowed list, add it to the CORS headers
    origin = request.headers.get("origin")
    if origin in settings.CORS_ALLOW_ORIGIN:
        cors_headers["Access-Control-Allow-Origin"] = origin

    response.headers.update(cors_headers)
    return response

def internal_exception_handler(request: Request, exc: Exception) -> JSONResponse:
    response = JSONResponse(
        status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
        content={
            "errors": {
                "general": [
                    "An unknown error has occurred. Please contact an administrator."
                ]
            }
        },
    )
    return add_cors(request, response)

settings 로 CORS 관련 세팅을 전역적으로 관리하려고 하는 시도가 돋보입니다.

ExceptionHandler 는 ServerErrorMiddleware 와 ExceptionMiddleware 에 적용되기 때문에 CORSMiddleware 를 우회하여 반환되는 이유로 CORS 헤더가 누락되는 문제를 해결할 수 있습니다.

평가

✅ 장점: 원하는 예외 상황에서 정확하게 CORS 헤더를 제어할 수 있습니다.
⚠️ 단점: 전역적으로 처리해야 할 CORS 헤더를 개별 ExceptionHandler에서 설정하는 것은 비효율적이며 비표준적입니다.

비록 CORS 관련 세팅을 전역적으로 처리하려고 했으나 본질적으로 예외 처리 시 응답에 CORS 헤더를 수동으로 추가하는 것입니다. CORS에 처리는 Applciation 전역적으로 처리되어야 하는데, 지엽적인 처리에 머물러 있는것 같아 아쉽습니다.

결론

지극히 개인적인 의견입니다.

CORS Middleware 로 FastAPI application 을 감싸는 행위는 이해하기 어려습니다. 과연 라이브러리 수준에서 정식으로 권장하는 문제라고 받아들일 수 있을까요?

또한 ExceptionHandler 에서 직접 header 를 추가하는것도 이상합니다. 일부 경우를 제외하고 CORS 에 대한 대응은 application 전역적인 처리가 되어야 하기 때문입니다.

제 3의 해법이 필요해 보입니다, 그리고 이 문제를 해결하는 과정은 "FastAPI ErrorHandling 과 CORS (3) - 문제 해결" 에 정리했습니다.

FastAPI ErrorHandling 과 CORS (1) - 문제 파악

개발프로브 — Mon, 10 Feb 2025 00:02:11 +0900

Starlette와 FastAPI에서 제공하는 CORSMiddleware와 ExceptionHandler가 함께 작동하지 않는 상황은 꽤 혼란스럽습니다. 이는 REST API 개발자 입장에서 상당히 중요한 이슈로, 많은 FastAPI 사용자들이 다양한 해결책을 논의(link, link, link)해 왔지만 제가 봤을때 명확하고 만족스러운 답이 나오지 않은 상태입니다. 우선 문제의 원인과 그 해법이 만족스럽지 않은 이유를 이야기해보겠습니다.

다소 장황한 글이 될 수 있기 때문에 문제 원인과 문제 상황만 파악하고자 하시는 분은 "문제의 원인" 그리고 "문제 상황" 만 보셔도 됩니다.

문제 파악

Starlette Middlewere chain

Strlette 는 ASGI Spec 을 준수하며, 그에 따라 Middleware 라는 개념이 적용되어 있습니다. 그리고 이러한 Middleware 들이 요청, 응답 과정에서 연쇄적으로 동작하는 것을 Middleware chain 이라고 합니다.

FastAPI application 은 Starlette application 을 더 사용하기 편하게 포장한것이고, 대부분의 주요 철학과 구현은 Starlette에 의존하고 있기 때문에 Sarlette의 Middleware chain 을 분석하겠습니다.

주요 Middleware

Starlette 의 middleware chain 에서 cors 문제가 발생하는 문제를 이해하기위해 다음의 개념을 알아야 한비다.

Middleware: 요청이 Starlette 애플리케이션에 도달하기 전과 응답이 반환된 후에 개입하여 처리합니다.
CORSMiddleware: 사용자가 설정한 CORS 정책에 따라 preflight 요청을 검증하고 응답에 CORS 헤더를 추가합니다.
ExceptionMiddleware: 특정 status_code 혹은 Exception 대해서 어떻게 대응할지 설정합니다.
ServerErrorMiddleware: ExceptionMiddleware 에서 처리되지 않은 나머지 Exception 에 대응합니다.
ExceptionHandler: 예외가 발생했을 때 이를 처리하는 방법을 정의합니다. ExceptionMiddleware 에 등록됩니다.
HttpException: Starlette와 FastAPI에서 정의된 예외 클래스로, 상태 코드와 헤더 정보를 포함할 수 있습니다.

Starlette 코드 분석

이제 직접 Starlette application 에 대한 코드를 보겠습니다. 이를 통해 ExceptionMiddleware 와 ServerErrorMiddleware 는 자동으로 Startlette application 이 최초 요청을 받을때 초기화 되어(Lazy) 이후에는 캐싱되어 재사용되는 구조를 가지고 있다는 사실을 알 수 있습니다.

또한 ExceptionHandler 에 등록된 Exception 에 대한 처리는 ServerErrorMiddleware 에 할당된다는 사실도 파악이 가능합니다.

# starlette/applications.py

class Starlette:
    """Creates an Starlette application."""

    def __init__(...)
    
    # line 79
    def build_middleware_stack(self) -> ASGIApp:
        debug = self.debug
        error_handler = None
        exception_handlers: dict[typing.Any, typing.Callable[[Request, Exception], Response]] = {}

        for key, value in self.exception_handlers.items():
            if key in (500, Exception):
                error_handler = value
            else:
                exception_handlers[key] = value

        middleware = (
        	# outermost
            [Middleware(ServerErrorMiddleware, handler=error_handler, debug=debug)]
            + self.user_middleware
            + [Middleware(ExceptionMiddleware, handlers=exception_handlers, debug=debug)]
            # innermost
        )

        app = self.router
        for cls, args, kwargs in reversed(middleware):
            app = cls(app, *args, **kwargs)
        return app

    # line 108
    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
        scope["app"] = self
        if self.middleware_stack is None:
            self.middleware_stack = self.build_middleware_stack()
        await self.middleware_stack(scope, receive, send)
        
    # line 123 
    def add_middleware(
        self,
        middleware_class: _MiddlewareFactory[P],
        *args: P.args,
        **kwargs: P.kwargs,
    ) -> None:
        if self.middleware_stack is not None:  # pragma: no cover
            raise RuntimeError("Cannot add middleware after an application has started")
        self.user_middleware.insert(0, Middleware(middleware_class, *args, **kwargs))

    # line 133
    def add_exception_handler(
        self,
        exc_class_or_status_code: int | type[Exception],
        handler: ExceptionHandler,
    ) -> None:  # pragma: no cover
        self.exception_handlers[exc_class_or_status_code] = handler

실제 코드 line 79 에 위치한 build_middleware_stack 함수를 통해 유저가 주입한 exception_handler 의 값에 따라 error_handler 와 exception_handler 가 구분되며, middleware 에 유저가 정의한 user_middleware 를 감싸는 구조로 ServerErrorMiddleware 와 ExceptionMiddleware 가 주입됩니다.

실제코드 line 108 에 위치한 __call__ 에서 build_middleware_stack 함수가 호출되며, 이를 통해 미들웨어는 Starlette application 생성 시점이 아니라 최초에 Starlette application 이 요청을 처리하는 시점에 초기화 된다는 것을 알 수 있습니다.

문제의 원인

그렇다면 ExceptionMiddleware, ServerErrorMiddleware, CORSMiddleware 중 어디가 문제인걸까요?

http status code 500 이나 Exception, 혹은 ExceptionHandler 에서 처리되지 않은 Exception 을 상속한 예외들에 대한 책임은 오롯이 ServerErrorMiddleware 의 것입니다.

Outermost 에 ServerErrorMiddleware 가 존재하고 status_code 500 이나 Exception 으로 밖에 감지되지 않는 Exception 은 ServerErrorMiddleware로 바로 전달됩니다. 정확히 말하면, 다른 middleware 에서 처리하지 않고 다음 middleware 를 계속 호출한 끝에 ServerErrorMiddleware 에게 전달됩니다.

그렇기 때문에 요청에서는 CORS 를 검사하지만 Exception 에 의한 응답에는 CORS 관련 헤더를 받을 수 없는 겁니다.

문제 상황

그렇다면 도대체 Exception(ServerError)가 발새할때 CORS 헤더가 반환되지 않는게 왜 문제일까요?

1. 클라이언트와의 약속이 깨집니다.

일반적으로 클라이언트는 서버와 약속된 에러코드에 따른 적절한 처리를 구현할 것입니다. 하지만 Exception 이 발생할때 의도치 않은 동작을 서버가 반환하기 때문에 클라이언트단에서 적절히 에러에 대응할 수 없게 됩니다.

이는 유저경험에도 치명적이며 클라이언트단에서 에러 원인을 파악할 수 없도록 만들기에 에러 대응 시간을 늦추게 됩니다.

2. 일관적이지 못한 예외처리로 혼란을 초래합니다.

Exception 이 아니라 HttpException 과 WebsocketException 은 ExceptionMiddleware에서 처리되기 때문에 CORSMiddleware 의 처리를 거치게 됩니다. 즉, 오로지 Exception 에 대해서만 CORS 응답 헤더가 추가되지 않는 것이지요. 이러한 Starlette의 동작을 이해하지 못한 개발자는 다소 혼란을 겪을 수 밖에 없습니다.

특히 FastAPI 에서 제공되는 HttpException 이 발생할때는 CORS 응답이 제대로 처리되 기 때문에 "원인을 알 수 없지만, 종종 서버가 CORS 에러를 만들어낸다" 는 결론에 도달하게 됩니다. 게다가 FastAPI 공식문서에서는 이러한 이슈를 다루고 있지 않기 때문에 더욱더 혼란스러울 뿐입니다.

FastAPI 유저들은 이 문제를 어떻게 대응하고 있는지 "FastAPI ErrorHandling 과 CORS (2) - 대안 파악" 에서 알아보겠습니다.

FastAPI log (3) - 설계, 구현

개발프로브 — Thu, 30 Jan 2025 22:03:56 +0900

이 시리즈는 AWS EKS & FastAPI 환경에서 로그를 적용하는 과정을 다루고 있습니다. 전체 시리즈는 다음과 같습니다.

- FastAPI log (1) - AWS EKS Fargate 환경에서 log 를 외부시스템에 보내기

- FastAPI log (2) -AWS EKS Fargate, 왜 Fluent Bit 인가?

- FastAPI log (3) - 설계, 구현

- FastAPI log (4) - 개선하기

이전 글 "AWS EKS Fargate 환경에서 log 를 외부시스템에 보내기" 을 통해 로그를 Cloudwatch 로 보내는 인프라 세팅을 맞췄습니다. 이제는 FastAPI 프레임워크에서 어떻게 로그를 형성하여 보내는게 좋을지 더 실무적인 관점에서 고민한 내용을 기록해놓으려고 합니다.

uvicorn 의 기본 로그

FastAPI 는 보통 uvicorn 을 통해 구동됩니다. 이때 별도의 설정이 없다면 uvicorn 은 default access log 와 exception log 를 만들어낸다. 이런 형식의 로그를 Apache Common Log Format(CLF) 라고 합니다.

CLF 는직관적이고 가볍다는 장점이 있지만 필요한 정보를 충분히 담아내지 못한다는 단점이 있다. 그렇다면 로그에 "필요한 정보" 는 무엇이 있을까요?

API 서버의 표준 로그

API 요청, 응답을 로깅할때 사용되는 로그의 타입 Access Log, Error Log, Security Log, Performace Log 로 나뉩니다.

1. Access Log: 누가 언제 어떤 API 를 호출했는지 추적하는 로그.

2. Error Log: API 호출 중 예외가 발생했을 때의 오류 발생 원인을 파악하는 로그.

3. Security Log: API의 인증, 권한, 공격 시도와 관련된 정보를 기록하는 로그.

4. Performance Log: API의 응답 속도, DB 쿼리 성능, 캐싱 여부 등 성능 관련 데이터를 기록하는 로그.

표준 로그셋

각 로그 타입마다 요구하는 정보가 조금씩 다르지만 이들의 포맷을 통합하여 관리하는 것이 로그 수집기, 로그 분석기와 호환성이 좋을것이라고 생각했습니다. 이러한 이유로 다음의 통합 로깅 json 구조를 적용하고자 했습니다.

{
    "timestamp": "2025-01-30T14:54:45.345Z",
    "event_id": "999e8887-e77b-66d3-a456-426614174000",
    "log_type": "access",  // "access" | "error" | "security" |
    "level": "INFO",       // "INFO" | "WARNING" | "ERROR"
    "method": "GET",
    "path": "/api/v1/products",
    "status_code": 200,
    "client_ip": "192.168.1.1",
    "user_agent": "Mozilla/5.0",
    "time_taken_ms": 250,
    "exception": null,           // 에러 로그용 필드 (error)
    "error_message": null,       // 에러 로그용 필드 (error)
    "stack_trace": null,         // stacktrace 용 필드
}

*request 와 response 에 대한 자세한 정보는 민감한 정보를 담을 수 있기 때문에 기록하지 않습니다.

FastAPI 로깅 적용

1. 라이브러리 선택

logging 만 이용하기

python 에는 로그를 위해 내장된 logging 라이브러리가 존재합니다. python 언어에 내장된 라이브러리이기 때문에 굉장히 표준적인 선택이라고 할 수 있겠습니다. 하지만, 어플리케이션을 빌드하는 과정에서 다른 외부 라이브러리가 logging 모듈을 건드렸을때 그에 따른 영향을 받을 가능성도 존재합니다.

python-json-logger 과 함께 이용하기

python 에 내장되진 않았지만 별1.8k 를 받은 python-json-logger 라이브러리 역시 존재합니다. 기존 python logging 라이브러리에서 json 을 출력할때 더 편하게 할 수 있도록 도와주는 기능이 포함되어 있습니다.

라이브러리 선택: 결론

python-json-logger 공식문서에 제시된 예제를 통해 둘을 비교해보겠습니다.

python-json-logger 라이브러리를 통해 얻을 수 있는 이점은 json.dumps() 를 호출하지 않아도 된다는 것입니다.

하지만 message 라는 필드가 반드시 딸려나오고, 이를 없애기 위해서는 커스텀 설정을 해야한다는 점이 단점이있습니다.

import logging
import json
from pythonjsonlogger.json import JsonFormatter

plain_logger = logging.getLogger("plain-logger")
json_logger = logging.getLogger("json-logger")

plain_logger.setLevel(logging.INFO)
json_logger.setLevel(logging.INFO)

plain_logger_handler = logging.StreamHandler()
json_logger_handler = logging.StreamHandler()

# formatter 설정시 차이 발생
plain_logger_handler.setFormatter(logging.Formatter("%(message)s"))
json_logger_handler.setFormatter(JsonFormatter())

plain_logger.addHandler(plain_logger_handler)
json_logger.addHandler(json_logger_handler)


# json 형식 출력시 차이 발생
my_dict = {
	"message":"Logging only using logger!",
    "more_data":True
}
plain_logger.info(json.dumps(my_dict))
# {"message": "Logging only using logger!", "more_data": true}

json_logger.info("Logging using pythonjsonlogger!", extra={"more_data": True})
# {"message": "Logging using pythonjsonlogger!", "more_data": true}

다른 python 유저들은 logging 과 json 에는 익숙하겠지만, python-json-logger 라이브러리에 대해서 별도의 러닝 커브가 존재할것이라는 점, 그리고 이점보다 단점이 복잡성을 더 크게 증가시킨다는 점에서 logging 라이브러리만 이용하는 방향을 정했습다.

2. Middleware 와 ExceptionHandler 역할 분리

FastAPI 요청 흐름

FastAPI 요청 흐름을 보면 Middleware 와 ExceptionHandler 의 역할을 고민하게 됩니다.

로깅을 Middleware 에서 처리하는게 일반적인데, ExceptionHandler 에서 예외에 대한 정보 없이 응답만 전달하게 된다면 ErrorLog 를 남길 수 없게됩니다. 따라서 ExceptionHandler 에서 Exception 정보를 그대로 Middleware 로 넘겨야겠다! 로 처음에는 방향을 정했었는데, 그럴경우 굳이 ExceptionHandler 가 있을 필요가 없고, Middleware 가 로깅의 역할 뿐만 아니라 Exception 을 처리하는 역할까지 맡아야해서 굉장히 복잡해지는 문제가 있습니다.

그래서 ExceptionHandler 는 기존과 동일하게 Exception 에 따라 적절한 response 를 반환하는 역할을 하되 request.state 에 에러에 대한 정보를 넘겨주는 방법을 사용하게 되었습니다.

3. 환경에 따른 로그 변경

지금까지는 표준로그(json) 를 출력하기 위해 고민을 했습니다. 하지만 각 개발자들이 본인의 로컬 개발환경에서도 json 로그가 출력되는게 좋을까요? 경우에 따라서는 Yes 라고 할 수도 있겠지만, uvicorn 과 python 은 이미 훌륭한 기본 로그 시스템을 보유하고 있습니다.

따라서 환경변수로 다음과 같이 설정을 바꿀 수 있게 해주기로 했습니다.

if USE_JSON_LOGGING:
    setup_request_logger()      # request-logger를 JSON 포맷으로 설정
    disable_uvicorn_logs()      # uvicorn.access 로그 비활성화
    app.add_middleware(JsonRequestLoggerMiddleware)
else:
    # Uvicorn의 기본 로그 사용
    pass

결론: 구현코드

다음과 같은 middleware 를 구현하였습니다.

하지만 이 구현사항에는 결정적인 오류와 개선 사항이 있습니다. 자세한 이야기는 다음 글에서 이어서 하겠습니다.

import logging
import traceback
import time
import uuid
import json

from fastapi import FastAPI, Request
from starlette.middleware.base import BaseHTTPMiddleware

from app.logger.logger_setup import REQUEST_LOGGER_NAME
from app.exception import ErrorCode, MyCustomException
from app.util.env import get_bool_from_env

logger = logging.getLogger(REQUEST_LOGGER_NAME)

STACKTRACE_LOGGING_ENABLED = get_bool_from_env("IS_STACKTRACE_LOGGING", True)


class JsonRequestLoggerMiddleware(BaseHTTPMiddleware):
    def __init__(self, app: FastAPI):
        super().__init__(app)
    async def dispatch(self, request: Request, call_next):
        start_time = time.time()
        event_id = str(uuid.uuid4())

        log_data = {
            "timestamp": time.strftime("%Y-%m-%dT%H:%M:%S.%fZ", time.gmtime()),
            "event_id": event_id,
            "method": request.method,
            "path": request.url.path,
            "client_ip": request.client.host if request.client else "unknown",
            "user_agent": request.headers.get("user-agent"),
        }

        try:
            response = await call_next(request)
            status_code = response.status_code
            log_type = "access"

        except Exception as e: 
            status_code = 500 
            log_type = "error"
            log_data['error_code'] = "UNEXPECTED_ERROR" # Or some default code
            log_data['exception'] = type(e).__name__
            log_data['error_message'] = str(e) # Log the exception message as fallback
            log_data['stack_trace'] = traceback.format_exc().splitlines()

            application_exception = MyCustomException(ErrorCode.UNEXPECTED)
            response = application_exception.to_error_response()


        error_info = getattr(request.state, "error_info", None)  # Use getattr

        if error_info:  # exception handler 에서 넘기는 error_info 정보 확인

            status_code = error_info.get("http_status", getattr(ErrorCode.UNEXPECTED, "http_status", 500)) # Use status code from error_info, Default 500
            log_type = "error" if status_code >= 400 and status_code not in [401, 403] else 'security'

            log_data.update({  # error_info 를 log data 에 추가
                "error_code": error_info.get("code"),
                "error_message": error_info.get("message"),
                "stack_trace": error_info.get("stack_trace") if (STACKTRACE_LOGGING_ENABLED or error_info.get("code") == ErrorCode.UNEXPECTED.code) else None,
            })


        log_level = "ERROR" if status_code >= 400 else "INFO"

        log_data['time_taken_ms'] = int((time.time() - start_time) * 1000)
        log_data['log_type'] = log_type
        log_data['level'] = log_level
        log_data['status_code'] = status_code
        log_data['db_query_time_ms'] = getattr(request.state, "db_query_time_ms", None)

        # https://docs.python.org/3/library/logging.html#logging.getLevelName 의 Changed in version 3.4 에 따르면
        # logging.getLevelName(str) 은 유지되긴 하지만 실수였다고 한다. 이를 최대한 사용하지 않기 위해 이런 방법을 이용헀다.
        log_level_int: int = logging.getLevelNamesMapping()[log_level] 
        logger.log(log_level_int,json.dumps(log_data, ensure_ascii=False).encode('utf-8'))

        return response

이상의 고민으로 구현한 코드는 fastapi-logging-example 프로젝트로 정리해두었습니다.

참고자료

API 로그에 대하여: API Logs: Everything You Need to Know

API 로그 가이드: A guide to API logs

python logging: https://docs.python.org/3/library/logging.html#module-logging

python josn logger: https://nhairs.github.io/python-json-logger/latest/

FastAPI Middleware: https://fastapi.tiangolo.com/tutorial/middleware/

FastAPI ExceptionHandler: https://fastapi.tiangolo.com/tutorial/handling-errors/

AQLAlchemy 비동기 연결 이벤트: Examples of Event Listeners with Async Engines

FastAPI log (2) -AWS EKS Fargate, 왜 Fluent Bit 인가?

개발프로브 — Thu, 30 Jan 2025 22:02:56 +0900

이 시리즈는 AWS EKS & FastAPI 환경에서 로그를 적용하는 과정을 다루고 있습니다. 전체 시리즈는 다음과 같습니다.

- FastAPI log (1) - AWS EKS Fargate 환경에서 log 를 외부시스템에 보내기

- FastAPI log (2) -AWS EKS Fargate, 왜 Fluent Bit 인가?

- FastAPI log (3) - 설계, 구현

- FastAPI log (4) - 개선하기

이전글 "AWS EKS Fargate 환경에서 log 를 외부시스템에 보내기" 에서 Fargate 내부에 Fluent Bit 에이전트가 기본적으로 설치되어 있으며, AWS가 제공하는 설정 방식에 따라 CloudWatch 등으로 로그를 전송할 수 있음을 설명했다.

그러나 클라우드 환경에서 관측 데이터(telemetry data)를 수집하여 Log Storage로 보낼 수 있는 다양한 옵션이 존재하는데, 왜 AWS는 Fluent Bit을 선택하여 Fargate에 포함시켰을까?

1. 범용 로그 수집기 비교

일반적으로 사용되는 로그 수집기들의 성능을 비교한 자료(2021년 벤치마크)를 요약하면 다음과 같다.

Fluent Bit: 적은 CPU 자원으로도 높은 효율을 보이며, 높은 부하에서도 성능 저하가 크지 않음. 단, 대용량 로그 처리 시 메모리 사용량이 증가함.
Fluentd: 대량의 로그를 안정적으로 처리하지만, CPU와 메모리 사용량이 상대적으로 높음.
Vector: 가장 뛰어난 로그 처리 성능을 보였지만, CPU 사용량이 Fluent Bit보다 2~3배 많음.

Fluentd는 Fluent Bit 및 Vector와 비교했을 때 특별한 장점이 없기 때문에 고려 대상에서 제외할 수 있다. 결국 Fluent Bit과 Vector 중 하나를 선택해야 하는데, 메모리를 더 많이 활용할 경우 Fluent Bit을, CPU를 더 많이 활용할 경우 Vector를 선택하는 것이 합리적이다.

또한, LogStash와 Promtail은 AWS와의 통합이 부족하여 비교군에서 제외되었으며, Rsyslog는 시스템 로그 수집에 초점이 맞춰져 있어 범용성이 떨어지는 것으로 판단된다.

2. Fargate에서 CPU와 메모리의 특징

앞서 메모리를 더 많이 활용할 경우 Fluent Bit을, CPU를 더 많이 활용할 경우 Vector를 선택하는 것이 적절하다는 가설을 세웠다. 이를 검증하기 위해 AWS EKS Fargate의 리소스 할당 방식을 살펴보자.

Fargate의 리소스 할당 방식

AWS Fargate는 EC2 기반이 아닌 서버리스 컨테이너 환경으로, 인스턴스를 직접 관리하지 않는다. 대신, 컨테이너별로 고정된 CPU와 메모리를 할당하는 방식이 적용된다.

CPU (vCPU)

Fargate에서는 컨테이너에 할당할 수 있는 vCPU를 정해진 옵션에서 선택해야 함.
CPU는 Burstable 방식이 아니며, 설정된 값까지만 사용 가능.
과부하 시 추가적인 CPU 자원이 자동으로 할당되지 않음.

메모리 (RAM)

컨테이너에 고정된 메모리 값을 할당.
메모리가 초과되면 OOM(Out of Memory) Kill 발생 → 프로세스 강제 종료.
하지만 CPU와 다르게 사용 가능한 메모리를 미리 충분히 할당할 수 있음.

결론

할당 가능한 vCPU	할당 가능한 메모리
0.25 vCPU	0.5GB ~ 2GB
0.5 vCPU	1GB ~ 4GB
1 vCPU	2GB ~ 8GB
2 vCPU	4GB ~ 16GB
4 vCPU	8GB ~ 30GB

Fargate는 CPU 사용량을 필요 이상으로 증가시키는 것이 불리하다. (Burstable X)
메모리는 미리 할당해놓으면 활용 가능, 하지만 초과하면 프로세스가 죽는다.
즉, CPU를 많이 쓰는 Vector는 제약을 받을 가능성이 크고, Fluent Bit처럼 메모리를 활용하는 방식이 유리할 수 있다.

따라서 AWS가 Fargate 환경에서 Fluent Bit을 기본 로깅 솔루션으로 선택한 이유는 CPU 사용량을 최소화하면서도 안정적으로 로그를 수집할 수 있기 때문이다.

참고자료

logs hipper 비교: The Top 7 Log Shippers and How to Choose One
log collector 벤치마크: Who is the winner — Comparing Vector, Fluent Bit, Fluentd performance

FastAPI log (1) - AWS EKS Fargate 환경에서 log 를 외부시스템에 보내기

개발프로브 — Thu, 30 Jan 2025 21:06:09 +0900

이 시리즈는 AWS EKS & FastAPI 환경에서 로그를 적용하는 과정을 다루고 있습니다. 전체 시리즈는 다음과 같습니다.

- FastAPI log (1) - AWS EKS Fargate 환경에서 log 를 외부시스템에 보내기

- FastAPI log (2) -AWS EKS Fargate, 왜 Fluent Bit 인가?

- FastAPI log (3) - 설계, 구현

- FastAPI log (4) - 개선하기

기존 모놀리식 서비스를 마이크로서비스 아키텍처로 전환하면서 AWS EKS(Fargate) 기반으로 운영하는 방안을 선택했습니다. 이 과정에서 Java & Spring 기반 서비스를 Python & FastAPI로 변경하는 것뿐만 아니라, EKS Kubernetes 환경에서 운영하는 방법을 익히는 것도 중요한 과제였지요.

그중 하나가 로그 수집(logging) 이었는데요. Fargate 환경에서는 DaemonSet을 사용할 수 없기 때문에, 기존 방식대로 로그 수집을 설정할 수 없었다. 이에 따라 AWS가 제공하는 Fluent Bit 기반의 로그 수집 방식을 적용해야 했습니다.

AWS EKS Fargate의 로깅 구조

Fargate Dataplane

AWS EKS를 Fargate로 운영할 때, Dataplane 내부에는 이미 Fluent Bit 에이전트가 설치되어 있다. 이를 활용하면 추가적인 로그 수집용 에이전트 없이 AWS CloudWatch 또는 S3와 같은 외부 서비스로 로그를 보낼 수 있습니다.

EKS Fargate 환경에서는 aws-logging이라는 ConfigMap을 사용하여 로그를 관리합니다. 따라서, 로그를 수집하고 외부로 전송하려면 이 ConfigMap을 올바르게 설정해야 합니다.

AWS EKS Fargate 로깅 설정 방법

1. IAM role 정책 추가

EKS 운영에는 여러 IAM Role이 필요하지만, 로깅을 위해서는 Pod Execution Role에 다음과 같은 정책을 추가해야 합니다. 이 정책은 CloudWatch에 로그를 전송할 수 있도록 해줍니다.

"Version": "2012-10-17",
"Statement": [
    {
        "Effect": "Allow",
        "Action": [
            "logs:CreateLogGroup",
            "logs:CreateLogStream",
            "logs:PutLogEvents",
            "logs:DescribeLogGroups",
            "logs:DescribeLogStreams"
        ],
        "Resource": "*"
    }
]

AWS CLI 또는 AWS Console을 사용하여 Pod Execution Role에 위 정책을 적용합니다.

2. EKS Namespace 및 ConfigMap 설정

AWS에서 제공하는 표준 스크립트를 사용하여 Fluent Bit을 설정할 수 있습니다. 이 설정을 통해 CloudWatch로 로그를 전송하며, 필요에 따라 S3 또는 외부 서비스로 변경할 수도 있습니다.

다음과 같이 aws-logging.yaml 파일을 생성합니다:

kind: Namespace
apiVersion: v1
metadata:
  name: aws-observability # 이름 변경되면 안됨
  labels:
    aws-observability: enabled # 꼭 필요!
---    
kind: ConfigMap
apiVersion: v1
metadata:
  name: aws-logging # 이름 변경되면 안됨
  namespace: aws-observability
data:
  flb_log_cw: "true"  # Fluent Bit 자체 생산 log
  filters.conf: |
    [FILTER]
        Name parser
        Match *
        Key_name log
        Parser crio
    [FILTER]
        Name kubernetes
        Match kube.*
        Merge_Log On
        Keep_Log Off
        Buffer_Size 0
        Kube_Meta_Cache_TTL 300s
  output.conf: |
    [OUTPUT]
        Name cloudwatch_logs
        Match kube.*
        region {aws_region}
        log_group_name {log_group_name} # cloudwatch log group 이름
        log_stream_prefix from-fluent-bit- # 로그 prefix
        log_retention_days 60 # 로그 보존기간
        auto_create_group true
  parsers.conf: |
    [PARSER]
        Name crio
        Format Regex
        Regex ^(?<time>[^ ]+) (?<stream>stdout|stderr) (?<logtag>P|F) (?<log>.*)$
        Time_Key    time
        Time_Format %Y-%m-%dT%H:%M:%S.%L%z

위 설정을 적용하려면 다음 명령을 실행합니다:

kubectl apply -f aws-logging.yaml

참고: AWS Fargate에서 제공하는 Fluent Bit은 [FILTER], [OUTPUT], [PARSER] 설정만 지원합니다. [SERVICE] 및 [INPUT] 설정은 사용할 수 없습니다.

3. 로그 수집 적용하기

아직 올라와있는 pod 이 없다면 이제부터 Deployment 를 올리고 pod 을 올리면 자동으로 logging 이 적용됩니다. 하지만 이미 pod 이 올라와 있다면 pod 을 재시작하는 방법을 통해 aws-logging config map 을 참조하게 할 수 있습니다.

kubectl rollout restart deployment -n <namespace>

참고자료

이제 AWS EKS Fargate 환경에서 로그 수집이 정상적으로 설정되었네요. 적용이 완료된 후, AWS CloudWatch 콘솔에서 로그 그룹을 확인하여 로그가 정상적으로 전송되고 있는지 검토할 수 있습니다.

Fluent Bit 공식 문서: What is Fluent Bit?
AWS EKS Fargate 로깅 매뉴얼: EKS Fargate Logging

FastAPI 의존성 주입, 코드를 까보자

개발프로브 — Wed, 4 Dec 2024 20:47:28 +0900

이전 글에서 FastAPI 가 제공하는 의존성 주입 기능을 알아보았다. 하지만 그정도는 어떻게 쓰는지 알아보는 정도이고 아직 풀리지 않는 궁금증이 많다.

"어떻게 Callable 만 받아들이는가?"

"서브-의존성 을 구현하는 방법은 무엇인가?"

"왜 FastAPI 경로 동작 함수(path operation function)에서만 동작하는가?"

이런 궁금증을 풀기 위해서는 직접 코드를 까보는게 최고다.

fastapi.param_functions.Depends

코드를 까본 결과 직접 FastAPI 경로 작업 함수(path opration function)에서 참조하는 Depends 는 use_caches 기능이 있었다! 그리고 내부적으로 params.Depenndes 를 호출하여 파라미터를 그대로 전달하는 동작을 한다.

def Depends(  # noqa: N802
    dependency: Annotated[
        Optional[Callable[..., Any]],
        Doc(
            """
            A "dependable" callable (like a function).

            Don't call it directly, FastAPI will call it for you, just pass the object
            directly.
            """
        ),
    ] = None,
    *,
    use_cache: Annotated[
        bool,
        Doc(
            """
            By default, after a dependency is called the first time in a request, if
            the dependency is declared again for the rest of the request (for example
            if the dependency is needed by several dependencies), the value will be
            re-used for the rest of the request.

            Set `use_cache` to `False` to disable this behavior and ensure the
            dependency is called again (if declared more than once) in the same request.
            """
        ),
    ] = True,
) -> Any:

    return params.Depends(dependency=dependency, use_cache=use_cache)

여기까지 코드를 깠을때는 내부동작을 확인하기는 어렵지만, API 작성 팁을 확인할 수 있었다.

typing_extension.py 의 Doc 이라는 클래스를 통해 더 명시적으로 파라미터에 대한 설명을 작성할 수 있다는 것이다.
함수 인수(function parameter) 에 * 를 명시한 이후의 인수는 무조건 키워드 인수(keyword parameter) 로 구성된다. 파이썬 공식 문서를 읽어보면 더 다양한 팁을 확인할 수 있다.

API 작석 팁을 배운것 좋지만 뭔가 아쉽다. Depends 가 호출하는 params.Depends 를 파고 들어가보자, 특히 use_caches 를 사용하면 어디에 캐시가 되고 어떨때 사용하는게 좋은지도 궁금해진다.

fastapi.params.Depndes

잔뜩 기대를 안고 열어본 fastapi.params.Depndes 는 단순한 class 였다. __repr__

class Depends:
    def __init__(
        self, dependency: Optional[Callable[..., Any]] = None, *, use_cache: bool = True
    ):
        self.dependency = dependency
        self.use_cache = use_cache

    def __repr__(self) -> str:
        attr = getattr(self.dependency, "__name__", type(self.dependency).__name__)
        cache = "" if self.use_cache else ", use_cache=False"
        return f"{self.__class__.__name__}({attr}{cache})"

FastAPI 의존성 주입, Depends 를 알아보자

개발프로브 — Wed, 4 Dec 2024 20:05:21 +0900

Spring 을 쓰다가 FastAPI 로 전환하면서 많은 것들이 의문이었지만 그중 가장 큰 것은 "Python 은 빌드되는게 아닌데 의존성 주입을 사용할 수 있나?" 였다. 그리고 그런 나에게 보란듯이 FastAPI 공식 문서에는 의존성 주입 파트가 있다. 이 글은 공식문서를 정독하고 정리하는 글 정도가 되겠다. 이미 어느정도 Depends 를 알고 있고, Depends 의 내부동작을 파악하고 싶다면 다음 글이 도움이 될 수도 있다.

FastAPI 의존성 주입(Dependency Injection) 정리

FastAPI는 의존성 주입(Dependency Injection, DI)을 통해 코드의 재사용성, 유지보수성, 테스트 용이성을 향상시킨다.

1. 기본 의존성 주입

FastAPI에서 기본적인 의존성을 정의하고 사용하는 방법은 다음과 같다.

1.1. 의존성 함수 정의하기

from fastapi import Depends, FastAPI

app = FastAPI()

def get_db():
    db = connect_to_db()
    try:
        yield db
    finally:
        db.close()

위 예제에서는 데이터베이스 세션을 관리하는 의존성 함수를 정의했다. yield를 사용하여 세션을 반환하고, 요청이 완료된 후 세션을 닫는 동작을 한다.

1.2. 의존성 주입 사용하기

from fastapi import Depends, FastAPI
from sqlalchemy.orm import Session

app = FastAPI()

@app.get("/items/")
def read_items(db: Session = Depends(get_db)):
    items = db.query(Item).all()
    return items

경로 작업 함수(path operation function)에서 Depends를 사용하여 get_db 의존성을 주입받는다. 이를 통해 데이터베이스 세션을 쉽게 사용할 수 있다.

1.3. 기본 사용방법 정리

일단 나는 여기까지만 파악했을 때 혼란스러웠다. 이게 뭐지? 하는 기분이었다. 그런데 놀랍게도 의존성으로 주입되는 대상이 호출 가능한 (Callable) 객체라는 점에서 Spring 과 유사점이 있다. 다만 다른 점이 있다면 FastAPI 의 의존성은 경로 작업 함수(FastAPI 인스턴스로 정의된 경로)에서만 유효하다는 점이다.

아직까지 많은 것들이 이해되지 않지만 나같은 범재는 학습할때 우선 받아들이고 넘어가는 과정이 필요하다. 우선 팩트를 그대로 받아들이고 넘어가자.

그리고 이번 예제에서는 yield 를 사용하고 있다. 의존성 주입시 yield 를 이용하여 리소스를 안전하게 관리할 수 있다는 것도 장점이다.

2. 클래스를 사용한 의존성

클래스를 사용하여 의존성을 정의하면 상태를 유지하거나 여러 메서드를 포함할 수 있다.

from fastapi import Depends, FastAPI

app = FastAPI()

class CommonQueryParams:
    def __init__(self, q: str = None, limit: int = 10):
        self.q = q
        self.limit = limit

@app.get("/items/")
def read_items(commons: CommonQueryParams = Depends(CommonQueryParams)):
    return {"q": commons.q, "limit": commons.limit}

위 예제에서는 CommonQueryParams 클래스를 의존성으로 사용하여 공통 쿼리 매개변수를 처리한다.

2.1 클래스를 사용한 의존성 정리

Python 에서 클래스는 Callable 하다는 것을 명심하자. Java 도 클래스를 new 키워드로 호출하면 기본 생성자가 호출되지 않는가? Python 도 똑같다. CommonQueryParams 클래스의 __init__ 함수가 호출되는것이다.

3. 서브-의존성

의존성은 다른 의존성을 포함할 수 있습니다. 이를 서브-의존성이라고 한다.

from fastapi import Depends, FastAPI, HTTPException, Header
from datetime import datetime
from typing import Optional

app = FastAPI()


def get_token_header(authorization: Optional[str] = Header(None)):
    """
    Authorization 헤더에서 토큰을 추출하고 검증합니다.
    헤더 형식은 'Bearer <token>'이어야 합니다.
    """
    if authorization is None:
        raise HTTPException(status_code=400, detail="Authorization header missing")
    
    try:
        scheme, token = authorization.split()
        if scheme.lower() != "bearer":
            raise HTTPException(status_code=400, detail="Invalid authentication scheme")
    except ValueError:
        raise HTTPException(status_code=400, detail="Invalid Authorization header format")
    
    if token != "expected_token":
        raise HTTPException(status_code=400, detail="Invalid Token")
    
    return datetime.now()


def get_current_user(now: datetime = Depends(get_token_header)):
    """
    현재 사용자를 반환합니다. 여기서는 단순히 요청 시각을 반환합니다.
    """
    return {"time": f"{now}"}


@app.get("/users/me")
def read_current_user(current_user: dict = Depends(get_current_user)):
    """
    현재 사용자의 정보를 반환하는 엔드포인트입니다.
    """
    return current_user

여기서 get_current_user는 get_token_header를 서브-의존성으로 사용하여 토큰 검증 후 현재 시간을 반환한다.

3.1 서브-의존성 정리

API 문서를 보자, header 로 Authorization 을 요구함을 알 수 있다.

이 요청을 보내보자

curl -X 'GET' \
  'http://127.0.0.1:8000/users/me' \
  -H 'accept: application/json' \
  -H 'Authorization: bearer expected_token'

정상적으로 처리됨을 알 수 있다.

이를 통해 서브-의존성을 통핸 의존성 체인 구성은 결국 의존성 Stack(가정이다...) 의 최상단에 있는 의존성부터 순차적으로 처리해나가고 결국 API 에서는 최상단에서 요청하는 값을 요구하게 된다. 그리고 각 의존성 함수가 수행되면서 자신을 호출한 호출자에게 반환값을 전달한다.

이정도면 의존성 체이닝이라고 부를 수도 있지 않을까?

4. 전역 의존성

전역 의존성은 애플리케이션 전체에 걸쳐 모든 경로 연산자에 적용되는 의존성이다.

from fastapi import Depends, FastAPI

app = FastAPI()

def verify_token(token: str):
    if token != "secret-token":
        raise HTTPException(status_code=400, detail="Invalid Token")
    return token

app = FastAPI(dependencies=[Depends(verify_token)])

@app.get("/protected-route/")
def protected_route():
    return {"message": "Access granted"}

위 예제에서는 verify_token 의존성을 전역 의존성으로 설정하여 모든 경로 연산자에 적용된다.

이러한 전역 의존성은 FastAPI 구현체 혹은 APIRouter 구현체에 적용할 수 있다.

4.1 전역의존성 정리

전역 의존성의 역할이 미들웨어와 다른점이 무엇인지 고민이 생기는 지점이다. 그래서 GTP 에게 물어봤다.

오픈소스 초보자의 FastAPI 기여하기

개발프로브 — Tue, 3 Dec 2024 22:21:21 +0900

회사에서 FastAPI 로 전환을 하기에 FastAPI Document 를 보면서 공부중이었다. 한국어로 번역된 문서도 있는반면 영어 그대로인 문서들도 있었다. 왜일까? 하고 찾아보던중 FastAPI Github 에서 번역활동이 진행중이며, 한국인 번역 참여자는 16명 정도라는 것을 알게 되었다.

대학생때 수업 대부분을 영어로 들었고 점수도 나쁘지 않았다는 자신감에 그 번역, 내가 하면 되는거 아닌가 하는 생각이 들었다.

1) 공부도 하고, 2) 비록 번역이지만 오픈소스에 기여도 해보고, 3) 한국어로 된 자료가 늘어나면 FastAPI 가 한국에 더 뿌리내릴수도 있고, 1석 3조의 전략이었다.

첫번째 PR 을 위한 노력

하지만 걸림돌이 하나 있었다. 오픈소스에 RP을 날리는 방법을 모른다. 그동안 Spring 코드 까본다고 Spring 소스 clone 만 해봤지 그 소스코드에 내가 무언가를 해본적은 없었다. 그래서 아래와 같이 진행했다.

1) 구글에 "How to contribute open source project in github" 검색하고 관련 글 하나 읽기

2) 내가 기여하려고 하는 프로젝트의 기여 규칙을 찾는다. (아마 90% 이상의 관련 글이 해당 프로젝트의 "룰"을 준수하라고 했을 것이다.)

3) 그래서 FastAPI 에서 한국어 번역에 관한 규칙을 찾았다. 정형화된 커밋 메시지의 패턴을 찾아내고, 관련 Discussion 에서 원래 활동하시던 번역 기여자분들의 규칙을 찾았다.

4) 이제는 Fork 를 하고 내가 번역하고자 하는 문서를 번역하면 된다.

PR 을 다 해보고 찾은 정보인데 오픈소스에 기여하는 연습을 해볼 수 있는 repository 가 있다. (부디 다른 초심자분들은 미리 찾아서 도움을 받을 수 있길 바란다.

이렇게 노력해서 올린 첫번째 PR 은 내가 스스로 Close 했다. 의욕이 너무 앞서서 번역한 2개의 문서를 하나의 PR 에 묶어버린 것이다.

그리고 다시 작업을 했고, 두번째 PR 은 리뷰를 받고 최종적으로 Merge 까지 될 수 있었다.

두번째 PR 의 리뷰어분께서 찾아주신 오류는 2개의 사소한 오류였다. 번역 규칙을 찾아보고 적용하고자 했던 노력이 빛을 발한것 가아 뿌듯했다.

첫번째 Review 를 위한 노력

두번째 PR 이 Merge 가 된 이후 세번째 PR 을 올렸다. 내가 평소에 중요하게 생각하는 테스트에 대한 내용이어서 즐겁게 번역했다.

그런데 지난번엔 PR 요청을 보내고 7일 뒤에 리뷰를 받았었는데, 이번엔 14일이 다 지나도록 리뷰가 안되는 것이었다.

어떡할지 고민하다가 다른 한국어 번역 기여자 분이 PR 올린게 있어서 봤다. 이분의 PR 도 아직 리뷰를 받지 못하고 있었다. 그러다 문뜩 Discuss 에서 봤던 말이 떠올랐다. '한국어 번역을 리뷰할 수 있는 자격은 굳이 따지자면 한국어 네이티브 정도입니다. 활발히 리뷰해주세요' 이런 내용이었다.

그럼 나도 리뷰 할 수 있나? 하는 생각이 들어서 변경된 파일(Files changed) 버튼을 눌렀다. 역시나 리뷰가 가능했다. 마침 나의 두번째 PR 을 리뷰해주셨던 분이었기에 정성스럽게 리뷰해야겠다는 생각이 들었다.

번역 규칙 준수는 문제가 없었지만 번역이 애매한 용어가 나왔다. 나는 관련 영어문서에서 유사한 단어가 있는지 찾아보고 해당 문서를 번역한 기존 한국어 문서에서는 어떻게 다뤘는지 파악한 뒤 리뷰를 할 수 있었다.

첫번째 오픈소스 기여를 해본 소감

- 마음먹으면 바로 해보자, 만약 오픈소스에 어떻게 기여하는지 모르니까 다음에 하자 했으면 이런 경험을 못해봤을 것이다.

- 오픈소스 규칙을 잘 따르지 않는 사람이 생각보다 많다. 그리고 그들에게 아무도 심한 말을 하지 않는다. 기본적인 매너를 지키는 선에서 일단 도전해보자.

- 번역이라고 할지라도 PR 이나 리뷰를 하면서 공부에 많이 도움이 된다. 특히 리뷰같은 경우는 기존 영어문서, 한글문서를 모두 읽어야 의미있는 리뷰가 가능했기에 더욱 값진 경험이었다.

- 오픈소스를 주로 관리하는 사람이 있는것 같다. 거의 bot 마냥 PR 들에 태그를 붙이는 사람이 있는데...열정이 대단하다.

- Github 이라는 플랫폼을 다시 보게된것 같다. 이제는 관심있는 Repository 에 별표시를 하고 주기적으로 보게되었다. 세상엔 멋진 프로젝트가 많다.

FastAPI: fastapi-permissions 를 이용한 접근제어

개발프로브 — Sun, 1 Dec 2024 17:58:16 +0900

fastapi-permissions

fastapi-permissions는 Pyramid 프레임워크의 Pyraid Securiy 기능에서 영감을 받아 만들어진 라이브러리이다. 2024년 12월 기준으로 마지막 업데이트가 4년 전이어서 최신 FastAPI와의 호환성에 의문이 들지만, 접근 방식이 흥미로워 살펴보게 되었다.

fastapi-permissions 가 갖는 주요 철학과 개념, 내구 동작 방식을 살펴본다.

1. 주요 철학

fastapi-permissions 가 FastAPI security 와는 다른 점은 scope 로 접근을 제어하는게 아니라 더 저수준에서 세밀하게 접근을 제어한다는 것이다. 그에따라 접근자의 권한뿐만 아니라 접근 하려하는 리소스의 상태에 따라서도 접근을 제어할 수 있다.

2. 주요 개념

FastAPI에는 기본적으로 제공되지 않는 4가지 새로운 개념이 도입되었다.

Resource (리소스): 관리 대상 엔티티, Access Control List 를 제공한다.
ACL (Access Control List, 접근 제어 리스트): 리소스별 권한 규칙 집합, (액션, 주체, 권한) 들의 집합이다.
Principals (주체): 사용자 및 그룹, 정의에 제한을 두지 않는다.
Permissions (권한): 리소스에서 수행할 수 있는 작업, 정의에 제한을 두지 않는다.

주요개념들의 이름과 역할만 들어서 어떤식으로 접근제어를 하는지 감이 잡힌다. "특정 리소스의 권한 규칙이 있을때, 접근 주체가 권한을 가지고 있는지 검증한다."

2.1. Resource & ACL

이 예시에서 관리대상 엔티티(Resource)는 User 이다. User 클래스에 __acl__을 구현하였다.

from typing import List
from fastapi_permissions import Allow, Authenticated

# 사용자 데이터 모델 (ACL 포함)
class UserInDB:
    def __init__(self, id: int, email: str, full_name: str, roles: List[str]):
        self.id = id
        self.email = email
        self.full_name = full_name
        self.roles = roles

    def __acl__(self):
        return [
            (Allow, Authenticated, "view"),
            (Allow, f"user:{self.id}", ("edit", "delete")),
            (Allow, "role:admin", ("view", "edit", "delete")),
        ]
    
user_db: List[UserInDB] = [
    UserInDB(id=i, email=f"mail{i}@gmail.com", full_name=f"name_{i}", roles=["user"]) for i in range(10)
]

2.2. Principl & Permissions

구현된 접근 제어 리스트(acl) 이 반환하는 tuple 중 하나를 접근 제어 항목(Access Control Item) 이라고 부르겠다. 하나의 접근제어 항목은 다음과 같이 구성되어 있다.

(액션, 주체(Principal), 권한(Permission)), 따라서 (Allow, Authenticated, "view") 라는 접근 제어 항목은 어떤 방식으로든 Authenticated 되었다고 판단된 주체는 "view" 권한이 허가(Allow) 된다는 것을 의미한다.

각각의 항목을 조금 자세히 살펴보면,

액션: Allow 혹은 Deny 가 가능하다.
주체: 라이브러리에서 이미 정해놓은 EveryOne, Authenticated 를 제외한 나머지는 개발자가 정의하여 넣을 수 있다.
권한: 라이브러리에서 정해진게 없다. 개발자가 원하는대로 설정할 수 있다.

2.3 에제 코드

순서상 주요객체와 함수를 설명해야겠지만 개인적으로 새로운 내용을 학습하고나서 그게 구현된 코드를 보는게 도움이 되었다. 그래서 이상의 개념들을 활용해서 간단한 API 와 접근제어를 구현하였다. 유저 정보를 DB 에서 읽어와서 pydantic model 로 변환하여 반환하는 것처럼 동작하는 GET 엔드포인트 하나다.

아래 코드를 직접 python 파일에 넣고 필요한 의존성을 설치한 뒤 http://localhost:8000/users/1 등을 해보면 유저의 정보가 조회되는 것을 확인할 수 있다.

from typing import List, Optional

from fastapi import FastAPI, HTTPException, status
from fastapi_permissions import Allow, Authenticated, configure_permissions, Everyone
from pydantic import BaseModel


# 사용자 데이터 모델 (ACL 포함)
class UserInDB:
    def __init__(self, id: int, email: str, full_name: str, roles: List[str]):
        self.id = id
        self.email = email
        self.full_name = full_name
        self.roles = roles

    def __acl__(self):
        return [
            (Allow, Authenticated, "view"),
            (Allow, f"user:{self.id}", ("edit", "delete")),
            (Allow, "role:admin", ("view", "edit", "delete")),
        ]

# 사용자 읽기 모델 (Pydantic)
class UserRead(BaseModel):
    id: int
    email: str
    full_name: str
    roles: List[str]

# 데이터베이스 시뮬레이션
user_db: List[UserInDB] = [
    UserInDB(id=i, email=f"mail{i}@gmail.com", full_name=f"name_{i}", roles=["user"]) for i in range(10)
]

# 사용자 인증 및 주체(principals) 생성
def get_active_principals(user_id: int) -> List[str]:
    # 데이터베이스에서 사용자 조회
    user = next((u for u in user_db if u.id == user_id), None)
    if user:
        principals = [Everyone, Authenticated, f"user:{user.id}"] + [f"role:{role}" for role in user.roles]
        principals.extend(getattr(user, "principals", []))
    else:
        principals = [Everyone]

    return principals

# 특정 사용자 리소스 반환
def get_user_resource(user_id: int) -> Optional[UserInDB]:
    user = next((u for u in user_db if u.id == user_id), None)
    if not user:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail="User not found",
        )
    return user

# 권한 검사 시스템 설정
Permission = configure_permissions(get_active_principals)

# FastAPI 앱 초기화
app = FastAPI()

# 사용자 정보 조회 엔드포인트
@app.get("/users/{user_id}", response_model=UserRead)
async def get_user(
    user: UserInDB = Permission("view", get_user_resource),
):
    return UserRead(**user.__dict__)

get_active_principals(user_id: int)는 user_id 가 user_db 리스트에 있으면 user 정보를 활용해 principal 을 생성해 반환한다.

get_user_resource(user_id: int) 는 user_id 가 user_db 리스트에 있으면 user 정보를 반환한다.

그리고 아직 뭔지 모르는 Permission 이라는 객체는 configure_permissions(get_active_principals) 를 통해 생성되더니, 엔드포인트 파라미터에서는 객체 자체를 주입하고 "view" (요구되는 permission 일 것이다) 와 get_user_resource 를 이용해 구현체를 반환한다.

적절한 유저 정보를 반환한다는 사실과, get_active_principals 가 EveyOne 만 반환하게 바꾸면 엔드포인트가 403을 반환하다는 사실에 기반하여 어떤식으로든 Permission 객체는 user_id 를 읽어와서 get_user_resource 와 get_active_principals 를 호출하여 접근 제어와 유저정보 반환을 모두 수행한다는 것을 추측할 수 있다.

이제 직관적인 흐름이 그려졌다. 이제 세부적으로 파고들어가서 어떻게 이런 일이 가능한건지 알아보자.

3. fastapi-permission 내부동작 파헤치기

내부 동작을 세부적으로 파고들기에 앞서 결론부터 요약하자면 configure_permissions 함수를 통해 만들어낸 Permissions 이라는 객체는 내부적으로 has_permission 을 호출하여 접근주체(principal) 자원(resource)에 접근권한(permission) 이 있는지 체크하는 것으로 동작한다. 이때 fastapi 에서 제공하는 Depends 를 활용하여 동작을 추상화한다.

fastapi-permissions 동작 요약

이제 fastapi-permissions 라이브러리 README.md 에서 언급한 함수와 객체 위주로 코드를 까보자

3.1. 주요 객체와 함수

has_permissions(principals, permission, resource):

주어진 사용자(principals)가 특정 자원(resource) 에 대한 권한(permission)이 있는지 검사하여 True/False 를 반환한다.

list_permissions(princiapals, resource):

주어진 사용자(principals)가 특정 자원(resource) 에 대해 가질 수 있는 모든 권한(permission)을 반환다. dict를 반환한다.

Permission:

FastAPI 경로(Path Operation)에서 Depends 를 사용하여 권한 검사를 간단히 처리할 수 있도록 도와주는 의존성 객체이다.

내부적으로 이미 Depends 로 감싸져있기 때문에 별도로 Depneds 를 설정할 필요는 없다.

명시적으로는 confiture_permissions() 를 이용하여 생성하고, 내부적으로는 permission_dependency_factory() 가 생성한 함수를 사용하여 동작한다.

permission_dependency_factory(permission, resource, active_principals_func, permission_exception):

권한 검사를 위한 FastAPI 의존성(dependency)을 생성한다.

내부적으로 principals 와 resource 를 가져와 has_permissions() 를 호출하여 권한을 검사한다.

사용자(principals) 이 접근 권한이 없다고 판단되면 permission_exception 을 일으킨다. (default 값 변경가능)

configure_permissions(active_principals_func, permission_execption):

permission_dependency_factory 를 단순화한 버전이다.

대략적으로 살펴봤을때 중요한 역할을 하는 함수는 permission_dependency_factory() 와 configure_permissions() 으로 보인다. 이들을 중점적으로 살펴보자

3.2. permission_dependency_factory():

소스코드를 까보자

def permission_dependency_factory(
    permission: str,
    resource: Any,
    active_principals_func: Any,
    permission_exception: HTTPException,
):
    if callable(resource):
        dependable_resource = Depends(resource)
    else:
        dependable_resource = Depends(lambda: resource)

    # to get the caller signature right, we need to add only the resource and
    # user dependable in the definition
    # the permission itself is available through the outer function scope
    def permission_dependency(
        resource=dependable_resource, principals=active_principals_func
    ):
        if has_permission(principals, permission, resource):
            return resource
        raise permission_exception

    return Depends(permission_dependency)

검사할 권한(permission) 과 대상 자원(resource)를 전달받아서 의존성 주입을 받도록 만들고, 전달받은 접근자 정보를 얻는 방법(active_principals_func)를 활용하여 has_permission 으로 권한을 검사하는 permission_dependency 라는 함수를 정의하여 반환한다.

위의 예제코드에서 get_user_resource 가 의도한대로 동작할 수 있었던 이유는 FastAPI 엔드포인트에 의존성 (Depends) 으로 설정되어 주입됐기 때문이다.

그렇다면 active_principals_func 는 어떻게 그게 가능했을까? 이 함수는 FastAPI 의존성(Depends) 으로 선언되어 있지 않다.

그 비밀은 다음에 자세히 살펴볼 configure_permissions() 함수에 있다.

3.3. configure_permissions():

confiture_permissions() 는 permission_dedendency_factory 를 쉽게 사용하는 편의 함수정도로 얘기했지만 사실 중요한 차이가 있다. 바로 configure_permissions() 를 이용해야 active_principals_func 에 의존성(Depends)이 설정된다는 것이다.

def configure_permissions(
    active_principals_func: Any,
    permission_exception: HTTPException = permission_exception,
):

    active_principals_func = Depends(active_principals_func)

    return functools.partial(
        permission_dependency_factory,
        active_principals_func=active_principals_func,
        permission_exception=permission_exception,
    )

이제 위의 예제코드에서 필요한 부분만 짤라서 살펴보자, 각 주석에 자세히 설명되어 있다.

# 권한 검사 시스템 설정, 이때 넘긴 get_active_principals 함수는 FastAPI 의존성으로 설정된다.
# Permission 객체는 permission_dependency_factory() 를 functuools.partial 에 의해 호출하는 callable 객체이다.
# functuools.partial 덕분에 외부 클로저를 활용할 수 있어서 Permission 객체에는 permission: str, resource: Any 만 전달하면 된다.
Permission = configure_permissions(get_active_principals)

app = FastAPI()

# 사용자 정보 조회 엔드포인트
@app.get("/users/{user_id}", response_model=UserRead)
async def get_user(
    user: UserInDB = Permission("view", get_user_resource),
):
	# Permission 을 호출함으로써 get_user_resource 는 FastAPI 의존성으로 설정되었다.
    # 내부적으로 get_active_principals 함수와 get_user_resource 함수가 돌아가고 
    # has_permission 을 통해 "view" 권한이 있는지 검사한다.
    return UserRead(**user.__dict__)

MSA 주요 패턴: 중앙화된 로그 집계 패턴

개발프로브 — Wed, 27 Nov 2024 00:40:29 +0900

1. 중앙화된 로그 집계 패턴이란?

마이크로서비스 아키텍처(MSA)는 독립적인 서비스로 구성되기 때문에 서비스별로 로그를 개별적으로 수집하면 문제를 추적하거나 디버깅하는 과정에서 복잡성과 비효율이 증가하기 마련이다. 중앙화된 로그 집계 패턴은 이러한 문제를 해결하기 위해, 분산된 서비스의 로그를 한 곳으로 수집하고, 분석 및 검색이 용이하도록 중앙화된 로그 시스템을 구축하는 전략이다.

2. 왜 중앙화된 로그 집계가 필요한가?

2.1. MSA 환경에서의 로그 관리의 어려움

1 서비스 분산:

MSA 환경에서는 수십에서 수백 개의 마이크로서비스가 각각 독립적으로 로그를 생성한다.
이러한 로그를 각 서비스에서 확인하려면 많이 번거로워서 에러 발생 원인을 빠르게 찾기 어려워진다.

2 장애 원인 추적:

서비스 간 호출이 복잡해질수록, 장애의 원인을 파악하기 어려워진다.
예를 들어, 주문 서비스에서 발생한 문제의 원인이 결제 서비스나 인증 서비스일 수 있다.

3 로그 포맷과 구조의 다양성:

각 서비스가 서로 다른 언어, 프레임워크, 라이브러리를 사용할 경우, 로그 포맷이 일관되지 않을 수 있다.

2.2. 중앙화된 로그 집계의 장점

위의 필요에 의해 등장한 것이 중앙화된 로그 집계 패턴이기 때문에 장점이 대응된다.

빠른 문제 진단: 모든 서비스의 로그를 한곳에서 조회할 수 있으므로, 장애 원인을 신속히 파악할 수 있다.
일관된 로그 분석: 중앙화된 로그 시스템은 공통 포맷으로 데이터를 통합하여 검색 및 분석이 용이하다.
확장성 및 모니터링: 로그를 수집하고 분석하여 실시간 모니터링 및 알림 설정이 가능하다.
규제 준수 및 감사: 로그 데이터를 중앙에서 관리하면 보안 및 규제 준수 요건을 충족하기가 더 쉽다..

3. 중앙화된 로그 집계 아키텍처

3.1. 구성 요소

1 로그 수집기: 각 서비스의 로그를 수집하여 중앙 로그 시스템으로 전송. (eg. Filebeat, Fluentd, Logstash)

2 중앙 로그 저장소: 수집된 로그를 저장하는 장소. (eg. Elasticsearch, Amazon S3)

3 로그 분석 및 시각화 도구: 저장된 로그를 분석하고 시각화. (eg. Kibana, Grafana, Datadog)

4 알림 및 모니터링: 특정 조건(에러 발생, 트래픽 급증 등)을 감지하여 알림을 발송. (eg.PagerDuty, Slack)

4. 중앙화된 로그 집계 구현 시 고려사항

1. 성능: 로그 수집기가 과도한 부하를 유발하지 않도록 설계, 로그 전송 속도와 중앙 저장소의 처리 속도를 최적화.

2. 보안: 로그 데이터에 민감한 정보(예: 사용자 데이터, 인증 토큰)가 포함되지 않도록 마스킹 또는 필터링, 로그 저장소에 접근 제어.

3. 데이터 보존 정책: 로그 데이터를 무기한 저장하면 비용이 증가하므로, 적절한 보존 기간 설정(예: 30일, 90일).

MSA 전환을 위한 서비스 분리 전략

개발프로브 — Tue, 26 Nov 2024 23:18:59 +0900

회사에서 Monolith 로 개발해오던 프로젝트들을 MSA 로 옮겨간다고 한다. 내가 맡아서 개발해온 프로젝트의 도메인 지식은 내가 가장 잘 알고 있다보니 이 프로젝트 만큼은 내가 도메인 분리를 맡게 될 것 같다...그래서 공부중이다.

서비스 분리 전략 3가지 Key Point

단계적으로 마이그레이션 한다.
처음에는 크게 분리하고 추후 작게 분리한다.
서비스 분리를 깔끔하게 나눠주는 마법같은 공식은 없다. (이 부분이 너무 슬펐다.)

서비스 분리 8가지 원칙

첫 번째 원칙: 작고 분리가 쉬운 서비스로 워밍업

간단한 서비스를 분리하며 역량을 내재화.
신규 개발 기능이나 내부 의존성이 적고, 중요도가 낮은 기능부터 시작.
Pilot 서비스 분리의 기준:
- 내부 의존성이 낮은 기능(Core 의존성, 데이터 의존성 적음).
- 장애 발생 시 시스템 전체에 영향이 적은 기능.
- Fallback 처리 가능한 기능.
- 테이블 크기가 작고 데이터가 적은 기능.

두 번째 원칙: 핵심 기능의 분리 원칙

워밍업 이후 핵심 기능 분리를 고려.
핵심 기능 분리의 어려움:
- 결합도가 높고, 도메인 경계가 명확하지 않음.
핵심 기능 분리 전략:
- 도메인 정의: 이벤트 스토밍으로 Sub-Domain 및 Bounded Context 발견.
- 의존성 분석: 정적 분석 도구(Structure101, Stan4J 등) 활용.
- 조직 기반 분리: 비즈니스 팀 구조와 일치하는 서비스 경계를 설정.

세 번째 원칙: 데이터 분리의 원칙

서비스 간 결합도를 최소화하기 위해 데이터베이스 분리가 필수.
Anti-Pattern:
- 서비스 간 공유 데이터베이스 사용.
데이터 분리 전략:
- 저장소 및 데이터 마이그레이션 전략 수립.
- 서비스별 독립적인 데이터 소유.

네 번째 원칙: 분리 대상 선정의 원칙

분리 대상 선정 질문:
- 가장 문제가 되는 기능은 무엇인가?
- 비즈니스 요구사항 변경이 잦은 기능은 무엇인가?
- 잦은 코드 수정으로 배포를 유발하는 기능은 무엇인가?
- 트래픽이 몰려 유연한 확장이 필요한 기능은 무엇인가?
분리 대상 선정 방법:
- 코드 커밋 히스토리 분석.
- 프로젝트 로드맵 기반으로 선정.

다섯 번째 원칙: 코드의 재사용 vs 재개발

기존 코드 재사용:
- 기술 부채가 많아 비효율적일 가능성.
- 오래된 기술 스택으로 Boilerplate Code가 많음.
재개발의 장점:
- 도메인 요구사항 재정의 가능.
- 기술 부채 해결 및 새로운 기술 스택 도입.

여섯 번째 원칙: 진화적인 서비스 분리

서비스 크기 결정의 원칙:
- Go Macro, then Micro: 먼저 크게 분리, 이후 필요에 따라 세분화.
- 지나치게 작은 서비스는 인프라 복잡도 증가.
- Two Pizza Team, 독립 배포 가능성, 2주 내 재작성 가능 수준.

일곱 번째 원칙: 반복/점진적 분리

Strangler Pattern:
- 기존 시스템을 유지하며 새로운 기능을 마이크로서비스로 개발.
- 점진적으로 Monolith를 대체.

여덟 번째 원칙: MSA와 신기술 도입

MSA는 혁신과 실험을 가능하게 하지만, 초기 도입 시 신기술 적용은 신중해야 함.
충분한 역량 내재화 후 점진적으로 신기술 도입.

결론

MSA 전환은 단순히 기술적인 변화가 아니라, 비즈니스와 기술을 통합적으로 고려해야 하는 전략적 과정입니다. 단계적이고 점진적인 접근, 도메인 중심 설계, 데이터 분리, 그리고 팀 구조와의 연계를 통해 성공적인 MSA 전환을 이룰 수 있다.

참고자료: 샘 뉴먼의 Building MicroServices (책)

참고자료: monolith into microservice (블로그)

참고자료: Straingler pattern (블로그)

Terraform AWS: VPC 만들기

개발프로브 — Sun, 24 Nov 2024 23:20:46 +0900

Terraform 을 이용하여 로컬 리소스를 다루는것도 의미가 있겠으나, 내가 Terraform 을 알아보기 시작한 이유는 클라우드 인프라를 재사용가능한 효율적인 형태로 다루고 싶기 때문이었다.

그 첫번째로 AWS 의 기본 리소스중 하나인 VPC 를 만들어보겠다.

AWS VPC

우선 지금부터 만들려고하는 AWS VPC 에 대한 개념과 이를 구성하는 세부 요소에 대해서 알아보고 왜 많고 많은 AWS 인프라 중에서 VPC 를 먼저 만들려고하는지 알아보자

VPC(Virtual Private Cloud) 란 AWS 클라우드 내에서 자신의 네트워크를 "논리적" 으로 격리하여 정의할 수 있는 가상 네트워크이다. 인터넷에 노출되면 안되는 리소스를 격리하여 보안에 필수적이며, 보안 그룹과 네트워크 ACL 를 활용하여 더욱 보안성을 높일 수 있다.

VPC 는 가용 영역(AZ)이 아닌 Region 에 속하므로 여러 가용 영역에 걸쳐 네트워크를 확장할 수도 있다.

여러 서비스를 하나의 네트워크 망에서 다룰게 아니라면 만들려고 하는 AWS 리소스의 네트워크를 먼저 정의하는 것은 필수 과정일 것이다.

VPC의 구성 요소

간단하게 구성된 VPC

1. 서브넷 (Subnet)

서브넷은 VPC 내에서 IP 주소 범위를 더 세분화한 논리적 단위이다. VPC는 여러 서브넷으로 나뉠 수 있으며, 각 서브넷은 특정 가용 영역에 연결된다.

특징:
- 퍼블릭 서브넷: 인터넷 게이트웨이와 연결되어 외부 인터넷과 통신 가능.
- 프라이빗 서브넷: NAT 게이트웨이 등을 통해 간접적으로 인터넷에 액세스 가능.
용도:
- 퍼블릭 서브넷: 웹 서버, 로드 밸런서와 같이 외부 인터넷과 통신이 필요한 리소스 배치.
- 프라이빗 서브넷: 데이터베이스, 애플리케이션 서버와 같이 내부적으로만 접근 가능한 리소스 배치.

2. 라우팅 테이블 (Route Table)

라우팅 테이블은 네트워크 트래픽의 경로를 정의하는 규칙의 집합이다. 서브넷은 반드시 라우팅 테이블과 연결되어야 하며, 이를 통해 트래픽이 어디로 전달될지 결정된다.

구성:
- 기본 라우트: local로 설정된 라우트는 VPC 내의 모든 서브넷 간 통신을 허용.
- 추가 라우트: 특정 목적지(CIDR)로 트래픽을 보내기 위해 IGW, NGW, VPN, Direct Connect 등을 지정.
용도:
- 퍼블릭 라우팅 테이블: 트래픽이 인터넷 게이트웨이(IGW)를 통해 외부 인터넷으로 이동하도록 설정.
- 프라이빗 라우팅 테이블: 트래픽이 NAT 게이트웨이(NGW)를 통해 인터넷에 간접적으로 연결되도록 설정.

3. 인터넷 게이트웨이 (Internet Gateway, IGW)

인터넷 게이트웨이는 VPC와 외부 인터넷 간의 통신을 가능하게 하는 네트워크 컴포넌트이다.

특징:
- VPC당 하나의 IGW만 연결 가능.
- 퍼블릭 서브넷과 연결된 리소스가 인터넷에서 액세스 가능하도록 지원.
용도:
- 퍼블릭 서브넷의 리소스(예: EC2 인스턴스)가 인터넷과 양방향으로 통신할 수 있도록 설정.
- 일반적으로 웹 서버, API Gateway 등 외부와 직접 통신해야 하는 리소스에서 사용.

4. NAT 게이트웨이 (Network Address Translation Gateway, NGW)

NAT 게이트웨이는 프라이빗 서브넷의 리소스가 인터넷과 통신할 수 있도록 하지만, 외부에서 프라이빗 리소스를 직접적으로 액세스하지 못하도록 하는 역할을 한다.

특징:
- 퍼블릭 서브넷에 배치되며, Elastic IP를 사용.
- 프라이빗 서브넷에서 오는 요청을 NAT 게이트웨이가 대행하여 외부와 통신.
용도:
- 프라이빗 서브넷의 리소스(예: 데이터베이스, 애플리케이션 서버)가 소프트웨어 업데이트나 외부 API 호출을 위해 인터넷과 통신할 때 사용.
- 외부로부터의 직접적인 트래픽은 차단.

Terraform 으로 VPC 만들기

1. AWS CLI 준비

근본적인 질문이 있다. Terraform 은 내 컴퓨터에서 돌아가고 결국 AWS 에서 제공하는 API 를 호출할텐데 이러한 API 호출에 대한 인증,인가를 어떻게 이뤄지는 걸까? Terraform 안에 AWS credential 정보를 넣어야 하는걸까?

물론 Terraform 스크립트 안에 AWS credential 정보를 넣을 수도 있을 것이다. 하지만 그렇게 한다면 과연 이 스크립트를 팀내에서, 혹은 외부와 공유할 수 있을까?

그래서 등장하는게 AWS CLI 이다. AWS CLI 를 이용하면 터미널에서 AWS API 를 이용하여 클라우드 인프라를 생성, 삭제, 조회 할 수 있으며, 무엇보다 aws configure 명령어를 통해 지금부터 요청을 보내려고하는 IAM role 을 정해줄 수 있다.

굳이 로컬 작업 환경이 아니더라도 github action 에서는 별도 설치없이 AWC CLI 를 이용할 수 있는 등 CI/CD 에서 자주 이용하게 된다.

2. 기본 Terraform 구조

어떤 변수 없이, 그저 static 하게 main.tf 하나로도 AWS VPC와 subent 을 public 과 private 로 나누고 라우트 테이블을 분리하여 인터넷 게이트웨이와 네트워크 게이트웨이로 라우팅하도록 만들 수 있다.

main.tf 는 다음과 같다.

provider "aws" {
  region = "ap-northeast-2"
}

# VPC 생성
resource "aws_vpc" "my_vpc" {
  cidr_block           = "10.0.0.0/16"
  enable_dns_support   = true
  enable_dns_hostnames = true
  tags = {
    Name = "my-vpc"
  }
}

# 인터넷 게이트웨이 생성
resource "aws_internet_gateway" "my_igw" {
  vpc_id = aws_vpc.my_vpc.id
  tags = {
    Name = "my-igw"
  }
}

# 퍼블릭 서브넷 생성
resource "aws_subnet" "public_subnets" {
  count = 3
  vpc_id                  = aws_vpc.my_vpc.id
  cidr_block              = cidrsubnet("10.0.0.0/16", 4, count.index) # /20 서브넷 생성
  availability_zone       = ["ap-northeast-2a", "ap-northeast-2b", "ap-northeast-2c"][count.index]
  map_public_ip_on_launch = true
  tags = {
    Name = "public-subnet-${count.index + 1}"
  }
}

# 프라이빗 서브넷 생성
resource "aws_subnet" "private_subnets" {
  count = 3
  vpc_id            = aws_vpc.my_vpc.id
  cidr_block        = cidrsubnet("10.0.0.0/16", 4, count.index + 3) # /20 서브넷 생성
  availability_zone = ["ap-northeast-2a", "ap-northeast-2b", "ap-northeast-2c"][count.index]
  tags = {
    Name = "private-subnet-${count.index + 1}"
  }
}

# NAT 게이트웨이 생성
resource "aws_eip" "ngw_eip" {
  domain = "vpc"
  tags = {
    Name = "ngw-eip"
  }
}

resource "aws_nat_gateway" "nat_gateway" {
  allocation_id = aws_eip.ngw_eip.id
  subnet_id     = aws_subnet.public_subnets[0].id # 첫 번째 퍼블릭 서브넷에 배치
  tags = {
    Name = "nat-gateway"
  }
}

# 퍼블릭 라우팅 테이블 생성
resource "aws_route_table" "public_route_table" {
  vpc_id = aws_vpc.my_vpc.id
  tags = {
    Name = "public-route-table"
  }
}

# 퍼블릭 라우팅 테이블에 IGW 추가
resource "aws_route" "public_route" {
  route_table_id         = aws_route_table.public_route_table.id
  destination_cidr_block = "0.0.0.0/0"
  gateway_id             = aws_internet_gateway.my_igw.id
}

# 퍼블릭 서브넷과 퍼블릭 라우팅 테이블 연결
resource "aws_route_table_association" "public_associations" {
  count          = 3
  subnet_id      = aws_subnet.public_subnets[count.index].id
  route_table_id = aws_route_table.public_route_table.id
}

# 프라이빗 라우팅 테이블 생성
resource "aws_route_table" "private_route_table" {
  vpc_id = aws_vpc.my_vpc.id
  tags = {
    Name = "private-route-table"
  }
}

# 프라이빗 라우팅 테이블에 NAT 게이트웨이 추가
resource "aws_route" "private_route" {
  route_table_id         = aws_route_table.private_route_table.id
  destination_cidr_block = "0.0.0.0/0"
  nat_gateway_id         = aws_nat_gateway.nat_gateway.id
}

# 프라이빗 서브넷과 프라이빗 라우팅 테이블 연결
resource "aws_route_table_association" "private_associations" {
  count          = 3
  subnet_id      = aws_subnet.private_subnets[count.index].id
  route_table_id = aws_route_table.private_route_table.id
}

3. static한 방식의 문제점, cidr 중복

하지만 이렇게 VPC 리소스를 생성하면 결정적인 문제가 생긴다. 우선 재사용이 불가능하다는 것이다. 왜일까?

AWS CLI 가 연결되어 있다면 이런 커맨드를 입력해보자

1. VPC 조회

aws ec2 describe-vpcs --query "Vpcs[*].[VpcId, CidrBlock, Tags[?Key=='Name'].Value | [0]]" --output table

이런 결과를 반환한다. 원래 AWS 에서 기본으로 제공해주던 VPC 외에 위의 스크립트 때문에 생성된 my-vpc 가 보인다. 이 vpc 의 id를 이용하여 subent 들을 조회할 수 있다.

2. 특정 VPC 의 subent 조회

새롭게 생성한 my-vpc 의 subent 들을 조회해보겠다.

aws ec2 describe-subnets \
    --filters "Name=vpc-id,Values={VPC_ID}" \
    --query "Subnets[*].[SubnetId, AvailabilityZone, MapPublicIpOnLaunch, CidrBlock]" \
    --output table

문제점이 보이는가? 바로 위 스크립트에 명시했던 subent 이 규칙에 따라 생성된것이 확인된다. subent 리소스를 생성한 규칙을 다시 보겠다.

resource "aws_subnet" "public_subnets" {
  count = 3
  vpc_id                  = aws_vpc.my_vpc.id
  cidr_block              = cidrsubnet("10.0.0.0/16", 4, count.index) # /20 서브넷 생성
  availability_zone       = ["ap-northeast-2a", "ap-northeast-2b", "ap-northeast-2c"][count.index]
  map_public_ip_on_launch = true
  tags = {
    Name = "public-subnet-${count.index + 1}"
  }
}

resource "aws_subnet" "private_subnets" {
  count = 3
  vpc_id            = aws_vpc.my_vpc.id
  cidr_block        = cidrsubnet("10.0.0.0/16", 4, count.index + 3) # /20 서브넷 생성
  availability_zone = ["ap-northeast-2a", "ap-northeast-2b", "ap-northeast-2c"][count.index]
  tags = {
    Name = "private-subnet-${count.index + 1}"
  }
}

이 리소스 생성의 행심은 cidrsubent 이다. cidrsubent 함수는 CIDR 블록을 분할 및 하위 네트워크 생성에 사용된다. 여기서는 VPC 의 cidr_block 을 "10.0.0.0/16" 로 정했기 때문에 이를 기준으로 새로운 하위 네트워크를 생성하도록 하였다. 즉, 다음에 다른 Terraform 작업 공간에서 이 스크립트를 다시 이용할때 겹치지 않는 cidr 을 subent 에 부여한다는 것을 보장할 수도 없으며 무엇보다 VPC 의 cidr_block 이 겹치는 문제가 발생한다.

3.1 cidr 중복 문제의 해결

기존 vpc 와 subent 의 cidr 을 읽어와서 처리하면 해결될 수 있는 문제이다. main.tf 제일 윗 부분을 이렇게 바꾸로

# 기존 VPC 확인
data "aws_vpcs" "existing_vpcs" {}

# 기존 VPC CIDR 블록 가져오기
data "aws_vpc" "vpc_details" {
  count = length(data.aws_vpcs.existing_vpcs.ids)
  id    = data.aws_vpcs.existing_vpcs.ids[count.index]
}

# 기존 서브넷 CIDR 가져오기
data "aws_subnets" "existing_subnets" {}

data "aws_subnet" "subnet_details" {
  count = length(data.aws_subnets.existing_subnets.ids)
  id    = data.aws_subnets.existing_subnets.ids[count.index]
}

# 동적 CIDR 계산
locals {
  base_cidr      = "10.0.0.0/8" # CIDR 블록 기본 값
  existing_cidrs = concat(
    [for vpc in data.aws_vpc.vpc_details : vpc.cidr_block],
    [for subnet in data.aws_subnet.subnet_details : subnet.cidr_block]
  )
  new_vpc_cidr = cidrsubnet(local.base_cidr, 8, length(local.existing_cidrs)) # CIDR 범위 /16~ 사용
}

aws_vpc 와 aws_subent 을 생성하는 블록을 변경하자

resource "aws_vpc" "my_vpc" {
  cidr_block           = local.new_vpc_cidr
  enable_dns_support   = true
  enable_dns_hostnames = true
  tags = {
    Name = "my-vpc"
  }
}

# 퍼블릭 서브넷 생성
resource "aws_subnet" "public_subnets" {
  count = 3
  vpc_id                  = aws_vpc.my_vpc.id
  cidr_block              = cidrsubnet(local.new_vpc_cidr, 4, count.index) # /20 서브넷 생성
  availability_zone       = ["ap-northeast-2a", "ap-northeast-2b", "ap-northeast-2c"][count.index]
  map_public_ip_on_launch = true
  tags = {
    Name = "public-subnet-${count.index + 1}"
  }
}

# 프라이빗 서브넷 생성
resource "aws_subnet" "private_subnets" {
  count = 3
  vpc_id            = aws_vpc.my_vpc.id
  cidr_block        = cidrsubnet(local.new_vpc_cidr, 4, count.index + 3) # /20 서브넷 생성
  availability_zone = ["ap-northeast-2a", "ap-northeast-2b", "ap-northeast-2c"][count.index]
  tags = {
    Name = "private-subnet-${count.index + 1}"
  }
}

여기까지 수정된 파일은 이다.

4. static 한 방식의 문제점, resoucre 이름 및 개수

다른 문제점은 리소스 개수가 하드코딩 되어있다는 점이다. 가용영역과 리소스의 이름을 변수화해서 이러한 문제를 해소할 수 있다.

4.1 variable 을 이용한 해결

# variable.tf
variable "availability_zones" {
  description = "Availability zones to use for subnets"
  type        = list(string)
  default     = ["ap-northeast-2a", "ap-northeast-2b", "ap-northeast-2c"]
}

variable "resource_name_prefix" {
  description = "Prefix for resource names"
  type        = string
  default     = "my"
}

variable "base_cidr" {
  description = "Base CIDR for VPC"
  type        = string
  default     = "10.0.0.0/16"
}

# main.tf

# 추가
resource "random_string" "resource_suffix" {
  length  = 6
  upper   = false
  special = false
}

# ... 기존 스크립트

이상의 스크립트를 이용하면 이렇게 유연하게 VPC 를 생성할 수 있겠다.

관련코드는 깃헙 (https://github.com/jts8257/terraform-aws/tree/main/vpc-section) 에 올려두었다.

Terraform 기초: 리소스 생명 주기 및 데이터 소스 관리하기

개발프로브 — Fri, 22 Nov 2024 19:47:31 +0900

1. 리소스 생명 주기 (Lifecycle Rules)

Terraform은 리소스를 업데이트할 때 기존 리소스를 삭제(destroy)하고 새로운 리소스를 생성(create)하는 immutable 인프라 접근 방식을 따릅니다. 그러나 모든 경우에 이러한 동작이 적합하지 않을 수 있습니다. 이를 제어하려면 lifecycle rules를 활용할 수 있습니다.

1.1 `create_before_destroy`

기존 리소스를 삭제하기 전에 새로운 리소스를 먼저 생성한다. 어떤 리소스는 다운 타임을 최소화하기 위해 이러한 조치가 필요할 것이다.

resource "aws_instance" "example" {
  ami           = "ami-123456"
  instance_type = "t2.micro"

  lifecycle {
    create_before_destroy = true
  }
}

1.2 `prevent_destroy`

리소스가 삭제되지 않도록 보호한다, 이때 보호되는것은 변경에 의한 삭제이지 main.tf 등 문서에서 리소스가 사라졌을때 삭제되는 것까지지 방지하는것은 아니다.

resource "aws_s3_bucket" "example" {
  bucket = "example-bucket"

  lifecycle {
    prevent_destroy = true
  }
}

1.3. `ignore_changes`

특정 속성 변경을 무시한다. 예를 들어, 태그 변경을 Terraform에서 무시하도록 설정할 수 있다.

resource "aws_instance" "web" {
  ami           = "ami-123456"
  instance_type = "t2.micro"

  lifecycle {
    ignore_changes = [
      tags
    ]
  }
}

주로 외부 시스템이나 사용자에 의해 변경될 수 있는 속성을 terraform 이 덮어쓰지 않도록 할 때 유용하다.

- 위의 예시처럼 EC2 인스턴스의 태그나

- S3 의 ACL 처럼 시스템이나 사용자에 의해 변경될 수 있는 것들

- 테스트 환경에서 의도적으로 속성을 변경하려고 할때

ignore_changes 가 유용하지만 Terraform 이 바라보는 상태와 실제 인프라의 상태가 달라지게 되므로 나중에 둘을 동기화할때 추가작업이 필요해진다. 따라서 신중히 사용해야한다.

2. Meta Arguments: Count

Terraform에서 동일한 리소스를 여러 개 생성하려면 count 메타 인수를 사용한다.

2.1 기본 사용법

다음은 로컬 파일을 3개 생성하는 예제이다.

resource "local_file" "example" {
  count    = 3
  filename = "/root/file-${count.index}.txt"
  content  = "This is file ${count.index}"
}

이렇게 하면 /root/file-0.txt, /root/file-1.txt, /root/file-2.txt가 생성된다.

2.2 Count와 리스트

동적 파일 이름을 사용하려면 리스트 변수를 활용할 수 있다.

variable "filenames" {
  default = ["file-a.txt", "file-b.txt", "file-c.txt"]
}

resource "local_file" "example" {
  count    = length(var.filenames)
  filename = "/root/${var.filenames[count.index]}"
  content  = "This is ${var.filenames[count.index]}"
}

리스트 길이가 변경되면 자동으로 리소스 개수가 조정된다.

3. Data Sources

Terraform은 외부에서 생성된 리소스를 읽고 활용하기 위해 Data Sources를 사용한다. 이때 외부라 하면 현재 terraform 파일에서 관리되지 않는 것을 총칭한다. 외부 클라우드에서 제공되는 데이터 소스일 수도 있으며, 내가 작업중인 컴퓨터의 다른 파일일 수도 있겠다.

3.1 기본 사용법

다음은 로컬 파일의 내용을 읽는 예시이다. example.txt 의 내용을 읽어서 new_example.txt 에 넣는다.

data "local_file" "example" {
  filename = "/root/example.txt"
}

resource "local_file" "new_file" {
  filename = "/root/new_example.txt"
  content  = data.local_file.example.content
}

3.2 Data Sources vs Managed Resources

Managed Resources	Data Sources
Terraform에서 리소스를 생성, 업데이트, 삭제	외부 리소스에서 데이터만 읽기
`resource` 키워드를 사용	`data` 키워드를 사용
Terraform이 리소스의 상태를 관리	Terraform 외부의 리소스를 참조

위의 내용을 활용하여 Terraform을 더욱 효율적으로 관리해보자!

Terraform 기초: commands

개발프로브 — Thu, 21 Nov 2024 21:03:39 +0900

Terraform는 인프라를 코드로 관리하기 위한 강력한 도구이다. Terraform을 효과적으로 사용하려면 다양한 명령어를 이해하고 활용하는 것이 중요하므로 Terraform에서 자주 사용되는 명령어들과 그 활용 사례에 대해 살펴보자.

주요 Terraform 명령어

1. `terraform init`

terraform init은 Terraform 프로젝트를 초기화하는 데 사용된다. 이 명령은 구성 디렉토리를 준비하고 필요한 provider 플러그인을 다운로드한다. Terraform 작업의 첫 단계로 항상 실행해야 한다.

2. `terraform validate`

terraform validate는 Terraform 구성 파일의 구문 오류를 확인한다. 이 명령은 코드를 실행하기 전에 구성 파일이 올바른지 검증하는 데 유용하다.

성공적인 유효성 검사:결과: "Success! The configuration is valid."
terraform validate
오류 발생 시:오류가 발생한 줄과 수정 방법이 제공된다.
Error: Unsupported argument

3. `terraform fmt`

terraform fmt는 구성 파일을 표준 형식으로 자동 정렬한다. 이 명령은 코드의 가독성을 높이고, 팀 협업 시 코드 스타일을 통일하는 데 유용하다.

아래와 같이 포맷이 통일되어 있지 않은 tf 문서가 있는 작업공간에서 terraform fmt 를 실행하면 일관된 포맷으로 만들어준다.

resource "local_file" "pet" {
filename = var.filename
content  = "${var.content} - ${random_pet.my-pet.id}"
}

resource "random_pet" "my-pet" {
prefix    = var.prefix
            separator = var.separator
                    length    = var.length
}

resource "local_file" "pet" {
  filename = var.filename
  content  = "${var.content} - ${random_pet.my-pet.id}"
}

resource "random_pet" "my-pet" {
  prefix    = var.prefix
  separator = var.separator
  length    = var.length
}

이때 파일 실행 결과 std out 에 수정된 파일 목록이 출력되며, 변경 사항은 저장된다.

4. `terraform plan`

terraform plan은 실행 계획을 생성하여 Terraform이 구성 파일에 정의된 변경 사항을 실제 인프라에 적용하기 전에 어떤 작업이 수행될지 확인할 수 있다.

변경 사항이 없다면: "No changes. Infrastructure is up-to-date."
변경 사항이 있다면, 추가/수정/삭제할 리소스 목록이 출력된다.

5. `terraform apply`

terraform apply는 terraform plan에서 생성된 실행 계획을 실제 인프라에 적용한다.

명령 실행 후 확인 프롬프트에서 yes를 입력하면 Terraform이 실행 계획을 실행한다.

6. `terraform show`

terraform show는 현재 인프라 상태를 표시한다. 이 명령은 Terraform의 상태 파일을 읽어 리소스의 속성을 출력한다.

terraform show

JSON 형식으로 출력하려면:
```
terraform show -json
```

7. `terraform output`

terraform output은 구성 파일에서 정의된 출력 변수의 값을 표시합니다.

모든 출력 변수 표시:
```
terraform output
```
특정 변수의 값 표시:
```
terraform output <variable_name>
```

8. `terraform refresh`

terraform refresh는 실제 인프라 상태를 동기화하고 Terraform의 상태 파일을 업데이트합니다. 수동으로 외부에서 리소스가 변경된 경우 유용하다.

terraform refresh

이 명령은 terraform plan 및 terraform apply 실행 시 자동으로 수행되지만, -refresh=false 플래그를 사용하면 이를 건너뛸 수 있다.

9. `terraform graph`

terraform graph는 Terraform 구성 파일 또는 실행 계획에 정의된 의존성 그래프를 생성한다.

위의 fmt 에서 사용된 파일을 예시로 사용해보면 사람이 해석하기에는 다소 난해한 DOT 형식의 텍스트를 출력한다.

➜  terraform-files terraform graph
digraph {
        compound = "true"
        newrank = "true"
        subgraph "root" {
                "[root] local_file.pet (expand)" [label = "local_file.pet", shape = "box"]
                "[root] provider[\"registry.terraform.io/hashicorp/local\"]" [label = "provider[\"registry.terraform.io/hashicorp/local\"]", shape = "diamond"]
                ...
        }
}

이러한 텍스트를 그래프 시각화 도구에 파이프라인으로 연결하면 시각화된 그래프를 볼 수 있다. mac 과 linux 에서는 Graphviz 를 이용할 수 있겠다.

terraform graph | dot -Tpng > graph.png

아래가 그 결과인데, 그다지 보기 좋진 않다.

10. `terraform providers`

terraform providers는 현재 구성 파일에서 사용하는 provider 목록을 표시한다.

terraform providers

필요한 provider 플러그인을 다른 디렉토리에 복사하려면 mirror 서브 명령을 사용할 수 있다.

11. `terraform state`

Terraform 상태 파일을 직접 수정하는 대신, terraform state 명령어를 사용하여 안전하게 상태 파일을 관리할 수 있다. 이 명령은 상태 파일에서 리소스를 이동하거나 수정하는 데 사용된다.

Terraform 명령어 사용 팁

1. 협업 환경에서의 Remote State

팀 환경에서는 Remote State를 사용하여 상태 파일을 공유하는 것이 중요하다. Terraform 상태 파일을 원격 스토리지(예: AWS S3, Terraform Cloud)에 저장하면, 모든 팀원이 항상 최신 상태를 유지할 수 있다.

2. 자동화된 워크플로우

Terraform 명령어를 CI/CD 파이프라인에 통합하면 인프라 배포를 자동화할 수 있다. terraform init, plan, apply를 순서대로 실행하여 안전한 배포를 구현할 수 있겠다.

3. `-refresh=false`로 성능 최적화

대규모 인프라에서는 -refresh=false 옵션을 사용하여 불필요한 상태 동기화를 줄이고 실행 속도를 개선할 수 있다.

Terraform 기초: State

개발프로브 — Thu, 21 Nov 2024 20:56:14 +0900

Terraform를 사용할 때 중요한 개념 중 하나는 State 이다. 이번 글에서는 Terraform의 State의 역할과 중요성, 그리고 실무에서의 활용 방안에 대해 살펴보겠다.

Terraform State란 무엇인가?

Terraform의 State 파일은 리소스 구성과 실제 인프라 간의 매핑 정보를 저장하는 역할을 한다. 이는 Terraform이 실행 계획을 생성하고, 구성 파일과 실제 인프라 간의 불일치(Drift)를 식별하는 데 사용된다. 쉽게 말해, Terraform State 파일은 실제 세상에 존재하는 모든 리소스의 청사진(blueprint)이라고 볼 수 있다.

이러한 State 는 terraform apply 가 되는순간 terraform.tfstate 파일에 json 형태로 저장이 된다.

Terraform State의 주요 역할

1. 리소스 매핑 및 의존성 관리

Terraform 은 리소스를 생성할 때 해당 리소스의 ID를 State에 기록한다. 이 ID는 로컬 파일 리소스, 클라우드 리소스, 또는 논리적 리소스와 같은 모든 리소스를 유일하게 식별할 수 있는 값이다.

뿐만 아니라, State는 리소스 간의 의존성 정보를 포함하고 있다. 예를 들어:

resource "random_pet" "my_pet" {
 prefix = "Mrs"
 separator = "."
 length = 1
}

resource "local_file" "pet" {
  content  = random_pet.my_pet.id
  filename = "pet_name.txt"
}

위 구성에서 local_file.pet은 random_pet.my_pet 에 의존한다. 따라서 random_pet 이 생성된 이후에만 local_file 이 생성된다.

2. 삭제 순서 제어

Terraform에서 리소스를 삭제할 때도 State 파일의 의존성 정보가 중요하다. 예를 들어, 위의 예제에서 random_pet 과 local_file 을 모두 삭제한다고 가정해보자. Terraform은 State 파일에 기록된 의존성 정보를 기반으로 local_file 을 먼저 삭제한 후 random_pet 을 삭제한다.

3. 성능 최적화

Terraform은 수백 개의 리소스를 관리할 수 있으며, 이 중 일부는 여러 클라우드 제공업체에 분산될 수 있다. 매번 모든 리소스 상태를 확인하려면 많은 시간이 소요된다.

Terraform State는 이러한 리소스 상태를 캐시로 저장하여 실행 속도를 대폭 개선하는 역할을 수행한다. 예를 들어, -refresh=false 플래그를 사용하면 Terraform은 State 파일만 참조하고 실시간 상태 갱신을 건너뛰게 된다.

terraform plan -refresh=false

4. 협업 지원

개인 프로젝트에서는 로컬 State 파일(terraform.tfstate)을 사용하는 것이 문제없을 것이다. 하지만 팀 협업 환경에서는 로컬 State 파일 사용이 비효율적이며 예측 불가능한 에러를 초래할 수 있다.

따라서 Remote State를 사용하는 것이 권장된다. Remote State는 State 파일을 원격 저장소에 저장함으로써 팀원들이 항상 최신 상태를 공유할 수 있도록 한다.

Terraform에서 지원하는 Remote State 백엔드의 예는 다음과 같다:

AWS S3
Google Cloud Storage
Azure Blob Storage
Terraform Cloud

Terraform State의 보안 고려사항

Terraform State 파일은 JSON 형식으로 저장되며, 모든 리소스 속성 값이 포함된다. 여기에는 다음과 같은 민감 정보도 포함될 수 있다:

클라우드 리소스의 IP 주소
SSH 키
데이터베이스 초기 비밀번호

따라서 로컬 State 파일은 항상 안전한 스토리지에 저장해야 하며, 민감한 데이터가 유출되지 않도록 주의해야 한다.

Git 저장소에 State 파일을 저장하지 말 것

Terraform 구성 파일은 Git과 같은 분산 버전 관리 시스템에 저장하는 것이 일반적이다. 하지만 State 파일은 예외다. 민감한 정보를 포함하고 있으므로, State 파일은 반드시 원격 백엔드에 저장해야 한다.

Terraform State 수정 주의사항

State 파일은 Terraform의 내부 용도로 설계되었으며, 직접 수정해서는 안 된다. 수정이 필요한 경우 terraform state 명령어를 사용해야 한다.

MSA 주요 패턴: 사가(Saga) 패턴

개발프로브 — Wed, 20 Nov 2024 20:59:37 +0900

1. Saga 패턴

모놀로식 아키텍처에서 단일 DB 를 사용하고 있다면 트랜잭션의 원자성과 일관성을 DBMS 수준에서 보장을 해준다. 따라서 데이터의 일관성을 유지하는게 어렵지 않다.

하지만 MSA 에서 여러 서비스의 서로 다른 DBMS 를 거쳐 영속화 해야하는 것은 흔한 일이다. 때문에 데이터 일관성 문제가 발생한다. 이러한 문제를 해결하기 위해 “서로다른 DBMS 의 트랜잭션을 논리적으로 묶을 필요”가 있었고 이를 위해 등장한 설계 패턴이 Saga 패턴이다. (마치 트랜잭션이 전파되는 것이 이야기가 전파되는것과 같다고 하여 Saga 라고 부른다)

Saga 패턴에서 트랜잭션을 논리적으로 묶는 주체는 어플리케이션이다. 위와 같이 트랜잭션이 실패했을 때 보상 트랜잭션(cancel) 을 호출 어플리케이션에 전달하고 트랜잭션 롤백 등 지정된 행위를 하게 만든다. 이 과정에서 일시적으로 데이터 정합이 깨져있을 수 있으나 “결과적 정합”을 보장한다.

위 그림은 단순히 트랜잭션 신호 전달만 도식화했을 뿐이다. 실제로 트랜잭션 성공(TransactionComplete) 혹은 실패(Cancel) 은 메시지 브로커를 통한 이벤트로 전달된다.

이러한 saga 패턴은 코레오그래피 기반 사가(Choreography-based Saga)와 오케스트레이션 기반 사가(Orchestration-based Saga) 등이 있다.

2. 코레오그래피 기반 사가(Choreography-based Saga)

코레오그래피 기반 사가는 아래의 그림과 같이 각 서비스간 메시지 브로커로 직접 결합된 형태이다.

서비스와 서비스를 메시지 브로커가 직접 중계하기 때문에 구현이 쉽다. 하지만,

트랜잭션 Saga 참가자가 많을 수록 트랜잭션 흐름이 복잡해지고 마이크로 서비스간 순환 종속이 발생할 수 있다. 또한 서비스가 발행, 소비 주체를 알고 있다고 가정하고 메시지를 설계한다면 서비스간 결합도가 높아진다는 부작용이 있다.

3. 오케스트레이션 기반 사가(Orchestration-based Saga)

오케스트레이션 기반 사가는 중앙 집중된 Saga Orchestration 이 saga 참여자들에게 어떤 로컬 트랜잭션에 참여해야 하는지 알려주는 형태이다.

트랜잭션 흐름이 명확해지고 서비스간 결합도를 낮출 수 있다는 장점이 있지만,

오케스트레이터(Orchestrator) 가 실패했을 때 모든 트랜잭션 연계가 끊길 수 있다는 SPOF 문제가 있으며 서비스간 결합도는 낮아지지만 서비스와 오케스트레이터간 결합도가 높아진다는 단점있다. 이러한 이유로 유연성과 확장성이 낮아질 수 이다는 위험이 있다.

4. 보장되지 않은 영속화 순서, CorrelationID

아래와 같은 DB 를 가지고 있고 BFF 로 MSA 를 호출하는 환경을 생각해보자

BFF 는 A,B,C 를 생성할 수 있는 요청을 모두 받았고 이들을 각기 분리하여 A 서비스, B 서비스, C 서비스로 전달하였다. 이때 A, B, C 의 ERD 는 다음과 같다.

BFF 는 각 서비스의 순서를 모르게(결합도가 낮은) 설계 되었기 때문에 동시에 A, B, C 서비스를 호출하였고, 각각의 A, B, C 의 영속화 순서는 보장되지 않았다. 그 결과 C → B → A 순서로 영속화가 되었다. B 는 A의 id 를 알아야하고 C는 B 의 id 를 알아야 하지만 B 와 C 는 fk 가 누락된 상황이다.

각 서비스는 본인들의 영속화 업무가 끝나자 TransactionComplete 이벤트를 발행한다. 그 순서는 아래와 같다.

발생 이벤트의 payload 에는 생성된 엔티티의 id 만 담겨있다고 생각하면 B 는 A 가 생성되었다는 이벤트를 구독하여 확인했지만 도대체 이 A 를 어떤 B 와 연관시켜야 할지 알 지 못하며 C 역시 마찬가지다.

어떻게 해야할까? BFF 가 모든 paylaod 를 A 에게 넘기고 A는 영속화후 남는 payload 로 B 를 만들고, 다시 같은 작업을 B 는 C에 대해 반복해야할까? 이렇게 설계된다면 서비스간 결합도가 굉장히 높은 상태이므로 좋은 설계라고 볼 수 없다.

이때 등장하는게 correlationID란 개념이다. BFF 에서(혹은 API Gateway 에서) 각 요청을 고유하게 구분할 수 있는id 를 생성하여 각 서비스의 생성 요청에 함께 보내는 것이다. 그리고 각 서비스는 이벤트를 발행할때 생성된 엔티티의 id 와 이 유니크한 id 를 함께 payload 에 넣고 발행한다면 상호 결합도는 낮추면서 DB 의존 관계를 명확하게 유지할 수 있게 된다.

이러한 correlationID 를 적용하여 위의 이벤트 발행에 payload 를 붙여서 보여주면 다음과 같다.

5. 보장되지 않은 영속화 순서 , 아직 메시지를 받아들일 준비가 안됨...

이번엔 반대로 영속화 순서가 A -> B -> C 순서라고 생각해보자. 그리고 이런 경우에는 A 가 TransactionComplete이벤트를 발행해도 B 는 이 메시지를 구독하고도 처리할 준비가 되지 않았을 것이다. 이것은 C역시 마찬가지다.

주로 한국에서 많이 사용하는 kafka 에서 어떻게 처리할지 알아보겠다.

5.1 Kafka 에서 준비되지 않은 TransactionComplte 메시지 처리

이벤트를 소비했으나 연관관계를 매핑해줄 엔티티가 아직 없는 경우

- Kafka 는 메시지의 오프셋을 고의로 커밋하지 않는 것으로 메시지를 유지할 수 있다. 그리고 N 초 뒤에 다시 메시지를 소비한다.

- 이벤트를 Dead Letter Queue 에 저장하고, 엔티티 B 가 영속화 되었을때 재처리하도록 할 수 있다.

- Fallback Storage 를 이용하여 TransactionComplete 이벤트를 임시 저장소(Redis, DB) 에 저장한 뒤 B 가 영속화된 뒤 재처리한다.

Python 코드로 보면 이렇다.

from kafka import KafkaConsumer, KafkaProducer
import json
import time

consumer = KafkaConsumer(
    'transaction-events',
    group_id='service_b',
    bootstrap_servers='localhost:9092',
    enable_auto_commit=False,  # 오프셋 자동 커밋 비활성화
    value_deserializer=lambda v: json.loads(v.decode('utf-8'))
)

# 임시 저장소 (Redis나 DB로 대체 가능)
temp_storage = {}

def handle_event(event):
    correlation_id = event['correlation_id']
    a_id = event['a_id']

    # B 엔티티가 아직 없는 경우
    b_entity = find_b_entity_by_correlation_id(correlation_id)
    if not b_entity:
        print(f"B entity not found for Correlation ID {correlation_id}. Retrying...")
        temp_storage[correlation_id] = event  # 이벤트를 임시 저장
        time.sleep(5)  # 대기 후 재처리
        return False

    # B 엔티티 업데이트
    b_entity.a_id = a_id
    save_b_entity(b_entity)
    print(f"Updated B entity with A ID {a_id}")
    return True

for message in consumer:
    event = message.value
    success = handle_event(event)

    # 성공적으로 처리된 경우만 오프셋 커밋
    if success:
        consumer.commit()

MSA 주요 패턴: 서비스 디스커버리(Service Discovery) 패턴

개발프로브 — Wed, 20 Nov 2024 20:45:30 +0900

1. 서비스 디스커버리 패턴

MSA 에서는 언제든 새로운 원격 서버 인스턴스(pod) 가 추가되거나 제거될 수 있으므로 그 개수와 물리적 주소가 고정되어 있지 않기 때문에 클라이언트가 물리적인 위치를 몰라도 서비스를 호출할 수 있도록 하는 것이 중요하다.
즉 “물리적인 주소”가 아니라 “논리적인 주소” 로 서버 인스턴스를 찾을수 있어야 한다.

1.1 클라이언트 사이드 서비스 디스커버리

클라이언트 사이드 서비스 디스커버리의 구성은 아래와 같다.

마이크로 서비스의 인스턴스들(pod)의 물리적인 주소를 Service Registry 라는 곳에 저장한다. 이때 인스턴들은 주기적으로 Hearthbeat 를 Service Registry 로 전송하여 Service Registry가 인스턴스 상태를 체크할 수 있도록 한다.

클라이언트는 직접 Service Registry 에 접근하여 주소 목록을 조회하고, 그 주소중 한 곳으로 요청을 전송한다. 이때 클라이언트에서 직접 로드밸런서를 구현하여 적절히 트래픽이 분산될 수 있도록 한다.

클라이언트 사이드 서비스 디스커버리의 장애 대응

[Service Registry 장애 대응]

어떠한 이유에서 Service Registry 가 다운된 상황에서 클라이언트가 주소를 요청하는 경우에 문제가 발생할 수 있다. 이러한 이유로 클라이언트는 Service Registry 가 반환한 주소 목록을 일정 기간동안 캐시를 해두는 전략을 사용하여 장애 대응 시간을 벌 수 있다.

[Instance 장애 대응]

Service Registry 가 반환한 주소 목록을 캐싱해뒀을 때 Service Registry 에서는 장애가 있는 Instance 라고 판단하여 주소 목록에서 제외했으나 클라이언트가 계속 요청을 보내는 경우가 있을 수 있다. 이런 경우에 기존 캐시에서 해당 Instance 주소를 삭제하고 다른 주소에 요청을 보내는 등의 로직이 클라이언트에서 적절히 구현되어야 한다.

1.2 서버 사이드 서비스 디스커버리

클라이언트 사이드 서비스 디스커버리의 구성은 아래와 같다.

클라이언트는 서버에서 구현된 로드밸랜서 주소로 요청을 보내고, 로드밸런서는 클라이언트 요청에 적절한 인스턴스 주소를 찾아서 요청을 처리한다.

서버 사이드 서비스 디스커버리 장애 대응

[Service Registry 장애 대응]

어떠한 이유에서 Service Registry 가 다운된 상황에서 LB가 주소를 요청하는 경우에 문제가 발생할 수 있다. 이러한 이유로 LB는 Service Registry 가 반환한 주소 목록을 일정 기간동안 캐시를 해두는 전략을 사용하여 장애 대응 시간을 벌 수 있다.

[Instance 장애 대응]

Service Registry 가 반환한 주소 목록을 캐싱해뒀을 때 Service Registry 에서는 장애가 있는 Instance 라고 판단하여 주소 목록에서 제외했으나 LB가 계속 요청을 보내는 경우가 있을 수 있다. 이런 경우에 기존 캐시에서 해당 Instance 주소를 삭제하고 다른 주소에 요청을 보내는 등의 로직이 LB에 적절히 구현되어야 한다.

1.3 K8s 에서 Service Discovery

K8s 에서 Service 란 Service Object 를 말하는 개념이다. K8s 네트워크 Object 에서 언급한것과 같이 Service Object는 클러스터에서 실행중인 pod 에 접근할 수 있는 방법을 정의한 것이다. 따라서 클라이언트 코드는 가변적인 pod 의 물리 주소 대신 Service Object 를 통해 더 안정적인 네트워크 엔드포인트를 제공 받는다.

이러한 사실에 기반하여 K8s 의 Service Object 자체가 서비스 디스커버리 패턴을 구현한 구현체라고 생각할 수 있겠다. 이때 Service Discovery 의 역할은 K8s 마스터를 구성하는 요소 중 etcd 와 Controller Manager 와 API Server 를 통해 구현되었다.

Kubernetes 기본구조

개발프로브 — Wed, 20 Nov 2024 20:40:16 +0900

1. Kbuernetes(K8s) 란?

MSA에서는 각 서비스가 컨테이너로 패키징되며, 하나의 서비스에 대해 N개의 컨테이너가 존재할 수 있습니다. 수십 개의 서비스만 있어도 수백 개 이상의 컨테이너를 관리해야 합니다.

컨테이너 관리에는 다음과 같은 요구 사항이 있습니다:

다수의 서버를 하나의 클러스터처럼 사용.
여러 서버에 컨테이너를 배포.
서비스 디스커버리로 서비스 간 연결.
부하에 따른 자동 스케일링(scale-out, scale-in).
장애 시 컨테이너 재생성과 트래픽 재연결.
서버 상태(헬스 체크) 모니터링.
스토리지 및 네트워크 관리.

이러한 복잡성을 사람이 수동으로 처리하는 것은 비효율적이며, 이를 자동화하기 위해 컨테이너 오케스트레이션이 필요합니다. Kubernetes(K8s)는 이러한 요구를 충족시키는 대표적인 오케스트레이션 도구로, 대규모 컨테이너 관리와 자동화를 지원합니다.

2. K8s 의 철학

K8s 는 다음과 같은 철학에 기초하여 설계, 구현되었습니다.

Immutable Infrastructure
- 클라우드 환경에서는 컴퓨터 리소스는 자유롭게 생성, 폐기, 확장할 수 있다. 따라서 인프라에 변경이 생기면 기존 인프라에 변경 사항을 적용하는게 아니라 기존 인프라를 파기하고 다시 만들도록 동작한다.
Declarative Configuration
- K8s 관리자는 인프라가 원하는 상태(Desired State)에 도달하기 위해 필요한 모든 과정을 선언적으로 명시해야한다.
Self Healing
- K8s 는 실시간으로 클러스터의 현재 상태(Current State) 를 바라보면서 Desired State 와 차이가 발생하면 이를 자동으로 복구한다.

3. K8s 의 구조

3.1 구조 개괄

K8s 의 구조를 단순하게 보면 “Master에 API 서버와 상태 저장소(etcd)를 두고 어플리케이션은 노드의 포드(pod) 에 배포되며, Master 가 각 노드의 에이전트(kubelet)와 통신하는 구조” 입니다.

K8s 구조 개괄

3.2 마스터

K8s 의 마스터는 클러스터를 관리하는 역할을 합니다. 즉 노드들의 상태를 파악하고 어떤 컨테이너를 어떤 노드에서 가동할지 선택합니다. 이때 분산 저장소에 클러스터의 정보를 저장하고 조회하게 됩니다. 이러한 기능을 위해 각각의 노들들은 상호 직접적으로 소통하는게 아니라 오로지 마스터를 통해서만 소통이 가능하게 됩니다.

이러한 마스터의 주요 구성 요소로는 API Server, Scheduler, Controller Manager, etcd 가 있습니다.

K8s master

3.2.1 API Server

모든 요청을 처리하는 마스터의 핵심 구성 요소입니다. 검증된 K8s 관리자, 노드의 요청만 처리해야 하므로 인증 및 인가 기능을 갖추고 있습니다.

3.2.2 Scheduler

pod(컨테이너) 가 어떤 노드에서 가동할지 결정하는 구성 요소입니다.

3.2.3 Controller Manager

K8s 클러스터의 상태를 실시간으로 검사하면서 Current State 와 Desired State 를 비교하고 Desired State 가 되도록 유지합니다.

3.2.4 etcd

분산 key-value 저장소로 클러스터의 모든 설정, 상태 데이터를 저장합니다. Scheduler, Controlelr Manager 는 API Server 를 통해 etcd 에서 클러스터의 정보를 조회하고 갱신합니다.

3.3 노드(node)

노드는 pod(컨테이너) 가 직접적으로 가동되는 서버입니다. 다수의 노드로 클러스터를 구성합니다. 하나의 노드도 다양한 구성요소가 존재하는데 대표적인것은 kubelet 과 Kube proxy , 그리고 pod 입니다.

K8s 노드

3.3.1 kubelet

실제로 마스터의 요청을 받아 pod(컨테이너) 를 생성하는 주체입니다.

pod(컨테이너) 의 상태를 감시하는 역할도 수행하여 pod 의 상태를 API Server 로 전송합니다.

3.3.2 Kube proxy

각 노드에서 실행되는 네트워크 프록시입니다. 노드의 네트워크 규칙을 유지 관리하고 내부 네트워크 세션이나 클러스터 바깥에서 컨테이너로 네트워크 통신을 할 수 있도록 해줍니다.

3.3.3 pod

K8s 에서 배포할 수 있는 가장 작은 단위로, K8s 의 Object 들 중 하나입니다.

pod 는 하나 이상의 컨테이너와 스토리지 그리고 네트워크 속성 가지고 있으며, 컨테이너와 스토리지는 네트워크를 공유하며 상호 localhost 로 접근할 수 있습니다.

4. K8s 의 Object 들

K8s 에는 대규모 분산환경에 필요한 요소들이 추상화 되어 있고 이러한 요소들을 Object 라고 부릅니다.

4.1 어플리케이션 배포에 관한 Object 들

pod
(pod) ReplicaSet
- pod 여러개를 복제하여 관리하는 Object
Deployment
- K8s 에서 실제 배포를 진행하는 기본 단위로 배포 전략 선택, 배포 Revision, Roll Back 등의 기능을 사용하려면 이 Objet 를 이용해야한다.
DaemonSet
- 클러스터 전체에 적용되는 pod 를 띄울때 사용하는 Controller로 DaemonSet 을 이용해 띄운 pod 는 항상 모든 node 에서 실행된다. 로그 수집이나 모니터링에 적합하다.
StatefulSet
- K8s Object 들은 대부분 Stateless 하다. Stateful 한 Volume 을 이용한 DB 등을 pod 로 만들때 사용하는 Object 이다.

4.2 네트워크에 관한 object 들

Service
- pod 간 연결 및 pod 와 외부 네트워크를 연결 하는 object 이다.
- 여러 pod 에 대한 L4 수준의 내부 로드밸런서의 역할을 수행하며 내부 DNS에 서비스를 등록하여 서비스 디스커버리 역할도 수행한다.

Ingress
- 외부 트래픽을 받는 Object 로 http, https 등 L7 레벨에서 라우팅 규칙, 로드밸런싱 규칙 등을 설정한다.
- 일반적으로 클러스터를 외부로 노출할때는 Ingress 를 이용한다.

5. 최종 K8s 구조

이상의 K8s 구조, Object 를 종합하면 아래와 같이 그릴 수 있습니다.

Container와 Docker

개발프로브 — Wed, 20 Nov 2024 20:23:42 +0900

컨테이너와 도커의 개념 및 역할

컨테이너란?
- 컨테이너는 애플리케이션과 그 애플리케이션이 실행되는 환경을 패키지화한 기술입니다. 이를 통해 개발 환경과 운영 환경의 차이로 인한 문제를 방지할 수 있습니다.
- 컨테이너는 가상 머신(VM)과는 다르게, 호스트 OS의 커널을 공유하므로 경량화된 프로세스 격리를 제공합니다.
도커란?
- 도커는 컨테이너 기술을 구현한 오픈소스 플랫폼으로, 컨테이너를 생성, 관리, 배포할 수 있는 도구입니다.
- 도커는 애플리케이션 개발, 테스트, 배포를 일관된 방식으로 처리할 수 있도록 지원합니다.
- 컨테이너 이미지를 빌드하고 실행하는 데 필요한 도구를 제공합니다.

컨테이너의 특징과 도커를 활용한 애플리케이션 배포

컨테이너의 주요 특징
- 격리성: 각 컨테이너는 독립적으로 실행되어 다른 컨테이너나 호스트 시스템과 격리됩니다.
- 경량성: 가상 머신과 달리 호스트 OS의 커널을 공유하기 때문에 리소스 소모가 적습니다.
- 이식성: 어디서나 동일한 환경에서 실행될 수 있도록 애플리케이션과 모든 종속성을 포함합니다.
- 확장성: 컨테이너는 빠르게 생성 및 삭제할 수 있어 대규모 트래픽에도 유연하게 대응할 수 있습니다.
도커를 활용한 배포 프로세스
- 개발: 개발자는 도커 이미지를 정의하기 위해 Dockerfile을 작성합니다.
- 테스트: 작성된 이미지를 도커 컨테이너로 실행하여 테스트합니다.
- 배포: 도커 이미지를 컨테이너 레지스트리(예: Docker Hub, AWS ECR)에 저장한 뒤 운영 환경에 배포합니다.
- 운영: 컨테이너 오케스트레이션 도구(Kubernetes 등)를 활용해 운영 환경에서 컨테이너를 관리합니다

도커가 MSA 구현에 필수적인 이유

일관된 환경 제공:
- 컨테이너를 사용하면 개발 환경과 운영 환경이 동일하게 유지되므로, 환경 간 차이로 인한 오류를 최소화할 수 있습니다.
빠른 배포와 확장 가능:
- MSA에서는 서비스별로 독립적인 배포가 중요한데, 도커는 이를 손쉽게 구현할 수 있습니다.
효율적인 자원 활용:
- 가상 머신보다 경량화된 구조를 가지므로 리소스를 효율적으로 사용할 수 있습니다.
격리성과 보안성:
- 각 서비스가 독립된 컨테이너로 실행되기 때문에 하나의 서비스 장애가 다른 서비스에 영향을 미치지 않습니다.
DevOps 친화성:
- CI/CD 파이프라인에 쉽게 통합할 수 있어 빠르고 안정적인 배포 프로세스를 지원합니다.

MSA 개념

개발프로브 — Wed, 20 Nov 2024 20:21:59 +0900

MSA 란?

하나의 애플리케이션을 다수의 독립적인 서비스로 구성한 아키텍처입니다.

마틴파울러의 블로그에 따르면 MSA 는 다음의 특징을 갖습니다.

서비스들은 각자 별도의 프로세스에서 실행된다.
HTTP API 와 같은 가벼운 매커니즘으로 통신하는 작은 애플리케이션이다.
작은 서비스들은 각자의 비즈니스 기능을 담당하고 완전 자동화 된 절차에 따라 독립적으로 배포된다.
각 서비스는 서로 다른 프로그맹 언어, 프레임워크, 데이터 저장 기술을 사용할 수 있다.

대표적인 사례로는 Netflix 가 있으며, 국내에는 쿠팡, 배달의 민족 등이 있습니다. MSA 의 어떤 점이 매력적이길래 이들은 MSA 를 도입한 걸까요?

MSA 의 장점

빠른 Delivery
- 각 서비스는 독립적이므로 코드 수정 영향 범위가 작습니다.
- 결과적으로, 고객에게 가치를 빠르게 전달할 수 있어 시장 경쟁력을 강화합니다.
Polyglot Architecture
- 각 서비스가 독립적으로 운영되므로 각 팀이 최적의 기술 스택을 선택할 수 있습니다.
- 도메인 전문성이 증가하고, 팀의 자율성이 높아집니다.
실험과 혁신 가능
- 코드베이스가 작아 수정으로 인한 영향 예측이 용이합니다.
- 혁신적인 기술을 더 쉽게 도입할 수 있어서 IT 의존적인 비즈니스들은 시장역량을 강화할 수 있습니다.
탄력적이고 선택적인 확장
- 특정 서비스만 Scale-out 할 수 있어 운영 효율성이 높아집니다.
대체가능성
- 서비스 단위로 기술을 변경하거나 외부 솔루션으로 교체가 용이합니다.
- 이를 통해 NIH(Not Invented Here) 증후군의 위험을 줄일 수 있습니다.

하지만 항상 기술 선택에 따른 트레이드오프가 있기 마렵입니다. MSA 는 다음과 같은 단점이 있어서 신중한 고려가 필요합니다.

MSA 의 단점

비교적 비효율적인 컴퓨타 자원 사용
- 각 서비스가 독립적으로 실행되기 때문에 컴퓨팅 자원(중복 런타임 리소스, 네트워크)을 더 많이 사용합니다.
- 예: JVM 런타임 중복 실행, 마샬링/언마샬링 오버헤드 등.
운영 난이도 상승
- 모니터링 대상이 증가할 뿐만아니라 모니터링 해야하는 기술도 다양해집니다.
- 각 서비스가 상호 의존적이기 때문에 단위 테스트 난이도가 증가합니다.
DB 트랜잭션의 모호함
- 서비스간 서로 다른 DB 를 사용하기 때문에 애초에 DB 수준에서 트랜잭션 관리가 안됩니다.
- 데이터 일관성이 중요한 서비스에서는 MSA 도입을 신중히 도입해야합니다.

MSA는 많은 장점이 있지만, 그만큼 기술적인 어려움도 존재합니다. 이러한 어려움을 해결하기 위해 컨테이너 기술과 오케스트레이션 도구(Kubernetes) 같은 기술들이 필요합니다.

Terraform 기초: depends_on, output

개발프로브 — Tue, 19 Nov 2024 21:14:12 +0900

Terraform 의존성과 Output 활용

지금까지 알아본 Terraform 블록은 resource와 variable이 전부였다. 이번 글에서는 output이라는 유용한 블록을 소개하고, depends_on이라는 argument를 다룬다.

1. depends_on

여러 리소스를 관리하다 보면 "의존적인 관계"에 있는 리소스들이 존재한다. AWS를 예로 들자면, 특정 VPC에 종속되어야 하는 security group은 VPC 리소스에 의존적일 수밖에 없다.

1.1 암시적 의존성

Terraform은 리소스 간의 참조 관계를 분석하여 자동으로 의존성을 생성한다. 예를 들어, security group이 특정 VPC의 ID를 참조할 때, Terraform은 이를 기반으로 암시적 의존성을 설정한다.


resource "aws_vpc" "example" {
  cidr_block = "10.0.0.0/16"
}

resource "aws_security_group" "example" {
  vpc_id = aws_vpc.example.id
  name   = "example_sg"
}

위 코드에서 `aws_security_group`은 `aws_vpc`에 암시적으로 의존한다.

1.2 명시적 의존성

암시적 의존성으로 충분하지 않은 경우, depends_on을 사용하여 명시적으로 의존성을 설정할 수 있다.


resource "aws_vpc" "example" {
  cidr_block = "10.0.0.0/16"
}

resource "aws_security_group" "example" {
  name   = "example_sg"
  depends_on = [aws_vpc.example]
}

이 경우 `aws_security_group`은 명시적으로 `aws_vpc`에 의존하도록 지정된다.

2. Output

output 블록은 특정 값을 출력하거나 다른 Terraform 구성에서 사용할 수 있도록 전달한다. 주로 생성된 리소스의 ID, 속성값, 또는 설정값을 화면에 출력하는 데 사용된다.

2.1 Output 기본 사용


output "vpc_id" {
  value = aws_vpc.example.id
}

Terraform apply 후, 위 output은 생성된 VPC의 ID를 화면에 출력한다.

2.2 다른 구성으로 전달

Output은 Terraform 모듈 간 데이터를 전달하는 데에도 활용된다.


output "subnet_ids" {
  value = aws_subnet.example.*.id
}

# 다른 Terraform 구성에서:
module "network" {
  source = "./network_module"
}

output "module_subnet_ids" {
  value = module.network.subnet_ids
}

Output은 리소스의 결과를 공유하고, 작업 결과를 효율적으로 활용하는 데 필수적이다.

Terraform 기초: 변수와 변수의 활용

개발프로브 — Mon, 18 Nov 2024 21:25:07 +0900

1. Terraform 변수

terraform 은 대규모 프로비저닝 관리를 위해 변수 를 지원해준다. 변수는 어떻게 구성되어 있고, 어떻게 사용하는지 알아보자

1.1 Terraform 변수의 구성

변수는 3개의 argument 로 구성된다.

default: 변수의 기본 값을 지정한다.
type: 변수의 타입 을 지정한다.
description: 변수에 대한 메타데이터를 지정한다.

아래와 같이 변수를 만들 수 있다.

variable "filename" {
 default = "pets.txt"
 type = string
 description = "name of file"
}

variable "length" {
 default = 2
 type = number
 description = "length of ..."
}

1.2 Terraform 변수 타입

Terraform은 인프라를 코드로 관리하기 위해 다양한 데이터 타입을 지원한다. 이러한 타입을 이해하면 효율적인 인프라 정의와 관리를 할 수 있다.

1.2.1. 기본 타입 (Primitive Types):

문자열 (string): 유니코드 문자들의 시퀀스로, 예를 들어 "hello"와 같다.
숫자 (number): 정수와 부동소수점을 모두 포함하며, 예를 들어 15나 6.283185 등이 있다.
불리언 (bool): 참(true) 또는 거짓(false) 값을 가지며, 조건문 등에 사용된다.

1.2.2. 복합 타입 (Complex Types):

복합 타입은 collection type 과 structural type 으로 구분지을 수 있다.

collection type 에는 list, map, set 이 있고 structural type 에는 object 와 tuple 타입이 있다.

리스트 (list)

동일한 타입의 값들이 순서대로 나열된 시퀀스이다. 예를 들어, ["us-west-1a", "us-west-1c"] 가 있다.

list 를 이용하는 방법은 다음과 같다.

맵 (map)

키-값 쌍으로 이루어진 집합으로, 각 키는 고유해야 한다. 예를 들어, {"name" = "Mabel", "age" = 52} 가 있다.

셋 (set)

고유한 값들의 집합으로, 순서가 없으며 중복을 허용하지 않는다.

그런데 set 타입으로 만든 변수는 이를 수용할 수 있는 argument 가 특정되어 있다.

이떄 string 타입을 가져오기 위해서는 다양한 방법을 사용할 수 있는데, 아래는 그 예시 3개를 보여준다.

객체(Object), 튜플(Tuple)

3. 특수 타입:

null: 값의 부재를 나타내며, 리소스의 특정 속성을 생략하고자 할 때 사용된다.

1.3 Terraform 변수 적용

variable 블록을 기존과 같이 resource 가 선언된 블록에서 같이 관리해도 된다. 하지만 동일 작업공간에서 terraform 은 .tf 파일을 모두 읽어들여서 작업을 진행하므로 굳이 둘을 하나의 파일에서 관리하지 말고 main.tf 와 variable.tf 로 나눠보도록 하자

main.tf: 리소스를 정의하는 테라폼 파일
variable.tf: 리소스에서 사용할 변수를 정의하는 테라폼 파일

HCL 기본기에서 다뤘듯이 argument 에 expression 을 대입할 수 있다.

main.tf

variable.tf

그리고 terraform init > terraform paln > terraform apply 순서로 돌리면 작업공간에 pets.txt 가 생성되면서 랜덤한 문자열이 생성된다.

1.4 Terraform 변수 관리

그렇다면 이제는 variable 의 내용만 바꾸면 변경 사항을 반영할 수 있지 않을까?

변경된 variable.tf

terraform paln > terraform apply 를 한 결과 기존 작업공간에 있던 pets.txt 는 사라지고 pets2.txt 가 생성되었다. 그리고 그 내용도 랜덤 변수 3개가 생성되는 것으로 바뀌었다.

Terraform 기초: 리소스 만들어보기

개발프로브 — Mon, 18 Nov 2024 13:44:02 +0900

Terraform 실습

Terraform 스크립트는 init -> plan -> apply 명령어 순으로 적용하여 리소스를 프로비저닝 할 수 있다.

이 순서에 따라서 local device에 txt 파일을 만들어본 후 txt 파일을 업데이트 해보겠다.

1. 스크립트 작성

Terraform 스크립트는 이전 Terraform:HCL 기본기 에서 살펴본것과 같이 Block 단위로 Resource 와 Argument 를 명시해주면 된다.

나는 terraform-tutorial 이라는 디렉터리를 만들고 그 공간에서 실습을 진행했다.

2 terraform init

script 를 적절히 작성한 후 terraform init 을 실행하면 작업공간(terraform-tutorial) 에 .terraform 디렉터리와 .terraform.locl.hcl 파일이 생성된다.

2.1 terraform 디렉터리

.terraform 디렉터리는 Terraform 의 작업공간으로서 "프로젝트 상태" 를 유지하고 필요한 파일을 관리하는데 사용된다. 구체적으로 다음의 역할을 수행한다:

플러그인(Providers) 캐싱: 프로젝트에 사용되는 Provider 들의 바이너리가 저장된다. 덕분에 매번 동일한 Provider 를 다운로드 받지 않아도 된다.
Terraform 상태 관리: Terraform이 인프라를 프로비저닝하거나 업데이트하면서 필요한 메타데이터를 보관한다. S3 나 Terraform Cloud 같은 원격 상태를 사용할 경우 원격 상태 정보가 저장되기도 한다.
Terraform 구성 파일 모듈 관리: 프로젝트에서 모듈을 사용할 경우, 다운로드된 모듈이 저장된다.
Terraform 작업 설정: Terraform 실행 시 생성되는 파일이나 설정 정보가 저장된다.

.terraform 디렉터리를 삭제하면 다시 필요한 Provider 를 다운로드 하는 과정을 거친다.

2.2 terraform.lock.hcl

.terraform.lock.hcl 파일은 Provider와 모듈의 버전을 고정하는 역할을 한다. 덕분에 실행 환경에서 동일한 버전을 사용할 수 있도록 보장된다.

3 terraform plan

terraform plan 커맨드를 입력하면, 사용자가 설정한 리소스 타입이 받아들인 argument 값을 알려주고 그에 따라 앞으로 생길 변화에 대해 리포트해준다. init 단계에서 생성된 .terraform 디렉터리와 .terraform.lock.hcl 에 영향은 없다.

4 terraform apply

terraform apply 커맨드를 입력하면 plan 에 따른 리소스 생성, 변경, 삭제가 이루어진다. 그리고 apply 가 될 때 terraform.tfstate 파일이 생성된다.

4.1 terraform.tfstate

terraform.tfstate 파일은 Terraform이 관리하는 현재 인프라의 상태를 저장한다.

이렇게 저장된 상태 정보는 Terraform이 정의한 Desired State(원하는 상태)와 Current State(현재 상태)를 비교하는 데 사용된다.

실제 생성된 terraform.tfstate 파일을 확인해보면 plan 에 나왔던 argument 들이 어떤 값이 들어가 있는지, 어떤 프로바이더가 사용되었는지 등의 정보가 생성된다.

5 리소스 수정

5.1 스크립트 수정

terraform 을 통해 생성된 리소스를 수정하기 위해 스크립트를 수정한다. 기존 pets.txt 의 content 를 변경했고, pets.json 이라는 파일을 추가하도록 했다.

5.2 paln & apply

이미 해당 작업공간에는 terraform init 이 되어 있으므로 추가로 init 할 필요는 없다.

terraform plan 커맨드를 입력하면 변경된 스크립트에 기반하여 어떤 변화가 생길지

흥미로운 점은 pets.txt 파일은 change 되는게 이니라 replaced 된다는 점이다. 덕분에 최종 plan 에는 2 to add, 0 to change, 1 to destroy 가 표시되었다. 이런식으로 변경된 사항만 바뀌는게 아니라아예 없애고 새롭게 만드게 하는것을 Immutable Infrastructure 라한다.

terraform apply 커맨드를 입력해보자, yes 를 누르면 plan 에 있던 변화가 반영된다.

6. 리소스 삭제

작업 공간에서 terraform destroy 를 입력하면 terraform 에 의해 관리되던 리소스를 destroy 하게 된다.

Terraform 기초: HCL 기본기

개발프로브 — Sun, 17 Nov 2024 23:26:37 +0900

아무리 HCL 이 쉬운 DSL 이라곤 하지만 정확히 쓰고 읽기 위해서는 최소한의 공부가 필요하다. 우선 Terraform 을 설치하는게 우선이다.

1. Terraform 설치 (업그레이드)

가장 좋은 방법은 공식 사이트의 설치 가이드를 보고 설치하는 것이다.

나는 mac 을 이용하고 brew 를 통해 설치, 삭제, 업그레이드를 관리하는 것이 용이하므로 brew 로 설치했었다.

그 결과 버전 1.8.2 가 설치되어 있는 것을 확인할 수 있었다.

$> brew list terraform
# /opt/homebrew/Cellar/terraform/1.8.2/bin/terraform

$> terraform version
# Terraform v1.8.2
# on darwin_arm64

24년 11월 17일 기준 terraform 최신 버전은 1.9.8 이므로 업그레이드가 필요했다. 이럴때 brew 가 빛을 발한다.

$> brew update
# ==> Updating Homebrew...

$> brew upgrade terraform
# ==> Upgrading 1 outdated package:
# hashicorp/tap/terraform 1.8.2 -> 1.9.8

2. HCL 문법

공식문서에 따르면 Terraform 을 이용하기 위해 모든 HCL 문법을 디테일하게 알 필요는 없다고 한다. (그럼에도 궁금하다면 HCL Spec 을 확인하자) 그리고 HCL 이 아닌 JSON 형태로도 동일한 기능을 수행하게 할 수 있는데, 개발자가 직접 다루기보다는 프로그래밍적으로 다룰때 유용한 형태이다.

2.1 블록 (block)

HCL 언어는 주로 블록(block)과 인수(argument)로 구성된다.

블록은 특정 리소스나 설정을 정의하는 기본 단위이다. 각 블록은 블록 유형, 라벨, 그리고 본문으로 구성된다. 예를 들어, AWS의 EC2 인스턴스를 정의하는 블록은 다음과 같다:

resource "aws_instance" "example" {
  ami           = "ami-0c55b159cbfafe1f0"
  instance_type = "t2.micro"
}

여기서 resource는 블록 유형을, aws_instance와 example은 각각 리소스 유형과 로컬 이름을 나타낸다. 블록 본문에는 해당 리소스의 속성을 정의하는 인수들이 포함된다.

2.2 인수(argument)

인수는 위의 예제에서 속성에 값을 할당하는 데 사용된다. ami 와 instnace_type 이 인수이며, 각각의 등호(=) 를 통해 할당된다. 인수의 값은 리터럴 값, 변수, 또는 표현식으로 지정할 수 있다.

2.3 표현식 (expression)

인수의 값에 표현식을 지정한다는 것의 예시는 다음과 같다.

resource "aws_subnet" "example" {
  vpc_id = aws_vpc.example.id
  cidr_block = "10.0.1.0/24"
}

여기서 vpc_id 에 aws_vpc.example.id 를 이용하여 다른 리소스의 id 를 참조하도록 하고 있는 형태가 표현식을 인수의 값으로 지정한 것이다.

2.4 주석 (Comment)

Terraform 구성 파일에서 주석은 # 또는 //로 시작하는 한 줄 주석과, /* */로 감싸는 여러 줄 주석이 있다.

3. 파일 구조

Terraform 구성은 .tf 확장자를 가진 파일로 작성되며, 하나의 디렉토리에 여러 파일이 있을 경우 Terraform은 이를 모두 읽어들여 하나의 구성으로 처리한다. 따라서 관련된 리소스나 모듈을 논리적으로 분리하여 파일을 구성하는 것이 좋다.

Terraform 소개

개발프로브 — Sun, 17 Nov 2024 23:24:09 +0900

1. Terraform

1.1 Terraform 이란?

Terraform은 HashiCorp에서 개발한 무료 오픈소스 IAC 도구이다. IAC 개요 및 주요 도구에서 다룬 것과 같이 주로 인프라 프로비저닝에 사용되는 툴로써, 설치 파일은 단일 바이너리로 구성돼 있어서 빠르게 설정할 수 있다.

Terraform의 가장 큰 장점 중 하나는 여러 플랫폼(프라이빗 클라우드와 퍼블릭 클라우드)을 아우르는 인프라 배포가 가능하다는 거이다. 예를 들어, 온프레미스 vSphere 클러스터부터 AWS, GCP, Azure 같은 클라우드 솔루션까지 지원한다.

1.2 Terraform 과 HashiCorp

HashiCorp 는 클라우드 인프라를 효율적으로 관리하고 자동화하기 위한 다양한 도구를 개발하는 회사이다. HashiCorp의 제품은 DevOps, 클라우드, 그리고 인프라 관리에 초점을 맞추고 있으며 Terrafrom 도 그들의 제품 중 하나이다.

2. Terraform의 핵심: Providers

Terraform이 이렇게 다양한 플랫폼을 지원할 수 있는 이유는 Provider 덕분이다.

Provider 는 HashiCorp 와 Terraform Community 에 의해 작성, 유지되며 외부 플랫폼을 API 형태로 생성, 관리 할 수 있도록 도와주는 역할을 한다. 대표적으로 다음과 같은 Provider 들이 있다:

클라우드 플랫폼: AWS, GCP, Azure
네트워크 인프라: CloudFlare, DNS, Palo Alto Networks
모니터링 및 데이터 관리 도구: DataDog, Grafana, Sumo Logic
데이터베이스: MySQL, PostgreSQL, MongoDB
버전 관리 시스템: GitHub, GitLab, Bitbucket

이 외에도 Terraform Registry 에서 수천개 이상의 Provider 를 찾을 수 있다.

3. Terraform의 언어: HCL

Terraform은 HashiCorp Configuration Language(HCL)라는 선언적 언어를 사용한다.
이 언어를 이용하면 .tf 확장자를 가진 구성 파일에 인프라 리소스를 코드로 정의 한다.

HCL 은 코드 작성과 읽기가 쉬워서 초보자도 금방 배울 수 있다는 장점이 있다.
선언형 코드로 현재 상태에서 원하는 상태(Desired State)로 인프라를 관리할 수 있다.
예를 들어, AWS에 EC2 인스턴스를 프로비저닝하는 코드를 작성하면, Terraform이 알아서 필요한 작업을 진행해서 현재 상태를 원하는 상태로 맞춰준다.

4. Terraform의 작업 단계

Terraform은 세 가지 주요 단계를 거쳐 작업한다.

Write: 프로젝트에 사용될 Provider 와 리소스를 정의하고 원하는 상태를 작성한다.
Plan: Terrafrom 은 해당 리소스의 현재 상태와 원하는 상태를 비교해서 실행 계획 작성한다.
Apply: 실행 계획대로 리소스를 생성, 수정, 삭제 등을 수행한다.

만약 환경이 원하는 상태에서 벗어나면, Terraform이 자동으로 수정해서 다시 맞춰준다. 덕분에 인프라는 항상 정의된 상태로 유지된다.

5. Terraform의 상태(State)

Terraform은 리소스의 상태를 기록해서 '실시간'으로 인프라 상태를 추적해.

State 파일: 인프라의 설계도 같은 역할을 수행
데이터 소스: 기존 리소스의 속성을 읽어서 다른 리소스 설정에 활용할 수도 있음
Import 기능: 수동으로 생성된 리소스나 다른 IAC 도구로 만든 리소스를 가져와서 Terraform 관리 하에 둘 수 있음

IAC 개요 및 주요 도구

개발프로브 — Sun, 17 Nov 2024 19:40:43 +0900

1. IAC(코드형 인프라)란?

IAC(Infrastructure as Code)는 클라우드 인프라를 코드로 정의하고 관리하는 방식이다.

기존의 클라우드 관리 콘솔을 통해 수작업으로 리소스를 프로비저닝(provisioning)하는 대신, IAC를 통해 코드로 정의하고 실행하여 리소스를 자동으로 생성, 구성, 업데이트, 삭제할 수 있다.

IAC는 데이터베이스, 네트워크, 스토리지, 애플리케이션 구성과 같은 다양한 인프라 구성 요소를 코드로 관리할 수 있도록 해준다. 예를 들어, 기존의 셸 스크립트를 사용해도 되지만, 이 방식은 관리와 재사용이 어려우며 유지보수를 위해 개발 기술을 필요로 한다. 이러한 문제를 해결하기 위해 Terraform이나 Ansible과 같은 IAC 도구가 등장했다.

2. 주요 IAC 도구 소개

IAC 도구는 크게 세 가지 유형으로 분류할 수 있다.

구성 관리(Configuration Management) 도구
- 예시: Ansible, Chef, Puppet, SaltStack
- 용도: 기존 인프라 리소스(서버, 데이터베이스, 네트워크 장치 등)에 소프트웨어를 설치하고 관리
- 특징:
  - 코드의 일관성과 표준 구조를 유지
  - 다수의 원격 리소스에서 동시에 실행 가능
  - Idempotent(멱등성): 동일한 코드를 여러 번 실행해도 환경을 정의된 상태로 유지하며, 불필요한 변경을 방지
  - 재사용성과 버전 관리 가능 (예: Ansible Playbook)
서버 템플릿(Server Templating) 도구
- 예시: Docker, Vagrant, Packer
- 용도: 필요한 소프트웨어와 종속성이 미리 설치된 VM(가상 머신) 이미지 또는 컨테이너 생성
- 특징:
  - 변경이 불가능한 Immutable Infrastructure(불변 인프라)를 지향
  - 기존 인스턴스를 업데이트하는 대신 이미지를 업데이트하고 새로운 인스턴스를 재배포
  - 예시: Amazon AWS의 Custom AMI, DockerHub의 Docker 이미지
프로비저닝(Provisioning) 도구
- 예시: 'Terraform', AWS CloudFormation
- 용도: 서버(VM), 데이터베이스, 네트워크(VPC, 서브넷, 보안 그룹 등)와 같은 인프라 구성 요소를 코드로 정의하고 프로비저닝
- 특징:
  - CloudFormation: AWS에 특화된 도구
  - Terraform: 클라우드 제공업체에 구애받지 않고 다양한 클라우드 제공업체 지원

3. IAC 도구 간 차이점 및 활용 사례

Ansible vs Terraform
Ansible은 소프트웨어 구성 관리에 적합하며, Terraform은 인프라 프로비저닝에 적합하다. 각 도구는 특정 목적에 맞춰 설계되었으며, 적절한 도구를 선택하는 것이 중요하다.

4. 왜 IAC를 사용해야 할까?

수작업을 줄이고 자동화를 통해 효율성 및 생산성 향상
코드 기반 관리를 통해 일관성과 재현성 확보
버전 관리를 통해 변경 이력 추적 가능
여러 리소스를 동시에 관리 가능

python 사용자 지정 불변 객체를 만드는 3가지 방법

개발프로브 — Sun, 17 Nov 2024 16:09:55 +0900

사용자 지정 불변 객체

이전 글에서는 사용자가 만든 클래스는 모두 가변 객체인것 처럼 설명되었다. 정말 사용자가 만든 클래스는 불변 객체가 될 수 없는 걸까?

용자가 작성한 클래스를 불변 객체로 만들기 위해서는 다음의 조건이 충족되어야 할 것이다.

새로운 attribute 를 추가하는것을 막는다.
기존 attribute 를 변경하는 것 모두가 막는다.
값을 기반으로 객체간 동등성을 비교하도록 재정의 한다.

1. 새로운 attribute 추가 제한

파이썬 객체는 별다른 설정을 하지 않는다면 attribute 를 dict 자료형에 저장한다. 그리고 dict 자료형은 값을 추가, 삭제할 수 있다. 아래의 예시를 보자.

자유로은 attribute 추가

class MutableClass:
    value: str

    def __init__(self, value: str):
        self.value = value

    def __repr__(self):
        # __dict__ 를 통해서 내부 attribute 에 접근
        attrs = ", ".join(f"{key}: {value}" for key, value in self.__dict__.items())
        return f"MutableClass({attrs})"


mutable = MutableClass("mutable")

print(f"mutable: {mutable}")
# mutable: MutableClass(value: mutable)

mutable.value2 = "mutable..."

print(f"mutable: {mutable}")
# mutable: MutableClass(value: mutable, value2: mutable...)

MutableClass 내부에 정의된 __repr__ 메서드에서 명시적으로 __dict__ 에서 값을 가져오는 것을 알 수 있다.

slots 를 이용한 attribute 추가 제한

클래스를 정의할때 __slots__ 를 통해 attribute 의 이름값을 정의한다면, 새로운 attribute 를 추가할때 AttributeError 가 발생하게 되며, 이는 IDE 에 따라서는 적절한 경고를 띄워준다.

__slots__ 를 이용하는 것은 객체의 사용방법을 제한하는 것 외에도 다른 장점이 있지만 이 글에서는 이 정도만 알아본다.

class MutableClass:
    value: str

    def __init__(self, value: str):
        self.value = value

    def __repr__(self):
        # __dict__ 를 통해서 내부 attribute 에 접근
        attrs = ", ".join(f"{key}: {value}" for key, value in self.__dict__.items())
        return f"MutableClass({attrs})"


class ImmutableClass1:
    __slots__ = ["value"]

    def __init__(self, value: str):
        self.value = value

    def __repr__(self):
        # __slots__ 를 통해서 내부 attribute 에 접근
        attrs = ", ".join(
            f"{slot}: {getattr(self, slot, None)}" for slot in self.__slots__
        )
        return f"ImmutableClass1({attrs})"


mutable = MutableClass("mutable")
immutable1 = ImmutableClass1("immutable1")

print(f"mutable: {mutable}\nimmutable1: {immutable1}")
# mutable: MutableClass(value: mutable)
# immutable1: ImmutableClass1(value: immutable1)

mutable.value2 = "mutable..."
immutable1.value2 = "immutable1..." # AttributeError: 'ImmutableClass1' object has no attribute 'value2'

하지만 __slots__ 를 통해 새로운 attribute 를 추가하는 것을 막았다고 하더라도 이는 기존 attribute 의 불변성을 보장하는 것이 아니다.

2. 기존 attribute 변경 제한

2.1 setattr 재정의

파이썬 클래스는 내부적으로 attribute의 값을 초기화하거나 변경할때 __setattr__ 메서드를 호출하게 되어있다. 따라서 처음에 객체를 초기화할때를 제외하는 __setattr__ 을 호출하지 못하게 하면 attribute 를 변경하지 못하는 불변 객체가 완성되는 것이다.

class ImmutableClass1:
    __slots__ = ["value"]

    def __init__(self, value: str):
        self.value = value

    def __repr__(self):
        # __slots__ 를 통해서 내부 attribute 에 접근
        attrs = ", ".join(
            f"{slot}: {getattr(self, slot, None)}" for slot in self.__slots__
        )
        return f"ImmutableClass1({attrs})"


class ImmutableClass2:
    __slots__ = ["value"]

    def __init__(self, value: str):
        # 속성을 직접 설정 (이 단계에서는 __setattr__ 호출 방지)
        super().__setattr__("value", value)

    def __setattr__(self, key, value):
        # 객체 초기화 후에는 속성 변경 금지
        raise AttributeError(f"Cannot modify attribute '{key}'")

    def __repr__(self):
        # __slots__ 를 통해서 내부 attribute 에 접근
        attrs = ", ".join(
            f"{slot}: {getattr(self, slot, None)}" for slot in self.__slots__
        )
        return f"ImmutableClass2({attrs})"



immutable1 = ImmutableClass1("immutable1")
immutable2 = ImmutableClass2("immutable2")

print(f"immutable1: {immutable1}\nimmutable2: {immutable2}")
# immutable1: ImmutableClass1(value: immutable1)
# immutable2: ImmutableClass2(value: immutable2)

immutable1.value = "immutable1+1"
immutable2.value = "immutable2+2" # AttributeError: Cannot modify attribute 'value'

3. 두가지를 한번에

사실 위의 과정은 너무 복잡하고 boilerplate 가 많다. 사용자가 정의한 클래스를 불변 객체로 만들고자하는 욕구는 먼저 python 을 거쳐갔던 수많은 개발자들도 동일했을 것이므로 더 멋진 방법이 있을 것이라고 생각하는게 당연하다.

3.1 dataclass

그리고 그 방법 중 하나가 datablasses 이다.

이 방법은 __slots__ 를 이용하지 않아도, __setattr__ 을 재정의 하지 않아도 기존에 기대하던 모든 것들을 충족시켜준다. IDE 에 따라서는 적절한 경고를 띄워준다.

(기본적으로 slot=False 로 설정되어 있는데, slot=True 로 설정하여 slots 을 사용하는 이점을 누릴 수 있다.)

from dataclasses import dataclass


class ImmutableClass2:
    __slots__ = ["value"]

    def __init__(self, value: str):
        # 속성을 직접 설정 (이 단계에서는 __setattr__ 호출 방지)
        super().__setattr__("value", value)

    def __setattr__(self, key, value):
        # 객체 초기화 후에는 속성 변경 금지
        raise AttributeError(f"Cannot modify attribute '{key}'")

    def __repr__(self):
        # __slots__ 를 통해서 내부 attribute 에 접근
        attrs = ", ".join(
            f"{slot}: {getattr(self, slot, None)}" for slot in self.__slots__
        )
        return f"ImmutableClass2({attrs})"


@dataclass(frozen=True)
class ImmutableClass3:
    value: str

    def __repr__(self):
        # __dict__ 를 통해서 내부 attribute 에 접근
        attrs = ", ".join(f"{key}: {value}" for key, value in self.__dict__.items())
        return f"ImmutableClass3({attrs})"


immutable2 = ImmutableClass2("immutable2")
immutable3 = ImmutableClass3("immutable3")

print(f"immutable2: {immutable2}\nimmutable3: {immutable3}")
# immutable2: ImmutableClass2(value: immutable2)
# immutable3: ImmutableClass3(value: immutable3)

immutable3.value = "immutable3+3"  # dataclasses.FrozenInstanceError: cannot assign to field 'value'
immutable3.value2 = "immutable3..." # dataclasses.FrozenInstanceError: cannot assign to field 'value2'

3.2 NamedTuple

NamedTuple 을 클래스가 상속하게 하는 방법도 있다. 이 방법 역시 새로운 attribute 의 추가와 기존 attribute 의 변경을 막는다. 이때는 기존 클래스의 __dict__ 나 __slots__ 를 이용하는 것이 아니라 tuple 구조로 바로 변경된다. tuple 자체가 불변 객체이므로 사용자가 정의한 객체에 불변성을 부여할 수 있다.

IDE 에 따라서는 적절한 에러를 띄워준다.

from dataclasses import dataclass
from typing import NamedTuple


@dataclass(frozen=True)
class ImmutableClass3:
    value: str

    def __repr__(self):
        # __dict__ 를 통해서 내부 attribute 에 접근
        attrs = ", ".join(f"{key}: {value}" for key, value in self.__dict__.items())
        return f"ImmutableClass3({attrs})"


class ImmutableClass4(NamedTuple):
    value: str

    def __repr__(self):
        # ._fields 를 통해 NamedTuple 필드에 접근
        attrs = ", ".join(f"{field}: {getattr(self, field)}" for field in self._fields)
        return f"ImmutableClass4({attrs})"


immutable3 = ImmutableClass3("immutable3")
immutable4 = ImmutableClass4("immutable4")

print(f"immutable3: {immutable3}\nimmutable4: {immutable4}")
# immutable3: ImmutableClass3(value: immutable3)
# immutable4: ImmutableClass4(value: immutable4)

immutable4.value = "immutable4+4"  # AttributeError: can't set attribute
immutable4.value2 = "immutable4..."  # AttributeError: 'ImmutableClass4' object has no attribute 'value2'

4. 동등성 비교 재정의

불변 객체의 동등성은 값 비교로 이루어지는게 타당할 것이다.

따라서 위의 예제 중 ImmutableClass2 에 __eq__ 메서드를 재정의할 수 있을 것이고, dataclass 와 NamedTuple 은 모두 값을 기준으로 __eq__ 비교를 하도록 재정의 해준다.

from dataclasses import dataclass
from typing import NamedTuple

class ImmutableClass2:
    __slots__ = ["value"]

    def __init__(self, value: str):
        # 속성을 직접 설정 (이 단계에서는 __setattr__ 호출 방지)
        super().__setattr__("value", value)

    def __setattr__(self, key, value):
        # 객체 초기화 후에는 속성 변경 금지
        raise AttributeError(f"Cannot modify attribute '{key}'")

    def __repr__(self):
        # __slots__ 를 통해서 내부 attribute 에 접근
        attrs = ", ".join(
            f"{slot}: {getattr(self, slot, None)}" for slot in self.__slots__
        )
        return f"ImmutableClass2({attrs})"

    def __eq__(self, other):
        # 동등성 비교: 다른 객체와 값 비교
        if not isinstance(other, ImmutableClass2):
            return False
        return all(
            getattr(self, slot, None) == getattr(other, slot, None)
            for slot in self.__slots__
        )

@dataclass(frozen=True)
class ImmutableClass3:
    value: str

    def __repr__(self):
        # __dict__ 를 통해서 내부 attribute 에 접근
        attrs = ", ".join(f"{key}: {value}" for key, value in self.__dict__.items())
        return f"ImmutableClass3({attrs})"


class ImmutableClass4(NamedTuple):
    value: str

    def __repr__(self):
        # ._fields 를 통해 NamedTuple 필드에 접근
        attrs = ", ".join(f"{field}: {getattr(self, field)}" for field in self._fields)
        return f"ImmutableClass4({attrs})"


immutable2_1 = ImmutableClass2("immutable2")
immutable2_2 = ImmutableClass2("immutable2")

immutable3_1 = ImmutableClass3("immutable3")
immutable3_2 = ImmutableClass3("immutable3")

immutable4_1 = ImmutableClass4("immutable4")
immutable4_2 = ImmutableClass4("immutable4")

print(f"""immutable2: {immutable2_1 == immutable2_2}
immutable3: {immutable3_1 == immutable3_2}
immutable4: {immutable4_1 == immutable4_2}
""")

5. 어떤걸 사용할까?

그렇다면 지금까지 알아본 3가지 방법중 어떤것을 이용하는게 좋을까?

직접 재정의한 불변 객체
dataclass 를 이용한 불변 객체
NamedTuple 을 이용한 불변 객체

5.1 구현 복잡도

직접 불변 객체를 재정의한 경우가 구현 복잡도가 가장 높았다. 그리고 dataclass 와 NamedTuple 의 경우 구현복잡도 에서 크게 차이가 있는것 같지는 않다, dataclass는 구현 복잡도가 아주 조금 더 높지만 그 덕분에 다양한 요구 사항에 따라 적절한 객체를 커스터마이징 하여 사용할 수 있다.

5.2 메모리 효율성

구현 복잡성은 너무나 명확한 문제이고, 메모리 효율성을 따져보자

from dataclasses import dataclass
from typing import NamedTuple
import sys
from pympler import asizeof


class ImmutableClass2:
    __slots__ = ["id", "value"]

    def __init__(self, id: int, value: str):
        super().__setattr__("id", id)
        super().__setattr__("value", value)

    def __setattr__(self, key, value):
        raise AttributeError(f"Cannot modify attribute '{key}'")


@dataclass(frozen=True, slots=True)
class ImmutableClass3:
    id: int
    value: str


class ImmutableClass4(NamedTuple):
    id: int
    value: str


immutable2 = ImmutableClass2(10, "immutable")
immutable3 = ImmutableClass3(10, "immutable")
immutable4 = ImmutableClass4(10, "immutable")

# 객체의 기본 메모리 크기만 측정
print(f"self created size: {sys.getsizeof(immutable2)} bytes")
print(f"dataclass size: {sys.getsizeof(immutable3)} bytes")
print(f"NamedTuple size: {sys.getsizeof(immutable4)} bytes")
# self created size: 48 bytes
# dataclass size: 48 bytes
# NamedTuple size: 56 bytes

print(f"======================")

# 객체와 객체가 참조하는 모든 메모리
print(f"self created actual size: {asizeof.asizeof(immutable2)} bytes")
print(f"dataclass actual size: {asizeof.asizeof(immutable3)} bytes")
print(f"NamedTuple actual size: {asizeof.asizeof(immutable4)} bytes")
# self created actual size: 136 bytes
# dataclass actual size: 136 bytes
# NamedTuple actual size: 144 bytes

NamedTuple 방식이 8 byte 정도 메모리를 더 소모하는 것을 확인할 수 있다.

이는 NamedTuple 이 Tuple 의 기능에 더해 "key" 값으로 "value" 를 조회할 수 있는 추가적인 기능을 갖는 자료구조를 구현함으로 추가 메모리 공간을 소모하는 것으로 추측된다.

5.3 결론

지금까지 확인한 사실을 상대적 비교로 도표화하면 아래와 같다.

그렇다면 항상 dataclass 를 사용하는게 이득이 아닐까? 반드시 그런것은 아니다.

dataclass 는 사용자에 따라서 설정 값이 달라질 수 있으므려 협업시 예상치 못한 행위를 일으키지 않기 위해 옵션을 확인해야하는 불편함이 있곗지만 NamedTuple 은 별다른 옵션이 없으므로 예상치 못한 행위가 발생될 가능성이 적다. 그리고 tuple 의 기능을 이용할 수 있다는 장점이 있다.

dataclass 를 이용하는 것은 직접 구현에 비해서 관련 클래스 메서드 오버라이딩 등 오버헤드가 있으므로 조금이지만 메모리 효율성에서 불리한 점이 있다. 따라서 엄청 대용량의 데이터를 객체로 매핑해서 다뤄야하는 경우에는 직접 구현하는 방법을 고려할 수 있겠다.

ProbeHub

Django WSGI 최적화 - Granian 과 ARM64(Graviton)

1. 문제 정의 및 가설 수립

2. 실험 설계

2.1 변수 설정

2.2 실험 단계

3. 실험 결과 데이터 및 해석

3.1 Gunicorn 워커/스레드 튜닝 (단기 부하)

3.1.1 실험 데이터

3.1.2 해석, 클라우드 환경의 vCPU 가 갖는 특수성

3.2 HTTP Server 교체 (Gunicorn vs Granian)

3.2.1 실험 데이터

3.2.2 해석, Python GIL 의 제약에 따른 502 에러

3.3 아키텍처 변경 (amd64/X86 vs arm64/Graviton)

3.3.1 실험 데이터

3.3.2 해석, vCPU 하이퍼스레딩 vs 물리 코어

참고

ORM의 편리함 속 함정 - SELECT *와 수직 분할의 중요성

SELECT * 를 쓰면 왜 안좋은가?

1. 네트워크에서의 성능 개선

2. 백엔드 서버에서의 성능 개선

3. 데이터베이스 서버에서의 성능 개선

어떻게 최적화 할 것인가?

1. ORM 에서 특정 칼럼만 가져오기

2. 명확한 관심사 분리와 수직분리

이렇게 까지 해야하나요?

Python 과 zstd - middleware 적용하기

전체 흐름 점검하기

클라이언트: 디코딩의 책임자

서버: 인코딩의 책임자

Python Backend 시스템에 도입하기

Middleware (ASGI)

Middleware (WSGI)

인코딩을 꼭 해야하나요?

지금 당장 우리 프로덕트에 적용해도 될까?

참고

Python 과 zstd - LZ77 과 허프만 코딩

대표적인 무손실 압축 알고리즘

LZ77

슬라이딩 윈도우

(Distance, Length) 쌍으로 인코딩

허프만 코딩

허프만 트리

이진코드 부여

참고

하나의 컨테이너에 하나의 프로세스

문제점

1. 운영 리스크를 키운다.

2. 컨테이너의 철학에 위배된다.

3. DevOps 를 복잡하게 만든다.

몇가지 추가적인 이야기들

그럼 Sidecar Container 로 빼면 되는 건가요?

어차피 동일한 로직, DB 접근을 공유하는데 코드는 어떡하죠?

현실적인 회색지대

참고

가시성 (1) - 그 개념에 대하여

가시성

가시성(observability)이란?

가시성은 모니터링과 다른 개념이다.

정말 가시성이 필요한가?

시간이 곧 돈이다.

복잡성의 기울기

조직의 속도와 개발자 경험

가시성을 확보하는 방법

참고

Python Monorepo - uv Docker 다이어트하기

문제 제기

맥락 요약 (이전 글 안본 분들을 위해)

프로젝트 구조

Dockerfile

원인 분석

1. Entrypoint 에서 uv run 재호출

2. Build vs Run 경계 모호

해결전략

1. .venv PATH 주입

2. Multi-stage Build

3. 최종 Dockerfile

삽질: uv sync --all-packages 를 사용한게 문제는 아닌가?

가설

증명

**SELECT * 를 쓰면 왜 안좋은가?**

1. `.venv` PATH 주입

**gRPC 러닝커브 * google.api 러닝커브를 줄일만한 방법이 있을까?**