This documentation is also available as markdown. For a complete index of all pages, see llms.txt at /llms.txt

CloudFront Embedder 연동 가이드

본 문서에서는 Amazon CloudFront CDN을 사용하는 서비스 사이트를 위해 CloudFront용 워터마크 임베딩 모듈을 Lambda@Edge로 적용하는 방법에 대하여 설명합니다.

sequenceDiagram
    participant A as 최종 사용자
    participant B as CloudFront CDN
    A ->> B: 세션 URL 재생 시작 (세그먼트 요청)
    Note right of B: CloudFront Embedder
    B -->> B: 세션 URL에 따른 0/1 세그먼트 조합
    B ->> A: 조합된 세그먼트 전달
    Note right of A: 조홥된 콘텐츠 재생

AWS CDK를 이용한 CloudFront Embedder 세팅

AWS CloudFront 와 lambda@edge 연동 하는데 필요한 리소스 등을 한번를 생성할 수 있는 CDK 샘플 소스가 제공됩니다. CloudFront Embedder CDK 샘플

직접 CloudFront Embedder 세팅

Lambda@Edge 설정에 필요한 CloudFront Embedder 파일은 샘플 다운로드 페이지에서 다운로드 받을 수 있습니다.

동영상 튜토리얼

CloudFront Embedder를 통한 포렌식 워터마킹 임베딩 방법을 설명하는 영상입니다.

Lambda@Edge 사용 가이드

Amazon CloudFront CDN에서의 Lambda@Edge 사용에 대해 익숙하지 않은 경우, 다음 단계로 진행하기 전에 아래 AWS 온라인 문서를 참고해 사용법을 숙지해 주실 것을 권장합니다.

IAM 권한 및 역할 생성

Lambda@Edge를 구성하기 위해서는 우선 해당 기능에 필요한 IAM 권한과 실행 역할을 생성해야 합니다. AWS 콘솔의 IAM 서비스 화면에서 해당 가이드를 참고해 다음과 같이 권한 및 역할을 생성합니다.

lambda:GetFunction, lambda:EnableReplication*, iam:CreateServiceLinkedRole, cloudfront:UpdateDistribution, cloudfront:CreateDistribution 권한을 추가하여 역할을 생성합니다.

권한 추가를 위해서는 우선 대상 서비스(Lambda)를 지정해야 합니다. 또한 lambda:EnableReplication* 권한을 추가하려면 우선 lambda:EnableReplication 권한 추가 후 JSON 코드를 수정해야 합니다.

