ラベルを作成、管理する

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

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

ラベルとは

ラベルとは、Google Cloud Dataproc クラスタとジョブの整理に役立つ Key-Value ペアのことです。各リソースにラベルを設定し、そのラベルに基づいてリソースをフィルタできます。ラベルに関する情報は課金システムに転送されるため、ラベルを基準に請求料金を分析することもできます。

ラベルの一般的な用途

タイムスタンプやすべての API 呼び出しに個別に値を作成するなど、一意のラベルを多数作成することはおすすめしません。次に、ラベルの一般的な使用例を示します。

  • チームまたはコストセンターのラベル: チームまたはコストセンターに基づいてラベルを追加し、各チームが所有する Dataproc クラスタとジョブを区別します(team:researchteam:analytics など)。このタイプのラベルは、費用計算や予算作成に使用できます。

  • コンポーネント ラベル: component:rediscomponent:frontendcomponent:ingestcomponent:dashboard など。

  • 環境ラベルまたはステージのラベル: environment:productionenvironment:test など。

  • 状態のラベル: state:activestate:readytodeletestate:archive など。

ラベルの要件

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

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

Dataproc ラベルの作成と使用

gcloud コマンド

作成または送信時に gcloud コマンドライン ツールを使用して、Cloud Dataproc クラスタまたはジョブに適用する 1 つ以上のラベルを指定できます。

gcloud dataproc clusters create args --labels env=prod,customer=acme
gcloud dataproc jobs submit args --labels env=prod,customer=acme
Cloud Dataproc クラスタまたはジョブが作成されたら、gcloud コマンドライン ツールを使用してそのリソースに関連付けられたラベルを更新できます。
gcloud dataproc clusters update args --update-labels env=prod,customer=acme
gcloud dataproc jobs update args --update-labels env=prod,customer=acme
同様に、gcloud コマンドライン ツールを使用し、次の labels.<key=value> 形式のフィルタ式を使用して、ラベルで Cloud Dataproc リソースをフィルタリングできます。
gcloud dataproc clusters list --filter "status.state=ACTIVE AND labels.env=prod"
gcloud dataproc jobs list --filter "status.state=ACTIVE AND labels.customer=acme"
フィルタ式の作成についての詳細は、clusters.list および jobs.list の Cloud Dataproc API ドキュメントをご覧ください。

REST API

ラベルは、Cloud Dataproc REST APIを使用して Cloud 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> の形式で一覧表示できます。次に示すサンプルでは、Cloud Dataproc API の clusters.list HTTPS GET リクエストで key=value ラベルフィルタが指定されています。呼び出し元により、projectregion と、フィルタ label-keylabel-valueapi-key が挿入されます。このサンプル リクエストは読みやすさのために 2 行に分けて記載されています。
GET https://dataproc.googleapis.com/v1/projects/project/regions/region/clusters?
filter=labels.label-key=label-value&key=api-key
フィルタ式の作成についての詳細は、clusters.list および jobs.list の Cloud Dataproc API ドキュメントをご覧ください。

コンソール

Cloud Console を使用して、Cloud Dataproc リソースの作成時または送信時に適用する一連のラベルを指定できます。下の図は、[Cloud Dataproc] → [クラスタの作成] ページから Cloud Dataproc クラスタに関連付けるラベルを作成する例です。

[Cloud Dataproc] → [ジョブを送信] ページで、Cloud Dataproc ジョブに関連付けるラベルを作成する例を次に示します。

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

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

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

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

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

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

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

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

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

次のステップ