# Cloud Shuffle Storage Plugin for Apache Spark
<a name="cloud-shuffle-storage-plugin"></a>

Cloud Shuffle ストレージプラグインは [`ShuffleDataIO` API](https://github.com/apache/spark/blob/master/core/src/main/java/org/apache/spark/shuffle/api/ShuffleDataIO.java) と互換性のある Apache Spark プラグインで、シャッフルデータをクラウドストレージシステム (Amazon S3 など) に保存することを可能にします。この機能では、Spark アプリケーションにおいて `join`、`reduceByKey`、`groupByKey`、および `repartition` などの変換によってトリガーされることが多い、大規模なシャッフル操作用のローカルディスクストレージ容量を補充または置換できます。このため、サーバーレスデータ分析ジョブやパイプラインでの、一般的な障害やコスト対パフォーマンスの不整合を軽減するのに役立ちます。

**AWS Glue**  
AWS Glue バージョン 3.0 と 4.0 には、このプラグインが事前インストールされており、特別な手順なしで Amazon S3 でシャッフルが利用可能になります。Spark アプリケーションでこの機能を有効にする方法については、「[AWS Glue シャッフルマネージャーと Amazon S3](https://docs.aws.amazon.com/glue/latest/dg/monitor-spark-shuffle-manager.html) 」を参照してください。

**その他の Spark 環境**  
他の Spark 環境では、このプラグインに以下の Spark 構成を設定する必要があります。
+ `--conf spark.shuffle.sort.io.plugin.class=com.amazonaws.spark.shuffle.io.cloud.ChopperPlugin`: こSpark に対し、Shuffle IO 用としてこのプラグインを使用することを通知します。
+ `--conf spark.shuffle.storage.path=s3://{{bucket-name}}/{{shuffle-file-dir}}`: シャッフルファイルが保存されるパスです。

**注記**  
このプラグインは、Spark コアクラスの 1 つを上書きします。そのため、プラグインの jar ファイルは、Spark jar に先行してロードする必要があります。プラグインを AWS Glue の外部で使用する場合は、オンプレミスの YARN 環境で `userClassPathFirst` を使用して、この処理を実行できます。

## Spark アプリケーションへのプラグインのバンドル
<a name="cloud-shuffle-storage-plugin-bundling"></a>

Spark アプリケーションをローカルで開発する際、Maven `pom.xml` にプラグインの依存関係を追加することで、Spark アプリケーションと Spark ディストリビューション (バージョン 3.1 以降) にプラグインをバンドルできます。このプラグインと Spark バージョンの詳細については、「[プラグインのバージョン](#cloud-shuffle-storage-plugin-versions)」を参照してください。

```
<repositories>
   ...
    <repository>
        <id>aws-glue-etl-artifacts</id>
        <url>https://aws-glue-etl-artifacts.s3.amazonaws.com/release/ </url>
    </repository>
</repositories>
...
<dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>chopper-plugin</artifactId>
    <version>3.1-amzn-LATEST</version>
</dependency>
```

別の方法として、以下のように AWS Glue Maven アーティファクトからバイナリを直接ダウンロードして、Spark アプリケーションにインクルードすることも可能です。

```
#!/bin/bash
sudo wget -v https://aws-glue-etl-artifacts.s3.amazonaws.com/release/com/amazonaws/chopper-plugin/3.1-amzn-LATEST/chopper-plugin-3.1-amzn-LATEST.jar -P /usr/lib/spark/jars/
```

spark-submit の例

```
spark-submit --deploy-mode cluster \
--conf spark.shuffle.storage.s3.path=s3://<ShuffleBucket>/<shuffle-dir> \
--conf spark.driver.extraClassPath={{<Path to plugin jar>}} \ 
--conf spark.executor.extraClassPath={{<Path to plugin jar>}} \
--class <your test class name> s3://{{<ShuffleBucket>}}/{{<Your application jar>}} \
```

## オプションの設定
<a name="cloud-shuffle-storage-plugin-optional"></a>

これらは Amazon S3 シャッフルの動作を制御するための、オプションの設定値です。
+ `spark.shuffle.storage.s3.enableServerSideEncryption`: ファイルのシャッフルおよびスピルのために、S3 SSE を有効化/無効化します。デフォルト値は `true` です。
+ `spark.shuffle.storage.s3.serverSideEncryption.algorithm`: 使用される SSE アルゴリズム。デフォルト値は `AES256` です。
+ `spark.shuffle.storage.s3.serverSideEncryption.kms.key`: aws:kms が有効になっている場合の KMS キーの ARN。

これらの構成に加え、ユースケースに応じて適切な暗号化が適用されるように `spark.hadoop.fs.s3.enableServerSideEncryption`、**その他の環境固有の構成**などの設定が必要になる場合があります。

## プラグインのバージョン
<a name="cloud-shuffle-storage-plugin-versions"></a>

このプラグインは、AWS Glue のバージョンごとに関連付けられている Spark バージョンで、それぞれサポートされています。次の表に、AWS Glue のバージョン、Spark バージョン、およびプラグインのソフトウェアバイナリ用の Amazon S3 ロケーションと関連付けたプラグインバージョンを示します。


| AWS Glue バージョン | Spark バージョン | プラグインバージョン | Amazon S3 ロケーション | 
| --- | --- | --- | --- | 
| 3.0 | 3.1 | 3.1-amzn-LATEST | s3://aws-glue-etl-artifacts/release/com/amazonaws/chopper-plugin/3.1-amzn-0/chopper-plugin-3.1-amzn-LATEST.jar | 
| 4.0 | 3.3 | 3.3-amzn-LATEST | s3://aws-glue-etl-artifacts/release/com/amazonaws/chopper-plugin/3.3-amzn-0/chopper-plugin-3.3-amzn-LATEST.jar | 

## ライセンス
<a name="cloud-shuffle-storage-plugin-binary-license"></a>

このプラグインのソフトウェアバイナリは、Apache-2.0 License の下でライセンスされています。