ラベルを作成、管理する

Dataproc のクラスタおよびジョブリソースにユーザーラベルを適用すると、リソースおよび関連オペレーションをグループ分けでき、後でフィルタリングや一覧表示することが可能です。リソースの作成時、クラスタの作成時、またはジョブの送信時にラベルをリソースに関連付けます。リソースがラベルに関連付けられると、そのラベルはリソースで実行されるオペレーション（クラスタの作成、更新、パッチ適用、削除やジョブの送信、更新、キャンセル、削除）に伝播されて、クラスタ、ジョブ、オペレーションをラベルでフィルタリングおよび一覧表示できます。

また、仮想マシンのインスタンスやディスクなど、クラスタリソースに関連付けられた Compute Engine リソースにラベルを追加することもできます。

ラベルとは

ラベルは、Google Cloud Dataproc クラスタとジョブに割り当てることができる Key-Value ペアです。ラベルはこれらのリソースを整理し、必要な粒度に基づいてコストを大規模に管理する場合に役立ちます。各リソースにラベルを設定し、そのラベルに基づいてリソースをフィルタできます。ラベルに関する情報は課金システムに転送され、請求料金をラベル別に分類できます。組み込みの請求レポートにより、リソースラベルで費用をフィルタしてグループ化できます。また、ラベルを使用して請求データエクスポートをクエリすることもできます。

ラベルの要件

リソースに適用するラベルは、次の要件を満たす必要があります。

各リソースには、最大 64 個のラベルを設定できます。
ラベルは、Key-Value ペアでなければなりません。
キーは 1 文字以上、63 文字までにする必要があります。空にすることはできません。値は 63 文字以下にします。空にすることもできます。
キーと値には、小文字、数字、アンダースコア、ダッシュのみを使用できます。すべての文字は UTF-8 でエンコードする必要があります。国際文字も使用できます。キーは、小文字または国際文字で始める必要があります。
ラベルのキー部分は、単一のリソース内では一意である必要があります。ただし、複数のリソースで同じキーを使用できます。

これらの上限は、各ラベルのキーと値だけでなく、ラベルのある個々の Google Cloud リソースにも適用されます。1 つのプロジェクト内のすべてのリソースに適用できるラベルの数に上限はありません。

ラベルの一般的な用途

次に、ラベルの一般的な使用例を示します。

チームまたはコストセンターのラベル: チームまたはコストセンターに基づいてラベルを追加し、各チームが所有する Dataproc クラスタとジョブを区別します（team:research、team:analytics など）。このタイプのラベルは、費用計算や予算作成に使用できます。
コンポーネントラベル: component:redis、component:frontend、component:ingest、component:dashboard など。
環境ラベルまたはステージのラベル: environment:production、environment:test など。
状態のラベル: state:active、state:readytodelete、state:archive など。
オーナー権限ラベル: 運用担当チームの識別に使用されます（例: team:shopping-cart）。

すべての API 呼び出しにタイムスタンプや個別の値を設定するなど、一意のラベルを多数作成することはおすすめしません。このアプローチの問題は、値が頻繁に変更される場合やカタログを混乱させるキーを使用している場合に、リソースを効果的にフィルタして報告することが困難になることです。

ラベルとタグ

ラベルは、リソースに対するクエリ可能なアノテーションとして使用できますが、ポリシーの条件の設定には使用できません。タグを使用すると、ポリシーをきめ細かく制御することによって、リソースに特定のタグが付加されているかどうかに基づいて、条件付きでポリシーを許可または拒否することが可能になります。詳細については、タグの概要をご覧ください。

Dataproc ラベルの作成と使用

セカンダリワーカーを持つクラスタのラベル更新クラスタには、プリエンプティブルセカンダリワーカーまたは非プリエンプティブルセカンダリワーカーのどちらかを含めることができますが、両方を含めることはできません。ラベルの更新は、24 時間以内にすべてのプリエンプティブルセカンダリワーカーに反映されます。現在、ラベルの更新はプリエンプティブルでない既存のセカンダリワーカーには反映されません。ラベルの更新は、ラベルの更新後にクラスタに追加されたワーカーにも反映されます。たとえば、クラスタをスケールアップすると、すべての新しいプライマリワーカーとセカンダリワーカーに新しいラベルが付けられます。

gcloud コマンド

Google Cloud CLI を使用して Dataproc クラスタまたはジョブを作成または送信するときに、適用するラベルを 1 つまたは複数指定できます。

gcloud dataproc clusters create args --labels environment=production,customer=acme
gcloud dataproc jobs submit args --labels environment=production,customer=acme

Dataproc クラスタまたはジョブが作成されたら、Google Cloud CLI を使用して、そのリソースに関連付けられたラベルを更新できます。

