컨테이너 이미지로 Lambda 함수 만들기

컨테이너 이미지로 Lambda 함수 만들기

AWS Lambda 함수의 코드는 스크립트 또는 컴파일된 프로그램과 그 의존성으로 구성돼요. 함수 코드를 Lambda에 배포할 때는 배포 패키지(deployment package) 를 사용하죠. Lambda는 컨테이너 이미지와 .zip 파일 아카이브, 두 가지 유형의 배포 패키지를 지원해요.

Lambda 함수용 컨테이너 이미지를 빌드하는 방법은 세 가지가 있어요:

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

컨테이너 이미지에서 Lambda 함수를 만들려면 이미지를 로컬에서 빌드하고 Amazon Elastic Container Registry(Amazon ECR) 저장소에 업로드하세요. AWS Marketplace 판매자가 제공하는 컨테이너 이미지를 쓰는 경우 먼저 이미지를 프라이빗 Amazon ECR 저장소로 복제해야 해요. 그런 다음 함수를 만들 때 저장소 URI를 지정하죠. Amazon ECR 저장소는 Lambda 함수와 같은 AWS 리전에 있어야 해요. 이미지가 Lambda 함수와 같은 리전에 있다면 다른 AWS 계정의 이미지로도 함수를 만들 수 있어요. 자세한 내용은 Amazon ECR 교차 계정 권한을 참고하세요.

참고
Lambda는 컨테이너 이미지용 Amazon ECR FIPS 엔드포인트를 지원하지 않아요. 저장소 URI에 ecr-fips가 있으면 FIPS 엔드포인트를 사용하는 거예요. 예: 111122223333.dkr.ecr-fips.us-east-1.amazonaws.com.

이 페이지는 Lambda 호환 컨테이너 이미지를 만들기 위한 기본 이미지 유형과 요구 사항을 설명해요.

참고
기존 함수의 배포 패키지 유형(.zip 또는 컨테이너 이미지)은 변경할 수 없어요. 예를 들어 컨테이너 이미지 함수를 .zip 파일 아카이브를 쓰도록 변환할 수 없죠. 새 함수를 만들어야 합니다.

출처: AWS Lambda 개발자 안내서

본문

Topics(주제)

요구 사항

AWS CLI version 2와 Docker CLI를 설치하세요. 또한 다음 요구 사항에 유의하세요:

  • 컨테이너 이미지는 커스텀 런타임용 Lambda 런타임 API 사용을 구현해야 해요. AWS 오픈소스 런타임 인터페이스 클라이언트가 이 API를 구현해요. 선호하는 기본 이미지에 런타임 인터페이스 클라이언트를 추가하면 Lambda와 호환되게 만들 수 있어요.
  • 컨테이너 이미지는 읽기 전용 파일 시스템에서 실행될 수 있어야 해요. 함수 코드는 512MB에서 10,240MB까지(1MB 단위)의 저장 공간이 있는 쓰기 가능한 /tmp 디렉토리에 접근할 수 있어요.
  • 기본 Lambda 사용자는 함수 코드를 실행하는 데 필요한 모든 파일을 읽을 수 있어야 해요. Lambda는 최소 권한을 가진 기본 Linux 사용자를 정의하는 보안 모범 사례를 따르기 때문에, Dockerfile에서 USER를 지정할 필요가 없어요. 애플리케이션 코드가 다른 Linux 사용자의 실행이 제한되는 파일에 의존하지 않는지 확인하세요.
  • Lambda는 Linux 기반 컨테이너 이미지만 지원해요.
  • Lambda는 멀티 아키텍처 기본 이미지를 제공해요. 하지만 함수용으로 빌드하는 이미지는 아키텍처 중 하나만 대상으로 해야 해요. Lambda는 멀티 아키텍처 컨테이너 이미지를 사용하는 함수를 지원하지 않아요.

Lambda용 AWS 기본 이미지 사용

함수 코드용 컨테이너 이미지를 빌드하는 데 AWS 기본 이미지 중 하나를 사용할 수 있어요. 기본 이미지에는 언어 런타임과 Lambda에서 컨테이너 이미지를 실행하는 데 필요한 다른 구성 요소가 미리 로드되어 있어요. 함수 코드와 의존성을 기본 이미지에 추가한 다음 컨테이너 이미지로 패키징하면 되죠.

