プログラムの実行

スクリプトファイル

スクリプトファイルは、apt, source, data, run, upload の 5要素からなる YAML ファイルです。 簡単なサンプルファイルは次のようになります。

apt:
  - unrar
source: https://github.com/abcdefg/some-program.git
data:
  - http://mmnet.iis.sinica.edu.tw/dl/wowah/wowah.rar
run:
  - unrar x -r wowah.rar
  - ./analyze WoWAH
upload:
  - *.png

大雑把にいうと、上記のスクリプトファイルは次のことを実行します。

  1. apt パッケージの unrar をインストールします,
  2. ソースコードを Git リポジトリからクローンします,
  3. ある URL からデータファイルをダウンロードします、
  4. 二つのコマンド、ダウンロードしたファイルの解凍と解析プログラムの実行を行います、
  5. 計算結果として、標準出力に書かれたメッセージと *.png にマッチするファイルを クラウドストレージへアップロードします。

なお、スクリプトファイルでは、不要なセクションは省略できます。

apt セクション

apt セクションはプログラムの実行に必要な apt パッケージのリストを設定します。

apt:
  - python-numpy
  - python-scipy
  - python-matplotlib

上の例では、科学技術計算によく用いられる Python パッケージをインストールしています。 もし、何らかのコマンドを実行した後で apt パッケージのインストールが必要な場合は、 run セクションに apt-get install コマンドを追加してください。

source セクション

source セクションでは、プログラムで必要となるデータファイルの URL リストを指定できます。 これらの URL には次の拡張が利用できます。

  • URL が .git で終わる場合、Git リポジトリとして扱われます。 すなわち、ソースコードの取得に git clone が使われます。
  • URL が dropbox:// で始まる場合、ソースコードは Dropbox にあるとみなされます。 この URL は、Dropbox 上で作成された公開リンクの、https を dropbox へ 書き換えたものです。
  • URL が gs:// で始まる場合、そのリソースは Google Cloud Storage 上に あるとみなされます。(Google Cloud Platform 利用時のみ)
  • URL が roadie:// で始まる場合、そのリソースはRoadie が管理するファイルを指します。 詳しくはファイルの管理を参照ください。
  • それ以外では、http と https から始まる URL をサポートしています。

どの場合でも、URL が .zip, .tar または .tar.gz で終わる場合、 適切に解凍されます。

例えば、

source: https://github.com/jkawamoto/roadie.git

は、Github からソースコードをクローンして利用します。

しかし、プログラムが開発途中の場合など、 アーカイブを作成してどこかに配置することが手間な場合もあります。 Roadie は、ローカルにあるファイルをクラウドストレージにアップロードして、 それらをソースコードとして利用する機能も提供しています。 詳細は、後の節を参照してください。

source セクションで指定されたソースファイルは、 仮想マシン上の /data にコピーされます。 また、ソースファイルが Python で記載されていて、 requirements.txt ファイルを含む場合、依存パッケージは自動でインストールされます。

data セクション

data セクションでは、プログラムの実行に必要なデータファイルの取得先 URL リストを指定します。 URL には、source セクションで説明した、 http、https、gs (Google Cloud Platform 利用時のみ)、 roadie そして dropbox のスキームが利用できます。 また、同様に URL が .zip, .tar または .tar.gz で終わっている場合、 適切に解凍されます。

デフォルトでは、指定されたファイルは /data ディレクトリにコピーされます。 もし他のディレクトリに保存する必要がある場合、 URL に : に続けて保存先パスを与えることができます。 例えば、

data:
  - https://www.sample.com/program.zip:/data/input

は、program.zip をダウンロードし、 解凍して得られたファイルを /data/input にコピーします。 URL が指すファイルがアーカイブでない場合、別名保存になります。 例えば、

data:
  - roadie://data/some_data_v2.json:some_data.json

は、Roadie 管理下の some_data_v2.json をダウンロードし、 some_data.json という名前で /data に保存します。

なお、roadie://data/ は、roadie data put コマンドにてアップロードしたデータファイルの 格納先です。

run セクション

run セクションには、実行するコマンドを順に記述します。 ここには、任意のコマンドを列挙することができます。 例えば、プログラムの実行に必要な追加パッケージがある場合は、 ここでインストールを支持することができます。

例えば、node.js 用のアプリケーションの場合、 run セクション最初のコマンドは npm install になるでしょう。 この時、apt セクションで node.js をインストールするのを忘れないでください。

source セクションで指定したソースファイルを実行する場合、 各コマンドを ./ で始めることを忘れないでください。 roadie は自動で /data をパスへは追加しません。

run セクションに列挙された各コマンドには、0 から順に番号が割り当てられます。 つまり、最初のコマンドは 0 番になります。 このこ番号は、標準出力へ書き出されたメッセージの参照に利用します。 i 番目のコマンドの出力は stdout{i}.txt としてクラウドストレージに保存されます。 これらのファイルは roadie result コマンドで取得できます。

upload セクション

