Batch on GKE でのジョブの実行

beta

このページでは、Batch on GKE（Batch）を使用してバッチジョブを実行する方法を説明します。ジョブを Batch で送信する方法は次の 2 つ（ksub と kubectl）です。ksub コマンドを使用すると、ジョブとしてシェルスクリプトを送信できます。また、kubectl を使用すると、yaml ファイルを使ってジョブを送信できます。

ksub を構成する

ksub は、Batch システムでジョブ関連のアクションを実行するコマンドラインツールです。行頭が #KB で始まるキーワードを使用してジョブのプロパティを指定できます。

ksub を構成するには、次の手順を行います。

ksub に対して API アクセスのために自身のユーザー認証情報の使用を許可します。
```
    gcloud auth application-default login
    
```
kbatch ディレクトリに移動します。ご利用の OS に応じて、./ksub フォルダから適切な ksub バージョンを選択します。たとえば、Linux ユーザーの場合は、次のバージョンを使用します。
```
    cd ksub/linux/amd64
    
```
デフォルトの構成ファイルを設定します。
```
    ./ksub --config --create-default
    
```
これにより ~/.ksubrc に構成ファイルが作成されます。
.ksubrc に projectID と clusterName のデフォルト値を追加します。
デフォルトの名前空間である namespace で作業していない場合は、namespace フィールドを編集して新しいデフォルトの名前空間を設定します。
```
    vi ~/.ksubrc
    
```
マウントポイントを設定します（クラスタ管理者が作成した非公開の PersistentVolumeClaim を使用しない場合は省略可）。
```
    ./ksub --config --add-volume fs-volume --volume-source PersistentVolumeClaim
     --params claimName:[PVC_NAME] --params readOnly:false
    
```
ここで、[PVC_NAME] は、個人用の非公開入出力ファイルを保存するために管理者に作成してもらった PersistentVolumeClaim 名です。Filestore インスタンスを使用する場合、これは Filestore インスタンスの名前です。
$PATH に ksub のインストールディレクトリを追加します。
```
    export PATH=$PATH:/path/to/kbatch/
    
```

kubectl を構成する

Kubernetes のデフォルトのツールは kubectl で、すでに Cloud SDK に含まれています。

最新バージョンの kubectl で作業するために、次のコマンドを実行します。

    gcloud components update

サンプルジョブの実行

Batch on GKE には、サンプルジョブがいくつか含まれています。

ComputePi

サンプルを取得します。

    git clone https://github.com/GoogleCloudPlatform/Kbatch.git

「デフォルト」の K8s 名前空間にデフォルトの Batch 管理者リソースを作成します。
```
    ./samples/defaultresources/create.sh
    
```

ジョブは、ksub または kubectl を使用して送信できます。

ksub

/samples/computepi で ComputePi ジョブを実行します。
```
    ksub run_pi_with_ksub.sh
    
```
このコマンドは、ジョブ名を出力します。
ジョブが完了するまで待ちます。
```
    ksub -Gw [JOB_NAME]
    
```
タスク名を取得します。
```
    ksub -Ga [JOB_NAME]
    
```
このコマンドはタスク名を出力します。
ログを表示します。
```
    ksub -L [TASK_NAME]
    
```

kubectl

/samples/computepi で ComputePi ジョブを実行します。
```
    kubectl create -f pi-job.yaml
    
```
ここでの出力は次のようになります。
```
    batchjob.kbatch.k8s.io/[JOB_NAME] created
    
```

ジョブに関連付けられているポッドを確認します。

    kubectl get pods | grep [JOB_NAME]

次のように出力されます。

    [POD_NAME]   0/1     Completed   0          1m

ログを表示します。
```
    kubectl logs pod/[POD_NAME]
    
```

依存関係にあるジョブの実行

依存関係を利用して、前のジョブに関して特定の条件が発生した場合にのみジョブを実行できます。ベータ版では、次の 3 つの依存関係タイプがサポートされています。