AWS는 Lambda용 AWS 기본 이미지에 대한 업데이트를 주기적으로 제공해요. Dockerfile의 FROM 속성에 이미지 이름을 포함하면 Docker 클라이언트가 Amazon ECR 저장소에서 최신 버전의 이미지를 가져와요. 업데이트된 기본 이미지를 사용하려면 컨테이너 이미지를 다시 빌드하고 함수 코드를 업데이트해야 해요.

Node.js 20, Python 3.12, Java 21, .NET 8, Ruby 3.3 이후 기본 이미지는 Amazon Linux 2023 minimal 컨테이너 이미지를 기반으로 해요. 더 이른 기본 이미지는 Amazon Linux 2를 사용하죠. AL2023은 Amazon Linux 2보다 몇 가지 이점을 제공하는데, 더 작은 배포 공간과 glibc 같은 라이브러리의 업데이트된 버전이 포함돼요.

AL2023 기반 이미지는 Amazon Linux 2의 기본 패키지 관리자인 yum 대신 microdnf(dnf로 심링크됨)를 패키지 관리자로 사용해요. microdnf는 dnf의 독립 실행형 구현이에요. AL2023 기반 이미지에 포함된 패키지 목록은 Amazon Linux 2023 컨테이너 이미지에 설치된 패키지 비교의 Minimal Container 열을 참고하세요. AL2023과 Amazon Linux 2의 차이에 대해 더 알아보려면 AWS Compute Blog의 AWS Lambda용 Amazon Linux 2023 런타임 소개를 참고하세요.

참고
AL2023 기반 이미지를 AWS Serverless Application Model(AWS SAM)을 포함해 로컬에서 실행하려면 Docker version 20.10.10 이상을 사용해야 해요.

AWS 기본 이미지로 컨테이너 이미지를 빌드하려면 선호하는 언어의 지침을 선택하세요:

AWS OS 전용 기본 이미지 사용

AWS OS 전용 기본 이미지는 Amazon Linux 배포판과 런타임 인터페이스 에뮬레이터를 담고 있어요. 이 이미지는 Go와 Rust 같은 컴파일 언어, 그리고 Lambda가 기본 이미지를 제공하지 않는 언어나 언어 버전(예: Node.js 19)용 컨테이너 이미지를 만드는 데 흔히 사용돼요. OS 전용 기본 이미지로 커스텀 런타임을 구현할 수도 있죠. 이미지를 Lambda와 호환되게 만들려면 이미지에 여러분의 언어용 런타임 인터페이스 클라이언트를 포함해야 해요.

태그 런타임 운영 체제 Dockerfile 폐기
al2023 OS-only Runtime Amazon Linux 2023 GitHub의 OS 전용 런타임 Dockerfile 2029년 6월 30일

Amazon Elastic Container Registry Public Gallery: gallery.ecr.aws/lambda/provided

AWS가 아닌 기본 이미지 사용

Lambda는 다음 이미지 매니페스트 형식 중 하나를 따르는 모든 이미지를 지원해요:

  • Docker 이미지 매니페스트 V2, schema 2 (Docker version 1.10 이상에서 사용)
  • Open Container Initiative (OCI) 사양 (v1.0.0 이상)

Lambda는 모든 레이어를 포함해 최대 압축 해제 이미지 크기 10GB를 지원해요.

참고
이미지를 Lambda와 호환되게 만들려면 이미지에 여러분의 언어용 런타임 인터페이스 클라이언트를 포함해야 해요.
최적의 성능을 위해 이미지 매니페스트 크기를 25,400바이트 미만으로 유지하세요. 이미지 매니페스트 크기를 줄이려면 이미지의 레이어 수를 최소화하고 주석(annotation)을 줄이세요.

런타임 인터페이스 클라이언트

OS 전용 기본 이미지나 대체 기본 이미지를 사용한다면 이미지에 런타임 인터페이스 클라이언트를 포함해야 해요. 런타임 인터페이스 클라이언트는 Lambda와 함수 코드 사이의 상호작용을 관리하는 커스텀 런타임용 Lambda 런타임 API 사용을 구현해야 해요. AWS는 다음 언어용 오픈소스 런타임 인터페이스 클라이언트를 제공해요:

