G-gen の佐々木です。当記事では Cloud Run における環境変数の設定について解説します。

Cloud Run の環境変数

仕様

Cloud Run では、Cloud Run 側の設定項目としてコンテナに環境変数を設定することができます。

Cloud Run 側に設定した環境変数は、コンテナ上で実行するアプリケーションから利用することができます。これは、Dockerfile の ENV から設定した環境変数の挙動と似ています。

環境変数は最大1000個まで設定することができ、変数の最大長として 32kb の制限があります。

環境変数のキーには「空の文字列」、「=を含む文字列」、「X_GOOGLE_から始まる文字列」は使用できません。

当記事では Cloud Run services を例として解説しますが、環境変数の設定に関する基本的な仕様は Cloud Run jobs 等、その他の実行モデルでも同様です。

参考 : Configure containers for services（Cloud Run services）
参考 : Configure environment variables for job（Cloud Run jobs）
参考 : Configure environment variables for worker pools（Cloud Run worker pools）

暗黙的な環境変数

Cloud Run では、コンテナに対していくつかの環境変数が自動的に設定されます。

たとえば Cloud Run services では、K_REVISION 環境変数に実行中のリビジョンの名前が格納されています。また Cloud Run jobs では CLOUD_RUN_TASK_INDEX 環境変数に並列実行されるタスクのインデックスが格納されています。

その他、暗黙的に設定される環境変数のリストについては、以下のドキュメントを参照してください。

Dockerfile と重複して定義した場合

前述したように、Cloud Run で設定できる環境変数は、Dockerfile の ENV で設定した環境変数と同様の方法でアクセスできますが、もし Cloud Run 側の設定項目と Dockerfile の ENV で同じキーを持つ環境変数を設定した場合、Cloud Run 側の設定項目の値が優先されます。

Dockerfile 側ではコンテナから使用する環境変数のデフォルト値を設定し、Cloud Run 側の設定で必要に応じて上書きするといった使い方ができます。

環境変数の設定方法

コンソール

デプロイ方法を問わず、Cloud Run では作成時および更新時に環境変数を設定することができます。

コンソールの場合、コンテナの設定項目として「変数とシークレット」があるため、ここで環境変数の Key/Value を設定します。

gcloud CLI

--set-env-vars オプション

gcloud CLI では、gcloud run deploy コマンドや gcloud run services update コマンドなどで --set-env-vars オプションを使用することで環境変数を設定することができます。

# gcloud CLI で環境変数を設定する
$ gcloud run deploy <サービス名> --image <コンテナイメージ> \
  --set-env-vars key1=value1,key2=value2  # 複数設定する場合は,（カンマ）で区切る
  
# サービスの更新時に設定する場合
$ gcloud run services update <サービス名> \
  --set-env-vars key1=value1,key2=value2

--set-env-vars オプションは、指定した環境変数のリストで現在 Cloud Run に設定されている環境変数を上書きします。したがって、Cloud Run を更新するときに、現在設定されている環境変数に加えて新たな別の環境変数を設定したい場合、--set-env-vars オプションには「現在設定されている環境変数」と「新たに設定する環境変数」を合わせたリストを渡す必要があります。

たとえば、環境変数として既に key1=value1 が設定されている Cloud Run に対して新たに key2=value2 の環境変数を追加したい場合、--set-env-vars key2=value2 ではなく --set-env-vars key1=value1,key2=value2 と記述します。

また、環境変数を複数設定するときは key=value を ,（カンマ）区切りに記述しますが、もし , を環境変数の値として使用したい場合は、以下の例のように @ などの別の文字を区切り文字として使用することができます。

# 値に,（カンマ）を含む環境変数を設定する
$ gcloud run deploy <サービス名> --image <コンテナイメージ> \
  --set-env-vars "^@^key1=value1,value11,value111@key2=value2,value22,value222"
  
$ gcloud run deploy <サービス名> --image <コンテナイメージ> \
  --set-env-vars "^:^key1=value1,value11,value111:key2=value2,value22,value222"
  
