Retz使用方法メモ

Retz（0.2.3）の使い方。

概要

Retzを使ってコマンドを実行するには、まず、“アプリケーション”をRetzに登録する必要がある。

$ retz-client load-app -A アプリケーション名 -F アーカイブファイルURL -U ユーザーID

これで、アーカイブファイルに名前（アプリケーション名）を付けて、Retz内に保存される。
（アーカイブファイルは必須ではないが、アプリケーション名は必ず登録する必要がある）

そして、コマンドを実行する際にそのアプリケーション名を使用する。

$ retz-client run -A アプリケーション名 -cmd 'コマンド'

このとき、Retz内部では以下のような手順で実行されることになる。

1. 実行するマシンをMesosクラスター内から探し、決定する。
2. アーカイブファイルをそのマシン上に転送・解凍する。
3. そのマシン上でコマンド（シェル）を実行する。

例えばAsakusaアプリケーション（Asakusa Frameworkで作られたバッチ）の場合、通常は、実行環境にAsakusaアプリケーションのデプロイメントアーカイブを展開して置いておく（実行環境に事前にデプロイしておく）。

Retzを使う場合、このデプロイメントアーカイブファイルをRetzに登録しておくことで、事前デプロイが不要になる。（実行直前にRetzによって転送・解凍（つまりデプロイ）される為）

逆に、事前デプロイしてあるのであれば、Retzにアーカイブファイルを登録せず、デプロイしてある環境をそのまま使って実行することも出来る。

（AsakusaFWのデプロイメントアーカイブはバッチ数が多ければそれなりにサイズが大きくなる、つまり転送・解凍に時間がかかるので、どちらの方式が良いかはケースバイケース）

ヘルプ

retz-clientのcommandコマンドでコマンド一覧を表示できる。[2017-02-25]

$ retz-client command

-sを付けると各コマンドのオプションが表示される。

$ retz-client command -s load-app
$ retz-client command -s run
$ retz-client command -s list

アプリケーションの登録

Retzにアプリケーション（アーカイブファイル）を登録するには、load-appコマンドを使う。

$ retz-client load-app -A アプリケーション名 -U ユーザーID 〜

「-A」でアプリケーション名を付ける。
これは何でもいいが、後で（runコマンド等で）実行する際に使用する。

「-U」でユーザーIDを指定する。[2017-02-25]
このユーザーは、runコマンドで実行するコマンドをどのUNIXユーザーで実行するかを指定する。
（ユーザーを指定しない場合はRetz（Mesos？）のデフォルトのユーザーで実行されるので、権限が無くて実行できないことがある）
-Uを省略すると、retz-server/etc/retz.propertiesのretz.userが使われる。[2017-03-08]

ちなみに、retz-serverを再起動した場合は、load-appを再度行う必要がある。

登録されているアプリケーション名の一覧は以下のコマンドで確認できる。

$ retz-client list-app

アーカイブファイルの置き場所

Retzにアーカイブファイルを登録する為には、各Mesosスレーブサーバーからそのアーカイブをダウンロードできるような、共通の場所にアーカイブファイルを置いておく必要がある。
Retzとしては、httpやhdfs（maprfs）でダウンロードすることを想定しているようだ。

load-appコマンドではそのアーカイブファイルの場所（URL）を指定するが、その時点ではURLを保存するだけで、アーカイブファイルの転送自体は行われない。
実際にコマンドが実行されるときに、Mesosスレーブサーバー上にそのアーカイブファイルをダウンロードしてくる。（アーカイブファイルがtar.gzの場合は、転送した後で解凍も行われる）

httpを使う場合は、どこかでウェブサーバーを立ち上げ、そこにアーカイブファイルを置いておく必要がある。

$ retz-client load-app -A asakusa -P http://example.com/asakusa-m3bp.tar.gz -disk 6000

hdfsを使う場合は、MesosスレーブサーバーからHDFS（Hadoop分散ファイルシステム）にアクセスできる必要がある。

$ hadoop fs -put asakusa-m3bp.tar.gz
$ retz-client load-app -A asakusa -P hdfs:///user/hishidama/asakusa-m3bp.tar.gz -disk 6000

アーカイブの転送・解凍方法

アーカイブファイルの転送（Mesosスレーブサーバーへのダウンロード）には、コマンド実行の度に毎回転送する方法と、そのサーバーで初めて実行するときだけ転送する方法がある。
また、そのサーバーに既にインストールされているファイルだけ使えばいい場合は、アーカイブファイルは不要となる。

