내 PC에서
Spark 실습 환경 만들기

코드가 같아도 Java나 Python 버전이 다르면 결과가 달라지거나 실행에 실패할 수 있습니다. Docker는 프로그램과 필요한 실행 환경을 묶어 이런 차이를 줄입니다.

프로세스·서버·클러스터

• 프로세스: 지금 실행 중인 프로그램입니다.
• 서버: 다른 프로그램의 요청에 응답하는 프로그램 또는 그 컴퓨터입니다.
• 클러스터: 여러 실행 주체가 협력하는 구성입니다. 이번 실습에서는 한 PC 안에 여러 프로세스를 띄워 구성합니다.

Docker 도구와 실행 환경

이름과 태그 읽기

spark:4.1.3-scala2.13-java21-python3-ubuntu를 콜론으로 나누어 읽습니다.

• 콜론 앞 · 이름: spark입니다.
• 콜론 뒤 · 태그: 4.1.3-scala2.13-java21-python3-ubuntu처럼 버전 조합을 나타냅니다. 실습에서는 이 태그를 그대로 사용합니다.

서비스 이름과 컨테이너 이름

• 서비스 이름: YAML의 services: 아래 키입니다.
• 실제 컨테이너 이름: bigdata-week02-spark-master-1처럼 프로젝트명과 번호를 포함할 수 있습니다.

출처: 2장 강의자료 슬라이드 1–10. 슬라이드 번호는 파일의 실제 순서 기준입니다.

Linux용 Spark 환경을 Windows에서 실행하려고 WSL 2(Windows Subsystem for Linux 2)를 사용합니다. Docker Desktop이 이 환경을 이용해 Linux 컨테이너를 실행합니다.

Docker Desktop이 없다면 공식 Windows 설치 안내에서 설치 조건과 절차를 확인합니다. WSL이 없다면 아래 WSL 준비 절차부터 진행합니다.

1. Docker Desktop 실행과 Engine 확인

   실행 위치: Windows PowerShell, 어느 폴더에서나. Desktop에서 Engine running을 기다린 뒤 아래를 실행합니다.

   docker --version
   docker compose version
   docker version
   docker run --rm hello-world

   • docker --version: Docker 명령 도구의 버전을 확인합니다.
   • docker compose version: Compose 도구의 버전을 확인합니다.
   • docker version: Client와 Server(Engine)의 연결을 함께 확인합니다.
   • docker run --rm hello-world: 작은 시험 컨테이너를 실행합니다. --rm은 종료 후 그 컨테이너를 제거합니다.

   Server 연결 오류라면 Desktop 실행 상태부터 확인하세요.

2. WSL 상태 확인

   실행 위치: 일반 PowerShell에서 상태 확인.

   wsl --status
   wsl --version

   WSL 설치가 필요한 경우만 펼치기

   실행 위치: 관리자 권한 PowerShell. 설치가 안 된 경우 아래 설치 명령을 실행하고 Windows를 재시작합니다. 업데이트가 필요한 경우 업데이트 명령을 사용합니다. Docker Desktop 설치 후 WSL 2 기반 Engine 설정을 확인하세요.

   wsl --install
   wsl --update

   Microsoft 공식 WSL 설치 안내와 Docker Desktop Windows 설치 안내에서 자신의 환경에 맞는 설치 조건을 확인할 수 있습니다.

3. 실습 폴더로 이동

   실행 위치: 이 프로젝트의 BigData 최상단에서 Windows PowerShell. 이후 docker compose 명령은 이동한 실습 폴더에서 실행합니다.

   cd ".\실습자료\2장_실습자료"
   Get-ChildItem
   Get-ChildItem .\apps

   강의의 “week02-lab 폴더”에 해당합니다. 다음 6개 파일이 있는지 확인합니다.

   • compose.yaml: 서비스 구성 파일입니다.
   • README.md: 배포 절차를 안내합니다.
   • apps/check_pyspark.py: 이미지의 PySpark 실행을 검사합니다.
   • apps/check_network.py: 컨테이너 간 네트워크를 검사합니다.
   • apps/run.sh: 앱 제출 명령을 담습니다.
   • apps/first_app.py: 계산과 정답 검증을 수행합니다.