成功: 依存関係にあるジョブがすべて成功した場合にのみジョブが実行されます。
失敗: 依存関係にあるジョブがすべて失敗した場合にのみジョブが実行されます。
完了: 依存関係にあるジョブがすべて完了したときにのみジョブが実行されます。

依存関係が満たされないためジョブが実行されないと判断された場合、Batch はジョブを Failed とマークします。たとえば、依存関係タイプが Success の job2 に job1 が依存していて、job2 が失敗した場合、job1 は実行されず失敗したと見なされます。それ以外の場合、ジョブの失敗と成功は、Kubernetes Pod ライフサイクルで定義されたジョブに関連付けられた Pod の成功または失敗によって決まります。

このサンプルジョブを実行する前に、GKE クラスタのノードのロケーションと同じゾーンに Google Cloud Filestore インスタンスを設定する必要があります。

Batch サンプル、admintools、usertools を取得、展開します。他のサンプルジョブで実行済みの場合、この手順はスキップします。
```
    git clone https://github.com/GoogleCloudPlatform/Kbatch.git
    
```
```
    tar -xzvf kbatch-github.tar.gz
    
```
「デフォルト」の K8s 名前空間にデフォルトの Batch 管理者リソースを作成します。他のサンプルジョブで実行済みの場合、この手順はスキップします。
```
    ./samples/defaultresources/create.sh
    
```
imageprocess フォルダに移動します。
```
    cd ../imageprocess
    
```
apply-extra-config.sh を実行して PersistentVolume リソースと権限を作成します。「BatchTasks で root として実行し、ストレージにアクセス」できるかと聞かれた場合は「y」と入力します。
```
    pushd ../userstorage
    ./apply-extra-config.sh
    popd
    
```
前の手順で作成した永続ボリュームクレームを使用するように ksub の構成を更新します。
```
    ./ksub --config --add-volume fs-volume --volume-source PersistentVolumeClaim \
     --params claimName:[PVC_NAME] --params readOnly:false
    
```
ここで、[PVC_NAME] はステップ 4 で作成した PVC の名前です。この例では、ステップ 4 で pvc という名前の PersistentVolumeClaim が作成されているため、[PVC_NAME] を pvc に置き換えます。
copy-input.sh を実行して入力画像を Filestore にコピーします。

ジョブは、ksub または kubectl を使用して送信できます。

ksub

ksub を使用して依存関係にあるジョブを送信する

依存関係を設定してジョブを送信するには、1 つのコマンドで依存関係を指定する方法と、シェルスクリプトの KB Dependency Success: フィールドを手動で編集する方法があります。

ksub で依存関係を指定する

samples/imageprocess から次のコマンドを実行して、依存関係を指定して両方のジョブを実行します。
```
    ksub --dependency Success:job_name -- run_grey_with_ksub.sh
    
```
シェル変数を使用してジョブを結合することもできます。

ジョブ 1 を作成します。
```
    job1=`ksub run_checkerboard_with_ksub.sh` \
    
```
ジョブ 2 を送信します。
```
    ksub --dependency Success:${job1} -- ./run_grey_with_ksub.sh
    
```
タスク名を取得します。
```
    ksub -Ga [JOB_NAME]
    
```
このコマンドはタスク名を出力します。
ログを表示します。
```
    ksub -L [TASK_NAME]
    
```
copy-output.sh を実行し、処理された画像をローカルマシンにコピーします。

最初のジョブの名前を使用して依存関係を作成する

ImageProcess ジョブを送信します。

    ksub run_checkerboard_with_ksub.sh

たとえば次のような [JOB_NAME] が出力されます。

    checkerboard-64t5n