iam:CreateServiceLinkedRole 권한의 리소스를 "Resource": "*"로 지정하면 정책 편집기에 경고가 표시됩니다. 필요한 경우 리소스 범위를 arn:aws:iam::*:role/aws-service-role/replicator.lambda.amazonaws.com/*로 제한할 수 있습니다.

Lambda access log를 cloudwatch logs로 수집하기 위해 logs 관련 권한을 추가합니다.

{
    "Effect": "Allow",
    "Action": [
        "logs:CreateLogGroup",
        "logs:CreateLogStream",
        "logs:PutLogEvents"
    ],
    "Resource": "arn:aws:logs:*:*:*"
}

생성한 role의 Trust Relationship 탭에 아래 역할을 추가합니다.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": [
                    "lambda.amazonaws.com",
                    "edgelambda.amazonaws.com"
                ]
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

Lambda@Edge 함수 생성

AWS 콘솔에서 Lambda 서비스로 이동해 함수 생성 버튼을 클릭합니다.
콘솔 우측 상단의 AWS 리전을 미국 동부(버지니아 북부)로 선택합니다. (Lambda@Edge는 Virginia Region에 생성해야 사용 가능합니다.)

1. 함수 이름 및 Runtime 설정

함수 이름: 임의의 이름으로 입력합니다. (예: fwm-cf-embedder)
런타임: Node.js 22.x를 선택합니다. 임베더 샘플은 콜백 방식의 핸들러를 사용하는데, Node.js 24.x 런타임은 이 방식을 더 이상 지원하지 않기 때문에 더 높은 버전의 기본값을 그대로 사용하면 안 됩니다.
아키텍처: x86_64를 사용합니다. Additional settings의 ARM64 architecture 토글은 끈 상태로 둡니다.

2. 실행 역할 설정

Additional settings에서 Custom execution role을 켜고, Configure custom execution role 패널에서 이전 단계에서 생성한 IAM 역할을 선택한 후 Save를 클릭합니다.
화면 하단의 함수 생성 버튼을 클릭해 Lambda@Edge 함수를 생성합니다.

3. 샘플 코드 업로드 및 수정

Code source 화면에서 Update > Update from a .zip file을 클릭해 샘플 다운로드 페이지에서 다운받은 CloudFront Embedder zip 파일을 업로드합니다.
업로드된 샘플 코드 내용을 확인하고 아래와 같은 사항을 수정합니다.

아래 안내된 부분 이외의 소스를 수정할 경우, 오류가 발생할 수 있으니 주의하시기 바랍니다.

config.json 소스에서 아래 테이블에 해당하는 변수의 값을 설정합니다.

Name	Required	Description
`aesKey`	True	도브러너 콘솔 사이트에서 제공하는 사이트 키 값을 입력합니다.
`type`	True	전처리된 A/B 버전 세그먼트가 하나의 폴더에 함께 저장된 콘텐츠인 경우는 `unlabeled_a_variant`를 입력하고, 각각 `0`과 `1` 폴더로 나뉘어 패키징된 경우는 `directory_prefix`를 입력합니다. 하나의 폴더에 저장된 경우 B 버전 파일에는 `b.` 접두어가 붙습니다. 값을 설정하기 전에 스토리지의 출력 폴더 구조를 확인하시기 바랍니다. T&P 서비스로 전처리한 콘텐츠는 `0`과 `1` 폴더로 나뉘어 저장되므로 `directory_prefix`를 입력합니다. 폴더 구조와 값이 맞지 않으면 S3가 `403 AccessDenied`를 반환합니다. (기본값: `unlabeled_a_variant`)
`availableInterval`	True	워터마크 적용을 위해 요청된 URL에는 timestamp 값이 포함되어 있습니다. 본 항목은 해당 timestamp의 유효 기간을 체크하기 위한 값입니다. `0`으로 설정할 경우 timestamp 유효 기간을 체크하지 않습니다. 샘플 `config.json`에는 `60000`으로 설정되어 있습니다. (단위: 분)
`prefixFolder`	True	A/B 버전 콘텐츠가 저장되어 있는 상위 폴더 명 설정 - 기존 패키징 서비스로 패키징한 경우: `dldzkdpsxmdnjrtm` - 신규 T&P 서비스로 패키징한 경우: `wm-contents` 기본 값은 `["dldzkdpsxmdnjrtm", "wm-contents"]`로, 위 두 가지 경우를 모두 지원합니다.
`wmtPublicKey`	False	세션 발급시 `wmt` 토큰 유형을 사용할 때 설정합니다. 도브러너 사이트에서 발급된 Akamai 공용 키를 사용하며, 헬프데스크에 요청할 수 있습니다.
`wmtPassword`	False	세션 발급시 `wmt` 토큰 유형을 사용할 때 설정합니다. 도브러너 사이트에서 발급된 Akamai 암호를 사용하며, 헬프데스크에 요청할 수 있습니다.

임베더 2.10.0에 추가된 syncSkipBit 옵션(zip 파일의 RELEASE.md 참고)은 config.json에서 설정하는 항목이 아닙니다. 임베더가 세션 URL의 페이로드(sync_skip_bit)에서 값을 읽으며, 값이 없으면 -1을 사용하기 때문에 별도로 설정할 필요가 없습니다.

저장한 후 Action 버튼의 Publish new version을 클릭하여 version을 생성합니다.
생성된 version이 포함된 ARN을 복사해 놓습니다. 우측 상단에 표시됩니다.
- 예) arn:aws:lambda:us-east-1:{계정넘버}:function:{lambda이름}:{version}

Lambda 콘솔의 Actions > Capabilities > Deploy to Lambda@Edge 메뉴에서 해당 버전을 배포(distribution)에 연결할 수도 있습니다.

CloudFront 설정

Lambda@Edge는 기존 CloudFront 배포에 적용하거나, 새로 생성한 배포에 적용할 수 있습니다. 배포 생성 마법사에는 함수 연결 단계가 없기 때문에 두 경우 모두 배포를 생성한 후에 함수를 연결합니다.

배포 생성

워터마크 콘텐츠를 서비스하는 배포가 이미 있는 경우에는 Lambda@Edge 적용 단계로 넘어갑니다.

AWS 콘솔에서 CloudFront 메뉴를 선택하고 Create distribution을 클릭한 후, 아래 순서대로 마법사를 진행합니다.

Choose a plan: Pay as you go를 선택합니다.
Get started: 배포 이름을 입력합니다.
Specify origin: A/B 버전 콘텐츠가 저장된 S3 버킷을 선택합니다. Allow private S3 bucket access to CloudFront는 선택된 상태로 둡니다. CloudFront가 OAC(Origin Access Control)를 생성하고 필요한 구문을 버킷 정책에 자동으로 추가합니다.
Enable security: AWS WAF 보안 보호 기능은 기본으로 활성화되어 있으며 추가 요금이 발생합니다. 서비스에 맞게 사용 여부를 선택합니다.
Review: 설정을 확인하고 배포를 생성합니다.

Lambda@Edge 적용

AWS console 에 접속하여 CloudFront 메뉴 선택 후 lambda@Edge를 적용시킬 배포를 선택합니다.

1. Behaviors 설정

Behaviors 탭에서 Default (*) 동작을 선택한 후 Edit 버튼을 클릭합니다.
Function associations 항목에서 Viewer request를 설정합니다.
- Function type : Lambda@Edge 선택
- Function ARN : Lambda@Edge 생성 과정에서 복사해 놓았던 ARN 입력
Save changes 버튼을 클릭합니다.

2. 설정 완료

배포 목록의 Status는 Enabled로 유지되며, 변경 사항이 배포되는 동안 Last modified에 Deploying이 표시됩니다. Last modified에 날짜가 표시되면 Lambda@Edge 적용이 완료되고 모든 설정이 끝납니다.

자세한 Lambda@Edge 관련 내용은 AWS 에서 제공하는 CloudFront 가이드를 참조하시기 바랍니다.

CORS 설정

플레이어가 CloudFront 배포와 다른 origin에서 실행되는 경우, 배포가 CORS 헤더를 반환해야 합니다. Lambda@Edge를 연결한 동작에 사용자 지정 응답 헤더 정책을 적용합니다.

Policies > Response headers에서 응답 헤더 정책을 생성하고 Cross-origin resource sharing (CORS)를 활성화합니다. Access-Control-Allow-Origin, Access-Control-Allow-Headers, Access-Control-Allow-Methods는 플레이어 환경에 맞게 설정하고(예: All origins, All headers, All methods), Origin override를 선택합니다.
해당 동작의 Edit 화면에서 Response headers policy로 생성한 정책을 선택하고 Save changes를 클릭합니다.

문제 해결

응답	원인	조치
`X-Cache: LambdaExecutionError from cloudfront`가 포함된 `503`	Lambda@Edge 함수가 실행되지 못한 경우입니다. 임베더 샘플이 지원하지 않는 런타임(예: `Node.js 24.x`)을 선택하면 이 오류가 발생합니다.	`Configuration` > `Runtime settings` > `Edit`에서 런타임을 `Node.js 22.x`로 변경하고, 새 버전을 게시한 후 새 버전 ARN을 동작에 연결합니다.
S3가 반환한 `403 AccessDenied` (`Server: AmazonS3`)	임베더가 변환한 세그먼트 경로가 버킷에 존재하지 않는 경우입니다. 주로 `config.json`의 `type` 값이 폴더 구조와 맞지 않을 때 발생합니다. CloudFront에 `s3:ListBucket` 권한이 없기 때문에 S3는 `404` 대신 `403`을 반환합니다.	폴더 구조를 확인해 `type`을 다시 설정하고, 새 버전을 게시한 후 새 버전 ARN을 동작에 연결합니다.