Usar contêineres personalizados

O Serviço Gerenciado para Apache Spark executa cargas de trabalho sem servidor em contêineres do Docker. O contêiner fornece o ambiente de execução para os processos de driver e executor da carga de trabalho. Por padrão, o Serviço Gerenciado para Apache Spark usa uma imagem de contêiner que inclui os pacotes padrão do Spark, Java, Python e R associados a uma versão de lançamento do ambiente de execução. A API de lotes do Serviço Gerenciado para Apache Spark permite usar uma imagem de contêiner personalizada em vez da imagem padrão. Normalmente, uma imagem de contêiner personalizada adiciona dependências de Java ou Python da carga de trabalho do Spark não fornecidas pela imagem de contêiner padrão. Importante:não inclua o Spark na imagem do contêiner personalizada. O Serviço Gerenciado para Apache Spark vai montar o Spark no contêiner no tempo de execução.

Enviar uma carga de trabalho em lote do Spark usando uma imagem de contêiner personalizada

gcloud

Use o comando gcloud dataproc batches submit spark com a flag --container-image para especificar sua imagem de contêiner personalizada ao enviar uma carga de trabalho em lote do Spark.

gcloud dataproc batches submit spark \
    --container-image=custom-image, for example, "gcr.io/my-project-id/my-image:1.0.1" \
    --region=region \
    --jars=path to user workload jar located in Cloud Storage or included in the custom container \
    --class=The fully qualified name of a class in the jar file, such as org.apache.spark.examples.SparkPi \
    -- add any workload arguments here

Observações:

  • Custom-image: especifique a imagem de contêiner personalizada usando o seguinte formato de nomenclatura de imagem do Container Registry: {hostname}/{project-id}/{image}:{tag}, por exemplo, "gcr.io/my-project-id/my-image:1.0.1". Observação: hospede sua imagem de contêiner personalizada no Container Registry ou no Artifact Registry. O Serviço Gerenciado para Apache Spark não pode buscar contêineres de outros registros.
  • --jars: Especifique um caminho para uma carga de trabalho do usuário incluída na imagem de contêiner personalizada ou localizada no Cloud Storage, por exemplo, file:///opt/spark/jars/spark-examples.jar ou gs://my-bucket/spark/jars/spark-examples.jar.
  • Outras opções de comando de lotes: é possível adicionar outras flags de comando de lotes opcionais, por exemplo, para usar um servidor de histórico persistente (PHS, na sigla em inglês). Observação: o PHS precisa estar localizado na região em que você executa cargas de trabalho em lote.
  • Argumentos de carga de trabalho: é possível adicionar argumentos de carga de trabalho adicionando um "--" ao final do comando, seguido pelos argumentos de carga de trabalho.

REST

A imagem do contêiner personalizada é fornecida pelo RuntimeConfig.containerImage como parte de uma solicitação de API batches.create.

O exemplo a seguir mostra como usar um contêiner personalizado para enviar uma carga de trabalho em lote usando a API batches.create do Serviço Gerenciado para Apache Spark.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • project-id: ID do projeto do Google Cloud
  • region: região
  • custom-container-image: especifique a imagem de contêiner personalizada usando o seguinte formato de nomenclatura de imagem do Container Registry: {hostname}/{project-id}/{image}:{tag}, por exemplo, "gcr.io/my-project-id/my-image:1.0.1". Observação: hospede seu contêiner personalizado no Container Registry ou no Artifact Registry . O Serviço Gerenciado para Apache Spark não pode buscar contêineres de outros registros.
  • jar-uri: especifique um caminho para um jar de carga de trabalho incluído na imagem do contêiner personalizada ou localizado no Cloud Storage, por exemplo, "/opt/spark/jars/spark-examples.jar" ou "gs:///spark/jars/spark-examples.jar".
  • class:o nome totalmente qualificado de uma classe no arquivo jar, como "org.apache.spark.examples.SparkPi".
  • Outras opções: é possível usar outros campos de recursos de carga de trabalho em lote, por exemplo, use o campo sparkBatch.args para transmitir argumentos à carga de trabalho. Consulte a documentação do recurso Batch para mais informações. Para usar um servidor de histórico persistente (PHS), consulte Como configurar um servidor de histórico persistente. Observação: o PHS precisa estar localizado na região em que você executa cargas de trabalho em lote.