次の run_grey_with_ksub.sh は、job1 への依存関係を持つ job2 のサンプルスクリプトの内容です。

    #!/bin/sh

    #KB Jobname grey-
    #KB Namespace default
    #KB Image gcr.io/kbatch-images/greyimage/greyimage:latest
    #KB Queuename default
    #KB MaxWallTime 5m
    #KB MinCpu 1.0
    #KB MinMemory 2Gi
    #KB Mount fs-volume /mnt/pv
    #KB Dependency Success:[JOB_NAME]

    echo "Starting job grey"
    # greyimage is in /app directory.
    cd /app
    ./greyimage -in=/mnt/pv/checker.png -out=/mnt/pv/checkergrey.png
    echo "Completed job grey"

run_grey_with_ksub.sh を任意のエディタで開き、[JOB_NAME] を作成したジョブの名前に置き換えます。
2 番目のジョブを送信する
```
    ksub run_grey_with_ksub.sh
    
```
ジョブ名が出力されます。
タスク名を取得します。
```
    ksub -Ga [JOB_NAME]
    
```
このコマンドはタスク名を出力します。
ログを表示します。
```
    ksub -L [TASK_NAME]
    
```
copy-output.sh を実行し、処理された画像をローカルマシンにコピーします。

kubectl

kubectl を使用して依存関係にあるジョブを送信する

ImageProcess ジョブを送信します。

    kubectl create -f imageprocess-job.yaml

出力は次のようになります。

    batchjob.kbatch.k8s.io/checkerboard created
    batchjob.kbatch.k8s.io/grey created

最初のジョブを確認します。

    kubectl describe batchjob/checkerboard

2 番目のジョブを確認します。
```
    kubectl describe batchjob/grey
    
```
copy-output.sh を実行し、処理された画像をローカルマシンにコピーします。

GPU を使用するジョブの実行

Batch サンプル、admintools、usertools を取得、展開します。他のサンプルジョブで実行済みの場合、この手順はスキップします。
```
    git clone https://github.com/GoogleCloudPlatform/Kbatch.git
    
```
```
    tar -xzvf kbatch-github.tar.gz
    
```
「デフォルト」の K8s 名前空間にデフォルトの Batch 管理者リソースを作成します。他のサンプルジョブで実行済みの場合、この手順はスキップします。
```
    ./samples/defaultresources/create.sh
    
```

ジョブは、ksub または kubectl を使用して送信できます。

ksub

クラスタで使用できる GPU タイプが samples/GPUjob/run_gpu_with_ksub.sh に指定されていることを確認します。
ジョブを送信します。
```
    ksub samples/GPUjob/run_gpu_with_ksub.sh
    
```
ジョブ名が出力されます。
ジョブが完了するまで待ちます。
```
    ksub -Gw [JOB_NAME]
    
```
注: GPU ノードプールのスケールアップはノードの初期化と nVidia ドライバのインストールの両方の作業を伴うため、このテストには数分かかることがあります。
タスク名を取得します。
```
    ksub -Ga [JOB_NAME]
    
```
このコマンドはタスク名を出力します。
ログを表示します。
```
    ksub -L [TASK_NAME]
    
```

gcloud

gpu-job.yaml ファイルに記されている GPU が、オートスケーラーゾーンで使用できる GPU タイプと一致していることを確認します。
ジョブを送信します。
```
    kubectl create -f samples/GPUjob/run_gpu_with_ksub.sh
    
```
出力は次のようになります。
```
    batchjob.kbatch.k8s.io/[JOB_NAME] created
    
```
注: GPU ノードプールのスケールアップはノードの初期化と nVidia ドライバのインストールの両方の作業を伴うため、このテストには数分かかることがあります。

ログを表示します。

    kubectl describe batchjob/[JOB_NAME]

配列ジョブの実行

配列ジョブとは、同じコンテナイメージを共有し、配列インデックスで区別されるタスクのグループのことです。IndexSpec で「taskCount」を指定すると、最大 1,000 個のタスクを作成できます。

