ラベルを使用したリソースの整理

このドキュメントでは、ラベルを使用して Batch リソースを整理する方法について説明します。

ラベルとは、リソースをグループ化して記述するためにリソースに適用される Key-Value ペアのことです。Batch には、リソースに自動的に適用される事前定義されたラベルと、ジョブの作成時に定義して適用できるカスタムラベルがあります。

ラベルを使用すると、リソースリストと Cloud Billing レポートの結果をフィルタリングできます。たとえば、ラベルを使用して次のことができます。

プロジェクトのジョブのリストを明確にし、整理します。
ラベルを使用して、指定されたコンテナまたはスクリプトのタイプを記述し、ジョブの実行可能ファイルを区別します。
Batch または特定のジョブによって作成されたリソースの Cloud Billing レポートをフィルタリングして、費用を分析します。

ラベルの詳細については、ラベルに関する Compute Engine のドキュメントもご覧ください。

準備

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

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

制限事項

Compute Engine のドキュメントで指定されたラベルの要件に加えて、Batch ジョブとそのリソースにラベルを適用するには、次の制限があります。

Batch では、Batchを使用して作成され、以下のタイプのリソースのラベルのみがサポートされます：
- ジョブ
- 実行可能ファイル
- ジョブのグラフィックプロセッシングユニット（GPU）（ある場合）
- ジョブの永続ディスク（ブートディスクとストレージボリューム）
- ジョブの仮想マシン（VM）インスタンス
Batch が自動的にジョブに適用する事前定義されたラベルを考慮した後、次の量のカスタムラベルを定義できます。
- ジョブとその実行可能ファイルに適用する最大 63 個のカスタムラベルを定義できます。
- ジョブ用に作成された各 GPU、永続ディスク、VM に適用する最大 61 個のカスタムラベルを定義できます。
Batch では、一意の名前を持つカスタムラベルの定義のみがサポートされています。結果として次のようになります。
- 事前定義されたラベルをオーバーライドしようとすると、エラーが発生します。
- 重複するカスタムラベルを定義すると、既存のカスタムラベルがオーバーライドされます。
Batch ではジョブの作成時にラベルを定義することのみがサポートされます。
- ジョブと実行可能ファイルのラベルは追加、更新、削除できません。
- Compute Engine を使用して、ジョブ用に作成された永続ディスクと VM のラベルを追加、更新、削除することはできますが、おすすめしません。ジョブのリソースが存在する期間を正確に予測することはできません。また、Batch で変更が正しく機能しない可能性があります。
ラベルを使用してジョブのリストをフィルタリングするには、gcloud CLI または Batch API を使用してジョブのリストを表示する必要があります。

定義済みのラベル

事前定義された各ラベルには、batch- 接頭辞で始まるキーがあります。デフォルトでは、Batch は次の事前定義ラベルを自動的に適用します。

作成するジョブごとに、次の操作を行います。
- batch-job-id: このラベルの値はジョブの名前に設定されます。
ジョブ用に作成された各 GPU、永続ディスク、VM に対して:
- batch-job-id: このラベルの値はジョブの名前に設定されます。
- batch-job-uid: このラベルの値は、ジョブの一意の識別子（UID）に設定されます。
- batch-node: このラベルの値は null です。ジョブ用に作成されたすべての GPU、永続ディスク、VM をグループ化するだけです。たとえば、Cloud Billing レポートを表示するときにこのラベルを使用して、Batch によって作成されたすべての GPU、永続ディスク、VM の費用を特定します。

カスタムラベルを定義する

必要に応じて、ジョブの作成時に 1 つ以上のカスタムラベルを定義できます。新しいキーまたはプロジェクトですでに使用されているキーでカスタムラベルを定義できます。カスタムラベルを定義するには、ラベルの目的に基づいて、このドキュメントから次のメソッドを 1 つ以上選択します。

ジョブとそのリソースのカスタムラベルを定義します。

このセクションでは、ジョブと、ジョブ用に作成された各 GPU、永続ディスク、VM に 1 つ以上のカスタムラベルを適用する方法について説明します。ジョブを作成した後に、これらのラベルを使用して Cloud Billing レポートとプロジェクトのジョブ、永続ディスク、VM のリストをフィルタリングできます。

注: ジョブ用に作成された永続ディスクと VM は、ジョブの実行中（作成後および削除前）にのみプロジェクトのリストに表示されます。
ジョブのカスタムラベルを定義します。

このセクションでは、1 つ以上のカスタムラベルをジョブに適用する方法について説明します。ジョブを作成した後に、これらのラベルを使用してジョブのプロジェクトリストをフィルタリングできます。
実行可能ファイルのカスタムラベルを定義する

このセクションでは、ジョブの 1 つ以上の実行可能ファイルに 1 つ以上のカスタムラベルを適用する方法について説明します。ジョブを作成した後に、これらのラベルを使用してジョブのプロジェクトリストをフィルタリングできます。

ジョブとそのリソースのカスタムラベルを定義する

