Lambda 환경 변수 사용

환경 변수를 사용하면 코드를 업데이트하지 않고도 함수의 동작을 조정할 수 있습니다. 환경 변수는 함수의 버전별 구성에 저장된 문자열 쌍입니다. Lambda 런타임은 코드에 환경 변수를 사용할 수 있게 하고 함수 및 호출 요청에 대한 정보가 포함된 추가 환경 변수를 설정합니다.

참고

데이터베이스 보안을 강화하려면 환경 변수 대신 AWS Secrets Manager을 사용하여 데이터베이스 보안 인증 정보를 저장하는 것이 좋습니다. 자세한 내용은 Amazon RDS와 함께 AWS Lambda 사용 단원을 참조하십시오.

환경 변수는 함수 간접 호출 전에 평가되지 않습니다. 정의한 모든 값은 리터럴 문자열로 간주되며 확장되지 않습니다. 함수 코드에서 변수 평가를 수행합니다.

환경 변수 구성(콘솔)

게시되지 않은 함수 버전에서 환경 변수를 정의합니다. 버전을 게시할 때 환경 변수는 다른 버전별 구성 설정과 함께 해당 버전에 대해 잠금 상태가 됩니다.

키와 값을 정의하여 함수에 환경 변수를 생성합니다. 함수는 키 이름을 사용하여 환경 변수 값을 검색합니다.

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

1. Lambda 콘솔의 함수 페이지를 엽니다.

2. 함수를 선택합니다.

3. 구성을 선택한 후 환경 변수를 선택합니다.

4. Environment variables(환경 변수)에서 편집을 선택합니다.

5. Add environment variable(환경 변수 추가)을 선택합니다.

6. 키와 값을 입력합니다.

   요구 사항

   • 키는 문자로 시작되며 최소 2자입니다.

   • 키에는 문자, 숫자 및 밑줄(_)만 포함됩니다.

   • 키는 Lambda에 의해 예약되지 않습니다.

   • 모든 환경 변수의 총 크기는 4KB를 초과하지 않습니다.

7. Save(저장)를 선택합니다.

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

Lambda 코드 편집기에서 환경 변수 목록을 생성할 수 있습니다. 이는 코딩하는 동안 환경 변수를 빠르게 참조할 수 있는 방법입니다.

1. 코드 탭을 선택합니다.

2. 환경 변수 탭을 선택합니다.

3. 도구, 환경 변수 표시를 선택합니다.

콘솔 코드 편집기에 나열되어 있는 환경 변수는 암호화된 상태로 유지됩니다. 전송 중 암호화에 대해 암호화 도우미를 활성화한 경우 해당 설정은 변경되지 않습니다. 자세한 내용은 환경 변수 보호 단원을 참조하십시오.

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

환경 변수 구성(API)

AWS CLI 또는 AWS SDK를 사용하여 환경 변수를 관리하려면 다음 API 작업을 사용합니다.

• UpdateFunctionConfiguration

• GetFunctionConfiguration

• CreateFunction

환경 변수 구성(AWS CLI)

다음 예제에서는 my-function라는 함수에서 두 개의 환경 변수를 설정합니다 .