upload セクションには、 glob パタンのリストを設定します. いずれかのパタンにマッチしたファイルは、 プログラムの実行結果としてクラウドストレージで保存されます。 これらのファイルも roadie result コマンドで取得できます。

プログラムの実行モデル

Roadie は、与えらえたプログラムを Docker コンテナを用いて実行します。

Docker

このコンテナは、Ubuntu を基にしたカスタムイメージを使用しており、 Ubuntu で利用可能なほとんどのパッケージが Roadie でも利用可能です。 スクリプトファイルの apt セクションで利用したいパッケージを登録することができます。

実行中のコンテナでは、プログラムは /data にコピーされます。 また、スクリプトファイルの data セクションで列挙されたデータファイルも、 デフォルトでは /data にコピーされます。

もし、ソースコードをアーカイブファイルとして用意し、 Roadie がソースコードが見つからないというエラーを出した場合、 アーカイブがディレクトリを生成しないか確認してください。 例えば、main という名前のプログラムをアーカイブした archive.zip というファイルがある場合、解凍後は /data/main に main がコピーされる場合と、 /data/archive/main が作成される場合があります。 デバッグのためには、スクリプトの run セクションに ls -la などを追加すれば良いでしょう。

一般的に、プログラムは標準出力 stdout と標準エラー出力 stderr に メッセージを書き出すことができます。 また、任意のファイルを作成することもできます。

Roadie では、標準出力 stdout に書き出されたメッセージは、 プログラムの実行結果として扱われ永続的なストレージに保存されます。 スクリプトファイルの run セクションに書かれたコマンドは、 0番から順に番号を振られます。 各コマンドが標準出力へ書き出したメッセージは stdout{番号}.txt という名前で保存されます。 コンテナ上では、/tmp に各ファイルが記録されるので、 他のコマンドから利用することもできます。

一方、標準エラー出力 stderr に書き出されたメッセージは、 即時性のあるログとして扱われ永続的なストレージに保存されるとは限りません。 その代わり、プログラムの実行中に roadie log コマンドを使って取得することができます。 標準エラー出力は通信を発生させるため、巨大なメッセージを書き出すことは避けた方が良いでしょう。

デフォルトでは、Roadie は他のファイルをプログラムの実行結果としては扱いません。 標準出力以外の出力を実行結果として永続的なストレージへ保存する場合は、 スクリプトの upload セクションを使ってください。

run コマンド

roadie run コマンドは、新しい仮想マシンを作成しその上でプログラムを実行します。 このコマンドは、次の節で説明するスクリプトファイルを引数として受け取ります。 その他、多数のオプションが用意されていますが、 最も重要なオプションの一つに --name オプションがあります。 このオプションを用いることで、作成する仮想マシンに名前を付けることができ、 また実行結果の取得にもこの名前を使用します。 なお、--name オプションが与えれれない場合は、 スクリプトファイル名から一意の名前を生成します。

スクリプトファイルが script.yml で名前が instance1 である仮想マシンを作成するためには、

$ roadie run --name instance1 script.yml

を実行します。

roadie run コマンドに -f または --follow フラッグをセットすると、 インスタンスを作成したのち、プログラムの実行が終了するまでログを出力します。 これは、roadie log --follow コマンドを別途実行するのと同じです。 ただし、ログの取得が課金対象の場合や一定時間内に取得できるログの回数に制限がある場合があります。

ローカルファイルをソースコードとして使用する

source セクションでは、Web 上の様々なところから ソースコードを取得できるようになっています。 しかし、プログラムが開発途中である場合など、Web 上に配置することが手間な場合もあります。 Roadie では、ローカルにあるファイルをクラウドストレージへアップロードし、 それらをソースコードとして利用する仕組みが備わっています。

この機能を使う場合、スクリプトファイルの source セクションは省略できます。

ローカルディレクトリをソースコードとして使用する場合、 roadie run コマンドに --local フラッグを用いてローカルディレクトリを指定します。

例えば、

$ roadie run --local . --name instance-1 script.yml

では、カレントディレクトリ以下のファイルがソースコードとして扱われます。 これらのファイルはアーカイブされ、クラウドストレージにアップロードされます。 そして、そのアーカイブをソースコードとする仮想マシンを作成し実行します。

なお、指定したディレクトリに .git フォルダが含まれている場合、 このフォルダは無視されます。 通常、リポジトリ全体がプログラムの実行に必要なケースは稀であるため、 通信データ量を削減するために除外しています。

もし、--local フラッグでディレクトリではなく単一のファイルを指定した場合は、 そのファイルをソースファイルとして扱います。

この --local フラッグを利用してアップロードされたソースファイルは、 再利用することができます。 ソースコードの変更なしに、別のパラメータでプログラムを実行させたい場合などに便利です。 ソースコードの再利用には、--source と共に、再利用したい仮想マシンの名前を渡します。

例えば、--local フラッグを使って、次のようにプログラムを実行したとします。

$ roadie run --local . --name instance-1 script.yml

この時にアップロードされたソースコードを再利用する場合、

$ roadie run --source instance-1 --name instance2 script2.yml

のように指定します。