Método HTTP e URL: 

POST https://dataproc.googleapis.com/v1/projects/project-id/locations/region/batches

Corpo JSON da solicitação: 

{
  "runtimeConfig":{
    "containerImage":"custom-container-image
  },
  "sparkBatch":{
    "jarFileUris":[
      "jar-uri"
    ],
    "mainClass":"class"
  }
}

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

{
"name":"projects/project-id/locations/region/batches/batch-id",
  "uuid":",uuid",
  "createTime":"2021-07-22T17:03:46.393957Z",
  "runtimeConfig":{
    "containerImage":"gcr.io/my-project/my-image:1.0.1"
  },
  "sparkBatch":{
    "mainClass":"org.apache.spark.examples.SparkPi",
    "jarFileUris":[
      "/opt/spark/jars/spark-examples.jar"
    ]
  },
  "runtimeInfo":{
    "outputUri":"gs://dataproc-.../driveroutput"
  },
  "state":"SUCCEEDED",
  "stateTime":"2021-07-22T17:06:30.301789Z",
  "creator":"account-email-address",
  "runtimeConfig":{
    "properties":{
      "spark:spark.executor.instances":"2",
      "spark:spark.driver.cores":"2",
      "spark:spark.executor.cores":"2",
      "spark:spark.app.name":"projects/project-id/locations/region/batches/batch-id"
    }
  },
  "environmentConfig":{
    "peripheralsConfig":{
      "sparkHistoryServerConfig":{
      }
    }
  },
  "operation":"projects/project-id/regions/region/operation-id"
}

Criar uma imagem de contêiner personalizada

As imagens de contêiner personalizadas do Serviço Gerenciado para Apache Spark são imagens do Docker. É possível usar as ferramentas para criar imagens do Docker para criar imagens de contêiner personalizadas, mas há condições que as imagens precisam atender para serem compatíveis com o Serviço Gerenciado para Apache Spark. As seções a seguir explicam essas condições.

Sistema operacional

É possível escolher qualquer imagem de base do sistema operacional para a imagem de contêiner personalizada.

Recomendação: use as imagens padrão do Debian 12, por exemplo, debian:12-slim, porque elas foram testadas para evitar problemas de compatibilidade.

Utilitários

É necessário incluir os seguintes pacotes de utilitários, que são necessários para executar o Spark, na imagem de contêiner personalizada:

  • procps
  • tini

Para executar o XGBoost no Spark (Java ou Scala), inclua libgomp1.

Usuário do contêiner

O Serviço Gerenciado para Apache Spark executa contêineres como o usuário do Linux spark com um UID 1099 e um GID 1099. As diretivas USER definidas em Dockerfiles de imagem de contêiner personalizada são ignoradas no momento da execução. Use o UID e o GID para permissões do sistema de arquivos. Por exemplo, se você adicionar um arquivo jar em /opt/spark/jars/my-lib.jar na imagem como uma dependência de carga de trabalho, conceda permissão de leitura ao usuário spark para o arquivo.

Streaming de imagens

O Serviço Gerenciado para Apache Spark normalmente inicia uma carga de trabalho que exige uma imagem de contêiner personalizada fazendo o download da imagem inteira para o disco. Isso pode significar um atraso no tempo de inicialização, especialmente para clientes com imagens grandes.

Em vez disso, é possível usar o streaming de imagens, que é um método para extrair dados de imagem conforme necessário. Isso permite que a carga de trabalho seja iniciada sem esperar o download da imagem inteira, o que pode melhorar o tempo de inicialização. Para ativar o streaming de imagens, ative a API Container File System. Você também precisa armazenar as imagens de contêiner no Artifact Registry, e o repositório do Artifact Registry precisa estar na mesma região que a carga de trabalho do Serviço Gerenciado para Apache Spark ou em uma multirregião que corresponde à região em que a carga de trabalho está em execução. Se o Serviço Gerenciado para Apache Spark não oferecer suporte à imagem ou se o serviço de streaming de imagens não estiver disponível, nossa implementação de streaming fará o download da imagem inteira.