$ gcloud run deploy <サービス名> --image <コンテナイメージ> \
  --set-env-vars "^--^key1=value1,value11,value111--key2=value2,value22,value222"

--update-env-vars

環境変数は、前述の --set-env-vars オプションの他に --update-env-vars を利用して設定することもできます。

--update-env-vars オプションでは、追加・変更したい環境変数のみを指定することができるため、あとから環境変数を追加するケースではこちらを使用したほうが安全でしょう。

$ gcloud run services update dotenv \
  --update-env-vars key1=value100  # 追加・変更したい環境変数だけ指定できる

参考 : Configure environment variables for services - Update environment variables

--env-vars-file オプション

Cloud Run のデプロイ時にローカルにある .env ファイルの内容を環境変数として設定することもできます。この設定方法は、2025年8月現在、Preview 公開です。

$ gcloud beta run deploy <サービス名> --image=<コンテナイメージ> \
  --env-vars-file=<.envファイルのパス>  # .env のあるパスを指定する

.env ファイルは以下のような key=value の形式で記述します。

key1=value1
key2=value2

参考 : Configure environment variables for services - Set multiple environment variables using the .env file

環境変数の削除

環境変数の削除には、--remove-env-vars オプションと --clear-env-vars オプションが利用できます。

--remove-env-vars オプションでは、指定したキーの環境変数を削除します。

# 指定した環境変数のみ削除する（カンマ区切りで複数指定も可能）
$ gcloud run services update <サービス名> \
  --remove-env-vars key1

--clear-env-vars オプションでは、設定されている全ての環境変数を削除します。

# 全ての環境変数を削除する
$ gcloud run services update <サービス名> \
  --clear-env-vars

参考 : Configure environment variables for services - Delete environment variables

YAML ファイル

YAML ファイルを使用して Cloud Run をデプロイする場合、以下のように spec.template.spec.containers の env 属性として環境変数を設定します。

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: <サービス名>
spec:
  template:
    spec:
      containers:
      - image: <コンテナイメージ>
        env:
        - name: key1
          value: value1
        - name: key2
          value: value2

Terraform

Terraform で環境変数を設定する場合は以下のような記述となります。

# Cloud Run services の場合
resource "google_cloud_run_v2_service" "this" {
  
  project  = var.project_id
  name     = var.name
  location = var.location
  
  template {
    containers {
      image = var.image
  
      # 環境変数を設定する
      env {
        name  = "key1"
        value = "value1"
      }
      env {
        name  = "key2"
        value = "value2"
      }
    }
  }
  deletion_protection = var.deletion_protection
}

上記の場合、環境変数1つにつき template.containers.env を1つ記述する必要があるため、環境変数を多数設定する必要がある場合、Terraform の記述が冗長になってしまいます。

実際には、以下のように dynamic ブロックと for_each を併用するなどして、変数として渡された環境変数の数だけブロック動的に生成するとよいでしょう、

# Cloud Run services の場合
resource "google_cloud_run_v2_service" "this" {
  
  project  = var.project_id
  name     = var.name
  location = var.location
  
  template {
    containers {
      image = var.image
  
      # key/valueが変数として渡されている場合、渡された数だけ繰り返し設定する
      # 渡されていない場合は何も設定しない
      dynamic "env" {
        for_each = coalesce(var.env_vars, {})
        content {
          name  = env.key
          value = env.value
        }
      }
    }
  }
  deletion_protection = var.deletion_protection
}

上記のように記述した場合、variables.tf に定義する変数は以下のように記述します。

# variable.tf（抜粋）
variable "env_vars" {
  type        = map(string)
  default     = {}
}

シークレットのマウント

Cloud Run では、Secret Manager に格納した機密情報（シークレット）をマウントすることで、環境変数と同様の方法でシークレットの値にアクセスすることができます。

参考 : サービスのシークレットを構成する（Cloud Run services）
参考 : ジョブのシークレットを構成する（Cloud Run jobs）

詳細は以下の記事を参考にしてください。

blog.g-gen.co.jp