서버리스 Spark Connect 클라이언트 사용

Managed Service for Apache Spark Connect 클라이언트(google-cloud-spark-connect)는 오픈소스 Apache Spark Connect 클라이언트를 기반으로 빌드된 Python 클라이언트 라이브러리입니다. 이를 통해 로컬 애플리케이션, 스크립트, 노트북이 Spark Connect 프로토콜을 통해 원격 Managed Service for Apache Spark 세션에서 PySpark 워크로드를 실행할 수 있습니다.

표준 Apache Spark Connect 클라이언트를 직접 사용하는 것과 비교하여 google-cloud-spark-connect는 다음과 같은 이점을 제공합니다.

  • 자동화된 세션 수명 주기 및 인증: ManagedSparkSession.builder.getOrCreate()는 원격 Managed Service for Apache Spark 대화형 세션을 자동으로 프로비저닝, 구성 또는 재사용하고 갱신되는 Google Cloud 사용자 인증 정보를 연결합니다. ManagedSparkSession로 작성된 코드는 google-cloud-spark-connect 패키지가 일괄 워크로드의 Python 환경에 설치되어 있는 경우 Managed Service for Apache Spark 일괄 워크로드로 제출될 때 변경되지 않은 상태로 실행됩니다.
  • 실시간 진행률 표시줄 및 모니터링 링크: 세션 생성 및 Spark 작업 실행 중에 노트북 및 대화형 터미널에 실시간 진행률 표시줄을 표시하고(단계별 작업 완료 추적) Google Cloud 콘솔의 세션 세부정보 페이지, Spark UI, 개별 Spark 쿼리 실행 페이지에 대한 직접 링크를 제공합니다.
  • 대화형 노트북 추가 기능: interactive 추가 기능과 함께 설치된 경우 IPython 또는 Jupyter 노트북에서 google.cloud.managed_spark_connect를 가져오면 다음이 자동으로 로드됩니다.
    • explore_dataframe()(google-colabsqlviz 제공): 플로팅 코드를 작성하지 않고도 PySpark DataFrame을 대화형으로 탐색, 필터링, 정렬, 집계, 차트화할 수 있습니다.
    • %%sparksql 및 %sparksql 매직 명령어: 대화형 결과 시각화 및 Python 변수 또는 DataFrame 바인딩을 사용하여 노트북 셀에서 Spark SQL 쿼리를 실행합니다.
    • %dpip 매직 명령어를 사용하여 커스텀 컨테이너 이미지를 빌드하지 않고 원격 세션의 드라이버 및 실행자에 PyPI 패키지를 직접 설치합니다.

오픈소스 Spark Connect 클라이언트와 마찬가지로 google-cloud-spark-connect에는 로컬 Spark 설치가 필요하지 않습니다. [client] 추가 기능을 사용하면 전체 pyspark 배포 대신 경량 pyspark-client 패키지만 설치하므로 Managed Service for Apache Spark에서 PySpark를 실행하기 위해 Spark를 다운로드하거나 머신에 Java를 설치할 필요가 없습니다.

이 문서에서는 클라이언트를 설치, 구성, 사용하는 방법을 보여줍니다.

시작하기 전에

  1. 대화형 세션 및 런타임 프로필(세션 템플릿)을 관리하는 데 필요한 권한이 포함된 Identity and Access Management 역할이 있는지 확인합니다.

  2. Google Cloud외부에서 클라이언트를 실행하는 경우 사용자 인증 정보를 제공합니다. GOOGLE_APPLICATION_CREDENTIALS 환경 변수를 서비스 계정 키 파일의 경로로 설정합니다.

클라이언트 설치 또는 제거하기

pip를 사용하여 google-cloud-spark-connect 패키지를 설치하거나 제거할 수 있습니다.

설치

로컬 노트북 및 개발 환경(예: Google Cloud Data Agent Kit 또는 JupyterLab이 있는 VS Code)의 경우 가상 환경의 명령줄에서 클라이언트를 설치합니다.

pip install 'google-cloud-spark-connect[interactive,client]'

이렇게 하면 google-cloud-spark-connect가 설치되며, 다음과 같은 두 가지 선택적 추가 기능이 있습니다.

  • interactive: 대화형 노트북 확장 프로그램(explore_dataframe(), %%sparksql, %dpip)을 설치합니다. 노트북 외부의 독립형 Python 스크립트의 경우 생략할 수 있습니다.
  • client: 로컬 JVM이 필요하지 않은 경량 pyspark-client 패키지를 설치합니다.

Colab Enterprise와 같은 관리형 노트북 환경(전체 pyspark가 사전 설치됨)에서는 노트북 상단의 전용 설정 셀에서 client 대신 spark 추가 항목을 사용하여 %pip install를 실행합니다.

%pip install 'google-cloud-spark-connect[interactive,spark]'