Não oferecemos suporte ao seguinte para streaming de imagens:

Nesses casos, o Serviço Gerenciado para Apache Spark extrai a imagem inteira antes de iniciar a carga de trabalho.

Spark

Não inclua o Spark na imagem de contêiner personalizada. No momento da execução, o Serviço Gerenciado para Apache Spark ativa os binários e as configurações do Spark do host no contêiner: os binários são ativados no diretório /usr/lib/spark e as configurações são ativadas no diretório /etc/spark/conf. Os arquivos atuais nesses diretórios são substituídos pelo Serviço Gerenciado para Apache Spark no momento da execução.

Java Runtime Environment

Não inclua seu próprio Java Runtime Environment (JRE) na imagem de contêiner personalizada. No momento da execução, o Serviço Gerenciado para Apache Spark ativa o OpenJDK do host no contêiner. Se você incluir um JRE na imagem do contêiner personalizada, ele será ignorado.

Pacotes Java

É possível incluir arquivos jar como dependências de carga de trabalho do Spark na imagem de contêiner personalizada e definir a variável de ambiente SPARK_EXTRA_CLASSPATH para incluir os jars. O Serviço Gerenciado para Apache Spark vai adicionar o valor da variável de ambiente no classpath dos processos da JVM do Spark. Recomendação: coloque jars no diretório /opt/spark/jars e defina SPARK_EXTRA_CLASSPATH como /opt/spark/jars/*.

É possível incluir o jar de carga de trabalho na imagem de contêiner personalizada e fazer referência a ele com um caminho local ao enviar a carga de trabalho, por exemplo, file:///opt/spark/jars/my-spark-job.jar (consulte Enviar uma carga de trabalho em lote do Spark usando uma imagem de contêiner personalizada para ver um exemplo).

Pacotes do Python

Por padrão, o Serviço Gerenciado para Apache Spark ativa a criação do ambiente Conda usando um repositório OSS Conda-Forge do host para o diretório /opt/managed-spark/conda no contêiner no momento da execução. PYSPARK_PYTHON é definido como /opt/managed-spark/conda/bin/python. O diretório de base, /opt/managed-spark/conda/bin, está incluído em PATH.

É possível incluir o ambiente Python com pacotes em um diretório diferente na imagem do contêiner personalizada, por exemplo, em /opt/conda, e definir a PYSPARK_PYTHON variável de ambiente como /opt/conda/bin/python.

A imagem do contêiner personalizada pode incluir outros módulos Python que não fazem parte do ambiente Python, por exemplo, scripts Python com funções utilitárias. Defina a variável de ambiente PYTHONPATH para incluir os diretórios em que os módulos estão localizados.

Ambiente R

É possível personalizar o ambiente R na imagem do contêiner personalizada usando uma das seguintes opções:

  • Use o Conda para gerenciar e instalar pacotes R do canal conda-forge.
  • Adicione um repositório R para o SO Linux da imagem do contêiner e instale pacotes R usando o gerenciador de pacotes do SO Linux. Consulte o índice de pacotes de software R.

Ao usar qualquer uma das opções, defina a variável de ambiente R_HOME para apontar para o ambiente R personalizado. Exceção: se você estiver usando o Conda para gerenciar o ambiente R e personalizar o ambiente Python, não será necessário definir a variável de ambiente R_HOME. Ela é definida automaticamente com base na variável de ambiente PYSPARK_PYTHON.

Exemplo de criação de imagem de contêiner personalizada

Esta seção inclui exemplos de criação de imagem de contêiner personalizada, que incluem Dockerfiles de amostra, seguidos por um comando de criação. Um exemplo inclui a configuração mínima necessária para criar uma imagem. O outro exemplo inclui exemplos de configuração extra, incluindo bibliotecas Python e R.

Configuração mínima

# Recommendation: Use Debian 12.
FROM debian:12-slim

# Suppress interactive prompts.
ENV DEBIAN_FRONTEND=noninteractive

# Install utilities required by Spark scripts.
RUN apt update && apt install -y procps tini libjemalloc2

# Enable jemalloc as default memory allocator.
ENV LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libjemalloc.so.2

# Create the 'spark' group/user.
# The GID and UID must be 1099. Home directory is required.
RUN groupadd -g 1099 spark
RUN useradd -u 1099 -g 1099 -d /home/spark -m spark
USER spark

Configuração extra

# Recommendation: Use Debian 12.
FROM debian:12-slim

# Suppress interactive prompts.
ENV DEBIAN_FRONTEND=noninteractive

# Install utilities required by Spark scripts.
RUN apt update && apt install -y procps tini libjemalloc2

# Enable jemalloc as default memory allocator
ENV LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libjemalloc.so.2

# Install utilities required by XGBoost for Spark.
RUN apt install -y procps libgomp1

# Install and configure Miniconda3.
ENV CONDA_HOME=/opt/miniforge3
ENV PYSPARK_PYTHON=${CONDA_HOME}/bin/python
ENV PATH=${CONDA_HOME}/bin:${PATH}
ADD https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh .
RUN bash Miniforge3-Linux-x86_64.sh -b -p /opt/miniforge3 \
  && ${CONDA_HOME}/bin/conda config --system --set always_yes True \
  && ${CONDA_HOME}/bin/conda config --system --set auto_update_conda False \
  && ${CONDA_HOME}/bin/conda config --system --set channel_priority strict
# Packages ipython and ipykernel are required if using custom conda and want to
# use this container for running notebooks.
RUN ${CONDA_HOME}/bin/mamba install ipython ipykernel

#Install Google Cloud SDK.
RUN ${CONDA_HOME}/bin/mamba install -n base google-cloud-sdk

# Install Conda packages.
#
# The following packages are installed in the default image.
# Recommendation: include all packages.
#
# Use mamba to quickly install packages.
RUN ${CONDA_HOME}/bin/mamba install -n base \
    accelerate \
    bigframes \
    cython \
    deepspeed \
    evaluate \
    fastavro \
    fastparquet \
    gcsfs \
    google-cloud-aiplatform \
    google-cloud-bigquery-storage \
    google-cloud-bigquery[pandas] \
    google-cloud-bigtable \
    google-cloud-container \
    google-cloud-datacatalog \
    google-cloud-dataproc \
    google-cloud-datastore \
    google-cloud-language \
    google-cloud-logging \
    google-cloud-monitoring \
    google-cloud-pubsub \
    google-cloud-redis \
    google-cloud-spanner \
    google-cloud-speech \
    google-cloud-storage \
    google-cloud-texttospeech \
    google-cloud-translate \
    google-cloud-vision \
    langchain \
    lightgbm \
    koalas \
    matplotlib \
    mlflow \
    nltk \
    numba \
    numpy \
    openblas \
    orc \
    pandas \
    pyarrow \
    pynvml \
    pysal \
    pytables \
    python \
    pytorch-cpu \
    regex \
    requests \
    rtree \
    scikit-image \
    scikit-learn \
    scipy \
    seaborn \
    sentence-transformers \
    sqlalchemy \
    sympy \
    tokenizers \
    transformers \
    virtualenv \
    xgboost

# Install pip packages.
RUN ${PYSPARK_PYTHON} -m pip install \
    spark-tensorflow-distributor \
    torcheval

# Install R and R libraries.
RUN ${CONDA_HOME}/bin/mamba install -n base \ 
    r-askpass \
    r-assertthat \
    r-backports \
    r-bit \
    r-bit64 \
    r-blob \
    r-boot \
    r-brew \
    r-broom \
    r-callr \
    r-caret \
    r-cellranger \
    r-chron \
    r-class \
    r-cli \
    r-clipr \
    r-cluster \
    r-codetools \
    r-colorspace \
    r-commonmark \
    r-cpp11 \
    r-crayon \
    r-curl \
    r-data.table \
    r-dbi \
    r-dbplyr \
    r-desc \
    r-devtools \
    r-digest \
    r-dplyr \
    r-ellipsis \
    r-evaluate \
    r-fansi \
    r-fastmap \
    r-forcats \
    r-foreach \
    r-foreign \
    r-fs \
    r-future \
    r-generics \
    r-ggplot2 \
    r-gh \
    r-glmnet \
    r-globals \
    r-glue \
    r-gower \
    r-gtable \
    r-haven \
    r-highr \
    r-hms \
    r-htmltools \
    r-htmlwidgets \
    r-httpuv \
    r-httr \
    r-hwriter \
    r-ini \
    r-ipred \
    r-isoband \
    r-iterators \
    r-jsonlite \
    r-kernsmooth \
    r-knitr \
    r-labeling \
    r-later \
    r-lattice \
    r-lava \
    r-lifecycle \
    r-listenv \
    r-lubridate \
    r-magrittr \
    r-markdown \
    r-mass \
    r-matrix \
    r-memoise \
    r-mgcv \
    r-mime \
    r-modelmetrics \
    r-modelr \
    r-munsell \
    r-nlme \
    r-nnet \
    r-numderiv \
    r-openssl \
    r-pillar \
    r-pkgbuild \
    r-pkgconfig \
    r-pkgload \
    r-plogr \
    r-plyr \
    r-praise \
    r-prettyunits \
    r-processx \
    r-prodlim \
    r-progress \
    r-promises \
    r-proto \
    r-ps \
    r-purrr \
    r-r6 \
    r-randomforest \
    r-rappdirs \
    r-rcmdcheck \
    r-rcolorbrewer \
    r-rcpp \
    r-rcurl \
    r-readr \
    r-readxl \
    r-recipes \
    r-recommended \
    r-rematch \
    r-remotes \
    r-reprex \
    r-reshape2 \
    r-rlang \
    r-rmarkdown \
    r-rodbc \
    r-roxygen2 \
    r-rpart \
    r-rprojroot \
    r-rserve \
    r-rsqlite \
    r-rstudioapi \
    r-rvest \
    r-scales \
    r-selectr \
    r-sessioninfo \
    r-shape \
    r-shiny \
    r-sourcetools \
    r-spatial \
    r-squarem \
    r-stringi \
    r-stringr \
    r-survival \
    r-sys \
    r-teachingdemos \
    r-testthat \
    r-tibble \
    r-tidyr \
    r-tidyselect \
    r-tidyverse \
    r-timedate \
    r-tinytex \
    r-usethis \
    r-utf8 \
    r-uuid \
    r-vctrs \
    r-whisker \
    r-withr \
    r-xfun \
    r-xml2 \
    r-xopen \
    r-xtable \
    r-yaml \
    r-zip

ENV R_HOME=/usr/lib/R

# Add extra Python modules.
ENV PYTHONPATH=/opt/python/packages
RUN mkdir -p "${PYTHONPATH}"

# Add extra jars.
ENV SPARK_EXTRA_JARS_DIR=/opt/spark/jars/
ENV SPARK_EXTRA_CLASSPATH='/opt/spark/jars/*'
RUN mkdir -p "${SPARK_EXTRA_JARS_DIR}"

#Uncomment below and replace EXTRA_JAR_NAME with the jar file name.
#COPY "EXTRA_JAR_NAME" "${SPARK_EXTRA_JARS_DIR}"

# Create the 'spark' group/user.
# The GID and UID must be 1099. Home directory is required.
RUN groupadd -g 1099 spark
RUN useradd -u 1099 -g 1099 -d /home/spark -m spark
USER spark

Comando de criação

Execute o comando a seguir no diretório do Dockerfile para criar e enviar a imagem personalizada para o Artifact Registry.

# Build and push the image.
gcloud builds submit --region=REGION \
    --tag REGION-docker.pkg.dev/PROJECT/REPOSITORY/IMAGE_NAME:IMAGE_VERSION