ジョブの割り当てポリシーの labels フィールドで定義されたラベルが、ジョブおよびジョブ用に作成された各 GPU（存在する場合）、永続ディスク（すべてのブートディスクと任意の新しいストレージボリューム）、および VM に適用されます。

ジョブとそのリソースのラベルは、gcloud CLI または Batch API を使用してジョブを作成するときに定義できます。

gcloud

たとえば、ジョブおよびジョブ用に作成されたリソースに適用される 2 つのカスタムラベルを定義する基本的なコンテナジョブを us-central1 で作成するには、以下の手順に沿って操作します：

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

{
  "allocationPolicy": {
    "instances": [
      {
        "policy": {
          "machineType": "e2-standard-4"
        }
      }
    ],
    "labels": {
      "VM_LABEL_NAME1": "VM_LABEL_VALUE1",
      "VM_LABEL_NAME2": "VM_LABEL_VALUE2"
    }
  },
  "taskGroups": [
    {
      "taskSpec": {
        "runnables": [
          {
            "container": {
              "imageUri": "gcr.io/google-containers/busybox",
              "entrypoint": "/bin/sh",
              "commands": [
                "-c",
                "echo Hello world!"
              ]
            }
          }
        ]
      }
    }
  ]
}

以下を置き換えます。

VM_LABEL_NAME1: ジョブ用に作成された VM に適用する最初のラベルの名前。
VM_LABEL_VALUE1: ジョブ用に作成された VM に適用する最初のラベルの値。
VM_LABEL_NAME2: ジョブ用に作成された VM に適用する 2 番目のラベルの名前。
VM_LABEL_VALUE2: ジョブ用に作成された VM に適用する 2 番目のラベルの値。

gcloud batch jobs submit コマンドを使用して、us-central1 にジョブを作成します。
```
gcloud batch jobs submit example-job \
    --config=JSON_CONFIGURATION_FILE \
    --location=us-central1
```
JSON_CONFIGURATION_FILE は、前の手順で作成したジョブの構成の詳細を含む JSON ファイルのパスに置き換えます。

API

ジョブおよびジョブ用に作成されたリソースに適用される 2 つのカスタムラベルを定義する基本的なコンテナジョブを us-central1 で作成するには、jobs.create メソッドに POST リクエストを行い、allocationPolicy.labels フィールドを指定します。

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

{
  "allocationPolicy": {
    "instances": [
      {
        "policy": {
          "machineType": "e2-standard-4"
        }
      }
    ],
    "labels": {
      "VM_LABEL_NAME1": "VM_LABEL_VALUE1",
      "VM_LABEL_NAME2": "VM_LABEL_VALUE2"
    }
  },
  "taskGroups": [
    {
      "taskSpec": {
        "runnables": [
          {
            "container": {
              "imageUri": "gcr.io/google-containers/busybox",
              "entrypoint": "/bin/sh",
              "commands": [
                "-c",
                "echo Hello world!"
              ]
            }
          }
        ]
      }
    }
  ]
}

以下を置き換えます。

VM_LABEL_NAME1: ジョブ用に作成された VM に適用する最初のラベルの名前。
VM_LABEL_VALUE1: ジョブ用に作成された VM に適用する最初のラベルの値。
VM_LABEL_NAME2: ジョブ用に作成された VM に適用する 2 番目のラベルの名前。
VM_LABEL_VALUE2: ジョブ用に作成された VM に適用する 2 番目のラベルの値。

ジョブのカスタムラベルを定義する

ジョブの labels フィールドで定義されたラベルは、ジョブにのみ適用されます。

gcloud CLI または Batch API を使用してジョブを作成するときに、ジョブのラベルを定義できます。

gcloud

たとえば、ジョブ自体に適用される 2 つのカスタムラベルを定義する基本的なコンテナジョブを us-central1 に作成するには、次のようにします。

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

{
  "taskGroups": [
    {
      "taskSpec": {
        "runnables": [
          {
            "container": {
              "imageUri": "gcr.io/google-containers/busybox",
              "entrypoint": "/bin/sh",
              "commands": [
                "-c",
                "echo Hello World!"
              ]
            }
          }
        ]
      }
    }
  ],
  "labels": {
    "JOB_LABEL_NAME1": "JOB_LABEL_VALUE1",
    "JOB_LABEL_NAME2": "JOB_LABEL_VALUE2"
  }
}

以下を置き換えます。

JOB_LABEL_NAME1: ジョブに適用する最初のラベルの名前。
JOB_LABEL_VALUE1: ジョブに適用する最初のラベルの値。
JOB_LABEL_NAME2: ジョブに適用する 2 番目のラベルの名前。
JOB_LABEL_VALUE2: ジョブに適用する 2 番目のラベルの値。

次のフラグを指定して gcloud batch jobs submit コマンドを使用し、us-central1 にジョブを作成します。
```
gcloud batch jobs submit example-job \
    --config=JSON_CONFIGURATION_FILE \
    --location=us-central1
```
JSON_CONFIGURATION_FILE は、前の手順で作成したジョブの構成の詳細を含む JSON ファイルのパスに置き換えます。

