.NET Lambda 함수를 컨테이너 이미지로 배포하기

.NET Lambda 함수를 위한 컨테이너 이미지를 만드는 방법은 세 가지가 있어요:

출처: AWS Lambda 개발자 안내서

본문

.NET용 AWS 베이스 이미지 사용하기 — AWS 베이스 이미지에는 언어 런타임, Lambda와 함수 코드 사이의 상호 작용을 관리하는 런타임 인터페이스 클라이언트, 그리고 로컬 테스트용 런타임 인터페이스 에뮬레이터가 미리 탑재되어 있어요.
AWS OS-only 베이스 이미지 사용하기 — AWS OS-only 베이스 이미지에는 Amazon Linux 배포판과 런타임 인터페이스 에뮬레이터가 들어 있어요. 이 이미지는 Go, Rust 같은 컴파일 언어나, Lambda가 베이스 이미지를 제공하지 않는 언어·버전(Node.js 19 같은)의 컨테이너 이미지를 만들 때 주로 사용합니다. OS-only 베이스 이미지로 커스텀 런타임을 구현할 수도 있어요. 이미지를 Lambda와 호환되게 하려면 이미지에 .NET용 런타임 인터페이스 클라이언트를 반드시 포함해야 합니다.
비-AWS 베이스 이미지 사용하기 — Alpine Linux나 Debian처럼 다른 컨테이너 레지스트리의 대체 베이스 이미지를 사용할 수 있어요. 조직에서 만든 커스텀 이미지도 가능합니다. 역시 .NET용 런타임 인터페이스 클라이언트를 이미지에 포함해야 해요.

팁

Lambda 컨테이너 함수가 활성화되는 시간을 줄이려면 Docker 문서의 멀티 스테이지 빌드 사용하기를 참고하세요. 효율적인 컨테이너 이미지를 만들려면 Dockerfile 작성 모범 사례를 따르세요.

이 페이지에서는 Lambda용 컨테이너 이미지를 빌드하고, 테스트하고, 배포하는 방법을 설명합니다.

.NET용 AWS 베이스 이미지

AWS는 .NET용으로 다음과 같은 베이스 이미지를 제공합니다:

버전	.NET 버전	운영 체제	Dockerfile	사용 중단 날짜
10	.NET 10	Amazon Linux 2023	GitHub의 .NET 10용 Dockerfile	2028년 11월 14일
9	.NET 9	Amazon Linux 2023	GitHub의 .NET 9용 Dockerfile	2026년 11월 10일
8	.NET 8	Amazon Linux 2023	GitHub의 .NET 8용 Dockerfile	2026년 11월 10일

Amazon ECR 저장소: gallery.ecr.aws/lambda/dotnet

.NET용 AWS 베이스 이미지 사용하기

사전 조건

이 섹션의 단계를 완료하려면 다음이 필요해요:

.NET SDK — 아래 단계는 .NET 8 베이스 이미지를 사용합니다. 여러분의 .NET 버전이 Dockerfile에서 지정한 베이스 이미지 버전과 일치하는지 확인하세요.
Docker (최소 버전 25.0.0)
Docker buildx 플러그인

베이스 이미지를 사용해 이미지 만들고 배포하기

다음 단계에서는 Amazon.Lambda.Templates와 Amazon.Lambda.Tools를 사용해 .NET 프로젝트를 만듭니다. 그다음 Docker 이미지를 빌드해 Amazon ECR에 업로드하고 Lambda 함수로 배포합니다.

