환경 변수 구성

Cloud Run 함수와 함께 임의의 키-값 쌍을 배포할 수 있습니다. 이러한 쌍은 함수에 런타임에서 코드로 액세스할 수 있는 리터럴 환경 변수 또는 Google Cloud 빌드팩의 구성 정보로 제공됩니다.

환경 변수는 단일 함수에 바인딩되며 Google Cloud 프로젝트의 다른 함수에는 표시되지 않습니다. 각 변수는 Cloud Run Functions 백엔드에 저장되고 변수가 바인딩된 함수와 같은 수명 주기 내에 존재합니다.

Google Cloud CLI 또는 Google Cloud 콘솔을 사용하여 런타임 환경 변수를 추가하거나 삭제할 수 있습니다.

런타임 환경 변수 설정

이러한 메서드를 사용하여 새 변수를 설정하거나 기존 변수를 완전히 대체할 수 있습니다. 추가 변경을 수행하려면 다음 섹션에 설명된 업데이트 프로세스를 사용합니다.

gcloud

Google Cloud CLI를 사용하여 런타임 환경 변수를 설정하려면 배포할 때 --set-env-vars 플래그를 사용합니다.

gcloud functions deploy FUNCTION_NAME --set-env-vars FOO=bar FLAGS ...

쉼표로 구분된 목록을 사용하여 여러 런타임 환경 변수를 설정할 수도 있습니다.

gcloud functions deploy FUNCTION_NAME --set-env-vars FOO=bar,BAZ=boo FLAGS...

구성 내용을 파일(예: 소스 제어 아래)에 저장하려면 YAML 파일을 --env-vars-file 플래그와 함께 사용하면 됩니다.

gcloud functions deploy FUNCTION_NAME --env-vars-file .env.yaml FLAGS...

.env.yaml 파일의 내용은 다음과 같습니다.

 FOO: bar
 BAZ: boo

위의 예시에서 FLAGS...는 함수 배포 중에 전달하는 다른 옵션을 나타냅니다. deploy 명령어의 전체 참조는 gcloud functions deploy를 확인하세요.

Google Cloud 콘솔 UI

Google Cloud 콘솔에서 함수를 생성하는 동안 런타임 환경 변수를 설정할 수 있습니다.

1. Google Cloud 콘솔에서 함수 개요 페이지를 엽니다.

   Cloud Run Functions 개요 페이지로 이동

2. 함수 만들기를 클릭합니다.

3. 함수의 필수 필드를 작성합니다.

4. 런타임, 빌드 및 연결 설정 섹션을 엽니다.

5. 런타임 탭을 선택합니다.

6. 런타임 환경 변수 섹션에서 변수 추가를 클릭하고 이름과 값을 추가합니다.

   기존 함수에 대해 환경 변수를 추가하는 방법에 대한 안내는 런타임 환경 변수 업데이트를 참조하세요.

런타임 환경 변수 업데이트

기존 함수의 런타임 환경 변수를 업데이트할 수도 있습니다. 이는 비파괴적인 접근 방식으로, 런타임 환경 변수를 변경 및 추가하지만 삭제하지는 않습니다.

gcloud

Google Cloud CLI를 사용하여 변수를 업데이트하려면 배포 시 --update-env-vars 플래그를 사용하세요.

gcloud functions deploy FUNCTION_NAME --update-env-vars FOO=bar

쉼표로 구분된 목록을 사용하여 여러 런타임 환경 변수를 업데이트할 수도 있습니다.

gcloud functions deploy FUNCTION_NAME --update-env-vars FOO=bar,BAZ=boo

Google Cloud 콘솔 UI

Google Cloud 콘솔을 사용하여 런타임 환경 변수를 업데이트하려면 다음 안내를 따르세요.

1. Google Cloud 콘솔에서 함수 개요 페이지를 엽니다.

   Cloud Run Functions 개요 페이지로 이동

2. 기존 함수를 클릭하여 세부정보 페이지로 이동합니다.

3. 수정을 클릭합니다.

4. 런타임, 빌드 및 연결 설정 섹션을 엽니다.

5. 런타임 탭을 선택합니다.

6. 런타임 환경 변수 섹션에서 수정합니다.

