Lambda 환경 변수 사용하기

Lambda 환경 변수 사용하기

환경 변수를 사용해서 코드를 업데이트하지 않고 함수의 동작을 조정할 수 있어요. 환경 변수는 함수의 버전별 구성에 저장되는 문자열 쌍이에요. Lambda 런타임은 환경 변수를 코드에서 사용할 수 있게 만들고, 함수와 호출 요청에 대한 정보를 담은 추가 환경 변수도 설정해요.

참고(Note) 보안을 강화하려면 데이터베이스 자격 증명과 API 키·인증 토큰 같은 민감한 정보를 환경 변수 대신 AWS Secrets Manager에 저장하는 것을 권장해요. 자세한 내용은 Lambda 함수에서 Secrets Manager 시크릿 사용을 참고하세요.

환경 변수는 함수 호출 전에 평가되지 않아요. 정의하는 모든 값은 리터럴 문자열로 간주되며 확장되지 않아요. 변수 평가는 함수 코드에서 수행하세요.

출처: AWS Lambda 개발자 안내서

본문

Lambda 환경 변수 만들기

Lambda 콘솔, AWS Command Line Interface(AWS CLI), AWS Serverless Application Model(AWS SAM) 또는 AWS SDK를 사용해서 Lambda에서 환경 변수를 구성할 수 있어요.

콘솔(Console)

환경 변수는 함수의 미게시 버전에서 정의해요. 버전을 게시하면 환경 변수는 다른 버전별 구성 설정과 함께 해당 버전에 잠겨요.

키와 값을 정의해서 함수에 대한 환경 변수를 만들어요. 함수는 키의 이름을 사용해서 환경 변수의 값을 검색해요.

Lambda 콘솔에서 환경 변수를 설정하려면

  1. Lambda 콘솔의 Functions 페이지를 열어요.

  2. 함수를 선택해요.

  3. Configuration 탭을 선택한 다음 Environment variables를 선택해요.

  4. Environment variables에서 Edit을 선택해요.

  5. Add environment variable을 선택해요.

  6. 키와 값을 입력해요.

요구 사항(Requirements)

  • 키는 문자로 시작하고 최소 두 글자여야 해요.
  • 키는 문자, 숫자, 밑줄 문자(_)만 포함해야 해요.
  • 키는 Lambda가 예약한 것이 아니어야 해요.
  • 모든 환경 변수의 총 크기는 4KB를 초과하지 않아야 해요.
  1. Save를 선택해요.

콘솔 코드 편집기에서 환경 변수 목록을 생성하려면

Lambda 코드 편집기에서 환경 변수 목록을 생성할 수 있어요. 코드를 작성하면서 환경 변수를 빠르게 참조하는 방법이에요.

  1. Code 탭을 선택해요.

  2. 코드 편집기의 ENVIRONMENT VARIABLES 섹션까지 아래로 스크롤해요. 기존 환경 변수가 여기에 나열돼요.

  3. 새 환경 변수를 만들려면 더하기 기호(+)를 선택해요.

환경 변수는 콘솔 코드 편집기에 나열될 때 암호화된 상태로 유지돼요. 전송 중 암호화용 암호화 헬퍼를 활성화했다면 해당 설정은 변경되지 않은 상태로 유지돼요. 자세한 내용은 Lambda 환경 변수 보안을 참고하세요.

환경 변수 목록은 읽기 전용이며 Lambda 콘솔에서만 사용할 수 있어요. 이 파일은 함수의 .zip 파일 아카이브를 다운로드할 때 포함되지 않으며, 이 파일을 업로드해서 환경 변수를 추가할 수 없어요.

AWS CLI

다음 예시는 my-function이라는 함수에 두 개의 환경 변수를 설정해요.

aws lambda update-function-configuration \
  --function-name {{my-function}} \
  --environment {{"Variables={BUCKET=amzn-s3-demo-bucket,KEY=file.txt}"}}

update-function-configuration 명령으로 환경 변수를 적용하면 Variables 구조의 전체 내용이 대체돼요. 새 변수를 추가할 때 기존 환경 변수를 유지하려면 요청에 모든 기존 값을 포함하세요.

현재 구성을 가져오려면 get-function-configuration 명령을 사용해요.