Amazon.Lambda.Templates NuGet 패키지를 설치합니다.
lambda.image.EmptyFunction 템플릿을 사용해 .NET 프로젝트를 만듭니다. 프로젝트 파일은 MyFunction/src/MyFunction 디렉토리에 저장됩니다.
- aws-lambda-tools-defaults.json: Lambda 함수 배포를 위한 명령줄 옵션을 지정합니다.
- Function.cs: Lambda 핸들러 함수 코드입니다. 기본 Amazon.Lambda.Core 라이브러리와 기본 LambdaSerializer 속성이 포함된 C# 템플릿이에요. 직렬화 요구 사항과 옵션에 대한 자세한 내용은 C# Lambda 함수의 직렬화를 참고하세요. 제공된 코드를 테스트에 사용하거나 직접 작성한 코드로 교체할 수 있습니다.
- MyFunction.csproj: 애플리케이션을 구성하는 파일과 어셈블리를 나열하는 .NET 프로젝트 파일입니다.
- Dockerfile: 제공된 Dockerfile을 테스트에 사용하거나 직접 작성한 것으로 교체할 수 있어요. 직접 작성한다면 다음을 확인하세요.
  - FROM 속성을 베이스 이미지의 URI로 설정합니다. 베이스 이미지와 MyFunction.csproj 파일의 TargetFramework는 둘 다 동일한 .NET 버전을 사용해야 해요. 예를 들어 .NET 9를 사용하려면: Dockerfile에 FROM public.ecr.aws/lambda/dotnet:9, MyFunction.csproj에 <TargetFramework>net9.0</TargetFramework>처럼 지정합니다.
  - CMD 인자를 Lambda 함수 핸들러로 설정합니다. 이 값은 aws-lambda-tools-defaults.json의 image-command와 일치해야 해요.
Amazon.Lambda.Tools .NET Global Tool을 설치합니다. 이미 설치되어 있다면 최신 버전인지 확인하세요.
아직 그렇지 않다면 MyFunction/src/MyFunction 디렉토리로 이동합니다.
Amazon.Lambda.Tools를 사용해 Docker 이미지를 빌드하고 새 Amazon ECR 저장소에 푸시한 뒤 Lambda 함수로 배포합니다. --function-role에는 함수의 실행 역할의 역할 이름을 지정하세요(Amazon Resource Name(ARN)이 아니라요). 예: lambda-role. Amazon.Lambda.Tools .NET Global Tool에 대한 자세한 내용은 GitHub의 AWS Extensions for .NET CLI 저장소를 참고하세요.
함수를 호출합니다. 모든 것이 성공했다면 아래와 비슷한 응답이 보일 거예요.
Lambda 함수를 삭제합니다.

런타임 인터페이스 클라이언트가 있는 대체 베이스 이미지 사용하기

OS-only 베이스 이미지나 대체 베이스 이미지를 사용한다면, 이미지에 런타임 인터페이스 클라이언트를 반드시 포함해야 해요. 런타임 인터페이스 클라이언트는 Lambda와 함수 코드 사이의 상호 작용을 관리하는 Runtime API를 확장합니다.

다음 예시는 비-AWS 베이스 이미지를 사용해 .NET용 컨테이너 이미지를 빌드하고, .NET용 Lambda 런타임 인터페이스 클라이언트인 Amazon.Lambda.RuntimeSupport 패키지를 추가하는 방법을 보여줘요. 예시 Dockerfile은 Microsoft .NET 8 베이스 이미지를 사용합니다.

사전 조건

이 섹션의 단계를 완료하려면 다음이 필요해요:

.NET SDK — 아래 단계는 .NET 9 베이스 이미지를 사용합니다. 여러분의 .NET 버전이 Dockerfile에서 지정한 베이스 이미지 버전과 일치하는지 확인하세요.
Docker (최소 버전 25.0.0)
Docker buildx 플러그인

대체 베이스 이미지를 사용해 이미지 만들고 배포하기