런타임 환경 변수 삭제

gcloud

런타임 환경 변수를 선택적으로 삭제하려면 배포 시 --remove-env-vars 플래그를 사용하면 됩니다.

gcloud functions deploy FUNCTION_NAME --remove-env-vars FOO,BAZ

또는 --clear-env-vars 플래그를 사용하여 이전에 설정된 모든 런타임 환경 변수를 삭제할 수 있습니다.

gcloud functions deploy FUNCTION_NAME --clear-env-vars

Google Cloud 콘솔 UI

Google Cloud 콘솔을 사용하여 런타임 환경 변수를 삭제하려면 다음 안내를 따르세요.

1. Google Cloud 콘솔에서 함수 개요 페이지를 엽니다.

   Cloud Run Functions 개요 페이지로 이동

2. 기존 함수를 클릭하여 세부정보 페이지로 이동합니다.

3. 수정을 클릭합니다.

4. 런타임, 빌드 및 연결 설정 섹션을 엽니다.

5. 런타임 탭을 선택합니다.

6. 런타임 환경 변수 섹션에서 키-값 쌍 옆에 있는 휴지통 아이콘을 클릭하여 삭제합니다.

자동으로 설정된 런타임 환경 변수

이 섹션에는 자동으로 설정되는 런타임 환경 변수가 나열됩니다.

키	설명
FUNCTION_TARGET	예약됨: 실행할 함수
FUNCTION_SIGNATURE_TYPE	예약됨: 함수의 유형(HTTP 함수의 경우 http, 이벤트 기반 함수의 경우 event)
K_SERVICE	예약됨: 함수 리소스 이름
K_REVISION	예약됨: 함수의 버전 식별자
PORT	예약됨: 함수가 호출되는 포트

참고: 함수에 이전 런타임의 환경 변수 중 하나가 필요한 경우 함수를 배포할 때 해당 변수를 설정할 수 있습니다. 예를 들면 다음과 같습니다.

gcloud functions deploy envVarMemory \
--runtime nodejs10 \
--set-env-vars FUNCTION_MEMORY_MB=2Gi \
--memory 2Gi \
--trigger-http

런타임 환경 변수 설정 및 검색: 예시

런타임 환경 변수를 설정합니다.

Node.js

gcloud functions deploy envVar \
--runtime nodejs20 \
--set-env-vars FOO=bar \
--trigger-http

--runtime 플래그를 사용하여 함수를 실행할 지원되는 Node.js 버전의 런타임 ID를 지정합니다.

Python

gcloud functions deploy env_vars \
--runtime python312 \
--set-env-vars FOO=bar \
--trigger-http

--runtime 플래그를 사용하여 함수를 실행할 지원되는 Python 버전의 런타임 ID를 지정합니다.

Go

gcloud functions deploy EnvVar \
--runtime go121 \
--set-env-vars FOO=bar \
--trigger-http

--runtime 플래그를 사용하여 함수를 실행할 지원되는 Go 버전의 런타임 ID를 지정합니다.

자바

gcloud functions deploy java-envVar-function \
--entry-point functions.EnvVars \
--runtime java17 \
--memory 512MB \
--set-env-vars FOO=bar \
--trigger-http

--runtime 플래그를 사용하여 함수를 실행할 지원되는 Java 버전의 런타임 ID를 지정합니다.

C#

gcloud functions deploy csharp-envVar-function \
--entry-point EnvironmentVariables.Function \
--runtime dotnet6 \
--set-env-vars FOO=bar \
--trigger-http

--runtime 플래그를 사용하여 함수를 실행할 지원되는 .NET 버전의 런타임 ID를 지정합니다.

Ruby

gcloud functions deploy env_vars --runtime ruby32 \
--set-env-vars FOO=bar \
--trigger-http

--runtime 플래그를 사용하여 함수를 실행할 지원되는 Ruby 버전의 런타임 ID를 지정합니다.

PHP

 gcloud functions deploy envVar --runtime php82 \
--set-env-vars FOO=bar \
--trigger-http

--runtime 플래그를 사용하여 함수를 실행할 지원되는 PHP 버전의 런타임 ID를 지정합니다.