4. 지정된 이미지 다운로드

   실행 위치: 실습 폴더의 Windows PowerShell.

   $sparkImage = "spark:4.1.3-scala2.13-java21-python3-ubuntu"
   docker pull $sparkImage
   docker image ls $sparkImage

   확인: 목록의 이름·태그가 위 값과 일치해야 합니다. 다운로드에 실패하면 네트워크를 확인하고 오류 메시지를 교수님께 전달하세요.

docker image load -i <파일경로>

출처: 강의 슬라이드 11–16 · 배포 README의 이미지 확보·Plan B. Get-ChildItem .\apps는 파일 확인을 돕는 보충 명령입니다.

Compose 파일은 실행할 서비스와 설정을 정의합니다. 공통 설정을 한 번 정의하고, 서비스마다 실행 명령과 개별 설정을 추가합니다.

공통 설정: 한 번 쓰고 재사용

YAML은 들여쓰기로 포함 관계를 표현하는 설정 형식입니다. 아래는 compose.yaml 전체 원본에서 발췌한 공통 설정입니다.

name: bigdata-week02

x-spark: &spark
  image: spark:4.1.3-scala2.13-java21-python3-ubuntu
  environment:
    PYSPARK_PYTHON: python3
  init: true
  stop_grace_period: 30s

services:

Master: 상태 검사와 서비스 시작 조건

  spark-master:
    <<: *spark
    hostname: spark-master
    entrypoint: ["/opt/spark/bin/spark-class"]
    command: ["org.apache.spark.deploy.master.Master", "--host", "spark-master", "--port", "7077", "--webui-port", "8080"]
    ports:
      - "127.0.0.1:8080:8080"
    healthcheck:
      test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8080', timeout=3)"]
      interval: 5s
      timeout: 5s
      retries: 20
      start_period: 20s

• entrypoint: 처음 실행할 프로그램입니다.
• command: 그 프로그램에 전달할 실행 내용입니다. 여기서는 Spark의 Master 프로그램을 실행합니다.
• hostname: 컨테이너 내부 호스트 이름입니다.
• healthcheck: Engine이 Master 안에서 HTTP UI 응답을 주기적으로 확인하도록 합니다. 상태는 starting → healthy 또는 unhealthy로 표시됩니다.

healthy는 이 UI 검사에 통과했다는 뜻이며 계산 성공을 증명하지는 않습니다.

Worker: 제공할 CPU와 메모리 알리기

  spark-worker-1:
    <<: *spark
    hostname: spark-worker-1
    entrypoint: ["/opt/spark/bin/spark-class"]
    command: ["org.apache.spark.deploy.worker.Worker", "--host", "spark-worker-1", "--cores", "1", "--memory", "1g", "--webui-port", "8081", "--work-dir", "/tmp/spark-work", "spark://spark-master:7077"]
    ports:
      - "127.0.0.1:8081:8081"
    depends_on:
      spark-master:
        condition: service_healthy

Worker 하나가 Master에 알리는 자원은 1 core, 1 GiB입니다.

• core: 계산을 수행할 CPU 자원 단위입니다.
• GiB: 메모리 용량 단위입니다. 여기서 1 GiB는 1024 MiB입니다.
• --work-dir: 작업 파일과 로그 경로입니다.

Worker 2는 같은 역할이며 이름은 spark-worker-2, 호스트 UI 포트는 8082입니다.

Client: 실습 폴더 연결과 대기

  spark-client:
    <<: *spark
    hostname: spark-client
    entrypoint: ["/bin/bash", "-lc"]
    command: ["exec sleep infinity"]
    ports:
      - "127.0.0.1:4040:4040"
    volumes:
      - ./apps:/opt/spark/apps:ro
    depends_on:
      spark-master:
        condition: service_healthy

