spark-on-k8s-operstor / user-guide

ㅕgithub.com/GoogleCloudPlatform/spark-on-k8s-operator/blob/master/docs/user-guide.md

 

User Guide

spark 를 사용하기 위한 Kubernetes operator 를 빌드, 설치, 예제 앱 실행을 위해서는 Quick Start Guide 참조

SparkApplication, ScheduledSparkApplication  의 API 정의는 API Specification 을 참조

kubesctl 에 추가적인  기능을 제공하는 sparkctl  을 제공하고 있음. sparkctl 에 대한 문서는 README 참고

Using a SparkApplication

SparkApplication 을 YAML 파일에 명세하고, kubectl 또는 sparkctl 을 통해 쿠버네티스에 제출하면 operator 는 자동으로 앱을 Kubernetes 클러스터에 제출하고, 실행 상태를 사용자에게 노출함.

Writing a SparkApplication Spec

다른 Kubernetes API object 들 처럼, SparkApplication 에도 apiVersion, kind, metadata 필드를 작성해야 한다. manifest 에 대한 일반적인 정보는 object management using kubectl 에서 찾을 수 있다.

SparkApplication 은 .spec 섹션도 필요하다. 이 섹션에 언어(Scala, Java, Python, R), 배포 모드( cluster 또는 client), main application resource URI( 앱 jar 의 URI), 메인 클래스, 앱의 인수 등을 작성한다. .spec.nodeSelector 를 사용하면 Node selector 를 사용할 수 있다.

.spec.image 에는 (driver 와 executor 가 사용할) 통합이미지를 지정하고, .spec.imagePullPolicy 를 통해서는 이미지를 가져오는 규칙을 지정한다.  필요에 따라 .spec.initContainerImage 에 custom init-container 이미지를 적을 수 있는데, .spec.initContainerImage 가 .spec.image 에 우선하여 사용된다.

아래는 SparkApplication 명세의 부분 예제이다.

apiVersion: sparkoperator.k8s.io/v1beta2
kind: SparkApplication
metadata:
  name: spark-pi
  namespace: default
spec:
  type: Scala
  mode: cluster
  image: gcr.io/spark/spark:v3.0.0
  mainClass: org.apache.spark.examples.SparkPi
  mainApplicationFile: local:///opt/spark/examples/jars/spark-examples_2.12-3.0.0.jar

Specifying Deployment Mode 배포 모드 정하기

.spec.deploymode 는 cluster 로 지정해야 한다. client 는 구현되어 있지 않다. 드라이버 팟은 내부적으로는 client 모드로 spark-submit 을 실행하여 driver program 을 실행한다.

Specifying Application Dependencies 앱 의존성 정하기

Spark 앱에서 main 앱 자원을 실행하기 위해서 추가적인 파일들이 필요할 수 있는데, spark-submit 을 사용할 때는 --jar 나 --files 옵션을 통해 지정한다. SparkApplication 에는 .spec.deps.jars 와 .spec.deps.files 에 지정할 수 있다.

driver 와  executor 컨테이너들이 파일들을 다운 받을 경로는 .spec.deps.jarsDownloadDir 과 .spec.deps.filesDownloadDir 을 사용하여 지정할 수 있다. .spec.deps.downloadTimeout 과 .spec.deps.maxSimultaneousDownloads 를 사용하면 타임아웃과 HTTP 서버나 HDFS 와 같은 외부 저장소에서의 최대 동시 다운로드 수를 지정할 수 있다.

다음 예제는 container-local( 컨테이너 내부의) 와 원격 저장소의 의존성을 지정하는 예제이다.

spec:
  deps:
    jars:
      - local:///opt/spark-jars/gcs-connector.jar
    files:
      - gs://spark-data/data-file-1.txt
      - gs://spark-data/data-file-2.txt

