タスクの再試行を自動化する

このページでは、すべてまたは一部のエラー後にタスクを自動的に再試行する方法について説明します。

バッチジョブは、少なくとも 1 つのタスクが失敗するとエラーになります。これはさまざまな理由で発生します。デフォルトでは、ジョブ内の各タスクは 1 回だけ実行されます。タスクが失敗しても再試行されません。ただし、タスクが失敗する原因となる問題の中には、タスクを再試行するだけで簡単に解決できるものもあります。このような場合、タスクを自動的に再試行するようにジョブを構成することで、トラブルシューティングの負担とジョブの全体的な実行時間を大幅に短縮できます。

自動再試行は、疎結合（独立）タスクに適しており、さまざまな問題の解決に役立ちます。たとえば、タスクの自動再試行を使用すると、次のような時間に敏感な問題を解決できます。

Spot VM のプリエンプション
VM メンテナンスイベントとホストエラー
一時的なネットワークエラー

ジョブを作成するときに、タスクごとにタスクの自動再試行を構成できます。具体的には、タスクごとに次のいずれかの構成オプションを使用できます。

デフォルトでは、各タスクは失敗しても再試行されません。
すべてのタスクの再試行: 失敗したタスクを自動的に再試行する最大回数を構成できます。再試行回数は 0 ～ 10 の間で指定できます（デフォルトは 0）。
一部のタスクの再試行: 特定の失敗に対して、異なるタスクアクション（自動再試行または再試行なしでの失敗）を構成できます。指定されていないすべての失敗に対しては、逆のアクションが実行されます。特定の失敗は、アプリケーションまたは Batch で定義された終了コードによってそれぞれ識別できます。

準備

Batch を以前に使用したことがない場合は、Batch を使ってみるを確認し、プロジェクトとユーザーの前提条件を完了して Batch を有効にします。
ジョブの作成に必要な権限を取得するには、次の IAM ロールを付与するよう管理者に依頼してください。
- プロジェクトのバッチジョブ編集者（roles/batch.jobsEditor）
- ジョブのサービスアカウントのサービスアカウントユーザー（roles/iam.serviceAccountUser）。これは、デフォルトでは Compute Engine のデフォルトのサービスアカウントです。
ロールの付与については、プロジェクト、フォルダ、組織へのアクセスを管理するをご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

すべての失敗に対してタスクを再試行する

gcloud CLI または Batch API を使用して、ジョブが失敗したタスクの自動再試行の最大数（maxRetryCount フィールド）を定義できます。

gcloud

ジョブの構成の詳細と maxRetryCount フィールドを指定する JSON ファイルを作成します。

たとえば、失敗したタスクの最大再試行回数を指定する基本的なスクリプトジョブを作成するには、次の内容の JSON ファイルを作成します。
```
{
  "taskGroups": [
    {
      "taskSpec": {
        "runnables": [
          {
            "script": {
              "text": "echo Hello world from task ${BATCH_TASK_INDEX}"
            }
          }
        ],
        
        "maxRetryCount": MAX_RETRY_COUNT
        
      },
      "taskCount": 3
    }
  ],
  "logsPolicy": {
    "destination": "CLOUD_LOGGING"
  }
}
```
MAX_RETRY_COUNT は、各タスクの最大再試行回数に置き換えます。ジョブで失敗したタスクを再試行できるようにするには、この値を 1～10 の整数に設定する必要があります。maxRetryCount フィールドが指定されていない場合、デフォルト値は 0 です。これは、どのタスクも再試行しないことを意味します。
ジョブを作成して実行するには、gcloud batch jobs submit コマンドを使用します:
```
gcloud batch jobs submit JOB_NAME \
  --location LOCATION \
  --config JSON_CONFIGURATION_FILE
```
以下を置き換えます。
- JOB_NAME: ジョブの名前。
- LOCATION: ジョブのロケーション。
- JSON_CONFIGURATION_FILE: ジョブの構成の詳細を含む JSON ファイルへのパス。

API

maxRetryCount フィールドを指定する jobs.create メソッドに POST リクエストを送信します。

たとえば、失敗したタスクの最大再試行回数を指定する基本的なスクリプトジョブを作成するには、次のリクエストを行います。

POST https://batch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/jobs?job_id=JOB_NAME