配列ジョブのサンプルを実行するには、入出力用 {product_name_short}} クラスタのノードのロケーションと同じゾーンに Google Cloud Filestore インスタンスを設定する必要があります。filestore インスタンスの作成後、次の手順を実行して配列ジョブのサンプルを実行します。

Batch サンプル、admintools、usertools を取得、展開します。他のサンプルジョブで実行済みの場合、この手順はスキップします。
```
    git clone https://github.com/GoogleCloudPlatform/Kbatch.git
    
```
```
    tar -xzvf kbatch-github.tar.gz
    
```
「デフォルト」の K8s 名前空間にデフォルトの Batch 管理者リソースを作成します。他のサンプルジョブで実行済みの場合、この手順はスキップします。
```
    ./samples/defaultresources/create.sh
    
```
arrayjob フォルダに移動します。
```
      cd ../arrayjob
      
```
setup.sh を実行して PersistentVolume リソースと権限を作成します。filestore インスタンスの IP、ゾーン、ボリューム名を入力する必要があります。
```
    ./setup.sh
    
```
「BatchTasks で root として実行し、ストレージにアクセス」できるかと聞かれた場合は「y」と入力します。
前の手順で作成した永続ボリュームクレームを使用するように ksub の構成を更新します。
```
      ./ksub --config --add-volume fs-volume --volume-source PersistentVolumeClaim 

        --params claimName:[PVC_NAME] --params readOnly:false
      
```
ここで、[PVC_NAME] はステップ 4 で作成した PVC の名前です。この例では、ステップ 4 で pvc という名前の PersistentVolumeClaim が作成されているため、[PVC_NAME] を pvc に置き換えます。
copy-array-input.sh を実行して入力画像を Filestore にコピーします。
```
    ./copy-array-input.sh
    
```
入力ファイルは、PVC の下にある array-image-data ディレクトリにコピーされます。
ksub を使用して配列ジョブを送信します。
```
    ksub ./run_array_image_ksub.sh`
    
```
別の方法では、yaml ファイルを使い、kubectl create -f array-image.yaml を実行して配列ジョブを送信することもできます。
配列ジョブのステータスを、前の手順で生成したジョブ名により確認します。
```
    ksub -Ga [JOB_NAME],/var> --output=wide
    
```
または
```
    ksub -G [JOB_NAME],/var> --output=describe
    
```
ジョブが正常に終了すると、出力ファイルは PVC の下にある array-image-data ディレクトリに保存されます。

出力データをローカルマシンにコピーするには、次のコマンドを実行します。
```
    ./copy-array-output.sh
    
