4141 words
21 minutes
[Spark] Spark 배포모드
2025-10-30
2026-11-12

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 프로세스 안에 공존. 별도 프로세스가 아님.

Terminal window
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 UIAM 노드의 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-shellClient Mode 강제
pyspark (REPL)Client Mode 강제
Jupyter / ZeppelinClient Mode 강제
spark-sqlClient Mode 강제
Terminal window
$ spark-shell --master yarn --deploy-mode cluster
Error: 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 환경이면 대부분 여기서 막힘.

Terminal window
# 포트 고정으로 방화벽 규칙 작성 가능하게 만들기
--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에서 가장 많이 실패하는 지점.

문제 상황#

Terminal window
# 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

Terminal window
spark-submit --deploy-mode cluster \
--py-files utils.zip,common.egg \
main.py

자체 작성 모듈 배포에는 충분. C 확장이 포함된 패키지(pandas, numpy)에는 부적합.

② 환경 통째 배포 — --archives + conda-pack / venv-pack ← 실무 표준

Terminal window
# 1. 환경 패키징
conda create -n pyspark_env python=3.10 pandas pyarrow -y
conda activate pyspark_env
conda 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 ModeCluster Mode
main.py로컬 경로 그대로 읽힘클라이언트에서 클러스터로 업로드됨
--files config.yaml로컬 파일 그대로 접근 가능컨테이너 작업 디렉터리에 배포. SparkFiles.get() 또는 상대 경로
open("/home/me/x.txt")동작 ✅실패 ❌ — 그 노드에 파일 없음
로그 파일 쓰기로컬에 남음컨테이너 로컬 디스크. 종료 시 소실
from pyspark import SparkFiles
path = 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 이름을 제공해야 함
Terminal window
--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 유지, 재시도 가능
대용량 셔플·장시간 JobCluster내부망 통신, Driver 안정성
Jupyter / Zeppelin 탐색 분석Client강제. 대안 없음
spark-shell, pyspark REPLClient강제
로컬 개발·디버깅Client 또는 local[*]로그 즉시 확인, IDE 디버거 연결
사내망 분리로 방화벽 제약 큰 환경ClusterClient Mode는 역방향 포트 개방 필요
클라이언트 머신 사양이 빈약ClusterDriver 메모리를 클러스터에서 확보
collect()로 결과를 로컬 파일에 써야 함ClientCluster 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 모드 — 세 번째 선택지#

Terminal window
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는 기본적으로 임의 포트를 사용 → 방화벽 규칙 작성 불가
  • 해결: 포트를 고정하고 해당 포트만 개방
Terminal window
--conf spark.driver.port=30000
--conf spark.driver.blockManager.port=30001
  • 두 포트 모두 필요. driver.port는 RPC(Task 스케줄링), blockManager.port는 데이터 블록 전송용

③ 클라이언트 머신이 클러스터 네트워크와 분리

  • 사내망 분리 정책상 근본적으로 역방향 접속이 불가능한 경우
  • 해결: Cluster Mode로 전환. Driver가 클러스터 안으로 들어가면 이 문제 자체가 소멸

진단 순서: Executor 로그에서 접속 시도한 IP 확인 → 그 주소가 실제 Driver 주소인지 대조 → 아니면 ①, 맞는데 타임아웃이면 ②/③


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으로 환경 통째 배포 (온프레미스 표준)

Terminal window
# 1. 패키징
conda create -n job_env python=3.10 pandas pyarrow -y
conda activate job_env
conda 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가지

  1. appMasterEnv(Driver)와 executorEnv(Executor)를 둘 다 설정. 하나만 하면 Python 버전 불일치로 Python in worker has different version 오류
  2. 패키징 머신과 클러스터 노드의 OS/glibc가 호환되어야 함. C 확장이 링크한 시스템 라이브러리 때문. 가급적 클러스터와 동일한 이미지에서 패키징
  3. 아카이브 크기가 수백 MB이면 매 실행마다 전 노드에 배포 → HDFS에 미리 올려두고 경로로 참조하면 캐시 활용 가능

대안

  • 전 노드에 동일 환경 사전 설치 (버전 관리 부담)
  • Spark on K8s 전환 후 Docker 이미지에 의존성 포함 (재현성 최고)

다음 챕터(Lazy Evaluation과 연산의 분류 — Narrow/Wide Transformation, Action, Shuffle)로 진행할까요?

[Spark] Spark 배포모드
https://yjinheon.netlify.app/posts/02de/03-spark/spark-03-deploy-mode/
Author
Datamind
Published at
2025-10-30
License
CC BY-NC-SA 4.0