API

たとえば、ジョブ自体に適用される 2 つのカスタムラベルを定義するコンテナジョブを us-central1 に作成するには、jobs.create メソッドに POST リクエストを行い、labels フィールドを指定します。

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

{
  "taskGroups": [
    {
      "taskSpec": {
        "runnables": [
          {
            "container": {
              "imageUri": "gcr.io/google-containers/busybox",
              "entrypoint": "/bin/sh",
              "commands": [
                "-c",
                "echo Hello World!"
              ]
            }
          }
        ]
      }
    }
  ],
  "labels": {
    "JOB_LABEL_NAME1": "JOB_LABEL_VALUE1",
    "JOB_LABEL_NAME2": "JOB_LABEL_VALUE2"
  }
}

以下を置き換えます。

JOB_LABEL_NAME1: ジョブに適用する最初のラベルの名前。
JOB_LABEL_VALUE1: ジョブに適用する最初のラベルの値。
JOB_LABEL_NAME2: ジョブに適用する 2 番目のラベルの名前。
JOB_LABEL_VALUE2: ジョブに適用する 2 番目のラベルの値。

実行可能ファイルのカスタムラベルを定義する

実行可能ファイルの labels フィールドで定義されたラベルは、その実行可能ファイルにのみ適用されます。

gcloud CLI または Batch API を使用してジョブを作成するときに、1 つ以上の実行可能ファイルのラベルを定義できます。

gcloud

たとえば、2 つのジョブの実行可能ファイルのそれぞれに 1 つずつ、2 つのカスタムラベルを定義するジョブを us-central1 に作成するには、次の手順に沿って操作します。

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

{
  "taskGroups": [
    {
      "taskSpec": {
        "runnables": [
          {
            "container": {
              "imageUri": "gcr.io/google-containers/busybox",
              "entrypoint": "/bin/sh",
              "commands": [
                "-c",
                "echo Hello from task ${BATCH_TASK_INDEX}!"
              ]
            },
            "labels": {
              "RUNNABLE1_LABEL_NAME1": "RUNNABLE1_LABEL_VALUE1"
            }
          },
          {
            "script": {
              "text": "echo Hello from task ${BATCH_TASK_INDEX}!"
            },
            "labels": {
              "RUNNABLE2_LABEL_NAME1": "RUNNABLE2_LABEL_VALUE1"
            }
          }
        ]
      }
    }
  ]
}

以下を置き換えます。

RUNNABLE1_LABEL_NAME1: ジョブの最初の実行可能ファイルに適用するラベルの名前。
RUNNABLE1_LABEL_VALUE1: ジョブの最初の実行可能ファイルに適用するラベルの値。
RUNNABLE2_LABEL_NAME1: ジョブの 2 番目の実行可能ファイルに適用するラベルの名前。
RUNNABLE2_LABEL_VALUE1: ジョブの 2 番目の実行可能ファイルに適用するラベルの値。

gcloud batch jobs submit コマンドを使用して、us-central1 にジョブを作成します。
```
gcloud batch jobs submit example-job \
    --config=JSON_CONFIGURATION_FILE \
    --location=us-central1
```
JSON_CONFIGURATION_FILE は、前の手順で作成したジョブの構成の詳細を含む JSON ファイルのパスに置き換えます。

API

たとえば、2 つのジョブの実行可能ファイルのそれぞれに 1 つずつ、2 つのカスタムラベルを定義するジョブを us-central1 に作成するには、jobs.create メソッドに POST リクエストを行い、runnables.labels フィールドを指定します。

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

{
  "taskGroups": [
    {
      "taskSpec": {
        "runnables": [
          {
            "container": {
              "imageUri": "gcr.io/google-containers/busybox",
              "entrypoint": "/bin/sh",
              "commands": [
                "-c",
                "echo Hello from ${BATCH_TASK_INDEX}!"
              ]
            },
            "labels": {
              "RUNNABLE1_LABEL_NAME1": "RUNNABLE1_LABEL_VALUE1"
            }
          },
          {
            "script": {
              "text": "echo Hello from ${BATCH_TASK_INDEX}!"
            },
            "labels": {
              "RUNNABLE2_LABEL_NAME1": "RUNNABLE2_LABEL_VALUE1"
            }
          }
        ]
      }
    }
  ]
}

以下を置き換えます。

RUNNABLE1_LABEL_NAME1: 最初のジョブの実行可能ファイルに適用するラベルの名前。
RUNNABLE1_LABEL_VALUE1: 最初のジョブの実行可能ファイルに適用するラベルの値。
RUNNABLE2_LABEL_NAME1: 2 番目のジョブの実行可能ファイルに適用するラベルの名前。
RUNNABLE2_LABEL_VALUE1: 2 番目のジョブの実行可能ファイルに適用するラベルの値。

次のステップ

次の操作を行う場合は、ラベルをフィルタとして使用します。
ジョブの削除とエクスポートの方法を確認する。