Amazon.Lambda.Templates NuGet 패키지를 설치합니다.
lambda.CustomRuntimeFunction 템플릿을 사용해 .NET 프로젝트를 만듭니다. 이 템플릿에는 Amazon.Lambda.RuntimeSupport 패키지가 포함되어 있어요.
프로젝트 파일이 저장된 MyFunction/src/MyFunction 디렉토리로 이동해 다음 파일들을 확인합니다.
- aws-lambda-tools-defaults.json — Lambda 함수를 배포할 때 명령줄 옵션을 지정하는 파일입니다.
- Function.cs — Main 메서드가 있는 클래스를 담은 코드로, 이 메서드는 Amazon.Lambda.RuntimeSupport 라이브러리를 부트스트랩으로 초기화합니다. Main 메서드는 함수 프로세스의 진입점이에요. Main 메서드는 함수 핸들러를 부트스트랩이 작동할 수 있는 래퍼로 감쌉니다. 자세한 내용은 GitHub 저장소의 Amazon.Lambda.RuntimeSupport를 클래스 라이브러리로 사용하기를 참고하세요.
- MyFunction.csproj — 애플리케이션을 구성하는 파일과 어셈블리를 나열하는 .NET 프로젝트 파일입니다.
- Readme.md — 샘플 Lambda 함수에 대한 자세한 정보가 들어 있는 파일입니다.
aws-lambda-tools-defaults.json 파일을 열고 다음 줄을 추가합니다.
- package-type: 배포 패키지를 컨테이너 이미지로 정의합니다.
- docker-host-build-output-dir: 빌드 프로세스의 출력 디렉토리를 설정합니다.

예시 aws-lambda-tools-defaults.json

{
  "Information": [
    "This file provides default values for the deployment wizard inside Visual Studio and the AWS Lambda commands added to the .NET Core CLI.",
    "To learn more about the Lambda commands with the .NET Core CLI execute the following command at the command line in the project root directory.",
    "dotnet lambda help",
    "All the command line options for the Lambda command can be specified in this file."
  ],
  "profile": "",
  "region": "us-east-1",
  "configuration": "Release",
  "function-runtime": "provided.al2023",
  "function-memory-size": 256,
  "function-timeout": 30,
  "function-handler": "bootstrap",
  "msbuild-parameters": "--self-contained true",
  "package-type": "image",
  "docker-host-build-output-dir": "./bin/Release/lambda-publish"
}

MyFunction/src/MyFunction 디렉토리에 Dockerfile을 만듭니다. 다음 예시 Dockerfile은 AWS 베이스 이미지 대신 Microsoft .NET 베이스 이미지를 사용합니다.
- FROM 속성을 베이스 이미지 식별자로 설정합니다. 베이스 이미지와 MyFunction.csproj 파일의 TargetFramework는 둘 다 동일한 .NET 버전을 사용해야 해요.
- COPY 명령을 사용해 함수를 /var/task 디렉토리로 복사합니다.
- ENTRYPOINT를 Docker 컨테이너가 시작할 때 실행할 모듈로 설정합니다. 이 경우 모듈은 Amazon.Lambda.RuntimeSupport 라이브러리를 초기화하는 부트스트랩이에요. 예시 Dockerfile에는 USER 지시어가 없다는 점을 참고하세요. 컨테이너 이미지를 Lambda에 배포하면 Lambda가 최소 권한의 기본 Linux 사용자를 자동으로 정의합니다. 이는 USER 지시어가 없을 때 기본적으로 root 사용자를 사용하는 표준 Docker 동작과는 다른 점이에요.

예시 Dockerfile

# You can also pull these images from DockerHub amazon/aws-lambda-dotnet:8
FROM mcr.microsoft.com/dotnet/runtime:9.0

# Set the image's internal work directory
WORKDIR /var/task

# Copy function code to Lambda-defined environment variable
COPY "bin/Release/net9.0/linux-x64" .

# Set the entrypoint to the bootstrap
ENTRYPOINT ["/usr/bin/dotnet", "exec", "/var/task/bootstrap.dll"]

Amazon.Lambda.Tools .NET Global Tools 확장을 설치합니다. 이미 설치되어 있다면 최신 버전인지 확인하세요.
Amazon.Lambda.Tools를 사용해 Docker 이미지를 빌드하고 새 Amazon ECR 저장소에 푸시한 뒤 Lambda 함수로 배포합니다. --function-role에는 함수의 실행 역할의 역할 이름을 지정하세요(ARN이 아니라요). 예: lambda-role. Amazon.Lambda.Tools .NET CLI 확장에 대한 자세한 내용은 GitHub의 AWS Extensions for .NET CLI 저장소를 참고하세요.
함수를 호출합니다. 모든 것이 성공했다면 다음과 같은 결과가 보일 거예요.
Lambda 함수를 삭제합니다.

.NET Lambda 함수를 컨테이너 이미지로 배포하기