제거

클라이언트를 제거하려면 다음 명령어를 실행합니다.

pip uninstall google-cloud-spark-connect pyspark-client

클라이언트 구성

세션의 프로젝트와 리전을 지정합니다. 환경 변수를 사용하거나 코드에서 빌더 API를 사용하여 이러한 값을 설정할 수 있습니다.

환경 변수

GOOGLE_CLOUD_PROJECT 및 GOOGLE_CLOUD_REGION 환경 변수를 설정합니다.

# Google Cloud Configuration for Managed Spark Connect Integration Tests
# Copy this file to .env and fill in your actual values

# ============================================================================
# REQUIRED CONFIGURATION
# ============================================================================

# Your Google Cloud Project ID
GOOGLE_CLOUD_PROJECT="your-project-id"

# Google Cloud Region where Managed Spark sessions will be created
# Integration tests also accept a comma-separated ordered list of fallback regions
# (e.g. "us-east1,us-central1,us-west1") when using a short subnet name.
GOOGLE_CLOUD_REGION="us-central1"

# Path to service account key file (if using SERVICE_ACCOUNT auth)
GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account-key.json"

# ============================================================================
# AUTHENTICATION CONFIGURATION
# ============================================================================

# Authentication type (SERVICE_ACCOUNT or END_USER_CREDENTIALS). If not set, API default is used.
# MANAGED_SPARK_CONNECT_AUTH_TYPE="SERVICE_ACCOUNT"
# MANAGED_SPARK_CONNECT_AUTH_TYPE="END_USER_CREDENTIALS"

# Service account email for workload authentication (optional)
# MANAGED_SPARK_CONNECT_SERVICE_ACCOUNT="your-service-account@your-project.iam.gserviceaccount.com"

# ============================================================================
# SESSION CONFIGURATION
# ============================================================================

# Session timeout in seconds (how long session stays active)
# MANAGED_SPARK_CONNECT_TTL_SECONDS="3600"

# Session idle timeout in seconds (how long session stays active when idle)
# MANAGED_SPARK_CONNECT_IDLE_TTL_SECONDS="900"

# Automatically terminate session when Python process exits (true/false)
# MANAGED_SPARK_CONNECT_SESSION_TERMINATE_AT_EXIT="false"

# Custom file path for storing active session information
# MANAGED_SPARK_CONNECT_ACTIVE_SESSION_FILE_PATH="/tmp/managed_spark_connect_session"

# ============================================================================
# DATA SOURCE CONFIGURATION
# ============================================================================

# Default data source for Spark SQL (currently only supports "bigquery")
# MANAGED_SPARK_CONNECT_DEFAULT_DATASOURCE="bigquery"

# ============================================================================
# ADVANCED CONFIGURATION
# ============================================================================

# Custom Dataproc API endpoint (uncomment if needed)
# GOOGLE_CLOUD_DATAPROC_API_ENDPOINT="your-region-dataproc.googleapis.com"

# Subnet name or URI for Managed Spark Connect (optional; defaults to "default" in tests)
# Accepts a short subnet name (e.g. "default") or full resource URI:
# MANAGED_SPARK_CONNECT_SUBNET="default"
# MANAGED_SPARK_CONNECT_SUBNET="projects/your-project-id/regions/us-central1/subnetworks/your-subnet-name"


Builder API

.projectId(), .location(), .sessionId() 메서드를 사용합니다.

spark = (
    ManagedSparkSession.builder
    .projectId("my-project")
    .location("us-central1")
    .sessionId("my-spark-session")
    .getOrCreate()
)

Spark 세션 시작

Spark 세션을 시작하려면 PySpark 애플리케이션 또는 노트북에서 ManagedSparkSession를 가져온 후 ManagedSparkSession.builder.getOrCreate() API를 호출합니다. 노트북을 다시 실행하거나 세션의 TTL(수명) 내에서 여러 노트북을 실행하면 활성 세션이 재사용되고 세션 시작 시간이 제거되도록 .sessionId()를 사용하여 커스텀 세션 ID를 설정하는 것이 좋습니다.

  1. ManagedSparkSession 클래스를 가져옵니다. IPython 또는 Jupyter 노트북에서 google.cloud.managed_spark_connect를 가져오면 interactive 추가 기능이 설치된 경우 대화형 노트북 추가 기능(explore_dataframe(), %%sparksql, %dpip)도 자동으로 로드됩니다.

  2. .sessionId() 및 .getOrCreate()를 호출하여 세션을 시작하거나 재사용합니다.

    from google.cloud.managed_spark_connect import ManagedSparkSession
    spark = ManagedSparkSession.builder.sessionId("my-spark-session").getOrCreate()
    