コマンド実行の度に毎回転送（および解凍）するなら、「-F」オプションでアーカイブファイルを指定する。

$ retz-client load-app -A asakusa1 -F http://example.com/asakusa-m3bp.tar.gz

実行対象サーバー上で初めての場合だけ転送（および解凍）する場合は、「-P」オプションでアーカイブファイルを指定する。

$ retz-client load-app -A asakusa2 -P hdfs:///user/hishidama/asakusa-m3bp.tar.gz -disk 6000

「-disk」は、実行時に確保するディスクサイズを指定する。単位はMB。
アーカイブファイルのサイズと、解凍後のサイズの合計を指定する。
（Retzはこのディスクサイズを確保できるMesosスレーブサーバー上にアーカイブファイルを転送し解凍する）

アーカイブファイルを使う必要が無い場合は、アプリケーション名だけ指定すればよい。

$ retz-client load-app -A asakusa0

コマンド（ジョブ）の実行

retz-clientのrunコマンドでジョブを実行する。この場合、ジョブが終了するまでretz-clientは終わらない。
scheduleコマンドを使うと、ジョブを起動するだけで、retz-clientは終了する。

retz-clientのlistコマンドで、実行した/実行中のジョブ一覧を表示できる。
get-jobコマンドで、実行結果（ログ）を表示できる。

Asakusaアプリケーションを実行する例

事前に実行対象マシンにAsakusaデプロイメントアーカイブを展開してある前提（load-appでアーカイブファイルを指定しない）で、そのAsakusaアプリケーション（Asakusa on M3BP）をRetz経由で実行する例。

$ retz-client run -A asakusa0 \
    -cpu 16 \
    -mem 128000 \
    -E ASAKUSA_M3BP_ARGS='--engine-conf com.asakusafw.m3bp.thread.max=16' \
    -E ASAKUSA_M3BP_OPTS='-Xmx64g' \
    -E ASAKUSA_HOME=/home/hishidama/asakusa \
    -E YAESS_OPTS='-Duser.home=.' \
    -cmd '$ASAKUSA_HOME/yaess/bin/yaess-batch.sh m3bp.example.summarizeSales -A date=2011-04-01'

「-E」や「-cmd」では、Retzが定義した環境変数を使うことが出来る。
これはMesosスレーブサーバー上でコマンドを実行する際に値が入るものなので、retz-clientで指定する際にはシングルクォーテーションで囲む必要がある。

「-E YAESS_OPTS='-Duser.home=.'」は、HOMEを指定しないと何故かYAESSが上手く動かないので、指定している。

load-appでAsakusaデプロイメントアーカイブファイルを登録している場合は、以下のような感じ。

$ retz-client run -A asakusa2 \
    -cpu 16 \
    -mem 128000 \
    -E ASAKUSA_M3BP_ARGS='--engine-conf com.asakusafw.m3bp.thread.max=16' \
    -E ASAKUSA_M3BP_OPTS='-Xmx64g' \
    -E ASAKUSA_HOME='$RETZ_PVNAME' \
    -E YAESS_OPTS='-Duser.home=.' \
    -cmd '$ASAKUSA_HOME/yaess/bin/yaess-batch.sh m3bp.example.summarizeSales -A date=2011-04-01'

ASAKUSA_HOMEにRETZ_PVNAME（アーカイブが解凍された場所）を指定している。

実行状況の確認

アプリケーションの実行状況はretz-clientのlistコマンドで確認する。[2017-02-25]

引数を何も指定しない場合、（Retz 0.2.3では）実行中（ステータスがQUEUED,STARTING,STARTED）のものだけ表示される。

$ retz-client list

--statesでステータスを絞り込める。全てを見たい場合はALLを指定する。

$ retz-client list --states ALL

ジョブの確認

各ジョブの情報（ステータスや要求したリソース等）はretz-clientのget-jobコマンドで確認する。[2017-07-16]

$ retz-client get-job -id タスクID

ちなみに、Retz全体の現在のリソースの状態はhttp://retz-serverのホスト名:9090/statusで確認できる。

出力されたファイルの取得（表示）

アプリケーションを実行した結果として生成されたファイルはretz-clientのget-fileコマンドで取得できる。[2017-02-25]

$ retz-client get-file -id タスクID -path ファイル名

アプリケーションの標準エラーに出力されたログはstderrというファイルで生成されているので、ファイル名にstderrを指定すれば取得できる。

$ retz-client get-file -id タスクID -path stderr

どのようなファイルが生成されているかは、retz-clientのlist-filesコマンドで確認できる。[2017-07-20]

$ retz-client list-files -id タスクID