AWS가 제공하는 런타임 인터페이스 클라이언트가 없는 언어를 사용한다면 직접 만들어야 해요.

Amazon ECR 권한

컨테이너 이미지에서 Lambda 함수를 만들기 전에 이미지를 로컬에서 빌드하고 Amazon ECR 저장소에 업로드해야 해요. 함수를 만들 때 Amazon ECR 저장소 URI를 지정하죠.

함수를 만드는 사용자나 역할의 권한에 GetRepositoryPolicy, SetRepositoryPolicy, BatchGetImage, GetDownloadUrlForLayer가 포함되어 있는지 확인하세요.

예를 들어 IAM 콘솔을 사용해 다음 정책이 있는 역할을 만들 수 있어요:

[ JSON ]

{
  "Version":"2012-10-17",		 		 	
  "Statement": [
    {
      "Sid": "VisualEditor0",
      "Effect": "Allow",
      "Action": [
        "ecr:SetRepositoryPolicy",
        "ecr:GetRepositoryPolicy",
        "ecr:BatchGetImage",
        "ecr:GetDownloadUrlForLayer"
      ],
      "Resource": "arn:aws:ecr:{{us-east-1}}{{:111122223333}}:repository/{{hello-world}}"
    }
  ]
}

Lambda가 컨테이너 이미지를 가져오는 데 필요한 권한은 Amazon ECR 저장소가 함수와 같은 AWS 계정에 있는지 다른 계정에 있는지에 따라 달라져요. 다음 섹션은 각 시나리오의 요구 사항을 설명해요.

참고
IAM에서 같은 계정 접근은 한쪽만 권한을 부여하면 돼요 – 역할의 자격 기반 정책(identity-based policy) 또는 Amazon ECR 저장소의 리소스 기반 정책(resource-based policy) 중 하나만 있으면 되죠. 교차 계정 접근은 양쪽 모두 권한을 부여해야 해요 – 소비 계정의 역할에 있는 자격 기반 정책과 소유 계정의 Amazon ECR 저장소에 있는 리소스 기반 정책이 모두 그 작업을 허용해야 합니다.

같은 계정 Amazon ECR 저장소 정책

Amazon ECR의 컨테이너 이미지와 같은 계정에 있는 함수의 경우, 실행 역할의 자격 기반 정책이나 Amazon ECR 저장소의 리소스 기반 정책 중 하나로 Lambda에 접근 권한을 부여할 수 있어요. 한쪽만 허용하면 됩니다.

Amazon ECR 저장소 정책을 사용하기로 했다면 ecr:BatchGetImage와 ecr:GetDownloadUrlForLayer 권한을 추가하세요. 다음 예제는 최소 정책을 보여줘요:

{
        "Sid": "LambdaECRImageRetrievalPolicy",
        "Effect": "Allow",
        "Principal": {
          "Service": "lambda.amazonaws.com"
        },
        "Action": [
          "ecr:BatchGetImage",
          "ecr:GetDownloadUrlForLayer"
        ]
    }

Amazon ECR 저장소 권한에 대한 자세한 내용은 Amazon Elastic Container Registry 사용자 안내서의 프라이빗 저장소 정책을 참고하세요.

Amazon ECR 저장소에 이 권한들이 포함되어 있지 않으면 Lambda가 자동으로 추가하려고 해요. Lambda가 권한을 추가할 수 있는 것은 Lambda를 호출하는 보안 주체(principal)가 ecr:getRepositoryPolicy와 ecr:setRepositoryPolicy 권한을 가질 때뿐이에요.

Amazon ECR 저장소 권한을 보거나 편집하려면 Amazon Elastic Container Registry 사용자 안내서의 프라이빗 저장소 정책 문 설정 지침을 따르세요.

Amazon ECR 교차 계정 권한

한 계정의 함수가 다른 계정의 Amazon ECR 저장소에 있는 컨테이너 이미지를 사용할 때는 양쪽 모두 접근 권한을 부여해야 해요. 소비 계정의 역할에 있는 자격 기반 정책이 ecr:BatchGetImage와 ecr:GetDownloadUrlForLayer를 허용해야 하고, 소유 계정의 Amazon ECR 저장소에 있는 리소스 기반 정책도 이 작업들을 허용해야 합니다.