또한 .spec.deps.packages 에 maven 의존성을 추가할 수 있으며, .spec.deps.excludePackage 를 사용하여 의존성 충돌을 해결할 수 있다. 추가적인 maven 저장소는 .spec.deps.repositories 목록에 적을 수 있다. 이 항목들은 spark-submit 의 --packages, --exclude-packages, --repositories 등에 전달된다.

주의

• packages 에는 "groupId:artifactId:version" 의 형태로 지정해야 한다
• excludePackages 목록에는 "groupId:artifactId" 의 형태로 지정해야 한다.

spec:
  deps:
    repositories:
      - https://repository.example.com/prod
    packages:
      - com.example:some-package:1.0.0
    excludePackages:
      - com.example:other-package

Specifying Spark Configuration Spark 설정하기

두 가지 방식으로 하둡 설정을 할 수 있으며, 개별 하둡 설정을 .spec.hadoopConf 에 쓸수도 있고, .spec.hadoopConfigMap 을 사용하여, Kubernetes ConfigMap 에 저장한 core-site.xml 등을 사용할 수도 있다. operator 는 .spec.hadoopConf 에 지정한 개별 하둡 설정들에 spark.hadoop. 프리픽스를 자동으로 붙인다. .spec.hadoopConfigMap 을 사용한다면, ConfigMap 을 driver 와 executor 들에 ConfigMap 을 추가적으로 마운팅하고, HADDOP_CONF_DIR 를 그 마운팅된 경로로 지정해준다.

아래의 예제는 개별 하둡 설정이다.

spec:
  hadoopConf:
    "fs.gs.project.id": spark
    "fs.gs.system.bucket": spark
    "google.cloud.auth.service.account.enable": true
    "google.cloud.auth.service.account.json.keyfile": /mnt/secrets/key.json

Writing Driver Specification 드라이버 설정하기

.spec.driver 필드에 driver 설정을 넣는다. 요청할 메모리와 cpu 등의 자원을 지정하고, 드라이버가 사용해야 하는 컨테이너 이미지도 지정한다. driver 가 사용할 label, annotation, 환경변수도 설정할 수 있다. 기본적으로 driver 팟의 이름은 Spark submission client 가 자동적으로 셋팅하며 .spec.driver.podName 을 사용하여 지정할 수도 있다. 드라이버팟은 기본적으로 'default' service account 를 사용한다. 다른 권한이 있는 service account 를 사용하려면 .spec.driver.serviceAccount 을 사용할 수 있다. 별도의 컨테이너 이미지가 필요하다면 .spec.driver.image 를 사용한다. .spec.driver.image 는 .spec.image 에 우선한다. .spec.image 나 .spec.driver.image 중에 하나는 반드시 설정해야 한다.

spec:
  driver:
    cores: 1
    coreLimit: 200m
    memory: 512m
    labels:
      version: 3.0.0
    serviceAccount: spark

Writing Executor Specification 익서큐터 설정하기

executor 를 위한 설정은 .spec.executor 하위에 있다. executor 팟들이 사용할 메모리와 cpu 를 지정하고, executor 가 사용할 이미지도 지정할 수 있다. executor 가 사용할 label, annotation, 환경 변수들을 추가적으로 설정할 수 있다. 기본적으로는 하나의 executor 를 클러스터에 요청한다. 더 많이 필요하다면 .spec.executor.instances 를 사용해서 지정한다. 별도의 이미지가 필요하다면 .spec.executor.image 를 사용하며, .spec.image 값에 우선한다. .spec.image 와 .spec.executor.image 중 한가지를 반드시 설정해야 한다.

앱에 필요한 Secret 과 ConfigMap 을 executor 팟에 마운트하려면 .spec.sececutor.secrets 와 .spec.executor.configMap 을 사용한다.

spec:
  executor:
    cores: 1
    instances: 1
    memory: 512m
    labels:
      version: 3.0.0

Specifying Extra Java Options

.spec.driver.javaOptions 와 .spec.executor.javaOptions 를 통해 driver 와 executor 의 추가적인 java 옵션을 전달할 수 있다.