exec sleep infinity는 shell을 계속 대기하는 프로그램으로 바꿔 Client가 종료되지 않게 합니다. 이 시점에는 Driver가 없습니다.

실습 폴더 연결: bind mount

bind mount는 호스트 폴더를 컨테이너에서 보이게 연결하는 방식입니다. ./apps:/opt/spark/apps:ro는 세 부분으로 구성됩니다.

• ./apps: 호스트에 있는 실습 코드 폴더입니다.
• /opt/spark/apps: Client 안에서 그 폴더를 읽을 경로입니다.
• ro: read-only, 즉 컨테이너에서 읽기 전용이라는 뜻입니다.

파일을 따로 복사하지 않아도 Client에서 Windows의 실습 코드를 읽어 실행할 수 있습니다.

출처: 강의 슬라이드 17–29 · compose.yaml. Master·Worker 1·Worker 2·Client 네 서비스가 정의돼 있습니다.

Spark는 데이터를 나누어 여러 프로세스에서 처리하는 엔진입니다. 이번 실습에서는 Spark 자체의 클러스터 관리 방식인 Standalone을 사용합니다.

준비 → 제출 → 계산

1. 준비: Compose가 네 컨테이너 실행을 요청하고 Worker가 Master에 등록합니다. 별도 SSH 로그인이나 키 복사는 필요 없습니다.
2. 제출: Client에서 spark-submit을 실행하면 Driver가 앱을 등록하고 자원을 요청합니다. Master는 Worker에 Executor 시작을 지시합니다.
3. 계산: Executor가 Driver에 연결합니다. Driver와 Executor가 Task 지시·상태·결과를 직접 주고받습니다. Master가 모든 계산 메시지를 중계하지 않습니다.

• Task: Executor가 수행하는 작은 작업 단위입니다.
• Worker와 Executor: Worker는 Executor를 관리하고, Executor가 Task를 실행합니다.
• 이번 실습의 자원: 네 컨테이너 모두 한 PC의 자원을 사용합니다.

출처: 강의 슬라이드 18, 23–25, 37, 39–40, 45–48 · 역할 정의 보충: Apache Spark 공식 클러스터 개요. 이 실습의 실행 옵션과 버전은 제공 파일에 따릅니다.

프로그램에 연결할 때는 주소와 포트로 목적지를 지정합니다.

• 포트: 컴퓨터나 컨테이너 안의 통신 창구를 구분하는 번호입니다.
• 호스트: 여기서는 Docker를 실행하는 Windows PC입니다.

포트 설정의 세 자리

127.0.0.1:8082:8081은 호스트 IP : 호스트 포트 : 컨테이너 포트 순서입니다.

• 호스트 IP · 127.0.0.1: 같은 Windows PC에서 UI에 접속하도록 제한합니다.
• 호스트 포트 · 8082: Windows 브라우저에서 Worker 2 UI를 열 때 쓰는 번호입니다.
• 컨테이너 포트 · 8081: Worker 2 내부의 UI가 사용하는 번호입니다.

두 Worker는 서로 다른 컨테이너이므로 내부에서 각각 8081을 쓸 수 있습니다. Windows에서는 같은 IP의 같은 포트를 두 곳에 연결할 수 없어 8081과 8082로 나눕니다.

내부 연결은 서비스 이름으로

DNS(Domain Name System)는 이름을 IP 주소로 바꾸는 체계입니다. Compose 내부에서는 서비스 이름을 사용합니다.

• 연결 순서: Worker가 spark-master의 IP를 조회한 뒤 그 IP의 7077로 연결합니다.
• 이름을 쓰는 이유: 컨테이너 IP는 바뀔 수 있습니다. 숫자 IP를 코드에 고정하지 마세요.
• DNS 구성: Docker가 제공하므로 별도 컨테이너는 필요 없습니다.