{
  "taskGroups": [
    {
      "taskSpec": {
        "runnables": [
          {
            "script": {
              "text": "echo Hello world from task ${BATCH_TASK_INDEX}"
            }
          }
        ],
        
        "maxRetryCount": MAX_RETRY_COUNT
        
      },
      "taskCount": 3
    }
  ],
  "logsPolicy": {
    "destination": "CLOUD_LOGGING"
  }
}

以下を置き換えます。

PROJECT_ID: プロジェクトのプロジェクト ID
LOCATION: ジョブのロケーション。
JOB_NAME: ジョブの名前。
MAX_RETRY_COUNT: 各タスクの再試行の最大回数。ジョブで失敗したタスクを再試行できるようにするには、この値を 1～10 の整数に設定する必要があります。maxRetryCount フィールドが指定されていない場合、デフォルト値は 0 です。これは、どのタスクも再試行しないことを意味します。

一部の失敗に対してタスクを再試行する

ライフサイクルポリシー（lifecyclePolicies[] フィールド）を使用すると、ジョブがさまざまなタスクの失敗を処理する方法を定義できます。

ライフサイクルポリシーは、アクション（action フィールド）、アクション条件（actionCondition フィールド）、終了コード（exitCodes[]フィールド）で構成されます。指定したアクションは、アクション条件（特定の終了コード）が発生するたびに実行されます。次のいずれかのアクションを指定できます。

RETRY_TASK: exitCodes[] フィールドで指定された終了コードで失敗したタスクを再試行します。指定されていない終了コードで失敗したタスクは再試行されません。
FAIL_TASK: exitCodes[] フィールドで指定された終了コードで失敗したタスクを再試行しません。指定されていない終了コードで失敗したタスクは再試行されます。

特に、指定されていない終了コードで失敗したタスクは逆のアクションを実行します。一部の終了コードは再試行され、一部は失敗します。そのため、ライフサイクルポリシーが意図したとおりに機能するためには、ジョブが失敗したタスクを少なくとも 1 回自動的に再試行できるように、自動再試行の最大回数（maxRetryCount フィールド）も定義する必要があります。

各終了コードは、アプリケーションまたは Batch によって定義された特定の失敗を表します。50001～59999 の終了コードは予約されており、Batch によって定義されます。予約済みの終了コードの詳細については、トラブルシューティングをご覧ください。

gcloud CLI または Batch API を使用して、特定の失敗後にタスクを再試行または失敗するようにジョブに指定できます。

gcloud

ジョブの構成の詳細、maxRetryCount フィールド、lifecyclePolicies[] サブフィールドを指定する JSON ファイルを作成します。

失敗したタスクを一部のエグジットコードでのみ再試行する基本的なスクリプトジョブを作成するには、次の内容の JSON ファイルを作成します。

{
  "taskGroups": [
    {
      "taskSpec": {
        "runnables": [
          {
            "script": {
              "text": "echo Hello world from task ${BATCH_TASK_INDEX}"
            }
          }
        ],
        
        "maxRetryCount": MAX_RETRY_COUNT,
        "lifecyclePolicies": [
          {
            "action": "ACTION",
            "actionCondition": {
               "exitCodes": [EXIT_CODES]
            }
          }
        ]
      }
    }
  ],
  "logsPolicy": {
    "destination": "CLOUD_LOGGING"
  }
}

以下を置き換えます。

MAX_RETRY_COUNT: 各タスクの再試行の最大回数。ジョブで失敗したタスクを再試行できるようにするには、この値を 1～10 の整数に設定する必要があります。maxRetryCount フィールドが指定されていない場合、デフォルト値は 0 です。これは、どのタスクも再試行しないことを意味します。
ACTION: 指定された終了コードで失敗したタスクに対して行うアクション（RETRY_TASK または FAIL_TASK）。指定されていない終了コードで失敗したタスクは、別のアクションを実行します。
EXIT_CODES: 指定したアクションをトリガーする 1 つ以上の終了コードのカンマ区切りリスト（例: 50001, 50002）。

各終了コードは、アプリケーションまたは Batch で定義できます。50001～59999 の終了コードは Batch によって予約されています。予約済みの終了コードの詳細については、トラブルシューティングをご覧ください。

たとえば、次のジョブでは、Spot VM のプリエンプションが原因で失敗したタスクのみを再試行します。

