CloudFront 통합 가이드

NetFUNNEL CloudFront 에이전트는 Amazon CloudFront의 엣지에서 동작하며, 요청이 오리진 서버에 도달하기 전에 대기열을 제어합니다. 애플리케이션 코드를 수정하지 않고 AWS 콘솔 설정만으로 적용할 수 있습니다.

1. 적용 방식 선택

CloudFront 에이전트는 Lambda@Edge와 CloudFront Functions 두 가지 방식으로 적용할 수 있습니다.

구분	Lambda@Edge	CloudFront Functions
실행 환경	Node.js (us-east-1 리전에 생성)	`cloudfront-js-2.0`
연결 이벤트	Viewer request · Viewer response	Viewer request
설정 위치	함수 코드의 `config` 객체	KeyValueStore
트리거 규칙	NetFUNNEL 콘솔의 세그먼트 트리거 규칙 사용	KeyValueStore에 직접 입력
설정 변경 시	코드 수정 → 새 버전 발행 → 배포 동작에 다시 연결	KeyValueStore 값만 수정

2. 사전 준비

CloudFront 배포(Distribution)가 구성된 AWS 계정
NetFUNNEL 콘솔에서 확인한 CLIENT_ID
NetFUNNEL CloudFront 에이전트 파일 (적용 방식에 맞는 파일)
CloudFront Functions 방식인 경우: NetFUNNEL 콘솔의 프로젝트 키와 세그먼트 키

3. 에이전트 동작 흐름

대기 전: 엣지로 요청 유입 → 함수 실행 → 트리거 규칙 매치
대기 중: 넷퍼넬 서버 요청 → 넷퍼넬 키 발급 → 대기실 페이지로 이동
대기 후: 서비스 페이지 진입 → 넷퍼넬 키 반납

4. Lambda@Edge로 적용

4.1 IAM 역할 생성

Lambda@Edge 함수가 사용할 IAM 역할을 만듭니다.

IAM 콘솔에서 Roles > Create role을 클릭합니다.
Trusted entity type은 AWS service, Use case는 Lambda를 선택합니다.
역할을 만든 뒤 Trust relationships를 아래와 같이 수정합니다.

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

CloudWatch 로그를 남길 수 있도록 아래 인라인 정책을 추가합니다.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["logs:CreateLogGroup", "logs:CreateLogStream", "logs:PutLogEvents"],
      "Resource": "*"
    }
  ]
}

4.2 Lambda 함수 생성

us-east-1 리전의 Lambda 콘솔에서 Create function을 클릭합니다.
Author from scratch를 선택합니다.
함수 이름을 입력합니다. (예: netfunnel-agent)
Runtime은 Node.js를 선택합니다.
Execution role에서 4.1에서 만든 IAM 역할을 선택합니다.
Create function을 클릭합니다.

4.3 에이전트 코드 적용

Code 탭에 에이전트 파일을 추가하고, index.mjs와 package.json을 아래와 같이 작성합니다. {AGENT_FILE_NAME}은 추가한 에이전트 파일의 이름으로 바꿉니다.

import handleEvent from './{AGENT_FILE_NAME}';

const config = {
  client_id: '{CLIENT_ID}',
};

export const handler = async (event) => {
  return await handleEvent(event, config);
};

{
  "name": "cloudfront-lambda-agent",
  "type": "module",
  "dependencies": {}
}

작성을 마치면 Deploy를 클릭합니다.

4.4 버전 발행

Versions 탭에서 Publish new version을 클릭하고, 발행된 버전 번호를 확인합니다. CloudFront에는 특정 버전의 함수를 연결해야 합니다.

4.5 배포 동작에 연결

CloudFront 콘솔에서 대상 배포를 선택합니다.
Behaviors 탭에서 대기열을 적용할 동작을 선택하고 Edit을 클릭합니다.
하단의 Function associations에 아래와 같이 Lambda 함수를 연결합니다.

이벤트	Function type	Function ARN
Viewer request	Lambda@Edge	함수 ARN + `:버전` (예: `...:function:netfunnel-agent:1`)
Viewer response	Lambda@Edge	함수 ARN + `:버전`

Save changes를 클릭합니다.

4.6 캐시 무효화