런타임에서 프로그래매틱 방식으로 변수에 액세스합니다.

Node.js

Node.js에서 process.env 속성을 사용하여 런타임 환경 변수에 액세스합니다.

exports.envVar = (req, res) => {
  // Sends 'bar' as response
  res.send(process.env.FOO);
};

Python

Python에서 os.environ을 사용하여 런타임 환경 변수에 액세스합니다.

import os


def env_vars(request):
    return os.environ.get("FOO", "Specified environment variable is not set.")

Go

Go에서 os.Getenv()를 사용하여 런타임 환경 변수에 액세스합니다.

// Package tips contains tips for writing Cloud Functions in Go.
package tips

import (
	"fmt"
	"net/http"
	"os"
)

// EnvVar is an example of getting an environment variable in a Go function.
func EnvVar(w http.ResponseWriter, r *http.Request) {
	fmt.Fprintf(w, "FOO: %q", os.Getenv("FOO"))
}

자바

자바에서 System.getenv를 사용하여 런타임 환경 변수에 액세스합니다.

import com.google.cloud.functions.HttpFunction;
import com.google.cloud.functions.HttpRequest;
import com.google.cloud.functions.HttpResponse;
import java.io.BufferedWriter;
import java.io.IOException;

public class EnvVars implements HttpFunction {

  // Returns the environment variable "foo" set during function deployment.
  @Override
  public void service(HttpRequest request, HttpResponse response)
      throws IOException {
    BufferedWriter writer = response.getWriter();
    String foo = System.getenv("FOO");
    if (foo == null) {
      foo = "Specified environment variable is not set.";
    }
    writer.write(foo);
  }
}

C#

런타임에서 C#의 Environment.GetEnvironmentVariable을 사용하여 환경 변수에 액세스합니다.

using Google.Cloud.Functions.Framework;
using Microsoft.AspNetCore.Http;
using System;
using System.Threading.Tasks;

namespace EnvironmentVariables;

public class Function : IHttpFunction
{
    public async Task HandleAsync(HttpContext context)
    {
        string foo = Environment.GetEnvironmentVariable("FOO")
            ?? "Specified environment variable is not set.";
        await context.Response.WriteAsync(foo, context.RequestAborted);
    }
}

Ruby

런타임에서 Ruby의 ENV을 사용하여 환경 변수에 액세스합니다.

require "functions_framework"

FunctionsFramework.http "env_vars" do |_request|
  ENV["FOO"] || "Specified environment variable is not set."
end

PHP

런타임 시 PHP의 getenv 함수를 사용하여 환경 변수에 액세스할 수 있습니다.

use Psr\Http\Message\ServerRequestInterface;

function envVar(ServerRequestInterface $request): string
{
    return getenv('FOO') . PHP_EOL;
}

빌드 환경 변수 사용

빌드팩을 지원하는 런타임용 빌드 환경 변수를 설정할 수도 있습니다.

빌드 환경 변수는 함수와 함께 배포되는 키-값 쌍으로서, 이를 통해 구성 정보를 빌드팩에 전달할 수 있습니다. 예를 들어 컴파일러 옵션을 맞춤설정할 수 있습니다. Google Cloud CLI 또는 Google Cloud 콘솔 UI를 사용하여 이러한 빌드 환경 변수를 추가하거나 삭제할 수 있습니다.

참고: 키는 대문자 ASCII 문자로 시작해야 하며 대문자 ASCII 문자, 숫자, 밑줄로 구성되어야 합니다. GOOGLE_* 프리픽스를 사용하여 변수 키를 만들지 않아야 합니다. 지원되는 모든 빌드팩 환경 변수는 여기서 확인하세요.

빌드 환경 변수 설정

이러한 메서드를 사용하여 새 변수를 설정하거나 기존 변수를 완전히 대체할 수 있습니다. 추가 변경을 수행하려면 다음 섹션에 설명된 업데이트 프로세스(gcloud의 --update-build-env-vars 플래그)를 사용합니다.

gcloud

Google Cloud CLI를 사용하여 변수를 설정하려면 배포할 때 --set-build-env-vars 플래그를 사용합니다.