출처: 강의 슬라이드 9, 26–31, 42–43 · 실제 포트 설정 · 보충 확인: Docker 공식 Compose 네트워크 설명.

컨테이너 간 연결 없이 작은 계산을 실행합니다. 이 단계에서 실패하면 이미지와 실행 환경을 먼저 점검합니다.

① Compose 구성 확인

실행 위치: 실습자료/2장_실습자료 폴더의 Windows PowerShell.

docker compose config --quiet
docker compose config --services

• --quiet: 문법과 구성에 오류가 없으면 출력 없이 성공합니다.
• --services: 파일에 정의된 서비스 이름을 보여줍니다. 현재 파일에는 Master, Worker 1·2, Client의 서비스 이름 4개가 나옵니다.

이번 실습에서는 Worker 1·2를 사용합니다. 다음 단계에서 위 네 서비스를 실행합니다.

오류 시: 현재 폴더와 YAML 들여쓰기를 확인하세요.

② 일회용 컨테이너에서 PySpark 검사

실행 위치: 같은 PowerShell에서 입력하며, 검사는 일회용 컨테이너 안에서 실행됩니다.

docker compose run --rm --no-deps --entrypoint /opt/spark/bin/spark-submit spark-client --master "local[1]" /opt/spark/apps/check_pyspark.py
$LASTEXITCODE

• run: Client 설정으로 일회용 컨테이너를 만듭니다.
• --no-deps: Master와 Worker를 함께 시작하지 않는 옵션입니다.
• --entrypoint: 이번만 대기 명령 대신 Spark 제출 도구를 사용하게 합니다.
• local[1]: 이 컨테이너 안의 로컬 실행 스레드 하나를 쓰는 모드입니다.

로컬 검사입니다. $LASTEXITCODE는 직전 외부 프로그램의 종료 코드이며, 0이면 정상 종료입니다. 다른 명령으로 값이 바뀌기 전에 바로 확인하세요.

PYSPARK_VERSION=4.1.3
PYSPARK_IMAGE_CHECK=PASS

확인 질문: 이 검사에 PASS가 나오면 Worker 등록도 완료된 걸까요? 아닙니다. --no-deps와 local[1] 때문에 아직 Worker를 사용하지 않았습니다.

출처: 강의 슬라이드 32–35 · check_pyspark.py · README의 이미지 실행 검사.

컨테이너 상태, Spark 등록, 네트워크는 서로 다른 확인 항목입니다. 셋을 나누어 보면 어디에서 문제가 생겼는지 찾기 쉽습니다.

1. 네 서비스 실행

   실행 위치: 실습 폴더의 Windows PowerShell.

   docker compose up -d --remove-orphans spark-master spark-worker-1 spark-worker-2 spark-client
   docker compose ps -a

   -d는 백그라운드 실행입니다. 첫 줄은 이번 실습에 쓸 네 서비스를 지정합니다. --remove-orphans는 같은 Compose 프로젝트에서 현재 파일에 정의되지 않은 서비스의 컨테이너를 제거합니다. 실행 전에 같은 프로젝트에서 유지해야 할 컨테이너가 있는지 확인하세요.

   준비가 끝날 때까지 기다린 뒤 네 컨테이너의 상태를 확인하세요. 옵션의 의미는 Docker Compose up 공식 문서에서 확인할 수 있습니다.

   • Master: healthy
   • Worker 2개·Client: Up

2. Master UI에서 Worker 등록 확인

   실행 위치: Windows 브라우저에서 Master UI 열기.

   • Worker: ALIVE 2개
   • 각 Worker 자원: 1 core, 약 1024 MiB
   • Executor: 앱 제출 전에는 없어도 정상

3. Client에서 네트워크 검사

   입력 위치: 실습 폴더의 Windows PowerShell. 실제 검사 위치: Client 컨테이너 안.

   docker compose exec spark-client python3 /opt/spark/apps/check_network.py
   $LASTEXITCODE

   exec는 이미 실행 중인 컨테이너 안에서 명령을 수행합니다. run과 달리 새 컨테이너를 만들지 않습니다.

