CloudFront Agent (Functions)

개요

AWS CloudFront의 Functions 환경에서 NetFUNNEL과 유기적으로 통합되어, 사용자 요청이 발생하는 최전선에서 실시간으로 대기열을 제어합니다.

Function 생성

함수 생성

• CloudFront로 이동합니다.
• 왼쪽 사이드 메뉴에서 [함수]를 클릭하세요.
• [함수 생성]을 클릭하세요.
• 함수 이름을 입력하고 Runtime은 cloudfront-js-2.0(기본값)로 선택하여 [함수 생성]을 클릭하세요.

함수 설정

• [빌드] - [함수 코드] - [개발]에 에이전트 파일 코드를 복사해서 붙여넣어주세요.
• [변경 사항 저장]을 클릭합니다.
• [테스트] 탭으로 이동해서 [함수 테스트]를 클릭하여 실행 결과가 성공이 되는지 확인합니다.
• [게시] 탭으로 이동해서 [함수 게시]를 클릭합니다.

KeyValueStore 생성

KeyValueStore 생성

• Associated KeyValueStore 메뉴에서 [Create new KeyValueStore]를 클릭하세요.
• 이름을 입력하고 [Create]를 클릭하세요.
• Key value pairs 메뉴에서 [Edit]를 클릭하세요.
• [Add pair]를 클릭하고 아래 표를 참고하여 필수값을 추가하세요.

Key	Value (example)	설명
client_id	stclab-0000	넷퍼넬에서 고객에게 부여하는 id입니다. [넷퍼넬 콘솔] - [에이전트] - [CDN 에이전트]에서 확인할 수 있습니다.
project_key	service_1	사용하고자 하는 프로젝트의 키를 입력하세요. [넷퍼넬 콘솔] - [프로젝트]에서 확인할 수 있습니다.
segment_key	segKey_1111, segKey_2222	사용하고자 하는 모든 세그먼트의 키를 입력하세요. 입력 순서에 따라 트리거의 우선순위가 결정됩니다. [넷퍼넬 콘솔] - [프로젝트] - [세그먼트]에서 확인할 수 있습니다.

• 입력을 완료하면 [Save changes]를 클릭하고, 팝업창의 [Done]을 클릭하세요.

함수에 연결

• Associated functions 메뉴에서 [Go to functions]를 클릭하고 위에서 생성한 함수를 선택합니다.
• Associated KeyValueStore 메뉴에서 [Associate existing KeyValueStore]를 클릭합니다.
• 위에서 생성한 KeyValueStore를 선택하고 [Associate KeyValueStore]를 클릭합니다.

CloudFront 설정

CloudFront에 Functions 연결

• Function을 적용할 CloudFront ID를 선택합니다.
• [동작] 탭에서 항목을 선택하고 [편집]을 누릅니다.
• 제일 하단의 함수 연결에서 뷰어 요청에 위에서 생성한 함수를 선택하세요.
• [변경 사항 저장]을 클릭합니다.

CloudFront 무효화