gcloud beta functions deploy FUNCTION_NAME --set-build-env-vars FOO=bar FLAGS...

쉼표로 구분된 목록을 사용하여 여러 빌드 환경 변수를 설정할 수도 있습니다.

gcloud functions deploy FUNCTION_NAME --set-build-env-vars FOO=bar,BAZ=boo FLAGS...

구성 내용을 파일(예: 소스 제어 아래)에 저장하려면 YAML 파일을 --build-env-vars-file 플래그와 함께 사용하면 됩니다.

gcloud functions deploy FUNCTION_NAME --build-env-vars-file FILE_NAME.yaml FLAGS...

*.yaml 파일의 내용은 다음과 같습니다.

 FOO: bar
 BAZ: boo

위의 예시에서 FLAGS...는 함수 배포 중에 전달하는 다른 옵션을 나타냅니다. deploy 명령어의 전체 참조는 gcloud beta functions deploy를 확인하세요.

Google Cloud 콘솔 UI

Google Cloud 콘솔에서 함수를 생성하는 동안 빌드 환경 변수를 설정할 수도 있습니다.

1. Google Cloud 콘솔에서 함수 개요 페이지를 엽니다.

   Cloud Run Functions 개요 페이지로 이동

2. 함수 만들기를 클릭합니다.

3. 함수의 필수 필드를 작성합니다.

4. 런타임, 빌드 및 연결 설정 섹션을 엽니다.

5. 빌드 탭을 선택합니다.

6. 빌드 환경 변수 섹션에서 변수 추가를 클릭하고 이름과 값을 추가합니다.

빌드 환경 변수 업데이트

기존 함수의 빌드 환경 변수를 업데이트할 수도 있습니다. 이는 비파괴적인 접근 방식으로, 빌드 환경 변수를 변경 및 추가하지만 삭제하지는 않습니다.

gcloud

Google Cloud CLI를 사용하여 변수를 설정하려면 배포할 때 --update-build-env-vars 플래그를 사용합니다.

gcloud functions deploy FUNCTION_NAME --update-build-env-vars FOO=bar

쉼표로 구분된 목록을 사용하여 여러 빌드 환경 변수를 업데이트할 수도 있습니다.

gcloud functions deploy FUNCTION_NAME --update-build-env-vars FOO=bar,BAZ=boo

Google Cloud 콘솔 UI

Google Cloud 콘솔을 사용하여 빌드 환경 변수를 업데이트하려면 다음 안내를 따르세요.

1. Google Cloud 콘솔에서 함수 개요 페이지를 엽니다.

   Cloud Run Functions 개요 페이지로 이동

2. 기존 함수를 클릭하여 세부정보 페이지로 이동합니다.

3. 수정을 클릭합니다.

4. 런타임, 빌드 및 연결 설정 섹션을 엽니다.

5. 빌드 탭을 선택합니다.

6. 빌드 환경 변수 섹션에서 수정합니다.

빌드 환경 변수 삭제

gcloud

빌드 환경 변수를 선택적으로 삭제하려면 배포 시 --remove-build-env-vars 플래그를 사용하면 됩니다.

gcloud functions deploy FUNCTION_NAME --remove-build-env-vars FOO,BAZ

또는 --clear-build-env-vars 플래그를 사용하여 이전에 설정된 모든 빌드 환경 변수를 삭제할 수 있습니다.

gcloud functions deploy FUNCTION_NAME --clear-build-env-vars

Google Cloud 콘솔 UI

Google Cloud 콘솔을 사용하여 빌드 환경 변수를 삭제하려면 다음 안내를 따르세요.

1. Google Cloud 콘솔에서 함수 개요 페이지를 엽니다.

   Cloud Run Functions 개요 페이지로 이동

2. 기존 함수를 클릭하여 세부정보 페이지로 이동합니다.

3. 수정을 클릭합니다.

4. 런타임, 빌드 및 연결 설정 섹션을 엽니다.

5. 빌드 탭을 선택합니다.

6. 빌드 환경 변수 섹션에서 키-값 쌍 옆에 있는 휴지통 아이콘을 클릭하여 삭제합니다.

변수 수명 주기