새 세션이 시작되는 동안 클라이언트는 실시간 진행률 표시줄과 Google Cloud 콘솔의 세션 세부정보 페이지로 연결되는 링크를 표시합니다(VS Code에서 링크는 대신 Data Agent Kit에서 세션을 엽니다). 지정된 ID를 가진 활성 세션이 이미 있으면 클라이언트는 새 세션을 만드는 대신 이 세션에 연결합니다. 이 경우 클라이언트는 코드의 세션 구성을 무시합니다. 구성 변경사항을 적용하려면 기존 세션(spark.stop(terminate=True))을 종료하거나 다른 세션 ID를 사용하세요. 지정된 ID를 가진 세션이 이미 종료된 경우 클라이언트는 이전 세션을 자동으로 삭제하고 동일한 ID로 새 세션을 만듭니다. 세션이 활성화되면 다음이 적용됩니다.

  • 노트북 셀에서 spark를 평가하면 세션 세부정보 페이지와 Spark UI에 대한 직접 링크가 표시됩니다.
  • Spark 작업(예: df.show(), df.collect(), df.toPandas())을 실행하면 실시간 태스크 진행률 표시줄과 Spark UI의 작업 실행 페이지에 대한 Spark 쿼리 링크가 표시됩니다.

Spark 속성 구성

Spark 속성을 구성하려면 하나 이상의 .config() 메서드를 빌더에 연결합니다.

from google.cloud.managed_spark_connect import ManagedSparkSession

spark = (
    ManagedSparkSession.builder
    .sessionId('my-spark-session')
    .config('spark.executor.memory', '48g')
    .config('spark.executor.cores', '8')
    .getOrCreate()
)

고급 구성 사용

빌더 메서드를 사용하여 세션 ID, 런타임 버전, 서브네트워크, 서비스 계정, 세션 템플릿, TTL(.ttl() / .ttlSeconds() 및 .idleTtl() / .idleTtlSeconds()) 또는 라벨과 같은 일반적인 세션 설정을 직접 구성할 수 있습니다.

import datetime
from google.cloud.managed_spark_connect import ManagedSparkSession

spark = (
    ManagedSparkSession.builder
    .projectId('my-project')
    .location('us-central1')
    .sessionId('my-spark-session')
    .runtimeVersion('3.0')
    .subnetwork('SUBNET')
    .idleTtl(datetime.timedelta(minutes=30))
    .getOrCreate()
)

기본 세션 리소스를 완전히 맞춤설정하려면 google.cloud.dataproc_v1.Session 객체를 .sessionConfig()에 전달합니다.

from google.cloud.managed_spark_connect import ManagedSparkSession
from google.cloud.dataproc_v1 import Session

session_config = Session()
session_config.environment_config.execution_config.subnetwork_uri = 'SUBNET'
session_config.runtime_config.version = '3.0'

spark = (
    ManagedSparkSession.builder
    .projectId('my-project')
    .location('us-central1')
    .sessionId('my-spark-session')
    .sessionConfig(session_config)
    .getOrCreate()
)

이름이 지정된 세션 재사용

.sessionId()로 커스텀 세션 ID를 설정하면 세션의 TTL 내에서 여러 노트북 또는 커널 다시 시작에서 단일 Spark 세션을 재사용할 수 있으므로 세션 시작 지연 시간이 없어지고 비용이 절감됩니다.

  1. 첫 번째 노트북에서 커스텀 ID로 세션을 만듭니다.

    from google.cloud.managed_spark_connect import ManagedSparkSession
    
    session_id = 'my-ml-pipeline-session'
    spark = ManagedSparkSession.builder.sessionId(session_id).getOrCreate()
    df = spark.createDataFrame([(1, 'data')], ['id', 'value'])
    df.show()
    
  2. 다른 노트북에서(또는 커널을 다시 시작한 후) 동일한 세션 ID를 지정하여 세션을 재사용합니다.

    from google.cloud.managed_spark_connect import ManagedSparkSession
    
    session_id = 'my-ml-pipeline-session'
    spark = ManagedSparkSession.builder.sessionId(session_id).getOrCreate()
    df = spark.createDataFrame([(2, 'more-data')], ['id', 'value'])
    df.show()
    

세션 ID는 4~63자(영문 기준)여야 하고 소문자로 시작해야 하며 소문자, 숫자, 하이픈만 포함해야 합니다. ID는 하이픈으로 끝날 수 없습니다. 이름이 지정된 세션은 명시적으로 종료되거나 구성된 TTL에 도달할 때까지 유지됩니다. 지정된 ID를 가진 세션이 이미 TERMINATED, TERMINATING 또는 FAILED 상태인 경우 클라이언트는 경고를 내보내고 이전 세션을 삭제한 후 동일한 ID로 새 세션을 만듭니다. 이전 세션을 삭제하면 Managed Service for Apache Spark에서 이전 메타데이터와 Spark UI 기록이 삭제되지만 로그는 Cloud Logging에서 계속 사용할 수 있습니다.