• [무효화] 탭으로 이동하여 [무효화 생성]을 클릭합니다.
• 객체 경로에 /* 을 입력하고 [무효화 생성]을 클릭합니다.
• 무효화가 완료되면 CloudFront에 Functions의 연결이 적용됩니다.

KeyValueStore 설정

CloudFront Function은 외부와 통신을 할 수 없기 때문에 [넷퍼넬 콘솔] - [세그먼트]에서 제공하는 트리거 규칙, 진입 패스, 진입 키 무효화 기능은 KeyValueStore(이하 KVS)를 통해 사용할 수 있습니다.

그 외에도 에이전트에서 제공하는 기능인 트리거 시간, Good Bot 예외 처리, 진입 키 자동 반납 처리, 대기실 도메인 변경(cname), 쿠키 도메인 설정을 KVS를 통해 사용할 수 있습니다.

트리거 규칙

세그먼트별로 대기를 적용할 페이지의 조건(URL, Domain, Path)을 정의합니다.

설정 형식

Key	Value
{segment_key}:trigger:{component}:{match}	URL 전체 또는 일부 (예: stclab.com)

Key 상세 파라미터

Key의 구성 요소인 {component}와 {match}에는 아래의 값들을 조합하여 입력합니다.

• {component}: 비교 대상
  • url: 전체 URL 기준
  • domain: 도메인 주소 기준 (예: netfunnel.stclab.com)
  • path: 도메인 뒤의 경로 기준 (예: /shop, /login)
• {match}: 비교 방법
  • equal: 입력한 값과 정확하게 일치할 때
  • contain: 입력한 값이 대상에 포함되어 있을 때

설정 예시

적용 시나리오	Key	Value
특정 경로 포함 (URL 경로에 shop이 포함된 모든 요청)	segKey_1111:trigger:path:contain	shop
특정 도메인 일치 (특정 도메인으로 들어오는 모든 요청)	segKey_2222:trigger:domain:equal	netfunnel.stclab.com
특정 페이지 정확히 일치 (이벤트 페이지 주소와 정확히 일치할 때)	segKey_3333:trigger:url:equal	https://netfunnel.stclab.com/event

트리거 시간

세그먼트의 트리거 규칙이 매칭되지만, 특정 시간에만 대기가 발생하도록 하고 싶을 때 설정합니다. 일회용과 반복용으로 구분해서 설정할 수 있습니다.

정보

트리거 시간을 설정하지 않으면 항상 대기실로 이동합니다.

일회용 트리거 설정

Key	Value
{segment_key}:trigger:{action}	10자리 timestamp (예: 1777654300)

• {action}에는 start 또는 end를 입력하세요.
• start만 설정하는 경우에는 Value에 입력한 시간 이후부터 항상 대기실로 이동합니다.
• end만 설정하는 경우에는 Value에 입력한 시간까지 항상 대기실로 이동합니다.
• start와 end를 모두 설정하는 경우에는 각 Value에 입력한 시간 사이에 대기실로 이동합니다.

반복용 트리거 설정 - 매일 반복

Key	Value
{segment_key}:trigger:{action}:every:day	HH:mm (예: 17:30)

• {action}에는 start 또는 end를 입력하세요.
• start만 설정하는 경우에는 Value에 입력한 시간부터 24시까지 대기실로 이동합니다.
• end만 설정하는 경우에는 0시부터 Value에 입력한 시간까지 대기실로 이동합니다.
• start와 end를 모두 설정하는 경우에는 각 Value에 입력한 시간 사이에 대기실로 이동합니다.

반복용 트리거 설정 - 매주 반복

Key	Value
{segment_key}:trigger:{action}:every:week	day1,day2:HH:mm (예: mon,wed,fri:17:30)

• {action}에 들어가는 start, end에 대한 규칙은 매일 반복 설정과 같으므로 생략합니다.
• Value의 첫 번째 요소에는 sun, mon, tue, wed, thu, fri, sat가 올 수 있으며, 콤마(,)를 통해 여러 개를 입력할 수 있습니다.

타임존 설정

타임존을 설정합니다. 설정값을 기준으로 트리거 시간을 계산합니다.

정보

타임존을 설정하지 않으면 기본값 9(seoul, tokyo)로 처리됩니다.

Key	Value
timezone_offset	자연수 또는 음의 정수 (예: 9 또는 -3)

진입 패스 설정

대기가 끝난 사용자에게 임시 패스를 부여하여 설정한 시간 동안 대기실로 이동하지 않도록 합니다.

정보

진입 패스를 설정하지 않으면 최소값(5)으로 적용됩니다.

Key	Value
{segment_key}:entry_pass	초 단위 숫자 (예: 300)

• Value의 최소값은 5(5초), 최대값은 86400(24시간)입니다.
• Value의 입력값이 5보다 작으면 최소값으로, 86400보다 크면 최대값으로 보정됩니다.

진입 패스 무효화

특정 시간이나 URL에 진입했을 때 진입 패스 유효 시간이더라도 강제로 종료합니다. 무효화 이후 사용자가 트리거 규칙에 일치하는 URL에 진입했을 때 대기실로 이동하게 됩니다.

URL 기준 무효화

특정 URL에 진입하면 진입 패스를 무효화합니다. 무효화 설정한 URL에서는 대기실로 이동이 발생하지 않습니다.

Key	Value
{segment_key}:invalidate:url:{match}	URL 전체 또는 일부 (예: 도메인 주소, 특정 경로)

• {match}에는 트리거 규칙과 동일하게 equal 또는 contain을 사용합니다.

시간 기준 무효화

특정 시간 이전에 발급 받은 진입 패스를 무효화합니다. 무효화 설정한 시간 이후에 진입하는 경우에는 진입 패스가 동작합니다.

Key	Value
{segment_key}:invalidate:time	10자리 timestamp (예: 1777654300)

Good Bot 예외 처리

User-Agent에 굿봇 식별용 키워드가 포함된 경우, 해당 요청을 에이전트 제어 대상에서 제외합니다.

Key	Value
good_bots	goodbot 목록 (예: Googlebot, Bingbot, Slurp)

• 콤마(,)를 통해 여러 굿봇을 입력할 수 있습니다.

진입 키 자동 반납 처리

NetFUNNEL 에이전트는 진입 후 발급받은 키를 자동으로 반납하여 다음 대기자가 진입할 수 있도록 처리하고 있습니다. 키를 바로 반납하지 않고 세그먼트에서 설정한 타임아웃 시간에 반납하고 싶은 경우에 사용합니다.

정보

진입 키 자동 반납 처리를 설정하지 않으면 true로 적용되어 항상 자동으로 반납합니다.

Key	Value
return_key	true 또는 false

대기실 도메인 변경

NetFUNNEL 대기실 페이지의 도메인은 agent-lib.stclab.com입니다. 해당 도메인을 서비스 중인 도메인에 맞게 변경하려면 원하는 도메인을 요청하시고, 설정에도 추가해야 합니다.

Key	Value
vwr_page_domain	프로토콜과 도메인 (예: https://wait.stclab.com)

쿠키 도메인 설정

NetFUNNEL 에이전트는 진입 후 발급받은 키를 쿠키에 저장할 때 현재 페이지의 도메인을 기준으로 저장합니다. 만약 서로 다른 서브 도메인 간에 키를 공유해야 할 경우 메인 도메인이 쿠키에 저장되도록 설정합니다.

정보

netfunnel.stclab.com과 botmanager.stclab.com와 같이 서브 도메인이 서로 다른 페이지에서 쿠키를 공유해야 하면 .stclab.com으로 설정합니다.

Key	Value
cookie_domain	.메인 도메인 (예: .stclab.com)