aws lambda get-function-configuration \
  --function-name {{my-function}}

다음과 같은 출력이 표시되어야 해요.

{
    "FunctionName": "my-function",
    "FunctionArn": "arn:aws:lambda:us-east-2:111122223333:function:my-function",
    "Runtime": "nodejs24.x",
    "Role": "arn:aws:iam::111122223333:role/lambda-role",
    "Environment": {
        "Variables": {
            "BUCKET": "amzn-s3-demo-bucket",
            "KEY": "file.txt"
        }
    },
    "RevisionId": "0894d3c1-2a3d-4d48-bf7f-abade99f3c15",
    ...
}

get-function-configuration 출력의 리비전 ID를 update-function-configuration의 파라미터로 전달할 수 있어요. 이렇게 하면 구성을 읽을 때와 업데이트할 때 사이에 값이 변경되지 않도록 보장해요.

함수의 암호화 키를 구성하려면 KMSKeyARN 옵션을 설정해요.

aws lambda update-function-configuration \
  --function-name {{my-function}} \
  --kms-key-arn {{arn:aws:kms:us-east-2:111122223333:key/055efbb4-xmpl-4336-ba9c-538c7d31f599}}

AWS SAM

AWS Serverless Application Model을 사용해서 함수의 환경 변수를 구성할 수 있어요. template.yaml 파일에서 Environment와 Variables 속성을 업데이트한 다음 sam deploy를 실행해요.

예시 template.yaml

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: An AWS Serverless Application Model template describing your function.
Resources:
  {{my-function}}:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: .
      Description: ''
      MemorySize: 128
      Timeout: 120
      Handler: index.handler
      Runtime: nodejs24.x
      Architectures:
        - x86_64
      EphemeralStorage:
        Size: 10240
      Environment:
        Variables:
          {{BUCKET: amzn-s3-demo-bucket}}
          {{KEY: file.txt}}
      # Other function properties...

AWS SDKs

AWS SDK를 사용해서 환경 변수를 관리하려면 다음 API 작업을 사용해요.

자세한 내용은 선호하는 프로그래밍 언어의 AWS SDK 문서를 참고하세요.

환경 변수 사용 시나리오 예시

환경 변수를 사용해서 테스트 환경과 프로덕션 환경에서 함수 동작을 사용자 지정할 수 있어요. 예를 들어 동일한 코드지만 구성이 다른 두 함수를 만들 수 있어요. 한 함수는 테스트 데이터베이스에 연결하고 다른 함수는 프로덕션 데이터베이스에 연결해요. 이 상황에서 환경 변수를 사용해서 데이터베이스의 호스트 이름과 기타 연결 정보를 함수에 전달해요.

다음 예시는 데이터베이스 호스트와 데이터베이스 이름을 환경 변수로 정의하는 방법을 보여줘요.

테스트 환경이 프로덕션 환경보다 더 많은 디버그 정보를 생성하도록 하려면 테스트 환경이 더 자세한 로깅이나 더 상세한 트레이싱을 사용하도록 환경 변수를 설정할 수 있어요.

예를 들어 테스트 환경에서 키 LOG_LEVEL과 debug 또는 trace 로그 수준을 나타내는 값을 가진 환경 변수를 설정할 수 있어요. 그런 다음 Lambda 함수 코드에서 이 환경 변수를 사용해서 로그 수준을 설정할 수 있어요.

다음 Python과 Node.js 코드 예시는 이를 달성하는 방법을 보여줘요. 이 예시는 환경 변수가 Python에서는 DEBUG, Node.js에서는 debug 값을 가진다고 가정해요.

Python

로그 수준을 설정하는 예시 Python 코드

import os
import logging

# Initialize the logger
logger = logging.getLogger()

# Get the log level from the environment variable and default to INFO if not set
log_level = os.environ.get('LOG_LEVEL', 'INFO')

# Set the log level
logger.setLevel(log_level)

def lambda_handler(event, context):
    # Produce some example log outputs
    logger.debug('This is a log with detailed debug information - shown only in test environment')
    logger.info('This is a log with standard information - shown in production and test environments')

Node.js(ES 모듈 형식)

