Google Secrets Managerインポート

gcp-secrets-import コマンドは、Google Cloud Secret Managerからアクセス可能なすべてのシークレットを読み取り、指定した共有フォルダにKeeperレコードとして取り込みます。各シークレット名がレコードのタイトルとなり、シークレットの値はレコード上の名前付きフィールドに解析されます。

• エイリアス: gcsi

• 要件: google-cloud-secret-manager — pip install keeper-commander[gcp] でインストール

---

認証

GCP認証情報は以下の順序で解決されます。

1

サービスアカウントキーファイル

--service-account-file を指定した場合、指定したJSONキーファイルが読み込まれ、すべてのAPI呼び出しに使用されます。

2

Application Default Credentials (ADC)

キーファイルがない場合は、GCP SDK のADCチェーンが使用され、以下の順序で確認されます。

• GOOGLE_APPLICATION_CREDENTIALS 環境変数 (サービスアカウントキーファイルへのパス)

• gcloud auth application-default login で設定したユーザー認証情報

• 実行中のCompute Engineインスタンス、Cloud Runサービス、GKEワークロード、その他GCPホスト環境にアタッチされたサービスアカウント

本番環境では、--service-account-file を省略し、Workload Identityまたはアタッチされたサービスアカウントに任せることが多いです。

---

基本的な使い方

gcp-secrets-import <folder-uid> --project-id <project> [options]

位置引数 folder-uid と --project-id フラグの両方が必須です。

• folder-uid — インポート先となるKeeper共有フォルダの一意識別子。コマンダー内で list-sf を実行すると確認できます。

My Vault> list-sf

• --project-id — シークレットを所有するGCPプロジェクトID (プロジェクト番号ではない)。例: my-gcp-project。

---

引数とフラグ

位置引数

引数	説明
folder	必須。 シークレットのインポート先となる共有フォルダUID。

認証情報フラグ

フラグ	説明
--project-id ID	必須。 シークレットを所有するGCPプロジェクトID (例: my-gcp-project)。
--service-account-file PATH	GCPサービスアカウントJSONキーファイルへのパス。省略時はApplication Default Credentialsを使用。

動作フラグ

フラグ	説明
--record-type TYPE	インポートするレコードのKeeperレコードタイプ。既定値は login。
--dry-run	レコードを作成せず、インポート対象のシークレットを一覧表示。

フィルタフラグ

すべてのフィルタフラグは任意で、AND条件で組み合わされます。指定したすべてのフィルタを満たすシークレットのみがインポートされます。

フラグ	説明
--name NAME	この名前と完全一致するシークレットのみインポート。
--name-starts-with PREFIX	名前が PREFIX で始まるシークレットのみインポート。
--name-ends-with SUFFIX	名前が SUFFIX で終わるシークレットのみインポート。
--name-contains SUBSTRING	名前に SUBSTRING を含むシークレットのみインポート。
--tags KEY=VALUE[,KEY=VALUE,...]	指定したキー/値のGCPラベルとすべて一致するシークレットのみインポート。

GCPラベルについて: GCP Secret Manager では tags ではなく labels という用語を使います。--tags フラグはGCPラベルに直接マッピングされ、AWSやAzureと同じ使い方ができます。

---

シークレットのフィルタリング

フィルタを使うと、残りのシークレットに触れずに対象のサブセットだけをインポートできます。指定した各フィルタに一致する必要があります。

latest バージョンが無効、破棄済み、または権限不足でアクセスできないシークレットは、フィルタ設定にかかわらず警告付きで常にスキップされます。

名前フィルタ

名前フィルタは、短いシークレット名 (完全なGCPリソース名 projects/{project}/secrets/{secret-id} の最後のセグメント) に対して適用されます。

# 名前の完全一致
gcsi xAbCdEfGhIjK --project-id my-project --name database-primary-password

# 名前が "prod-" で始まるすべてのシークレット
gcsi xAbCdEfGhIjK --project-id my-project --name-starts-with prod-

# 名前が "-creds" で終わるシークレット
gcsi xAbCdEfGhIjK --project-id my-project --name-ends-with -creds

# 名前に "postgres" を含むシークレット
gcsi xAbCdEfGhIjK --project-id my-project --name-contains postgres

複数の名前フィルタを組み合わせることもできます。それぞれが追加の条件になります。

# "prod-" で始まり、かつ "database" を含む必要がある
gcsi xAbCdEfGhIjK --project-id my-project \
  --name-starts-with prod- --name-contains database

ラベルフィルタ (--tags)

GCP Secret Manager のシークレットには任意のキー/値 labels を付与できます。--tags フラグは、カンマ区切りの KEY=VALUE ペアのリストを受け取ります。指定したラベルをすべて、かつ与えた値と完全一致で持つシークレットのみが対象になります。