지정된 ID를 사용하는 활성 세션이 이미 있으면 클라이언트가 이 세션에 연결하고 코드의 세션 구성을 무시합니다. 구성 변경사항을 적용하려면 기존 세션을 종료하거나 다른 세션 ID를 사용하세요.

이름이 지정된 세션을 종료하려면 spark.stop(terminate=True)를 호출합니다. 인수 없이 spark.stop()를 호출하면 클라이언트 연결이 끊어지지만 이름이 지정된 세션은 계속 실행됩니다. .sessionId() 없이 생성된 세션은 spark.stop()에 의해 종료됩니다.

Spark SQL 매직 명령어 사용

interactive 추가 항목에는 Jupyter 노트북에서 Spark SQL 쿼리를 실행하고 google-colabsqlviz(explore_dataframe()에서 사용하는 것과 동일한 시각화 위젯)를 사용하여 대화형 테이블과 차트를 렌더링하는 %%sparksql 셀 매직과 %sparksql 라인 매직이 포함됩니다.

interactive 추가 기능이 있는 google-cloud-spark-connect를 설치하고 노트북에서 google.cloud.managed_spark_connect를 가져오면 매직 확장 프로그램이 자동으로 로드됩니다.

  1. 선택사항: google.cloud.managed_spark_connect를 가져오지 않은 경우 매직 확장 프로그램을 명시적으로 로드합니다.

    %load_ext google.cloud.managed_spark_magics
    
  2. 선택사항: 기본 설정을 구성합니다.

    %config SparkSql.limit=20
    
  3. %%sparksql 셀 매직(대화형 테이블을 렌더링하고 기본적으로 _df에 전체 DataFrame을 저장함) 또는 %sparksql 라인 매직(테이블 표시를 억제하고 DataFrame을 직접 반환함)을 사용하여 SQL 쿼리를 실행합니다.

    %%sparksql
    SELECT * FROM your_table
    
    df = %sparksql SELECT * FROM your_table
    
  4. 선택사항: Python 변수 및 DataFrame을 쿼리에 전달합니다. 유형이 지정된 SQL 리터럴 값은 :name, 테이블 또는 열 식별자는 IDENTIFIER(:name), 노트북 네임스페이스의 DataFrame은 {df}로 바인딩할 수 있습니다.

    min_id = 10
    df = spark.createDataFrame([(5, 'a'), (15, 'b')], ['id', 'val'])
    
    %%sparksql
    SELECT * FROM {df} WHERE id >= :min_id
    

고급 옵션을 사용하려면 %%sparksql 명령어에 플래그를 추가합니다. 예를 들어 결과를 캐시하고 뷰를 만들려면 다음 명령어를 실행합니다.

%%sparksql --cache --view result_view df
SELECT * FROM your_table WHERE condition = true

사용할 수 있는 옵션은 다음과 같습니다.

  • --cache 또는 -c: DataFrame을 캐시합니다.
  • --eager 또는 -e: localCheckpoint(eager=True)를 사용하여 결과를 즉시 계산합니다.
  • --view VIEW 또는 -v VIEW: 임시 뷰를 만듭니다.
  • --limit N 또는 -l N: 기본 행 표시 한도를 재정의합니다(셀 매직만 해당).
  • --display MODE 또는 -d MODE: 표시 모드를 설정합니다(colabsqlviz 또는 html, 셀 매직만 해당).
  • --quiet 또는 -q: 테이블 표시를 억제합니다.
  • --explain [MODE]: 결과를 표시하는 대신 쿼리 계획을 출력합니다.
  • --session NAME 또는 -s NAME: NAME 변수의 SparkSession에 대해 실행됩니다.
  • variable_name: 결과를 변수에 저장합니다(셀 매직만 해당, 기본값은 _df).

원격 세션에 PyPI 패키지 설치

커스텀 컨테이너 이미지를 빌드하거나 세션을 다시 시작하지 않고 PySpark 사용자 정의 함수(UDF) 내에서 서드 파티 Python 패키지를 사용하려면 원격 세션의 드라이버 및 실행자에 PyPI 패키지를 직접 설치하면 됩니다.

노트북 매직

활성 ManagedSparkSession가 있는 대화형 노트북에서 %dpip 매직 명령어(interactive 추가 항목이 설치될 때 google.cloud.managed_spark_connect와 함께 자동으로 로드됨)를 사용합니다.

%dpip install scipy

%dpip는 원격 세션에만 패키지를 설치합니다. Spark 외부의 로컬 코드에서 패키지를 가져오려면 로컬 Python 환경에도 설치합니다.

Python API

스크립트 또는 노트북에서 pypi=True를 spark.addArtifacts()에 전달합니다.

spark.addArtifacts("scipy", pypi=True)

다음 단계