로그 수준을 설정하는 예시 Node.js 코드 이 예시는 winston 로깅 라이브러리를 사용해요. npm을 사용해서 이 라이브러리를 함수의 배포 패키지에 추가하세요. 자세한 내용은 종속성이 있는 .zip 배포 패키지 만들기를 참고하세요.

import winston from 'winston';

// Initialize the logger using the log level from environment variables, defaulting to INFO if not set
const logger = winston.createLogger({
   level: process.env.LOG_LEVEL || 'info',
   format: winston.format.json(),
   transports: [new winston.transports.Console()]
});

export const handler = async (event) => {
   // Produce some example log outputs
   logger.debug('This is a log with detailed debug information - shown only in test environment');
   logger.info('This is a log with standard information - shown in production and test environment');
   
};

Lambda 환경 변수 검색

함수 코드에서 환경 변수를 검색하려면 프로그래밍 언어의 표준 방법을 사용해요.

Node.js

let region = process.env.AWS_REGION

Python

import os
  region = os.environ['AWS_REGION']

참고(Note) 경우에 따라 다음 형식을 사용해야 할 수도 있어요.

region = os.environ.get('AWS_REGION')

Ruby

region = ENV["AWS_REGION"]

Java

String region = System.getenv("AWS_REGION");

Go

var region = os.Getenv("AWS_REGION")

C#

string region = Environment.GetEnvironmentVariable("AWS_REGION");

PowerShell

$region = $env:AWS_REGION

Lambda는 환경 변수를 저장 시 암호화해서 안전하게 보관해요. Lambda가 다른 암호화 키를 사용하도록 구성하거나, 클라이언트 측에서 환경 변수 값을 암호화하거나, AWS Secrets Manager로 CloudFormation 템플릿에 환경 변수를 설정할 수 있어요.

정의된 런타임 환경 변수

Lambda 런타임은 초기화 중에 여러 환경 변수를 설정해요. 대부분의 환경 변수는 함수나 런타임에 대한 정보를 제공해요. 이러한 환경 변수의 키는 *예약(reserved)*되어 있으며 함수 구성에서 설정할 수 없어요.

예약 환경 변수(Reserved environment variables)

  • _HANDLER – 함수에 구성된 핸들러 위치예요.
  • _X_AMZN_TRACE_ID – X-Ray 트레이싱 헤더예요. 이 환경 변수는 호출할 때마다 변경돼요.
    • 이 환경 변수는 OS 전용 런타임(provided 런타임 계열)에는 정의되지 않아요. Next invocation의 Lambda-Runtime-Trace-Id 응답 헤더를 사용해서 사용자 지정 런타임에 _X_AMZN_TRACE_ID를 설정할 수 있어요.
    • Java 런타임 버전 17 이상에서는 이 환경 변수가 사용되지 않아요. 대신 Lambda는 트레이싱 정보를 com.amazonaws.xray.traceHeader 시스템 속성에 저장해요.
  • AWS_DEFAULT_REGION – Lambda 함수가 실행되는 기본 AWS 리전이에요.
  • AWS_REGION – Lambda 함수가 실행되는 AWS 리전이에요. 정의된 경우 이 값이 AWS_DEFAULT_REGION을 재정의해요.
    • AWS SDK와 함께 AWS 리전 환경 변수를 사용하는 방법에 대한 자세한 내용은 AWS SDKs and Tools 참조 안내서의 AWS 리전을 참고하세요.
  • AWS_EXECUTION_ENV – AWS_Lambda_가 접두사로 붙은 런타임 식별자(예: AWS_Lambda_java8)예요. 이 환경 변수는 OS 전용 런타임(provided 런타임 계열)에는 정의되지 않아요.
  • AWS_LAMBDA_FUNCTION_NAME – 함수의 이름이에요.
  • AWS_LAMBDA_FUNCTION_MEMORY_SIZE – 함수에 사용 가능한 메모리(MB)예요.
  • AWS_LAMBDA_FUNCTION_VERSION – 실행 중인 함수의 버전이에요.
  • AWS_LAMBDA_INITIALIZATION_TYPE – 함수의 초기화 유형으로, on-demand, provisioned-concurrency, snap-start, lambda-managed-instances 중 하나예요. 자세한 내용은 프로비저닝된 동시성 구성, Lambda SnapStart로 시작 성능 개선, Lambda Managed Instances를 참고하세요.
  • AWS_LAMBDA_LOG_GROUP_NAME, AWS_LAMBDA_LOG_STREAM_NAME – 함수의 Amazon CloudWatch Logs 그룹과 스트림의 이름이에요. AWS_LAMBDA_LOG_GROUP_NAME과 AWS_LAMBDA_LOG_STREAM_NAME 환경 변수는 Lambda SnapStart 함수에서는 사용할 수 없어요.
  • AWS_ACCESS_KEY, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN – 함수의 실행 역할에서 얻은 액세스 키예요.
  • AWS_LAMBDA_RUNTIME_API – (사용자 지정 런타임) 런타임 API의 호스트와 포트예요.
  • LAMBDA_TASK_ROOT – Lambda 함수 코드의 경로예요.
  • LAMBDA_RUNTIME_DIR – 런타임 라이브러리의 경로예요.
  • AWS_LAMBDA_MAX_CONCURRENCY – (Lambda Managed Instances 전용) Lambda가 하나의 실행 환경으로 보낼 동시 호출의 최대 수예요.
  • AWS_LAMBDA_METADATA_API – {ipv4_address}:{port} 형식의 메타데이터 엔드포인트 서버 주소예요(예: 169.254.100.1:9001).
  • AWS_LAMBDA_METADATA_TOKEN – 메타데이터 엔드포인트에 대한 요청을 인증하는 데 사용되는 현재 실행 환경의 고유 인증 토큰이에요. Lambda는 초기화 시 이 토큰을 자동으로 생성해요.

