base-cloudrun

name: base-cloudrun description: >- Google Cloud Run のサービス設計・デプロイ・設定・認証を扱う時に使用する。ステートレス設計、コールドスタート対策、グレースフルシャットダウン、Cloud SQL 接続、 Direct VPC Egress、IAP によるアクセス制御、リビジョン管理のリファレンスを提供する。 user-invocable: false

Google Cloud Run でセキュアかつスケーラブルなサービスを構築するためのリファレンススキル。常に適用する設計原則を本文に置き、トピックごとの詳細は ./references 配下のファイルへ分離する。

完全なステートレス設計が必須 — コンテナのローカルファイルシステムはインメモリであり、インスタンス終了とともに消える。永続化すべきデータやセッションは必ず外部（Cloud SQL・Firestore・Cloud Storage・Memorystore）へオフロードする。
環境変数 PORT で listen する — Cloud Run が注入する PORT（デフォルト 8080）で 0.0.0.0 にバインドする。ポートをハードコードしない。
CPU はリクエスト処理中のみ割り当てられる（リクエストベースの課金、デフォルト）。レスポンス返却後のバックグラウンド処理は CPU が絞られて停止する。継続処理が必要なら「インスタンスベースの課金（CPU 常時割り当て）」を有効化するか、Cloud Tasks / Pub/Sub で別サービスへ分離する。
実行環境はワークロードで選ぶ — デフォルトの第 1 世代は高速スケーリングに最適化。 NFS マウントや高度なネットワーク機能が必要な場合のみ第 2 世代（--execution-environment gen2）を指定する。
サービスとジョブを使い分ける — HTTP リクエストを処理するなら Service、完了して終了するバッチ処理なら Job（gcloud run jobs）を使う。

作業対象のトピックに対応するリファレンスを読み込む。複数トピックにまたがる場合は該当分すべてを読む。

トピック	パス
デプロイコマンド・フラグ・SA・Secret Manager・イメージ・ロールアウト	`./references/deploy.md`
コールドスタート・コンカレンシー・SIGTERM・ヘルスチェック	`./references/lifecycle.md`
Cloud SQL 接続・Direct VPC Egress・コネクションプーリング	`./references/cloudsql.md`
IAM / IAP 認証・CORS プレフライト・モバイルセッション	`./references/auth.md`

パターン	使うケース
`gcloud run deploy --source .`	ソースから直接デプロイ（Buildpacks / Dockerfile）
`--no-allow-unauthenticated --iap`	人間向けのゼロトラストアクセス制御
`roles/iap.httpsResourceAccessor`	特定アカウントのみへのアクセス許可
`--network` + `--subnet`（/26 以上）	Direct VPC Egress による Cloud SQL 閉域接続
`--set-secrets`	Secret Manager からのシークレット注入
`--service-account`	専用 SA による最小権限実行
`--min-instances`	コールドスタートを許容できないレイテンシ要件
`--max-instances`	DB 接続上限から逆算したスケール上限
`--no-traffic --tag` + `update-traffic`	カナリアロールアウトと即時ロールバック
`pool_recycle` + Managed Connection Pooling	コネクション枯渇の防止
SIGTERM ハンドラー（10 秒以内）	グレースフルシャットダウン
startup / liveness プローブ	起動失敗の早期検知とデッドロック回復