TCP는 프로그램 간 연결을 맺고 데이터를 주고받는 통신 방식입니다. 이 검사는 연결을 열 수 있는지만 봅니다. 실패 표시는 다음처럼 구분하세요.

• DNS_FAIL: 이름 조회에 실패했습니다.
• TCP_FAIL: 해당 포트 연결에 실패했습니다.

서비스 이름·실행 상태·로그를 순서대로 확인하세요.

출처: 강의 슬라이드 36–43 · check_network.py. 종료 코드 0/1 확인은 보충 단계입니다.

1부터 100까지 더하면 5050입니다. 정답을 미리 아는 문제로 Spark가 올바른 클러스터에서 실행됐는지 확인합니다.

계산과 검증 코드

numbers = spark.range(1, 101, 1, 4)
total = numbers.selectExpr("sum(id) AS total").first()["total"]
assert total == 5050, f"Unexpected result: {total}"

입력: 1~100을 네 조각으로

• 시작 · 1: 첫 숫자는 1입니다.
• 끝 · 101: 끝값은 포함하지 않으므로 마지막 숫자는 100입니다.
• 간격 · 1: 숫자가 1씩 증가합니다.
• 입력 partition · 4: 데이터를 네 조각으로 나눕니다.

데이터를 표현하는 두 용어

• partition(파티션): 데이터를 나누는 논리적 조각입니다.
• DataFrame: 행과 열로 표현하는 데이터입니다. 여기서는 id 열에 숫자가 들어갑니다.

계산과 확인: 합계가 5050인지

• selectExpr("sum(id) AS total"): id를 합산해 결과 열 이름을 total로 붙입니다.
• first(): 결과의 첫 행을 가져옵니다.
• ["total"]: 그 행에서 total 값을 꺼냅니다.
• assert: 조건이 틀리면 오류를 내어 검증 실패를 드러냅니다.

손으로도 100 × 101 ÷ 2 = 5050인지 대조할 수 있습니다.

run.sh가 정하는 실행 조건

#!/usr/bin/env bash
set -euo pipefail
exec /opt/spark/bin/spark-submit \
  --master spark://spark-master:7077 \
  --deploy-mode client \
  --driver-memory 512m \
  --executor-memory 512m \
  --executor-cores 1 \
  --total-executor-cores 2 \
  --conf spark.dynamicAllocation.enabled=false \
  --conf spark.driver.host=spark-client \
  --conf spark.driver.bindAddress=0.0.0.0 \
  --conf spark.driver.port=39000 \
  --conf spark.blockManager.port=39001 \
  /opt/spark/apps/first_app.py "$@"

"""Week 2: submit, verify a known answer, observe the UI, and stop."""
import argparse
import time
from pyspark.sql import SparkSession

parser = argparse.ArgumentParser()
parser.add_argument("--wait-seconds", type=int, default=120)
args = parser.parse_args()

spark = SparkSession.builder.appName("Week02-First-App").getOrCreate()
try:
    spark.sparkContext.setLogLevel("WARN")
    print(f"MASTER={spark.sparkContext.master}", flush=True)
    print(f"APP_ID={spark.sparkContext.applicationId}", flush=True)
    assert spark.sparkContext.master == "spark://spark-master:7077"

    # Four input partitions. DataFrame syntax is covered next week.
    numbers = spark.range(1, 101, 1, 4)
    total = numbers.selectExpr("sum(id) AS total").first()["total"]
    print(f"SUM_1_TO_100={total}", flush=True)
    assert total == 5050, f"Unexpected result: {total}"
    print("CHECK=PASS", flush=True)
    print(f"UI observation: {max(0, args.wait_seconds)} seconds", flush=True)
    time.sleep(max(0, args.wait_seconds))
finally:
    spark.stop()
print("APP_STOPPED", flush=True)