모든 환경 변수는 Cloud Run 함수의 배포에 결합되며 배포를 통해서만 설정 또는 변경될 수 있습니다. 만약 어떠한 이유로 배포에 실패하면 환경 변수에 대한 변경사항이 적용되지 않습니다. 따라서 환경 변수를 변경하려면 배포에 성공해야 합니다.

권장사항 및 예약된 환경 변수

일부 추가 환경 변수는 함수가 사용하는 런타임에 따라 자동으로 설정됩니다. 이는 런타임 운영체제(예: DEBIAN_FRONTEND, SHLVL 또는 PATH) 및 언어 런타임(예: NODE_ENV, VIRTUAL_ENV 또는 GOPATH)을 기반으로 합니다.

환경에서 제공된 환경 변수(환경 변수 자동 설정에 나열된 변수 이외)는 나중에 런타임 버전에서 변경될 수 있습니다. 명시적으로 설정하지 않은 환경 변수를 사용하거나 수정하지 않는 것이 좋습니다.

환경에서 제공하는 환경 변수를 수정하면 예기치 않은 결과가 발생할 수 있습니다. 이러한 환경 변수를 수정하려는 시도는 차단되거나 더욱이 시작할 수 없는 함수와 같은 의도하지 않은 결과를 초래할 수 있습니다. 모든 환경 변수에 고유 키를 사용하여 프리픽스로 지정하여 충돌을 피하는 것이 좋습니다.

마지막으로 다음 환경 변수는 사용할 수 없습니다.

키	설명
비어 있음('')	키는 빈 문자열일 수 없습니다.
=	키에는 '=' 문자가 포함될 수 없습니다.
X_GOOGLE_	키에는 프리픽스 X_GOOGLE_이 포함될 수 없습니다.

참고: 실행 환경에 표시되지만 위 표에 설명되지 않은 환경 변수는 지원 중단된 것으로 간주되어야 하며 사전 통지 없이 언제든지 사라질 수 있습니다.

크기 제한

환경 변수 이름이 사용하는 총 바이트 수와 개별 함수 값은 32KiB로 제한됩니다. 그러나 이 전체 용량을 초과하지 않는 한 개별 키나 값에는 구체적인 한도가 적용되지 않습니다.

빌드 환경 변수의 경우 최대 100개의 변수를 정의할 수 있으며 정의 문자열 foo=bar는 64KiB로 제한됩니다.

비밀번호 관리

환경 변수는 함수 구성에 사용될 수 있지만 데이터베이스 사용자 인증 정보 또는 API 키처럼 비밀번호를 저장하는 방법으로 사용하는 것은 좋지 않습니다. 이와 같이 더 민감한 값은 소스 코드 및 환경 변수 외부에 저장해야 합니다. 일부 실행 환경 또는 일부 프레임워크를 사용하면 환경 변수의 내용이 로그로 전송될 수 있으며 민감한 사용자 인증 정보는 YAML 파일, 배포 스크립트 또는 소스 제어에 저장하지 않는 것이 좋습니다.

보안 비밀을 저장하려면 Secret Manager를 사용하는 것이 좋습니다. Secret Manager에 저장된 보안 비밀에 접근하도록 Cloud Run Functions를 구성하려면 보안 비밀 구성을 참조하세요. Cloud KMS와의 Cloud Run Functions별 통합은 없습니다.

이동성

현재 Cloud Run 함수에서 작동하는 환경 변수는 다른 런타임 환경(다른 언어) 또는 특정 도구나 라이브러리에서 작동하지 않을 수 있으며 다른 플랫폼에 의해 거부될 수 있습니다.

환경 변수에 관한 POSIX 표준을 따르면 이러한 문제를 피할 수 있습니다. Google Cloud 콘솔을 사용하여 변수를 수정하는 경우 이동성 문제를 일으킬 수 있는 변수를 정의할 때마다 Google Cloud 콘솔에서 경고를 표시하지만 배포를 막지는 않습니다. 일반적으로 이동식 문자 집합에 정의된 대로 대문자, 숫자, <underscore>(_)만으로 환경 변수 키를 구성하는 것이 좋으며 숫자로 시작하지 않는 것이 좋습니다.