01. Cluster Mode vs Client Mode
Driver 프로세스가 어디에서 실행되는가
- Cluster Mode — Driver가 클러스터 안에서 실행 (YARN이면 AM 컨테이너 내부)
- Client Mode — Driver가 spark-submit을 실행한 머신에서 실행
Executor 쪽은 아무 차이 없음.
02. Cluster Mode 구조
┌─ Client 머신 (엣지 노드) ─┐│ ││ spark-submit ││ --deploy-mode cluster ││ │ ││ │ 1. 앱 제출 ││ │ 2. 제출 후 종료 가능└───────┼───────────────────┘ │┌───────▼──────────── Cluster ─────────────────┐│ ││ ResourceManager ││ │ 3. AM 컨테이너 할당 ││ ▼ ││ ┌────────────────────────────┐ ││ │ AM Container │ ││ │ ┌──────────────────────┐ │ ││ │ │ ApplicationMaster │ │ ││ │ │ + │ │ ④ Executor ││ │ │ DRIVER │ │ 요청 ││ │ │ (같은 JVM 프로세스) │ │ ││ │ └──────────────────────┘ │ ││ └──────────┬─────────────────┘ ││ │ ⑤ Task 전송 (클러스터 내부망) ││ ┌──────┼──────┬──────────┐ ││ ▼ ▼ ▼ ▼ ││ [Exec1] [Exec2] [Exec3] [Exec4] │└──────────────────────────────────────────────┘Cluster Mode에서는 AM과 Driver가 같은 JVM 프로세스 안에 공존. 별도 프로세스가 아님.
spark-submit \ --master yarn \ --deploy-mode cluster \ --class com.example.Job \ app.jar동작 특성
| 항목 | 내용 |
|---|---|
| 제출 후 클라이언트 | 종료해도 됨. 앱은 계속 실행 |
| Driver ↔ Executor 통신 | 클러스터 내부망. 저지연·고대역폭 |
| Driver 장애 시 | AM 재시도로 자동 재실행 가능 (spark.yarn.maxAppAttempts) |
| Driver 로그 | 컨테이너 로그. yarn logs -applicationId ...로 조회 |
| Driver 리소스 | YARN이 관리 (--driver-memory, --driver-cores가 실제로 강제됨) |
| Spark UI | AM 노드의 4040 포트. RM Proxy를 통해 접근 |
3-2. Client Mode 구조
┌─ Client 머신 (엣지 노드 / 노트북) ──┐│ ││ spark-submit ││ --deploy-mode client ││ │ ││ ┌────▼─────────────┐ ││ │ DRIVER │ ⚠️ 여기서 살아있어야 함│ │ SparkContext │ ││ │ DAGScheduler │ ││ │ TaskScheduler │ ││ └────┬─────────────┘ │└───────┼─────────────────────────────┘ │ ⑤ Task 전송 (클러스터 ↔ 외부, 방화벽 통과 필요) │ ⑥ 결과·heartbeat 수신┌───────┼──────────── Cluster ─────────────────┐│ │ ││ ┌────┴───────────────┐ ││ │ AM Container │ ← Driver 없음! ││ │ ExecutorLauncher │ Executor 기동만 ││ └────┬───────────────┘ ││ │ ④ Executor 요청 ││ ┌────┼──────┬──────────┐ ││ ▼ ▼ ▼ ▼ ││ [Exec1] [Exec2] [Exec3] [Exec4] │└──────────────────────────────────────────────┘핵심: AM은 존재하지만 껍데기(ExecutorLauncher). 자원 협상만 하고, 실제 지휘는 클라이언트 머신의 Driver가 담당.
동작 특성
| 항목 | 내용 |
|---|---|
| 제출 후 클라이언트 | 절대 종료 불가. 터미널 닫으면 앱 사망 ❌ |
| Driver ↔ Executor 통신 | 클러스터 경계를 넘음. 지연·대역폭·방화벽 문제 |
| Driver 장애 시 | 재시도 없음. 앱 즉시 종료 |
| Driver 로그 | 클라이언트 터미널에 바로 출력 ✅ |
| Driver 리소스 | 클라이언트 머신의 자원. --driver-memory는 로컬 JVM 힙 |
| Spark UI | 클라이언트 머신의 localhost:4040 |
3-3. 왜 Client Mode가 존재하는가 — 인터랙티브
Cluster Mode가 대부분 우월한데도 Client Mode가 필요한 이유:
Driver가 사용자 터미널과 직접 상호작용해야 하는 경우
>>> df = spark.read.parquet("/data")>>> df.count() # 결과가 즉시 내 화면에 찍혀야 함1234567>>> df.show() # REPL이 Driver 안에서 돌아야 가능Driver가 클러스터 안에 있으면 표준 입출력을 사용자와 주고받을 수 없음. 따라서:
| 도구 | 강제되는 모드 |
|---|---|
spark-shell | Client Mode 강제 |
pyspark (REPL) | Client Mode 강제 |
| Jupyter / Zeppelin | Client Mode 강제 |
spark-sql | Client Mode 강제 |
$ spark-shell --master yarn --deploy-mode clusterError: Cluster deploy mode is not applicable to Spark shells.즉 Client Mode = 개발·탐색·디버깅, Cluster Mode = 프로덕션 배치가 기본 구도.
3-4. 네트워크 — 가장 자주 사고나는 지점
Driver ↔ Executor 통신은 양방향이며 상시 발생함.
Driver → Executor
- 직렬화된 Task 코드(클로저) 전송
- Broadcast 변수 전송
- Task 취소 명령
Executor → Driver
- Heartbeat (기본 10초 간격)
- Task 상태 변경, 메트릭
- Task 결과 (작으면 직접 전송)
collect()결과 전체
Client Mode의 네트워크 함정
① 방화벽 — Executor가 Driver에 역방향 접속해야 함
Driver가 클라이언트 머신에 있으므로, 클러스터의 모든 Executor 노드가 클라이언트 머신의 임의 포트로 접속 가능해야 함. 온프레미스에서 사내망 분리·VPN 환경이면 대부분 여기서 막힘.
# 포트 고정으로 방화벽 규칙 작성 가능하게 만들기--conf spark.driver.port=30000 \--conf spark.driver.blockManager.port=30001 \--conf spark.driver.host=10.0.1.55 # NAT 뒤에 있으면 필수spark.driver.host를 지정하지 않으면 Driver가 자기 로컬 IP(예: 192.168.x.x 또는 Docker 내부 IP)를 광고하고, Executor가 그 주소로 접속하지 못해 연결 타임아웃 후 앱 실패. 컨테이너·VPN 환경에서 가장 흔한 실패 원인.
② 대역폭 — 지사 노트북에서 실행하는 경우
Task 수가 수만 개면 스케줄링 메시지만으로도 상당한 트래픽. 여기에 collect()까지 걸리면 데이터가 전부 WAN을 타고 넘어옴.
③ 지연 — 스케줄링 왕복 지연 누적
Task 하나당 왕복 지연이 5ms → 50ms로 늘면, Task 10만 개에서 스케줄링 오버헤드만 수십 분 차이.
3-5. 의존성 배포 — PySpark 특유의 함정
여기가 PySpark 사용자가 Cluster Mode에서 가장 많이 실패하는 지점.
문제 상황
# Client Mode — 잘 됨spark-submit --deploy-mode client main.py
# Cluster Mode — 실패spark-submit --deploy-mode cluster main.py# ImportError: No module named 'my_utils'# ImportError: No module named 'pandas'원인: Cluster Mode에서는 Driver가 클러스터의 임의 노드에서 실행됨. 그 노드에는:
- 내
main.py가 참조하는 로컬 모듈이 없음 - 내 개발 머신에
pip install한 서드파티 패키지가 없음 - Python 버전이 다를 수 있음
해결책 4가지
① 파일 단위 배포 — --py-files
spark-submit --deploy-mode cluster \ --py-files utils.zip,common.egg \ main.py자체 작성 모듈 배포에는 충분. C 확장이 포함된 패키지(pandas, numpy)에는 부적합.
② 환경 통째 배포 — --archives + conda-pack / venv-pack ← 실무 표준
# 1. 환경 패키징conda create -n pyspark_env python=3.10 pandas pyarrow -yconda activate pyspark_envconda pack -f -o pyspark_env.tar.gz
# 2. 배포 및 인터프리터 지정spark-submit --master yarn --deploy-mode cluster \ --archives pyspark_env.tar.gz#environment \ --conf spark.yarn.appMasterEnv.PYSPARK_PYTHON=./environment/bin/python \ --conf spark.executorEnv.PYSPARK_PYTHON=./environment/bin/python \ main.py#environment= 압축 해제될 심볼릭 링크 이름spark.yarn.appMasterEnv.PYSPARK_PYTHON→ Driver용 (cluster mode에서 Driver는 AM 안에 있으므로)spark.executorEnv.PYSPARK_PYTHON→ Executor용- 두 설정을 모두 해야 함. 하나만 하면 Driver와 Executor의 Python 버전 불일치로 실패
③ 클러스터 전 노드에 사전 설치 — 온프레미스에서 흔하나 버전 관리 부담
④ K8s 이미지에 포함 — Docker 이미지에 의존성 굽기. 가장 재현성 높음
파일 경로 해석 차이
| 리소스 | Client Mode | Cluster Mode |
|---|---|---|
main.py | 로컬 경로 그대로 읽힘 | 클라이언트에서 클러스터로 업로드됨 |
--files config.yaml | 로컬 파일 그대로 접근 가능 | 컨테이너 작업 디렉터리에 배포. SparkFiles.get() 또는 상대 경로 |
open("/home/me/x.txt") | 동작 ✅ | 실패 ❌ — 그 노드에 파일 없음 |
| 로그 파일 쓰기 | 로컬에 남음 | 컨테이너 로컬 디스크. 종료 시 소실 |
from pyspark import SparkFilespath = SparkFiles.get("config.yaml") # 두 모드 모두 안전3-6. Kubernetes에서의 두 모드
K8s는 AM이 없으므로 구조가 다름.
Cluster Mode (권장·표준)
kubectl / spark-submit │ ▼K8s API Server ──► [Driver Pod] ──► [Executor Pod] × N │ ▲ └── 직접 생성 요청 ┘- Driver가 Pod로 실행됨
- Driver Pod가 API Server에 Executor Pod 생성을 직접 요청
- Driver Pod에 ServiceAccount / RBAC 권한 필요
Client Mode
- Driver가 Pod 밖(또는 다른 Pod 안)에서 실행
- Executor Pod들이 Driver에 접속해야 하므로 Headless Service로 안정적 DNS 이름을 제공해야 함
--conf spark.driver.host=my-driver-svc.default.svc.cluster.local--conf spark.driver.port=30000- 클러스터 밖에서 Client Mode를 쓰는 것은 네트워크 구성이 매우 까다로움 → K8s에서는 Cluster Mode가 사실상 정답
3-7. 실무 선택 기준
| 상황 | 권장 모드 | 근거 |
|---|---|---|
| Airflow/Dagster에서 트리거하는 프로덕션 배치 | Cluster | 오케스트레이터가 죽어도 Job 유지, 재시도 가능 |
| 대용량 셔플·장시간 Job | Cluster | 내부망 통신, Driver 안정성 |
| Jupyter / Zeppelin 탐색 분석 | Client | 강제. 대안 없음 |
spark-shell, pyspark REPL | Client | 강제 |
| 로컬 개발·디버깅 | Client 또는 local[*] | 로그 즉시 확인, IDE 디버거 연결 |
| 사내망 분리로 방화벽 제약 큰 환경 | Cluster | Client Mode는 역방향 포트 개방 필요 |
| 클라이언트 머신 사양이 빈약 | Cluster | Driver 메모리를 클러스터에서 확보 |
collect()로 결과를 로컬 파일에 써야 함 | Client | Cluster Mode에선 로컬 파일 시스템 접근 불가 |
Airflow에서의 실무 주의점
SparkSubmitOperator( conn_id="spark_yarn", application="/opt/jobs/main.py", deploy_mode="cluster", # ← 프로덕션 권장 ...)deploy_mode="client"로 두면 Driver가 Airflow Worker 안에서 실행됨- Airflow Worker의 메모리를 Driver가 잠식 → Worker OOM으로 다른 Task까지 연쇄 실패
- Worker 재시작 시 실행 중이던 Spark Job 전부 사망
- 단,
cluster모드는 로그가 YARN에 있어 Airflow UI에서 바로 안 보임 →yarn logs연동 또는 History Server 병행 필요
3-8. local 모드 — 세 번째 선택지
spark-submit --master local[4] main.py--master의 값이지--deploy-mode가 아님. 별개 축- Driver와 Executor가 하나의 JVM 안 스레드로 실행
local[4]= 4개 스레드,local[*]= 코어 수만큼- 클러스터 매니저 없음. 단위 테스트·CI에 최적
- 셔플·직렬화는 실제로 일어나므로 로직 검증에는 유효하나, 성능 특성은 클러스터와 전혀 다름
3-9. 오해 정리
| 오해 | 정정 |
|---|---|
| Cluster Mode는 Executor가 클러스터에서 돈다는 뜻 | Executor는 두 모드 모두 클러스터에서 실행. 차이는 Driver 위치뿐 |
| Client Mode에는 AM이 없다 | 있음. ExecutorLauncher라는 축소 형태로 자원 협상만 담당 |
| Cluster Mode가 항상 빠르다 | Driver↔Executor 통신은 빠르나, 계산 자체 성능은 동일 |
--driver-memory는 두 모드에서 같게 동작 | Client Mode에선 클라이언트 머신 JVM 힙, Cluster Mode에선 YARN 컨테이너 크기 |
| local 모드는 deploy-mode의 한 종류 | --master의 값. --deploy-mode와 다른 축 |
Concept
- Deploy Mode : Driver 프로세스의 실행 위치를 결정하는 설정.
--deploy-mode또는spark.submit.deployMode - Cluster Mode : Driver가 클러스터 내부(YARN이면 AM 컨테이너 안)에서 실행되는 모드. 프로덕션 배치의 표준
- Client Mode : Driver가 spark-submit을 실행한 클라이언트 머신에서 실행되는 모드. 인터랙티브 작업에 필수
- local 모드 :
--master local[N]. Driver와 Executor가 단일 JVM의 스레드로 실행. 테스트·CI용 - ExecutorLauncher : Client Mode에서 AM이 취하는 축소 형태. Driver 없이 Executor 컨테이너 요청만 수행
- spark.driver.host : Executor가 Driver에 접속할 때 사용할 주소. NAT·컨테이너 환경에서 미지정 시 연결 실패의 주원인
- spark.driver.port / blockManager.port : Driver 통신 포트. 고정해야 방화벽 규칙 작성 가능
- Heartbeat : Executor가 Driver에 주기적으로 보내는 생존·메트릭 신호. 기본 10초 간격
- spark.yarn.maxAppAttempts : Cluster Mode에서 AM(=Driver) 실패 시 재시도 횟수. Client Mode에는 해당 없음
- —py-files : Python 모듈·zip·egg를 Driver와 Executor에 배포하는 옵션. C 확장 패키지에는 부적합
- —archives : 압축 파일을 배포하고 지정 이름으로 자동 해제. conda-pack/venv-pack 환경 배포에 사용
- conda-pack / venv-pack : Python 가상환경 전체를 tar.gz로 패키징하는 도구. Cluster Mode PySpark 의존성 배포의 실무 표준
- PYSPARK_PYTHON : 사용할 Python 인터프리터 경로.
spark.yarn.appMasterEnv.*(Driver)와spark.executorEnv.*(Executor)를 모두 설정해야 함 - —files : 설정 파일 등을 각 컨테이너 작업 디렉터리에 배포하는 옵션
- SparkFiles.get() : 배포된 파일의 실제 경로를 반환하는 API. 두 모드 모두에서 안전한 파일 접근 방법
- Headless Service (K8s) : Client Mode에서 Executor Pod가 Driver를 찾기 위한 안정적 DNS 이름 제공 수단
- RM Proxy : Cluster Mode에서 Spark UI에 접근하기 위한 YARN ResourceManager의 프록시 경로
- Spark History Server : 종료된 앱의 이벤트 로그를 재구성해 사후 UI를 제공. Cluster Mode 운영의 필수 요소
추가적으로 공부하면 좋은 컨셉, 주제들:
- Spark Connect (Spark 3.4+) : Driver를 원격 서버로 분리하고 클라이언트는 얇은 gRPC 스텁만 두는 새 아키텍처. Client/Cluster Mode 이분법 자체를 대체하려는 시도. 노트북 환경에서 특히 유용
- spark.yarn.dist.archives / spark.archives :
--archives의 설정 기반 등가물. K8s에서도 동일하게 동작하는 통합 옵션 - Spark Thrift Server / Kyuubi : 장기 실행 Spark 세션을 서버로 띄우고 JDBC로 접속하는 방식. 매 쿼리마다 앱을 띄우는 오버헤드 제거
- YARN Log Aggregation : 컨테이너 종료 후 로그를 HDFS로 모으는 메커니즘.
yarn.log-aggregation-enable. Cluster Mode 디버깅의 전제 - spark.driver.extraJavaOptions / extraClassPath : Driver JVM 옵션 주입. 모드에 따라 적용 시점이 달라 주의 필요
- Docker + spark-submit 조합의 네트워크 문제 : 컨테이너 내부 IP 광고 문제.
spark.driver.bindAddress와spark.driver.host의 분리 사용 - Airflow SparkSubmitOperator vs SparkKubernetesOperator : 전자는 Worker에서 spark-submit 실행, 후자는 SparkApplication CRD 생성. 운영 특성이 크게 다름
퀴즈
Q1. 사내 개발 서버에서 --deploy-mode client로 Spark Job을 제출했더니, Executor는 정상 기동되지만 곧 Failed to connect to driver 오류와 함께 앱이 실패함. Driver 로그에는 특별한 예외가 없음. 원인 후보와 각각의 해결책을 구조적으로 설명하시오.
A1.
Client Mode에서는 Executor가 클러스터 밖의 Driver로 역방향 접속해야 하므로, 그 경로 어딘가가 막힌 것.
① Driver가 잘못된 주소를 광고
- Driver는 자기 로컬 인터페이스 IP를 Executor에게 알려줌
- 개발 서버가 NAT 뒤에 있거나, Docker/VPN 가상 인터페이스 IP를 잡으면 Executor가 도달 불가
- 해결:
--conf spark.driver.host=<Executor가 도달 가능한 실제 IP> - (컨테이너 환경) 바인딩 주소와 광고 주소가 달라야 하면
spark.driver.bindAddress=0.0.0.0을 함께 지정
② 방화벽이 랜덤 포트를 차단
- Driver는 기본적으로 임의 포트를 사용 → 방화벽 규칙 작성 불가
- 해결: 포트를 고정하고 해당 포트만 개방
--conf spark.driver.port=30000--conf spark.driver.blockManager.port=30001- 두 포트 모두 필요.
driver.port는 RPC(Task 스케줄링),blockManager.port는 데이터 블록 전송용
③ 클라이언트 머신이 클러스터 네트워크와 분리
- 사내망 분리 정책상 근본적으로 역방향 접속이 불가능한 경우
- 해결: Cluster Mode로 전환. Driver가 클러스터 안으로 들어가면 이 문제 자체가 소멸
진단 순서: Executor 로그에서 접속 시도한 IP
Q2. Client Mode에서는 잘 되던 PySpark Job이 Cluster Mode로 바꾸자 ImportError: No module named 'pandas'로 실패함. 근본 원인과, 온프레미스 환경에서의 해결책을 설명하시오.
A2.
근본 원인
Cluster Mode에서 Driver는 클러스터의 임의 노드에 뜬 AM 컨테이너 안에서 실행됨.
- Client Mode: Driver = 내 개발 머신 → 내가
pip install한 pandas가 그대로 보임 - Cluster Mode: Driver = 클러스터 노드 → 그 노드의 시스템 Python에는 pandas가 없음
--py-files로도 해결이 안 되는 이유: pandas/numpy는 C 확장 바이너리를 포함하므로 단순 zip 배포로는 동작하지 않음.
해결책 — conda-pack으로 환경 통째 배포 (온프레미스 표준)
# 1. 패키징conda create -n job_env python=3.10 pandas pyarrow -yconda activate job_envconda pack -f -o job_env.tar.gz
# 2. 제출spark-submit --master yarn --deploy-mode cluster \ --archives job_env.tar.gz#environment \ --conf spark.yarn.appMasterEnv.PYSPARK_PYTHON=./environment/bin/python \ --conf spark.executorEnv.PYSPARK_PYTHON=./environment/bin/python \ --py-files my_utils.zip \ main.py주의점 3가지
appMasterEnv(Driver)와executorEnv(Executor)를 둘 다 설정. 하나만 하면 Python 버전 불일치로Python in worker has different version오류- 패키징 머신과 클러스터 노드의 OS/glibc가 호환되어야 함. C 확장이 링크한 시스템 라이브러리 때문. 가급적 클러스터와 동일한 이미지에서 패키징
- 아카이브 크기가 수백 MB이면 매 실행마다 전 노드에 배포 → HDFS에 미리 올려두고 경로로 참조하면 캐시 활용 가능
대안
- 전 노드에 동일 환경 사전 설치 (버전 관리 부담)
- Spark on K8s 전환 후 Docker 이미지에 의존성 포함 (재현성 최고)
다음 챕터(Lazy Evaluation과 연산의 분류 — Narrow/Wide Transformation, Action, Shuffle)로 진행할까요?