本記事では gcloud コマンドの --filter フラグと --format フラグを使った出力の制御について、具体例を交えて紹介します。

gcloud CLI コマンドの概要

Google Cloud CLI（gcloud CLI）は、リソースの作成と管理を行うためのツールです。このツールを利用することで、例えば以下のようなことが出来ます。

Compute Engine インスタンスの作成
Cloud SQL インスタンスのパラメータの確認
Google Kubernetes Engine クラスタの削除

出力結果を自在に操る

デフォルトの出力

まずは、何もフラグを指定せずに、リソース一覧を出力してみます。ここに様々な設定の Compute Engine インスタンスを3台用意しました。

次のコマンドを実行すると、内容を文字で確認することが出来ます。

$ gcloud compute instances list
NAME: test1
ZONE: asia-northeast1-a
MACHINE_TYPE: e2-small
PREEMPTIBLE: 
INTERNAL_IP: 192.168.1.15
EXTERNAL_IP: 34.84.108.247
STATUS: RUNNING
  
NAME: test2
ZONE: asia-northeast1-b
MACHINE_TYPE: e2-medium
PREEMPTIBLE: 
INTERNAL_IP: 192.168.1.16
EXTERNAL_IP: 35.187.200.2
STATUS: RUNNING
  
NAME: test3
ZONE: asia-northeast1-c
MACHINE_TYPE: e2-standard-2
PREEMPTIBLE: 
INTERNAL_IP: 192.168.1.17
EXTERNAL_IP: 
STATUS: TERMINATED

シンプルなコマンドで、主な内容を確認することが出来ました。しかし、この出力だと次のようなケースには対応するのに一手間必要になります。

対象の VM が100台あり、インスタンス名だけをすべて取得したい
インスタンス名とマシンタイプを Excel にまとめたい
ステータスが RUNNING の VM のみ値を取得したい

ここで用いるのが、gcloud コマンドの --filter フラグと --format フラグです。

format フラグで出力形式を指定

コマンドの後ろに --format フラグを付けることで、出力のフォーマットを変更することが出来ます。

例えば内容を JSON で出力したい場合、--format=json を指定することで、次のようになります。

$ gcloud compute instances list --format=json
[
  {
    "canIpForward": false,
    "confidentialInstanceConfig": {
      "enableConfidentialCompute": false
    },
    "cpuPlatform": "Intel Broadwell",
    "creationTimestamp": "2024-07-08T18:08:09.626-07:00",
    "deletionProtection": false,
    "description": "",
    "disks": [
      {
        "architecture": "X86_64",
        "autoDelete": true,
        "boot": true,
        "deviceName": "test1",
        "diskSizeGb": "10",
        "guestOsFeatures": [
          {
            "type": "UEFI_COMPATIBLE"
          },
          {
            "type": "VIRTIO_SCSI_MULTIQUEUE"
          },
          {
            "type": "GVNIC"
          },
          {
            "type": "SEV_CAPABLE"
          },
          {
            "type": "SEV_LIVE_MIGRATABLE_V2"
          }
        ],
        "index": 0,
（以下省略）

また、--format=table を使うと、特定の属性だけを抽出できます。例えば先程の例に上げた「インスタンス名だけを取得したい」場合、次のように指定出来ます。

$ gcloud compute instances list --format="table(name)"
NAME: test1
  
NAME: test2
  
NAME: test3

また、「インスタンス名とマシンタイプを取得したい」のように、複数の属性を取得することもできます。

$ gcloud compute instances list --format="table(name,MACHINE_TYPE)"
NAME: test1
MACHINE_TYPE: e2-small
  
NAME: test2
MACHINE_TYPE: e2-medium
  
NAME: test3
MACHINE_TYPE: e2-standard-2

また、csv 形式で出力することも可能です。結果をスプレッドシートや Excel に貼り付けたいときに有用です。

$ gcloud compute instances list --format="csv(name,MACHINE_TYPE)"
name,machine_type
test1,e2-small
test2,e2-medium
test3,e2-standard-2

このように format フラグを利用すると、JSON 形式、テーブル形式、csv 形式など、出力フォーマットを変更できます。

そのほか、詳細な仕様は公式ドキュメントをご参照ください。

参考 : gcloud topic formats

filter フラグで特定の値を持つリソースを抽出

コマンドの後ろに --filter フラグをつけることで、特定のパラメータを持つリソースだけを出力させることができます。

例えば、「RUNNING 状態の VM インスタンスの名前とインスタンスタイプを csv 出力したい」というケースの場合、次のように指定します。

$ gcloud compute instances list --format="csv(name,MACHINE_TYPE)" --filter="STATUS=RUNNING"
name,machine_type
test1,e2-small
test2,e2-medium

このように、出力結果の絞り込みに利用できるのが --filter フラグです。

詳細な仕様は公式ドキュメントをご参照ください。

参考 : gcloud topic filters

なお、--format フラグも --filter フラグも、ネストされた属性を指定することが可能です。

例えば「インスタンス名と、インスタンスに紐づいたサービスアカウント名を出力したい」というケースの場合、以下のように指定できます。

$ gcloud compute instances list --format="table(name,serviceAccounts[].email)"
  
NAME: test1
EMAIL: ['53xxxx11-compute@developer.gserviceaccount.com']