앱 제출

입력 위치: 실습 폴더의 Windows PowerShell. 앱은 Client 컨테이너에서 실행됩니다.

1. 첫 줄로 앱을 제출하고 다음 절의 UI를 120초 동안 관찰합니다.
2. 프롬프트가 돌아오면 즉시 두 번째 줄로 종료 코드를 확인합니다.

docker compose exec spark-client bash /opt/spark/apps/run.sh
$LASTEXITCODE

MASTER=spark://spark-master:7077
SUM_1_TO_100=5050
CHECK=PASS
UI observation: 120 seconds
APP_STOPPED

출처: 강의 슬라이드 44–50 · run.sh · first_app.py. 분할 그림과 손계산은 학습용 보충 설명입니다.

계산 결과와 함께 로그·UI를 보면 앱이 어떻게 실행됐는지 확인할 수 있습니다.

• 로그: 실행 중 일어난 일을 글로 기록한 자료입니다.
• UI(User Interface): 상태를 화면으로 보여주는 인터페이스입니다.

화면이 기대와 다르면 최근 로그부터

실행 위치: 같은 실습 폴더의 Windows PowerShell. 앱을 관찰 중이라면 두 번째 PowerShell을 열어 같은 폴더로 이동한 뒤 실행합니다.

docker compose logs --tail 80 spark-master spark-worker-1 spark-worker-2

• --tail 80: 최근 로그 80줄을 확인합니다.
• 찾을 내용: Master 시작, Worker·앱 등록, Executor 시작과 오류 메시지.

실시간 추적은 아래 명령을 사용합니다. Ctrl+C로 로그 추적을 끝냅니다.

docker compose logs -f spark-worker-1

확인 질문: 합계가 보인 후 4040이 닫혔습니다. 무조건 장애일까요? APP_STOPPED와 종료 코드 0이 확인되고 관찰 시간이 끝났다면 정상적인 종료입니다.

출처: 강의 슬라이드 51–52 · README의 관찰·종료 확인. 증상별 점검 표는 보충 안내입니다.

앱이 종료돼도 컨테이너는 남을 수 있습니다. 실습을 잠시 중단할 때는 컨테이너를 중지하고, 마칠 때는 제거합니다.

잠깐 중지하고 다시 시작할 때

실행 위치: 실습 폴더의 Windows PowerShell. 앱이 정상 종료된 뒤 실행합니다.

docker compose stop
docker compose ps -a
docker compose start spark-master spark-worker-1 spark-worker-2 spark-client
docker compose ps -a

• stop 후: 이번 실습에 사용한 네 컨테이너가 Exited 상태로 남습니다.
• start 후: 지정한 네 서비스를 다시 시작합니다. Master healthy, Worker·Client Up, Master UI의 Worker 2개 재등록을 확인합니다.

실습을 끝낼 때

docker compose down
docker compose ps -a

확인: 이 프로젝트의 컨테이너 목록이 비어야 합니다. Spark 이미지와 Windows의 apps 파일은 다음 실습에서 재사용합니다.

다시 시작할 때는 클러스터 실행 단계로 돌아가 네 서비스를 지정한 명령을 사용하세요.

학습 확인 항목

• 이미지 하나로 역할이 다른 컨테이너 네 개를 만들 수 있다.
• Master는 자원을 배정하고, Worker는 Executor를 관리하며, Driver는 Task를 조정한다.
• Windows의 localhost:8082는 Worker 2 내부 8081로 연결된다.
• 로컬 이미지 검사, Worker 등록, 네트워크 검사, 계산 검증은 각각 다른 증거다.
• 입력 partition 4개와 전체 Executor core 2개는 다른 개념이다.
• 합계 5050, CHECK=PASS, APP_STOPPED와 종료 코드 0을 함께 확인한다.
• stop과 down이 남기는 상태를 구분하고 다시 시작할 수 있다.

출처: 강의 슬라이드 53–56 · README의 종료 절차.