ラベルを作成、管理する

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

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

ラベルとは

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

ラベルの要件

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

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

これらの上限は、各ラベルのキーと値、およびラベルが付けられた個々の Managed Service for Apache Spark クラスタやジョブに適用されます。1 つのプロジェクト内のすべてのリソースに適用できるラベルの数に上限はありません。

ラベルの一般的な用途

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

  • チームまたはコストセンターのラベル: チームまたは コストセンターに基づいてラベルを追加し、各チームが所有する Managed Service for Apache Spark クラスタとジョブを区別します（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 呼び出しにタイムスタンプや個別の値を設定するなど、一意のラベルを多数作成することはおすすめしません。このアプローチの問題は、値が頻繁に変更される場合やカタログを混乱させるキーを使用している場合に、リソースを効果的にフィルタして報告することが困難になることです。

ラベルとタグ

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

Managed Service for Apache Spark ラベルを作成して使用する

コンソール

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

クラスタまたはジョブが作成または送信されたら、そのクラスタまたはジョブに関連付けられているラベルを更新できます。ラベルを更新するには、リストに表示されたクラスタまたはジョブの選択ボックスをオンにして、SHOW INFO PANEL をクリックします。次に示すのは、[Managed Service for Apache Spark] → [クラスタのリスト表示] ページの例です。

gcloud コマンド

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

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

Managed Service for Apache Spark クラスタまたはジョブが作成されたら、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 と 以下の形式のフィルタ式を使用して、ラベルで Managed Service for Apache Spark リソースをフィルタできます: labels.<key=value>

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"

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

REST API

Dataproc REST API を使用して、クラスタやジョブにラベルを付けることができます。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

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

Google Cloud

情報パネルが表示されたら、クラスタやジョブのラベルを更新できます。次に示すのは、Managed Service for Apache Spark クラスタのラベルを更新する例です。

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

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

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

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

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

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

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

次のステップ