다음 예제에서 여러분의 Amazon ECR 저장소 권한 정책에는 계정 번호 123456789012에 접근을 부여하는 다음 문이 필요해요.

  • CrossAccountPermission – 계정 123456789012가 이 ECR 저장소의 이미지를 사용하는 Lambda 함수를 만들고 업데이트할 수 있게 해줘요.
  • LambdaECRImageCrossAccountRetrievalPolicy – Lambda는 함수가 오랫동안 호출되지 않으면 함수 상태를 최종적으로 inactive로 설정해요. 이 문은 Lambda가 123456789012가 소유한 함수를 대신해 최적화·캐싱용 컨테이너 이미지를 가져올 수 있도록 필요해요.

예제 — 저장소에 교차 계정 권한 추가

{
  "Version":"2012-10-17",		 		 	
  "Statement": [
    {
      "Sid": "CrossAccountPermission",
      "Effect": "Allow",
      "Action": [
        "ecr:BatchGetImage",
        "ecr:GetDownloadUrlForLayer"
      ],
      "Principal": {
        "AWS": "arn:aws:iam::{{123456789012}}:root"
      },
      "Resource": "arn:aws:ecr:{{us-east-1}}:{{123456789012}}:repository/{{example-lambda-repository}}"
    },
    {
      "Sid": "LambdaECRImageCrossAccountRetrievalPolicy",
      "Effect": "Allow",
      "Action": [
        "ecr:BatchGetImage",
        "ecr:GetDownloadUrlForLayer"
      ],
      "Principal": {
        "Service": "lambda.amazonaws.com"
      },
      "Condition": {
        "ArnLike": {
          "aws:sourceARN": "arn:aws:lambda:{{us-east-1}}:{{123456789012}}:function:*"
        }
      },
      "Resource": "arn:aws:ecr:{{us-east-1}}:{{123456789012}}:repository/{{example-lambda-repository}}"
    }
  ]
}

여러 계정에 접근을 주려면 계정 ID를 CrossAccountPermission 정책의 Principal 목록과 LambdaECRImageCrossAccountRetrievalPolicy의 Condition 평가 목록에 추가하면 돼요.

AWS Organization에서 여러 계정으로 작업한다면 ECR 권한 정책에 각 계정 ID를 열거하는 것을 권장해요. 이 방식은 IAM 정책에서 좁은 권한을 설정하는 AWS 보안 모범 사례와 일치합니다.

Amazon ECR 저장소 정책 외에도 함수를 만드는 사용자나 역할은 자격 기반 정책에 BatchGetImage와 GetDownloadUrlForLayer 권한을 가지고 있어야 해요.

함수 수명 주기

새 컨테이너 이미지 또는 업데이트된 컨테이너 이미지를 업로드한 후 Lambda는 함수가 호출을 처리하기 전에 이미지를 최적화해요. 최적화 과정은 몇 초가 걸릴 수 있어요. 함수는 그 과정이 완료되어 상태가 Active로 전환될 때까지 Pending 상태로 남아 있죠. 함수는 Active 상태에 도달하기 전에는 호출할 수 없어요.

함수가 여러 주 동안 호출되지 않으면 Lambda가 최적화된 버전을 회수하고 함수는 Inactive 상태로 전환돼요. 함수를 다시 활성화하려면 호출해야 해요. Lambda는 첫 번째 호출을 거부하고 함수는 Lambda가 이미지를 다시 최적화할 때까지 Pending 상태가 된 뒤, Active 상태로 돌아갑니다.

Lambda는 주기적으로 Amazon ECR 저장소에서 관련 컨테이너 이미지를 가져와요. 해당 컨테이너 이미지가 Amazon ECR에 더 이상 없거나 권한이 철회되면 함수는 Failed 상태로 들어가고, Lambda는 모든 함수 호출에 실패를 반환해요.

Lambda API를 사용해 함수 상태에 대한 정보를 얻을 수 있어요. 자세한 내용은 Lambda 함수 상태를 참고하세요.

더 알아보기 (Learn more)

  • 기본 이미지 유형(AWS·OS 전용·비-AWS), 런타임 인터페이스 클라이언트, ECR 권한(같은 계정/교차 계정), 함수 수명 주기까지 컨테이너 이미지 기반 함수의 전반을 다뤄 보세요.