aws lambda update-function-configuration \
  --function-name my-function \
  --environment "Variables={BUCKET=my-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": "nodejs20.x",
    "Role": "arn:aws:iam::111122223333:role/lambda-role",
    "Environment": {
        "Variables": {
            "BUCKET": "my-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 파일의 환경 및 변수 속성을 업데이트한 다음 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: nodejs18.x
      Architectures:
        - x86_64
      EphemeralStorage:
        Size: 10240
      Environment:
        Variables:
          BUCKET: my-bucket
          KEY: file.txt
      # Other function properties...

환경 변수에 대한 예제 시나리오

환경 변수를 사용하여 테스트 환경 및 프로덕션 환경에서 함수 동작을 사용자 지정할 수 있습니다. 예를 들어, 코드는 같지만 구성이 다른 두 개의 함수를 생성할 수 있습니다. 한 함수는 테스트 데이터베이스에 연결되고, 다른 함수는 프로덕션 데이터베이스에 연결됩니다. 이 경우 환경 변수를 사용하여 데이터베이스의 호스트 이름 및 기타 연결 세부 정보를 함수에 전달합니다.

다음 예는 환경 변수로 데이터베이스 호스트 및 데이터베이스 이름을 정의하는 방법을 보여줍니다.

테스트 환경에서 프로덕션 환경보다 더 많은 디버그 정보를 생성하도록 하려면 환경 변수를 설정하여 더 많은 상세 표시 로깅 또는 더 자세한 추적을 사용하도록 테스트 환경을 구성하면 됩니다.

환경 변수 검색

함수 코드에서 환경 변수를 검색하려면 프로그래밍 언어에 대한 표준 메서드를 사용합니다.

Node.js

let region = process.env.AWS_REGION

Python

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

참고

경우에 따라 다음 형식을 사용해야 할 수 있습니다.

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를 사용해 AWS CloudFormation 템플릿에서 환경 변수를 설정할 수 있습니다.

정의된 런타임 환경 변수

Lambda 런타임은 초기화 중에 여러 환경 변수를 설정합니다. 대부분의 환경 변수는 함수 또는 런타임에 관한 정보를 제공합니다. 이러한 환경 변수의 키는 예약되어 있으며 함수 구성에서 설정할 수 없습니다.

예약된 환경 변수

• _HANDLER – 함수에 대해 구성된 핸들러 위치입니다.

• _X_AMZN_TRACE_ID – X-Ray 추적 헤더입니다. 이 환경 변수는 간접 호출할 때마다 변경됩니다.

  • 이 환경 변수는 OS 전용 런타임(provided 런타임 제품군)에서 정의되지 않았습니다. 다음 호출의 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 SDK 및 도구 참조 안내서의 AWS Region을 참조하세요.

• AWS_EXECUTION_ENV - 런타임 ID로서 앞에 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를 통한 시작 성능 개선 SnapStart 섹션을 참조하세요.

• 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 – 런타임 라이브러리의 경로입니다.

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

예약되지 않은 환경 변수

• 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)입니다.

• PYTHONPATH – (Python 2.7, 3.6, 3.8) Python 라이브러리 경로($LAMBDA_RUNTIME_DIR)입니다.

• GEM_PATH – (Ruby) Ruby 라이브러리 경로($LAMBDA_TASK_ROOT/vendor/bundle/ruby/2.5.0:/opt/ruby/gems/2.5.0)입니다.

• AWS_XRAY_CONTEXT_MISSING – X-Ray 추적의 경우 Lambda는 X-Ray SDK에서 런타임 오류가 발생하지 않도록 LOG_ERROR로 설정합니다.

• AWS_XRAY_DAEMON_ADDRESS – X-Ray 추적의 경우 X-Ray 데몬의 포트 및 IP 주소입니다.

• AWS_LAMBDA_DOTNET_PREJIT – .NET 6 및 .NET 7 런타임의 경우 이 변수를 설정하여 .NET 특정 런타임 최적화를 활성화하거나 비활성화합니다. 값에는 always, never 및 provisioned-concurrency가 포함됩니다. 자세한 내용은 프로비저닝된 동시성 구성 단원을 참조하십시오.

• TZ - 환경의 표준 시간대(UTC)입니다. 실행 환경에서는 NTP를 사용하여 시스템 클록을 동기화합니다.

표시된 샘플 값은 최신 런타임을 반영합니다. 특정 변수 또는 해당 값의 존재는 이전 런타임에 따라 다를 수 있습니다.

환경 변수 보호

환경 변수 보안을 위해 서버 측 암호화를 이용해 저장된 데이터를 보호하고 클라이언트 측 암호화를 이용해 전송 중 데이터를 보호할 수 있습니다.

참고

데이터베이스 보안을 강화하려면 환경 변수 대신 AWS Secrets Manager를 사용하여 데이터베이스 보안 인증 정보를 저장하는 것이 좋습니다. 자세한 내용은 Amazon RDS와 함께 AWS Lambda 사용 단원을 참조하십시오.

저장 중 보안

Lambda는 AWS KMS key를 이용해 항상 저장 중 서버 측 암호화를 제공합니다. 기본적으로 Lambda는 AWS 관리형 키를 사용합니다. 이 기본 동작이 워크플로에 적합한 경우 다른 작업을 설정할 필요가 없습니다. Lambda가 계정에 AWS 관리형 키를 생성하고 계정에 대한 허가를 관리합니다. AWS는 이 키를 사용하는 데 요금을 청구하지 않습니다.

원한다면 AWS KMS 고객 관리형 키를 대신 제공할 수 있습니다. KMS 키의 교체를 제어하거나 KMS 키를 관리하기 위한 조직의 요구 사항을 충족하기 위해 이 작업을 수행할 수 있습니다. 고객 관리형 키를 사용하면 KMS 키에 대한 액세스 권한이 있는 계정의 사용자만 함수에서 환경 변수를 보거나 관리할 수 있습니다.

고객 관리형 키에는 표준 AWS KMS 요금이 발생합니다. 자세한 내용은 AWS Key Management Service 요금을 참조하십시오.

전송 중 보안

보안을 강화하기 위해 전송 중 암호화를 위한 도우미를 사용하도록 설정하면 전송 중 보호를 위해 환경 변수가 클라이언트 측으로 암호화됩니다.

환경 변수 암호화를 구성하려면

1. AWS Key Management Service(AWS KMS)를 사용하여 서버 측 및 클라이언트 측 암호화에 사용할 Lambda에 대한 고객 관리형 키를 생성할 수 있습니다. 자세한 내용은 AWS Key Management Service 개발자 안내서에서 키 생성을 참조하세요.

2. Lambda 콘솔을 사용하여 환경 변수 편집 페이지로 이동합니다.

   1. Lambda 콘솔의 함수 페이지를 엽니다.

   2. 함수를 선택합니다.

   3. 구성을 선택한 다음 왼쪽 탐색 모음에서 환경 변수를 선택합니다.

   4. 환경 변수 섹션에서 편집을 선택합니다.

   5. Encryption configuration(암호화 구성)을 확장합니다.

3. (선택 사항) 클라이언트측 암호화를 사용하여 전송 중 데이터를 보호하도록 콘솔 암호화 도우미를 활성화합니다.

   1. 전송 중 암호화에서 전송 중 암호화에 대해 도우미 사용을 선택합니다.

   2. 콘솔 암호화 도우미를 사용 설정하려는 각 환경 변수에 대해 환경 변수 옆에 있는 암호화를 선택합니다.

   3. 전송 중 암호화할 AWS KMS key에서, 이 절차를 시작할 때 생성한 고객 관리형 키를 선택합니다.

   4. 실행 역할 정책을 선택하고 정책을 복사합니다. 이 정책은 환경 변수를 복호화할 수 있는 권한을 함수의 실행 역할에 부여합니다.

      이 정책을 저장하여 절차의 마지막 단계에서 사용합니다.

   5. 환경 변수를 복호화하는 함수에 코드를 추가합니다. 예제를 보려면 암호 코드 조각 해독을 선택합니다.

4. (선택 사항) 유휴 시 암호화를 위해 고객 관리형 키를 지정합니다.

   1. 고객 마스터 키 사용을 선택합니다.

   2. 이 절차를 시작할 때 생성한 고객 관리형 키를 선택합니다.

5. Save(저장)를 선택합니다.

6. 권한을 설정합니다.

   서버 측 암호화와 함께 고객 관리형 키를 사용하는 경우, 함수에서 환경 변수를 보거나 관리할 수 있는 사용자 또는 역할에 권한을 부여하세요. 자세한 내용은 서버 측 암호화 KMS 키에 대한 권한 관리 단원을 참조하십시오.

   전송 중 보안을 위해 클라이언트 측 암호화를 사용하도록 설정하는 경우, 함수가 kms:Decrypt API 작업을 호출하려면 권한이 필요합니다. 이전에 이 절차에서 저장한 정책을 함수의 실행 역할에 추가합니다.

서버 측 암호화 KMS 키에 대한 권한 관리

사용자 또는 함수의 실행 역할에 대한 AWS KMS 권한 없이도 기본 암호화 키를 사용할 수 있습니다. 고객 관리형 CMK를 사용하려면 키 사용 권한이 필요합니다. Lambda는 사용자의 권한을 사용하여 키에 대한 권한 부여를 생성합니다. 이를 통해 Lambda가 암호화에 해당 키를 사용할 수 있습니다.

• kms:ListAliases – Lambda 콘솔에서 키 보기.

• kms:CreateGrant, kms:Encrypt – 함수에 대한 고객 관리형 키 구성하기

• kms:Decrypt – 고객 관리형 키로 암호화된 환경 변수를 보고 관리하기

AWS 계정 또는 키의 리소스 기반 권한 정책에서 이러한 권한을 얻을 수 있습니다. ListAliases는 Lambda의 관리형 정책에서 제공합니다. 키 정책에 따라 키 사용자 그룹의 사용자는 나머지 권한을 받습니다.

Decrypt 권한이 없는 사용자도 기능을 관리할 수 있지만 Lambda 콘솔에서 환경 변수를 보거나 관리할 수는 없습니다. 사용자가 환경 변수를 볼 수 없도록 하려면 기본 키, 고객 관리형 키 또는 모든 키에 대한 액세스를 거부하는 사용자 권한에 문을 추가합니다.

예 IAM 정책 - 키 ARN별 액세스 거부

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Deny",
            "Action": [
                "kms:Decrypt"
            ],
            "Resource": "arn:aws:kms:us-east-2:111122223333:key/3be10e2d-xmpl-4be4-bc9d-0405a71945cc"
        }
    ]
}

키 권한 관리에 대한 자세한 내용은 AWS Key Management Service 개발자 안내서의 Key policies in AWS KMS를 참조하세요.

샘플 코드 및 템플릿

이 가이드의 GitHub 리포지토리에 있는 샘플 애플리케이션은 함수 코드 및 AWS CloudFormation 템플릿에서 환경 변수를 사용하는 방법을 보여줍니다.

샘플 애플리케이션

• 빈 함수 – 로깅, 환경 변수, AWS X-Ray 추적, 계층, 단위 테스트, AWS SDK를 사용하는 방법을 보여주는 기본 함수를 만듭니다.

• RDS MySQL – VPC와 Amazon Relational Database Service(RDS) DB 인스턴스를 하나의 템플릿에서 생성하고 Secrets Manager에 암호를 저장합니다. 애플리케이션 템플릿에서 VPC 스택에서 데이터베이스 세부 정보를 가져오고 Secrets Manager에서 암호를 읽은 다음, 환경 변수의 함수에 모든 연결 구성을 전달합니다.