# 単一ラベル条件
gcsi xAbCdEfGhIjK --project-id my-project --tags env=prod

# 複数ラベル条件 (両方が一致する必要がある)
gcsi xAbCdEfGhIjK --project-id my-project --tags env=prod,team=payments

GCPのラベルキーと値は慣例として小文字であり、大文字と小文字を区別します。指定する値はGCPに保存されている表記と一致させてください。

フィルタの組み合わせ

すべてのフィルタ種別を1つのコマンドで併用できます。

gcsi xAbCdEfGhIjK --project-id my-project \
  --name-starts-with prod- \
  --name-ends-with -creds \
  --tags env=prod,owner=platform

リストしたすべてのフィルタを満たすシークレットのみがインポートされます。

---

シークレット値の形式

GCP Secret Manager からシークレットを取得すると、latest バージョンのペイロードがUTF-8としてデコードされたうえで、以下のルールに従い名前付きフィールド値へ解析されます。

1

JSONオブジェクト

ペイロードが { で始まり、オブジェクトを表す有効なJSONである場合、オブジェクト内の各キー/値ペアがKeeperレコード上の個別フィールドになります。

{
  "username": "admin",
  "password": "s3cur3P@ss!",
  "host": "db.internal.example.com"
}

username、password、host の3フィールドになります。

2

KEY=VALUE行 (シェル形式)

ペイロードがJSONでない場合、改行区切りの KEY=VALUE ペア (.env ファイルと同じ形式) として解析を試みます。# で始まる行と空行は無視されます。

# Database credentials
username=admin
password=s3cur3P@ss!
host=db.internal.example.com

username、password、host の3フィールドになります。

3

代替 — プレーン文字列

JSONでも KEY=VALUE 行でも解析できない場合、文字列全体が value という名前の単一フィールドに保存されます。

s3cur3P@ss!

value = s3cur3P@ss! の1フィールドになります。

---

Keeperレコードの構造

インポートされた各シークレットは、対象の共有フォルダにTypedRecordが1件作成されます。

• タイトル — 短いGCPシークレット名 (例: prod-database-primary)。完全なリソースパスではない

• レコードタイプ — --record-type で制御 (既定値: login)

フィールドの配置

シークレットから解析したキー/値ペアは、レコードに配置する前にKeeperフィールドタイプへマッピングされます。

解析キー (大文字小文字を区別しない)	Keeperフィールドタイプ	配置
username, user, login	login	型付きフィールド
password, pass, secret, secret_value	password	型付きフィールド
url, endpoint, host	url	型付きフィールド
email, mail	email	型付きフィールド
note, notes	—	レコードのNotesセクション
上記以外	text	型付きフィールド

note および notes キーは、型付きフィールドやカスタムフィールドではなく、レコードのNotesフィールドに書き込まれます。上記以外のキーは text 型付きフィールドとして保存されます。同じ意味のタイプ (login、password、url、email など) が複数ある場合、最初の出現が型付きフィールドのスロットを占め、以降はカスタムフィールドに保存されます。

---

例

Application Default Credentialsですべてのシークレットをインポート

gcsi xAbCdEfGhIjK --project-id my-gcp-project

GOOGLE_APPLICATION_CREDENTIALS 環境変数、gcloud の認証情報、またはアタッチされたサービスアカウントを自動的に使用します。

サービスアカウントキーファイルで認証

gcsi xAbCdEfGhIjK \
  --project-id my-gcp-project \
  --service-account-file /path/to/service-account-key.json

インポート対象のプレビュー (ドライラン)

gcsi xAbCdEfGhIjK --project-id my-gcp-project --dry-run

すべてのフィルタを通過するシークレット名を表示し、レコードは作成しません。

paymentsチームが所有する本番シークレットのみインポート

gcsi xAbCdEfGhIjK --project-id my-gcp-project \
  --name-starts-with prod- --tags team=payments

既知の単一シークレットをインポート

gcsi xAbCdEfGhIjK --project-id my-gcp-project --name prod-stripe-api-key

ステージングのデータベースシークレットを serverCredentials レコードとしてインポート

gcsi xAbCdEfGhIjK --project-id my-gcp-project \
  --name-contains database \
  --tags env=staging \
  --record-type serverCredentials

複雑なフィルタをコミット前にドライラン

gcsi xAbCdEfGhIjK --project-id my-gcp-project \
  --name-starts-with prod- \
  --name-ends-with -creds \
  --tags env=prod,owner=platform \
  --dry-run

CIシークレットに保存したサービスアカウントキーでインポート

# CI環境変数からキーをデコードしてインポート
echo "$GCP_SA_KEY" > /tmp/sa-key.json
gcsi xAbCdEfGhIjK \
  --project-id my-gcp-project \
  --service-account-file /tmp/sa-key.json \
  --tags env=prod
rm /tmp/sa-key.json