```
確認するには、array-image-data ディレクトリに移動します。各入力ファイルには対応する出力ファイルがあります。

ジョブの送信

ジョブは、ksub または kubectl を使用して送信できます。

ksub の使用

ksub ではジョブとしてスクリプトを送信できます。行頭が #KB で始まるキーワードを使用してジョブのプロパティを指定できます。

次の run_pi_with_ksub.sh は、サンプルの ksub ジョブの内容です。

    #!/bin/sh

    # Keywords to specify job parameters

    #KB Jobname pi-
    #KB Namespace default
    #KB Image gcr.io/kbatch-images/generate-pi/generate-pi:latest
    #KB Queuename default
    #KB MaxWallTime 5m
    #KB MinCpu 1.0
    #KB MinMemory 2Gi

    echo "Starting job pi"
    # pi is in /app directory.
    cd /app
    ./pi
    echo "Completed job pi"

スクリプトを送信するには、次のコマンドを実行します。

    ksub run_pi_with_ksub.sh

ksub キーワードの指定

キーワードを使用してジョブのパラメータを指定します。キーワードの行頭には #KB が付けられます。ksub では、空白行や空白文字による行を挟まずに、複数のキーワード行をひとかたまりにして指定することになっています。#KB で始まらない行があると、ksub は、そこでキーワードの解析を止めます。

ksub は次のキーワードをサポートしています。

キーワード	コメント	例
Jobname	ジョブ名の生成に使用されるジョブ名接頭辞。	#KB Jobname pi-
Namespace	ジョブが実行される名前空間。	#KB Namespace default
Queuename	ジョブが送信されるキュー。	#KB Queuename default
Image	ジョブコンテナを実行するイメージ。	#KB Image ubuntu
Mount	マウントする PVC およびマウントする場所。	#KB Mount fs-volume /tmp
MinCpu	ジョブに必要な CPU の数。	#KB MinCpu 1.0
MinMemory	コンテナに必要なメモリの量。	#KB MinMemory 2Gi
Gpu	ジョブに必要な GPU の数とタイプ。右側の例では `nvidia-tesla-k80` は使用される GPU のタイプで、「2」は使用される GPU の数です。	#KB GPU nvidia-tesla-k80 2
Dependency	ジョブの依存関係	#KB Dependency Success:job-name1
MaxWallTime	ジョブの最大実行時間	#KB MaxWallTime 5m
TaskCount	配列ジョブのタスク数（最大 1,000 件）	#KB TaskCount 10

kubectl の使用

kubectl はクラスタの Kubernetes 構成を使用して Batch システムに接続します。

次の pi-job.yaml は、サンプルの YAML ジョブの内容です。

    apiVersion: kbatch.k8s.io/v1beta1
    kind: BatchJob
    metadata:
      generateName: pi-  # generateName allows the system to generate a random name, using this prefix, for the BatchJob upon creation.
      namespace: default
    spec:
      batchQueueName: default
      taskGroups:
      - name: main
        maxWallTime: 5m
        template:
          spec:
            containers:
            - name: pi
              # This image has been made public so it can be pulled from any project.
              image: gcr.io/kbatch-images/generate-pi/generate-pi:latest
              resources:
                requests:
                  cpu: 1.0
                  memory: 2Gi
                limits:
                  cpu: 1.0
                  memory: 2Gi
              imagePullPolicy: IfNotPresent
            restartPolicy: Never

ジョブを送信するには、次のコマンドを実行します。

    kubectl create -f pi-job.yaml

データの管理

ユーザーツールを取得します。

    git clone https://github.com/GoogleCloudPlatform/Kbatch.git

モニタリングするディレクトリに移動します。
```
    cd usertools/filestore
    
```

Batch on GKE には、Kubernetes PersistentVolume との間でファイルコピーするためのユーティリティがあります。

このスクリプトの基本的な使い方は次のとおりです。

    ./datacopy.sh [-d|-u] -l [LOCAL_FILE] -r [REMOTE_FILE_PATH] -p [PVC_NAME]

ここで

-u は、ワークステーションからクラウドにデータをコピーします。
-d は、クラウドからワークステーションにデータをコピーします。
-h は、使い方の簡単な説明を出力します。

たとえば、入力ファイル input.dat がローカルマシンのカレントディレクトリにあり、このファイルを使用してジョブを実行する場合は、次のコマンドを入力すると、入力ファイルを自分専用の Batch ディレクトリにコピーできます。

    ./datacopy.sh -u -l input.dat -r problem-1-input.data -p [NAME]-team1

ジョブの表示

ジョブは、ksub または kubectl を使用して表示できます。

ksub

キューにある特定のユーザーのジョブを表示する

特定のユーザーのジョブを表示するには、次のコマンドを実行します。

    ksub -Q -n [NAMESPACE] [QUEUE_NAME]

ここで、最初の [NAMESPACE] は名前空間で、[QUEUE_NAME] は Queue の名前です。

出力は次のようになります。

    Name: pi-s4dwl, Status: Succeeded

キュー内のジョブを表示する

キュー内のジョブを表示するには、次のコマンドを実行します。

    ksub -Qa -n [NAMESPACE] [QUEUE_NAME]

ここで、最初の [NAMESPACE] は名前空間で、[QUEUE_NAME] は Queue の名前です。

出力は次のようになります。

    Name: pi-s4dwl, Creation Time Stamp: 2019-09-12 13:03:42 -0700 PDT, Status: Succeeded

kubectl

キュー内のジョブを表示する

キュー内のジョブを表示するには、次のコマンドを実行します。

    kubectl get batchjobs --selector=batchQueue=[QUEUE_NAME] --namespace [NAMESPACE]

ここで、[QUEUE_NAME] は Queue の名前で、[NAMESPACE] は名前空間です。

出力は次のようになります。

    NAME       AGE
    pi-6rc7s   2m

特定のユーザーのジョブを表示する

特定のユーザーのジョブを表示するには、次の手順を実行します。

ユーザー名を取得します。
```
    gcloud config get-value account
    