Invalidations 탭에서 Create invalidation을 클릭합니다.
Object paths에 /*를 입력하고 Create invalidation을 클릭합니다.
무효화가 완료되면 함수 연결이 적용됩니다.

4.7 부가 기능 설정

index.mjs의 config 객체에 설정값을 추가해 부가 기능을 사용할 수 있습니다.

설정	기본값	설명
`client_id`	-	NetFUNNEL 콘솔에서 확인한 클라이언트 아이디 (필수)
`good_bots`	-	대기열 제어에서 제외할 선의의 봇 키워드 배열입니다. 예: `["Googlebot", "Bingbot", "Slurp", "Applebot", "facebookexternalhit"]`
`return_key`	`true`	`true`: 대기 완료 후 즉시 키를 반납합니다. `false`: 세그먼트의 타임아웃 시점에 반납합니다.
`vwr_page_domain`	`agent-lib.stclab.com`	대기실 페이지 도메인입니다. 예: `"https://wait.stclab.com"`. 사용 전 STCLab에 도메인 등록을 요청해야 합니다.
`cookie_domain`	현재 페이지 도메인	키 쿠키의 도메인입니다. 형식: `".{MAIN_DOMAIN}"` (예: `".stclab.com"`). 하위 도메인 간에 키를 공유할 때 사용합니다.

const config = {
  client_id: '{CLIENT_ID}',
  good_bots: ['Googlebot', 'Bingbot'],
  return_key: true,
  cookie_domain: '.example.com',
};

5. CloudFront Functions로 적용

5.1 함수 생성

CloudFront 콘솔 왼쪽 메뉴에서 Functions를 선택합니다.
Create function을 클릭합니다.
함수 이름을 입력하고, Runtime은 기본값인 cloudfront-js-2.0을 유지한 채 Create function을 클릭합니다.

5.2 에이전트 코드 적용

Build 탭의 Function code > Development에 에이전트 파일의 코드를 붙여 넣습니다.
Save changes를 클릭합니다.
Test 탭에서 Test function을 클릭해 성공하는지 확인합니다.
Publish 탭에서 Publish function을 클릭합니다.

5.3 KeyValueStore 생성

함수의 Associated KeyValueStore에서 Create new KeyValueStore를 클릭하고, 이름을 입력한 뒤 Create를 클릭합니다.
Key value pairs에서 Edit > Add pair로 아래 필수 키를 추가합니다.

Key	예시 값	설명
`client_id`	`stclab-0000`	NetFUNNEL 콘솔의 에이전트 > CDN Agent에서 확인한 클라이언트 아이디
`project_key`	`service_1`	사용할 프로젝트 키
`segment_key`	`segKey_1111, segKey_2222`	사용할 세그먼트 키 전체. 입력한 순서가 트리거 우선순위가 됩니다.

Save changes를 클릭하고, 팝업에서 Done을 클릭합니다.

5.4 함수와 KeyValueStore 연결

KeyValueStore의 Associated functions에서 Go to functions를 클릭해 함수를 선택합니다.
함수의 Associated KeyValueStore에서 Associate existing KeyValueStore를 클릭하고, 만든 KeyValueStore를 선택해 Associate KeyValueStore를 클릭합니다.

5.5 배포 동작에 연결

CloudFront 콘솔에서 대상 배포를 선택합니다.
Behaviors 탭에서 대기열을 적용할 동작을 선택하고 Edit을 클릭합니다.
하단의 Function associations에서 Viewer request에 만든 함수를 선택합니다. (Function type: CloudFront Functions)
Save changes를 클릭합니다.

이후 4.6과 같은 방법으로 캐시를 무효화(/*)하면 함수 연결이 적용됩니다.

5.6 KeyValueStore 설정

CloudFront Functions 방식에서는 아래 키를 KeyValueStore에 추가해 대기열을 제어합니다. 키 이름의 {segment_key}는 실제 세그먼트 키로 바꿔 입력합니다.

트리거 규칙

Key	Value	설명
`{segment_key}:trigger:{component}:{match}`	URL, 도메인 또는 경로 (전체 또는 일부)	`component`: `url`(전체 URL), `domain`, `path` `match`: `equal`(일치), `contain`(포함)

예: segKey_1111:trigger:path:contain = shop → 경로에 shop이 포함된 요청에 대기열을 적용합니다.

트리거 시간

트리거 시간을 설정하지 않으면 트리거 규칙과 일치하는 요청은 항상 대기실로 이동합니다.

주기	Key	Value 예시
1회	`{segment_key}:trigger:start` · `{segment_key}:trigger:end`	`1777654300` (10자리 타임스탬프)
매일	`{segment_key}:trigger:start:every:day` · `{segment_key}:trigger:end:every:day`	`17:30`
매주	`{segment_key}:trigger:start:every:week` · `{segment_key}:trigger:end:every:week`	`mon,wed,fri:17:30` (요일: `sun`~`sat`)

start만 설정하면 그 시점부터, end만 설정하면 그 시점까지, 둘 다 설정하면 그 사이에만 대기열을 적용합니다.
timezone_offset: 트리거 시간 계산에 쓰는 UTC 기준 시차입니다. 정수로 입력하며 기본값은 9(서울·도쿄)입니다. (예: 9, -3)

진입 패스·무효화

Key	Value	설명
`{segment_key}:entry_pass`	초 단위 (예: `300`)	진입 패스 유효 시간. 기본 `5` · 최소 `5` · 최대 `86400` (범위를 벗어나면 최솟값·최댓값으로 조정)
`{segment_key}:invalidate:url:{match}`	URL (전체 또는 일부)	해당 URL에 접근한 사용자의 진입 패스를 무효화합니다. `match`: `equal`, `contain`
`{segment_key}:invalidate:time`	10자리 타임스탬프	지정 시각 이전에 발급된 진입 패스를 무효화합니다.

부가 기능

Key	기본값	설명
`good_bots`	-	대기열 제어에서 제외할 선의의 봇 키워드를 쉼표로 구분해 입력합니다. 예: `Googlebot, Bingbot, Slurp`
`return_key`	`true`	`true`: 대기 완료 후 즉시 키를 반납합니다. `false`: 세그먼트의 타임아웃 시점에 반납합니다.
`vwr_page_domain`	`agent-lib.stclab.com`	대기실 페이지 도메인입니다. 예: `https://wait.stclab.com`. 사용 전 STCLab에 도메인 등록을 요청해야 합니다.
`cookie_domain`	현재 페이지 도메인	키 쿠키의 도메인입니다. 형식: `.{MAIN_DOMAIN}` (예: `.stclab.com`)

6. 트리거 규칙 설정

Lambda@Edge 방식에서는 NetFUNNEL 콘솔의 세그먼트 트리거 규칙으로 대기열 제어 지점을 설정합니다. 사용자가 접속한 페이지의 URL과 트리거 규칙을 비교하여 일치하는 경우 대기열이 적용됩니다.

트리거 규칙 설정 방법은 트리거 규칙 문서를 참고하세요. CloudFront Functions 방식은 5.6 KeyValueStore 설정의 트리거 규칙을 사용합니다.