Secret Manager とは、API キーなどの秘密の値を版ごとに保管する Google Cloud のサービスです。
- secret と版（version）の関係と、gcloud secrets で版を足す・引く・止める・戻す命令
- Cloud Run で secret を環境変数として渡す形とボリュームとして渡す形の違い
- 当社が版の運用で踏んだ記録（壊れた値を入れた版、長さの読み違い、参照と宣言のずれ、zsh の修飾子）
Google Secret Manager、GCP Secret Manager と呼ばれる物も、この同じサービスです。当社は AIエージェント の席に Google Cloud の作業を任せていて、この頁は公式の文書の定義に、版の運用で実際に踏んだ記録を並べた物です。席が gcloud を撃つときの認証は gcloud auth の頁に、席に任せるときの安全の全体は AI エージェントのセキュリティ の頁に、配備の側は Cloud Run の頁にあります。
secret と版（version）の関係
secret は、版の束とラベルや権限などのメタデータを持つ入れ物です。実際の値を持つのは版の方です（Secret Manager の概要・2026-11-06 に確認）。
値そのものは変更できず、操作の多くは版に対して行います（版の追加の文書・2026-11-06 に確認）。つまり値を替えるとは、新しい版を足す事です。版の状態は Enabled・Disabled・Destroyed の 3 種類で、無効にした版にはアクセスできなくなりますが、同じ secret の他の版には影響しません（版の無効化の文書・2026-11-06 に確認）。
gcloud secrets で版を足す・引く・止める・戻す
| やる事 | 命令 | 公式の文書の注意 |
|---|---|---|
| 版を足す | gcloud secrets versions add <secret 名> --data-file="<ファイルの道>" | 標準入力からは --data-file=-。命令の行に値を直に書くと、プロセスの一覧やシェルの履歴に残る。役割は Secret Version Adder か Secret Version Manager を secret に付ける（版には付けられない） |
| 版の値を引く | gcloud secrets versions access <版> --secret=<secret 名> | <版> は番号か別名で、latest で最新を指せる。既定は stdout へ UTF-8 で出すので、バイナリの値は壊れ得る。生のバイト列は --out-file で取る |
| 版を止める | gcloud secrets versions disable <版> --secret=<secret 名> | 役割は Secret Version Manager。有効に戻すまで、その版への要求はエラーになる |
| 止めた版を戻す | gcloud secrets versions enable | 有効に戻せばアクセスも戻る |
出典: 版の追加・版の無効化・gcloud secrets versions access（いずれも 2026-11-06 に確認）。versions enable の命令の名は社の実測 2026-10-02。
Cloud Run の secret は環境変数かボリュームで渡す
| 見る所 | 環境変数 | ボリューム |
|---|---|---|
| 値を解決する時 | インスタンスの起動時 | 読むたびに Secret Manager から取る |
| 取れないとき | インスタンスが起動しない | 起動時の確かめは無く、読み取りが失敗する |
| 版の指し方 | latest でなく特定の版に固定する事を Google が勧めている | 既定で最新の版を使える |
--update-secrets の形 | <環境変数名>=<secret 名>:<版> | <ファイルの道>=<secret 名>:<版> |
出典: Cloud Run の secret の設定（2026-11-06 に確認）。
同じ文書では、サービスの実行主体に Secret Accessor（roles/secretmanager.secretAccessor）の役割が要るとされ、--set-secrets は既存の secret の設定を消してから指定する形だとされています。
繋がらない値を入れた版を止め、次の版で確かめ直した
接続先のユーザー名だけを差し替えた接続文字列を版 1 に入れました。ところがこれは 1 回も繋がらない壊れた値でした。検証を先に書いていたから捕まえられました（社の実測 2026-09-20）。
版 1 を disabled にして版 2 を作り、次の 3 つで確かめました（社の実測 2026-09-20）。
| 確かめ | 見た事 |
|---|---|
| 接続ユーザーの確認 | 繋がっているユーザーが意図したものか |
UPDATE … WHERE false | 拒否される |
| 行数の一致 | 5 表の行数が一致する |
出典: 社の実測 2026-09-20。
値を替える手順は、新しい値を先に Secret Manager へ足してからサーバ側を変える順にしています（社の実測 2026-09-26）。
versions access の長さを「引けた」と読み違えた
versions access … | wc -c が 178 を返したので「引けた」と読みました。中身は、版が DISABLED だというエラー文でした（社の実測 2026-10-03）。エラー文を stdout に混ぜて数えると、長さは値の有無を示しません。
2>&1 を混ぜず、終了コードと stdout の長さを別に見る形へ直しました（社の実測 2026-10-03）。形にすると、例えば次のとおりです。値は画面に出ません。
set -o pipefail
bytes=$(gcloud secrets versions access <版> --secret=<secret 名> | wc -c)
rc=$?
echo "exit=$rc stdout_bytes=$bytes"もう 1 つ、zsh では 2>&1 >/dev/null が stdout を捨てない事があります（社の実測 2026-09-24）。捨てたつもりの形で長さを測らないようにします。
latest の参照と版の固定で、版を足した後の作業が違った
| 参照の形 | 新しい版を足した後の作業 | 確かめ |
|---|---|---|
latest | 版を上げる作業は要らなかった | — |
| 版を固定 | deploy の workflow に版を指す口を足して、タグを切った | gcloud run services describe で版 2 を実測した |
出典: 社の実測 2026-10-18・2026-10-21。
固定には別の落とし穴もありました。本番の参照を手で :2 に固定し、宣言は :latest のままにしたところ、次のタグが宣言の照合で落ち、半日気づきませんでした。宣言を 1 行直して切り直し、本番は無傷でした（社の実測 2026-09-20）。手で変えた参照は、宣言の側にも同じ変更が要ります。
disable の前に、消費者と戻し先の revision を見る
版を disable する前に消費者を数え、0 を確かめました。見たのは Cloud Run のサービスと Cloud Scheduler のジョブです。撃った後の access は FAILED_PRECONDITION になり、戻すなら versions enable です（社の実測 2026-10-02）。
今動いている物だけでは足りません。戻し先の revision が消す側の版を参照していると、disable した後は起動時に解決できず、戻しが落ちます。事前にこれに気づき、戻しの窓を閉じるまで disable を保留しました。実際には落ちていません（社の実測 2026-09-24）。
平文の環境変数を secret 参照へ移したら、起動に失敗した
平文の環境変数を secret 参照へ移したとき、値の sha256 は一致したのに、新しい revision が 2 回同じ形で起動に失敗しました。--no-traffic --tag で作っていたので、本番は無傷でした（社の実測 2026-09-19）。
原因は未確定です。改行や引用符の差は仮説で、確かめられていません（社の実測 2026-09-19）。
NOT_FOUND は「無い」でなく「測れない」と読む
権限が無いと describe が NOT_FOUND を返しました。list ではエラー文を行数で数えてしまい、「8 本」に見えました（社の実測 2026-09-23）。命令の失敗は「無い」ではなく「測れない」と読みます。
--update-secrets で踏んだ zsh の修飾子と revision
| 踏んだ事 | 出た物 | 避け方・分かった事 |
|---|---|---|
zsh で --update-secrets X=$SEC:latest と書くと、:l が修飾子として効く | No secret version specified で 2 回空振り | ${SEC}:latest と書けば避けられる |
secret だけの更新でも、gcloud run services update は revision を作る | image の読み取り権限が無いと PERMISSION_DENIED で落ちた | secret だけの更新でも revision を作る前提で撃つ |
出典: 社の実測 2026-10-06。
よくある質問
Secret Manager の値は上書きできますか？
できません。値は変更できないので、新しい版を足します（版の追加の文書・2026-11-06 に確認）。当社は新しい値を先に足してからサーバ側を変える順にしています（社の実測 2026-09-26）。
gcloud secrets versions access で最新の版を引くには？
gcloud secrets versions access latest --secret=<secret 名> の形で、版の引数に latest を渡します（gcloud secrets versions access・2026-11-06 に確認）。引けたかどうかは、出力の長さでなく終了コードも合わせて見ます。
Cloud Run の環境変数は latest と版の固定のどちらを指しますか？
公式の文書は、環境変数では特定の版への固定を勧めています（Cloud Run の secret の設定・2026-11-06 に確認）。当社では、固定したサービスは版を足した後に deploy の workflow で版を指す作業が要り、latest のサービスは要りませんでした（社の実測 2026-10-18・2026-10-21）。
disable した版を access すると何が返りますか？
当社の実測では FAILED_PRECONDITION でした。versions enable で戻せます（社の実測 2026-10-02）。
「No secret version specified」と出ます
当社では、zsh で X=$SEC:latest と書いて :l が修飾子として効いたときに出ました。${SEC}:latest と書けば避けられます（社の実測 2026-10-06）。
出典
- Google Cloud「Secret Manager の概要」 https://docs.cloud.google.com/secret-manager/docs/overview（2026-11-06 に確認）
- Google Cloud「secret の版の追加」 https://docs.cloud.google.com/secret-manager/docs/add-secret-version（2026-11-06 に確認）
- Google Cloud「secret の版の無効化」 https://docs.cloud.google.com/secret-manager/docs/disable-secret-version（2026-11-06 に確認）
- Google Cloud「Cloud Run の secret の設定」 https://docs.cloud.google.com/run/docs/configuring/services/secrets（2026-11-06 に確認）
- Google Cloud「gcloud secrets versions access」 https://docs.cloud.google.com/sdk/gcloud/reference/secrets/versions/access（2026-11-06 に確認）
- 社の実測 2026-09-19（secret 参照へ移したときの起動の失敗）・2026-09-20（壊れた値の版と確かめ、参照と宣言のずれ）・2026-09-23（NOT_FOUND と行数の読み違い）・2026-09-24（戻し先の revision と disable の保留、zsh のリダイレクト）・2026-09-26（値を替える順）・2026-10-02（disable の前の確かめ）・2026-10-03（長さの読み違い）・2026-10-06（zsh の修飾子、secret だけの更新と revision）・2026-10-18・2026-10-21（latest と版の固定）
ブルーランプ 記事の編集部／更新日 2026-11-06