spec:
  executor:
    javaOptions: "-XX:+UnlockExperimentalVMOptions -XX:+UseCGroupMemoryLimitForHeap"

위 두 필드은 spark.driver.extraJavaOptions 와 spark.executor.extraJavaOptions 으로 전환된다.

spark.driver.extraJavaOptions 와 spark.executor.extraJavaOptions 대신 .spec.driver.javaOptions, .spec.executor.javaOptions 을 쓰도록 한다. 그 이유는 extraJavaOptions 들을 수정할 수 있는 다른 필드들과 잘 동작하기 때문이다.

Specifying Encivonment Variables

.spec.driver.env 와 .spec.executor.env, .spec.driver.envFrom 와 .spec.exeuctor.envForm  를 통해서 driver 와 executor 컨테이너에서 사용할 환경변수를 지정할 수 있다.

.spec.driver.env( 와 .spec.exeuctor.env) 는 EnvVar 리스트를 받는다. EnvVar 는 다양한 형태의 환경변수가 될수 있으며, name-value 쌍, ConfigMap 키, Secret 키 등이다.

.spec.driver.envFrom( 과 spec.executor.envFrom) 는 EnvFromSource 리스트를 받고, ConfigMap 이나 Secret 의 모든 key-value 쌍들을 환경 변수로 사용할 수 있게 해준다.

spec:
  driver:
    env:
      - name: ENV1
        value: VAL1
      - name: ENV2
        value: VAL2
      - name: ENV3
        valueFrom:
          configMapKeyRef:
            name: some-config-map
            key: env3-key
      - name: AUTH_KEY
        valueFrom:
          secretKeyRef:
            name: some-secret
            key: auth-key
    envFrom:
      - configMapRef:
          name: env-config-map
      - secretRef:
          name: env-secret
  executor:
    env:
      - name: ENV1
        value: VAL1
      - name: ENV2
        value: VAL2
      - name: ENV3
        valueFrom:
          configMapKeyRef:
            name: some-config-map
            key: env3-key
      - name: AUTH_KEY
        valueFrom:
          secretKeyRef:
            name: some-secret
            key: auth-key  
    envFrom:
      - configMapRef:
          name: my-env-config-map
      - secretRef:
          name: my-env-secret

레거시인 envVars 를 사용할 수 있지만, 사용하지 않도록 제안되며, 향후 API 버전에서는 제거된다.

Requesting GPU Resource

.spec.driver.gpu 와 .spec.driver.cpu 를 사용해서 GPU 자원을 지정한다

spec:
  driver:
    cores: 0.1
    coreLimit: "200m"
    memory: "512m"
    gpu:
      name: "amd.com/gpu"   # GPU resource name
      quantity: 1           # number of GPUs to request
    labels:
      version: 3.0.0
    serviceAccount: spark
  executor:
    cores: 1
    instances: 1
    memory: "512m"
    gpu:
      name: "nvidia.com/gpu"
      quantity: 1

이 기능은 mutating admission webhook 이 필요하다. Quick Start Guide 를 참조한다.

Host Network

선택적으로 .spec.driver.hostNetwork 와 .spec.executor.hostNetwork 필드를 사용해서 hostNetwork 를 설정할 수 있다. hostNetwork 가 true 이면, operator 는 파드의 spec.hostNetwork 를 ture 로 설정하고, spec.dnsPolicy 를 ClusterFirstWithHostNet 으로 설정한다.

spec:
  driver:
    cores: 0.1
    coreLimit: "200m"
    memory: "512m"
    hostNetwork: true
    labels:
      version: 3.0.0
    serviceAccount: spark
  executor:
    cores: 1
    instances: 1
    memory: "512m"

이 기능은 mutating admission webhook 이 필요하다.

Mounting Secrets

선택적으로 secrets 필드를 사용해서 Kuberntes Secrets 목록을 설정하여 driver 와 executor 에 마운트할 수 있다.