gcloud dataproc clusters update args --update-labels environment=production,customer=acme
gcloud dataproc jobs update args --update-labels environment=production,customer=acme

同様に、Google Cloud CLI と labels.<key=value> という形式のフィルタ式を使用して、ラベルで Dataproc リソースをフィルタできます。

gcloud dataproc clusters list \
    --region=region \
    --filter="status.state=ACTIVE AND labels.environment=production"
gcloud dataproc jobs list \
    --region=region \
    --filter="status.state=ACTIVE AND labels.customer=acme"

フィルタ式の作成方法については、Dataproc API のドキュメントで clusters.list および jobs.list をご覧ください。

REST API

Dataproc REST API を使用して、Dataproc リソースにラベルを付けることができます。clusters.create API や jobs.submit API を使用して、クラスタやジョブを作成または送信するときにラベルを付けることができます。リソースの作成後は、clusters.patch API や jobs.patch API を使用してラベルを編集できます。key1:value ラベルをクラスタに付ける cluster.create リクエストの JSON 本文の例を次に示します。

{
  "clusterName":"cluster-1",
  "projectId":"my-project",
  "config":{
    "configBucket":"",
    "gceClusterConfig":{
      "networkUri":".../networks/default",
      "zoneUri":".../zones/us-central1-f"
    },
    "masterConfig":{
      "numInstances":1,
      "machineTypeUri":"..../machineTypes/n1-standard-4",
      "diskConfig":{
        "bootDiskSizeGb":500,
        "numLocalSsds":0
      }
    },
    "workerConfig":{
      "numInstances":2,
      "machineTypeUri":"...machineTypes/n1-standard-4",
      "diskConfig":{
        "bootDiskSizeGb":500,
        "numLocalSsds":0
      }
    }
  },
  "labels":{
    "key1":"value1"
  }
}

clusters.list API や jobs.list API を使用すると、指定したフィルタに一致するリソースを labels.<key=value> の形式で一覧表示できます。

次に示すサンプルでは、Dataproc API の clusters.list HTTPS GET リクエストで key=value ラベルフィルタが指定されています。呼び出し元により、project、region と、フィルタ label-key および label-value、および api-key が挿入されます。このサンプルリクエストは読みやすさのために 2 行に分けて記載されています。

GET https://dataproc.googleapis.com/v1/projects/project/regions/region/clusters?
filter=labels.label-key=label-value&key=api-key

フィルタ式の作成方法については、Dataproc API のドキュメントで clusters.list および jobs.list をご覧ください。

コンソール

Google Cloud コンソールを使用して、作成または送信するときに Dataproc リソースに追加するラベルのセットを指定できます。

Dataproc の [クラスタの作成] ページにある [クラスタのカスタマイズ] パネルの [ラベル] セクションで、クラスタにラベルを追加します。
Dataproc の [ジョブの送信] ページで、ジョブにラベルを追加します。

Dataproc リソースを作成した後は、そのリソースに関連付けられているラベルを更新できます。ラベルを更新するには、まずページの左上にある SHOW INFO PANEL をクリックします。次に示すのは、[Dataproc] → [クラスタのリスト表示] ページの例です。

情報パネルが表示されたら、Cloud Dataproc リソースのラベルを更新できます。次に示すのは、Dataproc クラスタのラベル更新の例です。

また、1 回のオペレーションで複数のアイテムのラベルを更新することもできます。次の例では、複数の Dataproc ジョブのラベルを一度に更新しています。

ラベルを使用すると、[Dataproc] → [クラスタのリスト表示] ページと [Dataproc] → [ジョブのリスト表示] ページに表示される Dataproc リソースをフィルタリングできます。ページの上部で、検索パターン labels.<labelname>=<value> を使用してリソースをラベルでフィルタリングできます。

自動的に適用されるラベル

クラスタを作成または更新すると、Dataproc は複数のラベルをクラスタおよびクラスタリソースに自動的に適用します。たとえば、クラスタを作成すると Dataproc によって仮想マシン、永続ディスク、アクセラレータにラベルが適用されます。自動的に適用されるラベルには、特別な接頭辞の goog-dataproc が付いています。

次の goog-dataproc ラベルは、Dataproc リソースに自動的に適用されます。自動指定された値は、クラスタ作成時に予約された goog-dataproc ラベルに指定された値によって上書きされます。このため、これらのラベルに独自の値を指定することはおすすめしません。

ラベル	説明
`goog-dataproc-cluster-name`	ユーザー指定のクラスタ名
`goog-dataproc-cluster-uuid`	一意のクラスタ ID
`goog-dataproc-location`	Dataproc リージョンクラスタエンドポイント

これらの自動的に適用されたラベルは、以下をはじめとしてさまざまな方法で使用できます。

Dataproc リソースの検索とフィルタ
課金データのフィルタによる Dataproc 費用の計算