다음 추가 환경 변수는 예약되지 않으며 함수 구성에서 확장할 수 있어요.

비예약 환경 변수(Unreserved environment variables)

  • LANG – 런타임의 로케일(en_US.UTF-8)이에요.
  • PATH – 실행 경로(/usr/local/bin:/usr/bin/:/bin:/opt/bin)예요.
  • LD_LIBRARY_PATH – 시스템 라이브러리 경로(/var/lang/lib:/lib64:/usr/lib64:$LAMBDA_RUNTIME_DIR:$LAMBDA_RUNTIME_DIR/lib:$LAMBDA_TASK_ROOT:$LAMBDA_TASK_ROOT/lib:/opt/lib)예요.
  • NODE_PATH – (Node.js) Node.js 라이브러리 경로(/opt/nodejs/node12/node_modules/:/opt/nodejs/node_modules:$LAMBDA_RUNTIME_DIR/node_modules)예요.
  • NODE_OPTIONS – (Node.js) Node.js 런타임의 경우 NODE_OPTIONS를 사용해서 Lambda가 기본적으로 비활성화하는 실험적 기능을 다시 활성화할 수 있어요.
  • PYTHONPATH – (Python) Python 라이브러리 경로($LAMBDA_RUNTIME_DIR)예요.
  • GEM_PATH – (Ruby) Ruby 라이브러리 경로($LAMBDA_TASK_ROOT/vendor/bundle/ruby/3.3.0:/opt/ruby/gems/3.3.0)예요.
  • AWS_XRAY_CONTEXT_MISSING – X-Ray 트레이싱에 대해 Lambda는 이를 LOG_ERROR로 설정해서 X-Ray SDK의 런타임 오류 발생을 방지해요.
  • AWS_XRAY_DAEMON_ADDRESS – X-Ray 트레이싱의 X-Ray 데몬 IP 주소와 포트예요.
  • AWS_LAMBDA_DOTNET_PREJIT – (.NET) .NET 특정 런타임 최적화를 활성화하거나 비활성화하도록 이 변수를 설정해요. 값에는 always, never, provisioned-concurrency가 있어요. 자세한 내용은 함수의 프로비저닝된 동시성 구성을 참고하세요.
  • TZ – 환경의 시간대(:UTC)예요. 실행 환경은 NTP를 사용해서 시스템 시계를 동기화해요.

표시된 샘플 값은 최신 런타임을 반영해요. 특정 변수의 존재 여부나 값은 이전 런타임에서 달라질 수 있어요.

더 알아보기 (Learn more)

환경 변수 암호화에 대한 자세한 내용은 Lambda 환경 변수 보안을 참고하세요.