```
出力は次のようになります。
```
    user@company.com
    
```
注: 以降のコマンドでは、AT を @ に置き換えてください。たとえば、userATcompany.com のようにします。
特定のユーザーの Namespace に属するジョブを一覧表示するには、次のコマンドを実行します。
```
    kubectl get batchjobs --selector=submittedBy=[userATexample.com] --namespace [NAMESPACE]
    
```
ここで、--selector=submittedBy は emailATcompany.com で、[NAMESPACE] は名前空間です。

出力は次のようになります。
```
    NAME       AGE
    pi-6rc7s   36m
    
```
特定のユーザーが Queue に送信したジョブのリストを一覧表示するには、次のコマンドを実行します。
```
    kubectl get batchjobs --selector=batchQueue=[QUEUE_NAME],submittedBy=[userATexample.com] --namespace [NAMESPACE]
    
```
ここで、[QUEUE_NAME] は Queue の名前の emailATcompany.com で、[NAMESPACE] は名前空間です。

出力は次のようになります。
```
    NAME       AGE
    pi-6rc7s   36m
    
```

ジョブの停止

実行中のジョブを停止するには、ksub または kubectl を使用します。ジョブは「JobTerminationByUser」という状態で「Failed」とマークされ、ジョブ関連の履歴データは保持されます。

ksub

ジョブを停止するには次のコマンドを実行します。

    ksub -T [JOB_NAME] -n [NAMESPACE]

ここで、[JOB_NAME] は Job の名前で、[NAMESPACE] は名前空間です。

出力は次のようになります。

    Termination request for job [JOB_NAME] is sent to the server, please check the job status

次のコマンドを実行して、ジョブが完了するまで監視することもできます。

    ksub -Gw [JOB_NAME] -n [NAMESPACE]

kubectl

実行中のジョブを停止させるには、次のコマンドを実行します。

    kubectl patch batchjob [JOB_NAME] --namespace [NAMESPACE] --type merge --patch '{"spec": {"userCommand": "Terminate"}}'

ここで、[JOB_NAME] は Job の名前で、[NAMESPACE] は名前空間です。

出力は次のようになります。

    batchjob.kbatch.k8s.io/[JOB_NAME] patched

ジョブのログの表示

ジョブのログを表示できるのは、ジョブの実行が開始された後（つまり、ジョブがキュー待機状態から実行中の状態に移行した場合）のみです。ログを表示する前に、ジョブが開始されるまで待つ必要があります。

ジョブのログを取得するには、次のコマンドを実行します。

    ksub -L -n [NAMESPACE] [JOB_NAME]

ここで、[NAMESPACE] は名前空間で、[JOB_NAME] はジョブ名です。

トラブルシューティング

BatchTask が長期間「Ready」状態になった場合は、Cloud Console の「Workloads」タブに移動して対応する Pod を確認できます。

GKE 1.14 では、ネットワークの設定の問題により、Pod が「ContainerCreating」ステージで停止することがあるという既知の問題があります。この場合、ジョブを終了して再送信できます。この問題は、GKE 1.15 のリリースで修正される予定です。

次のステップ

Batch on GKE の詳細について学習する