이 필드는 Secret 의 이름이 키이고 마운트 경로와 타입을 값으로 갖는 map 이다. 아례 예제는 GCPServiceAccount 타입의 gcp-svc-account 라는 이름의 secret 를 /mnt/secrrets 에 마운팅하는 예제이다.

spec:
  driver:
    secrets:
      - name: gcp-svc-account
        path: /mnt/secrets
        secretType: GCPServiceAccount

secretType 필드에 쓴 시크릿의 타입은 특정 타입의 Secret 를 처리해야 하는지 operator 가 확인할 수 있는 hint 를 준다. 예를 들어 GCPServiceAccount 타입의 Secret 의 경우에는 operator 가 추가적으로 GOOGLE_APPLICATIOn_CREDENTIALS 환경변수가 시크릿에 저장된 JSON 키 파일을 가리키도록 한다. Getting Started with Authentication 에 service account JSON key file 을 사용해서 GCP 서비스에 인증하는 방법이 설명되어 있다.

유사하게 HadoopDelegationToken 타입의 Secret 라면, operator 는 HADOOP_TOKEN_FIL_LOCATION 이 하둡 delegation token 을 저장하고 있는 파일을 가리키도록 설정한다. 이 경우에는 delegation token file 이 저장되어 있는 Secret data map 의 키는 hadoop.token 으로 가정한다. secretType 필드는 다른 설정이 필요없다면 Generic 으로 해야 한다.

Mounting ConfigMaps

configMaps 필드를 통해 driver 와 exeuctor 에 Kubernetes ConfigMaps 목록을 설정할 수 있다. 해당 필드의 값은 ConfigMaps 의 이름이 키이고 값에는 마운팅경로를 값에 지정하는 map 이다.

아래 예제는 configmap1 이라는 이름의 ConfigMap 을 /mnt/config-maps 에 마운팅하는 설정이다.

spec:
  driver:
    configMaps:
      - name: configmap1
        path: /mnt/config-maps

이 기능을 사용하기 위해서는 mutating admission webhook 이 필요하다.

Mounting a ConfigMap storing Spark Configuration Files

SparkApplication 에는 spark-env.sh 나 spark-default.conf 와 같은 Spark 설정 파일들을 저장하는 ConfigMap 을 .spec.sparkConfigMap 필드에 지정할 수 있다. ConfigMap 은 SparkApplication 과 같은 namespace 에 있어야 한다. operator 는 /etc/spark/conf 에  ConfigMap 을 driver 와 executor 에 마운트한고 SPARK_CONF_DIR 에 /etc/spark/conf 를 할당한다.

이 기능을 사용하려면 mutating admission webhook 이 필요하다.

Mounting a ConfigMap storing Hadoop Configuration Files

core-site.xml 과 같은 하둡 설정파일을 지정한 ConfigMap 은 .spec.hadoopConfigMap 에 지정한다. operator 는 ConfigMap 을 /etc/hadoop/conf 경로에 driver 와 executor 모두에 마운트하고, HADOOP_CONF_DIR 을 /etc/hadoop/conf 로 설정한다.

이 기능을 사용하려면 mutating admission webhook 기능이 필요하다.

Mounting Volumes

.spec.volumes 에 driver 와 executor 들에 필요한 volume 목록을 지정할 수 있다.

volumnMounts 에는 driver 와 executor 각각에 필요한 volume 들을 지정할 수 있다.

spec:
  volumes:
    - name: spark-data
      persistentVolumeClaim:
        claimName: my-pvc
    - name: spark-work
      emptyDir: {}
  driver:
    volumeMounts:
      - name: spark-work
        mountPath: /mnt/spark/work
  executor:
    volumeMounts:
      - name: spark-data
        mountPath: /mnt/spark/data
      - name: spark-work
        mountPath: /mnt/spark/work

이 기능은 mutating admission webhook 이 필요하다.

 

... 읽는 중 ..