{
  "taskGroups": [
    {
      "taskSpec": {
        "runnables": [
          {
            "script": {
              "text": "sleep 30"
            }
          }
        ],
        "maxRetryCount": 3,
        "lifecyclePolicies": [
          {
             "action": "RETRY_TASK",
             "actionCondition": {
               "exitCodes": [50001]
            }
          }
        ]
      }
    }
  ],
  "allocationPolicy": {
    "instances": [
      {
        "policy": {
          "machineType": "e2-standard-4",
          "provisioningModel": "SPOT"
        }
      }
    ]
  }
}

ジョブを作成して実行するには、gcloud batch jobs submit コマンドを使用します:
```
gcloud batch jobs submit JOB_NAME \
  --location LOCATION \
  --config JSON_CONFIGURATION_FILE
```
以下を置き換えます。
- JOB_NAME: ジョブの名前。
- LOCATION: ジョブのロケーション。
- JSON_CONFIGURATION_FILE: ジョブの構成の詳細を含む JSON ファイルへのパス。

API

maxRetryCount フィールドと lifecyclePolicies[] サブフィールドを指定する jobs.create メソッドに POST リクエストを送信します。

一部の終了コードでのみ失敗したタスクを再試行する基本的なスクリプトジョブを作成するには、次のリクエストを行います。

POST https://batch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/jobs?job_id=JOB_NAME

{
  "taskGroups": [
    {
      "taskSpec": {
        "runnables": [
          {
            "script": {
              "text": "echo Hello world from task ${BATCH_TASK_INDEX}"
            }
          }
        ],
        
        "maxRetryCount": MAX_RETRY_COUNT,
        "lifecyclePolicies": [
          {
            "action": "ACTION",
            "actionCondition": {
                "exitCodes": [EXIT_CODES]
            }
          }
        ]
      }
    }
  ],
  "logsPolicy": {
    "destination": "CLOUD_LOGGING"
  }
}

以下を置き換えます。

PROJECT_ID: プロジェクトのプロジェクト ID
LOCATION: ジョブのロケーション。
JOB_NAME: ジョブの名前。
MAX_RETRY_COUNT: 各タスクの再試行の最大回数。ジョブで失敗したタスクを再試行できるようにするには、この値を 1～10 の整数に設定する必要があります。maxRetryCount フィールドが指定されていない場合、デフォルト値は 0 です。これは、どのタスクも再試行しないことを意味します。
ACTION: 指定された終了コードで失敗したタスクに対して行うアクション（RETRY_TASK または FAIL_TASK）。指定されていない終了コードで失敗したタスクは、別のアクションを実行します。
EXIT_CODES: 指定したアクションをトリガーする 1 つ以上の終了コードのカンマ区切りリスト（例: 50001, 50002）。

各終了コードは、アプリケーションまたは Batch で定義できます。50001～59999 の終了コードは Batch によって予約されています。予約済みの終了コードの詳細については、トラブルシューティングをご覧ください。

たとえば、次のジョブでは、Spot VM のプリエンプションが原因で失敗したタスクのみを再試行します。

POST https://batch.googleapis.com/v1/projects/example-project/locations/us-central1/jobs?job_id=example-job

{
  "taskGroups": [
    {
      "taskSpec": {
        "runnables": [
          {
            "script": {
              "text": "sleep 30"
            }
          }
        ],
        "maxRetryCount": 3,
        "lifecyclePolicies": [
          {
             "action": "RETRY_TASK",
             "actionCondition": {
               "exitCodes": [50001]
            }
          }
        ]
      }
    }
  ],
  "allocationPolicy": {
    "instances": [
      {
        "policy": {
          "machineType": "e2-standard-4",
          "provisioningModel": "SPOT"
        }
      }
    ]
  }
}

再試行回数に基づいてタスクの動作を変更する

必要に応じて、このページの前のセクションで説明したようにタスクの自動再試行を有効にした後、事前定義された BATCH_TASK_RETRY_ATTEMPT 環境変数を使用するように実行可能物を更新できます。BATCH_TASK_RETRY_ATTEMPT 変数は、このタスクがすでに試行された回数を表します。再試行回数に基づいてタスクの動作が異なるようにする場合は、実行可能物で BATCH_TASK_RETRY_ATTEMPT 変数を使用します。たとえば、タスクが再試行されている場合は、前の試行で正常に実行されたコマンドを確認できます。詳細については、事前定義された環境変数をご覧ください。

次のステップ

ジョブの作成または実行に問題がある場合は、トラブルシューティングをご覧ください。
ジョブとタスクを表示する。
別のジョブ作成オプションを学習する。