gcloud storage

Table of Contents

  1. 前提
  2. 基本コマンド
  3. バケット操作
    1. 作成
    2. ストレージクラス
    3. 管理
  4. オブジェクト操作
    1. アップロード
    2. ダウンロード
    3. 一覧・検索
    4. 削除
  5. ディレクトリ同期（rsync）
  6. アクセス制御
    1. バケットレベルの IAM
    2. よく使うストレージロール
    3. 署名付き URL
  7. ライフサイクル管理
  8. gsutil との違い
  9. 注意点
  10. 参考リンク

gcloud storage は Cloud Storage のバケットやオブジェクトを操作するコマンドです。従来の gsutil の後継として、高速な並列転送とシンプルなコマンド体系を提供します。

前提

1
2
# Cloud Storage API を有効化（デフォルトで有効な場合が多い）
gcloud services enable storage.googleapis.com

基本コマンド

コマンド 用途
gcloud storage buckets create バケットを作成
gcloud storage buckets list バケットの一覧を表示
gcloud storage buckets delete バケットを削除
gcloud storage cp オブジェクトのコピー（アップロード・ダウンロード）
gcloud storage ls オブジェクトの一覧を表示
gcloud storage rm オブジェクトを削除
gcloud storage rsync ディレクトリ同期
gcloud storage cat オブジェクトの内容を表示

バケット操作

作成

1
2
3
4
5
6
7
8
9
10
11
12
13
# バケットを作成（東京リージョン）
gcloud storage buckets create gs://my-bucket \
  --location=asia-northeast1

# ストレージクラスを指定して作成
gcloud storage buckets create gs://my-archive-bucket \
  --location=asia-northeast1 \
  --default-storage-class=NEARLINE

# 均一バケットレベルアクセスを有効化（推奨）
gcloud storage buckets create gs://my-bucket \
  --location=asia-northeast1 \
  --uniform-bucket-level-access

ストレージクラス

クラス 用途 最小保存期間
STANDARD 頻繁にアクセスするデータ なし
NEARLINE 月 1 回程度のアクセス 30 日
COLDLINE 四半期に 1 回程度のアクセス 90 日
ARCHIVE 年 1 回未満のアクセス 365 日

管理

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# バケットの一覧
gcloud storage buckets list

# バケットの詳細
gcloud storage buckets describe gs://my-bucket

# バケットのメタデータを更新
gcloud storage buckets update gs://my-bucket \
  --versioning \
  --lifecycle-file=lifecycle.json

# バケットを削除（中身が空である必要がある）
gcloud storage buckets delete gs://my-bucket

# 中身ごと削除
gcloud storage rm -r gs://my-bucket

オブジェクト操作

アップロード

1
2
3
4
5
6
7
8
9
# ファイルをアップロード
gcloud storage cp local-file.txt gs://my-bucket/

# ディレクトリを再帰的にアップロード
gcloud storage cp -r ./local-dir gs://my-bucket/remote-dir

# 並列アップロード（大量ファイル時に高速）
gcloud storage cp -r ./data gs://my-bucket/data \
  --additional-headers="Cache-Control:max-age=3600"

ダウンロード

1
2
3
4
5
# ファイルをダウンロード
gcloud storage cp gs://my-bucket/remote-file.txt ./

# ディレクトリを再帰的にダウンロード
gcloud storage cp -r gs://my-bucket/remote-dir ./local-dir

一覧・検索

1
2
3
4
5
6
7
8
9
10
11
# オブジェクトの一覧
gcloud storage ls gs://my-bucket/

# 再帰的に表示
gcloud storage ls -r gs://my-bucket/

# 詳細情報（サイズ、更新日時など）を表示
gcloud storage ls -l gs://my-bucket/

# ワイルドカードでフィルタ
gcloud storage ls gs://my-bucket/**/*.json

削除

1
2
3
4
5
6
7
8
# ファイルを削除
gcloud storage rm gs://my-bucket/file.txt

# ディレクトリを再帰的に削除
gcloud storage rm -r gs://my-bucket/old-data/

# ワイルドカードで一括削除
gcloud storage rm gs://my-bucket/**/*.tmp

ディレクトリ同期（rsync）

ローカルディレクトリと Cloud Storage を同期します。差分のみ転送するため効率的です。

1
2
3
4
5
6
7
8
9
10
11
# ローカル → Cloud Storage（アップロード同期）
gcloud storage rsync ./local-dir gs://my-bucket/remote-dir -r

# Cloud Storage → ローカル（ダウンロード同期）
gcloud storage rsync gs://my-bucket/remote-dir ./local-dir -r

# 同期元にないファイルを同期先から削除
gcloud storage rsync ./local-dir gs://my-bucket/remote-dir -r --delete-unmatched-destination-objects

# ドライラン（実際には実行しない）
gcloud storage rsync ./local-dir gs://my-bucket/remote-dir -r --dry-run

アクセス制御

バケットレベルの IAM

1
2
3
4
5
6
7
8
9
10
11
12
# サービスアカウントに読み取り権限を付与
gcloud storage buckets add-iam-policy-binding gs://my-bucket \
  --member="serviceAccount:my-sa@PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/storage.objectViewer"

# 全ユーザーに公開読み取り権限（静的サイトホスティングなど）
gcloud storage buckets add-iam-policy-binding gs://my-bucket \
  --member="allUsers" \
  --role="roles/storage.objectViewer"

# 権限の確認
gcloud storage buckets get-iam-policy gs://my-bucket

よく使うストレージロール

ロール 説明
roles/storage.objectViewer オブジェクトの読み取り
roles/storage.objectCreator オブジェクトの作成（上書き・削除は不可）
roles/storage.objectUser オブジェクトの読み書き削除
roles/storage.admin バケットとオブジェクトの完全な制御

署名付き URL

一時的なアクセス URL を生成します。認証なしでオブジェクトにアクセスさせたい場合に使います。

1
2
3
4
# 1 時間有効な署名付き URL を生成
gcloud storage sign-url gs://my-bucket/private-file.pdf \
  --private-key-file=key.json \
  --duration=1h

ライフサイクル管理

オブジェクトを自動でストレージクラス変更や削除するルールを設定します。

1
2
3
# ライフサイクルルールを設定
gcloud storage buckets update gs://my-bucket \
  --lifecycle-file=lifecycle.json

lifecycle.json の例:

1
2
3
4
5
6
7
8
9
10
11
12
{
  "rule": [
    {
      "action": {"type": "SetStorageClass", "storageClass": "NEARLINE"},
      "condition": {"age": 30}
    },
    {
      "action": {"type": "Delete"},
      "condition": {"age": 365}
    }
  ]
}

gsutil との違い

項目 gcloud storage gsutil
並列転送 デフォルトで高速 -m フラグが必要
コマンド体系 gcloud と統一 独自のコマンド体系
開発状況 推奨・アクティブ メンテナンスモード 
1
2
3
4
# gsutil → gcloud storage の置き換え例
gsutil cp file gs://bucket/       → gcloud storage cp file gs://bucket/
gsutil ls gs://bucket/            → gcloud storage ls gs://bucket/
gsutil -m rsync -r dir gs://b/    → gcloud storage rsync dir gs://b/ -r

注意点

  • バケット名はグローバルに一意。プロジェクト ID をプレフィックスに含めると衝突しにくい
  • --delete-unmatched-destination-objects を付けた rsync は同期先のファイルを削除するので注意
  • 均一バケットレベルアクセス（--uniform-bucket-level-access）を使うと ACL が無効になり、IAM だけでアクセス制御できて管理がシンプルになる

参考リンク