NetFUNNEL Integration

NetFunnel은 트래픽이 급증하는 상황에서 서비스를 보호하기 위해 Wave와 연동하는 가상 대기실입니다. Wave가 Pod 스케일링을 담당하는 동안, NetFunnel은 인프라가 요청을 처리할 준비가 될 때까지 들어오는 요청을 큐에 담아두면서 트래픽 흐름을 관리합니다.

What is NetFunnel?

NetFunnel은 트래픽이 몰리는 시기에도 안정적인 트래픽 흐름을 유지하도록 설계된 가상 대기실입니다. 방문자가 질서 있게 대기하는 통제된 큐 환경을 만들어, 제품 출시나 플래시 세일 같은 트래픽 급증 상황에서 서버 과부하를 막고 사이트 안정성을 유지합니다.

Wave는 NetFunnel과 연동해 메트릭 기반의 자동화된 트래픽 관리를 제공합니다. 애플리케이션에 트래픽이 갑자기 몰리면, Wave는 Pod를 스케일링하는 동안 NetFunnel의 큐를 자동으로 활성화해 들어오는 요청을 대기시킵니다. 리소스가 확보되고 메트릭이 안정되면 NetFunnel은 대기 중인 트래픽을 해제하여, 서비스에 과부하를 주지 않으면서도 매끄러운 사용자 경험을 보장합니다.

이 연동은 규칙 기반 트리거(CPU, 메모리, max replicas)를 사용해 NetFunnel 세그먼트를 자동으로 ON/OFF 전환하며, Wave의 스케일링 결정과 트래픽 관리를 조율합니다.

How the integration works

이 연동은 모니터링과 세그먼트 자동 활성화를 계속 반복하는 루프로 동작합니다.

1. 메트릭 모니터링: NetFunnel 규칙이 설정된 Deployment의 CPU, 메모리, 현재 레플리카 수를 지속적으로 추적합니다.
2. 임계값 초과 감지: 설정된 임계값을 초과하는 시점을 감지합니다(예: CPU 80% 초과, 메모리 85% 초과, max replicas 도달).
3. 세그먼트 ON: 매핑된 모든 세그먼트를 활성화하기 위해 동시에 API 요청을 보내 가상 대기실을 가동합니다.
4. 스케일링 중 트래픽 큐잉: NetFunnel이 들어오는 요청을 대기시키고 사용자에게 대기 순번을 보여주는 동안, Wave의 Autopilot이 Pod를 스케일링해 부하를 흡수합니다.
5. 안정화 대기 후 쿨다운: 사용량이 임계값 아래로 떨어지면, 설정 가능한 쿨다운 기간(예: 300초)이 빈번한 On/Off 전환을 막아줍니다.
6. 세그먼트 OFF 및 로그 기록: 세그먼트를 비활성화하고 정상적인 트래픽 흐름으로 복귀하며, 모든 활성화/비활성화 이벤트를 메트릭 스냅샷과 함께 기록합니다.

NetFunnel vs manual traffic management

Core features

1. Rule-based triggers

리소스 메트릭을 기준으로 NetFunnel을 자동으로 활성화합니다. 설정된 모든 임계값을 초과하면 매핑된 모든 세그먼트가 ON됩니다.

Cooldown Period:

• 세그먼트가 OFF된 후 설정 가능한 지연 시간(초)
• 메트릭이 변동하는 동안 빈번한 On/Off 전환 방지
• 기본값: 60초(1분)
• 프로덕션 워크로드에는 300초(5분) 권장
• 쿨다운 중에는 임계값이 다시 초과되어도 세그먼트가 OFF 상태를 유지

트리거 로직:

• 규칙은 AND 조건입니다. 세그먼트를 활성화하려면 설정된 모든 임계값을 초과해야 합니다
• 설정된 규칙만 평가합니다(설정하지 않은 임계값은 무시)
• 매핑된 모든 세그먼트는 함께 ON/OFF됩니다(개별 제어 불가)
• 메트릭은 일정한 간격으로 평가됩니다(작업 주기 설정 가능)
• 예: CPU 임계값(80%)과 메모리 임계값(85%)을 모두 설정했다면, CPU > 80% 그리고 Memory > 85%를 모두 만족할 때만 NetFunnel이 활성화됩니다

2. Segment mapping

Kubernetes Deployment를 NetFunnel 프로젝트 및 세그먼트에 매핑합니다.

프로젝트 및 세그먼트 선택:

• 계정에 있는 기존 NetFunnel 프로젝트 중에서 선택
• 프로젝트 내 특정 세그먼트 선택
• 하나의 Deployment에 여러 세그먼트 매핑 가능

Section Mode 대 Basic Control:

• Section Control: 섹션 기반 관리를 포함한 고급 세그먼트 제어
• Basic Control: 섹션 없이 세그먼트를 단순 활성화
• NetFunnel 프로젝트 설정에 맞는 모드를 드롭다운에서 선택

세그먼트 정보 표시:

• Max Inflow: 세그먼트가 허용하는 최대 동시 요청 수
• Access Status: 세그먼트의 트래픽 허용 여부
• Active Status: 세그먼트의 현재 ON/OFF 상태

다중 세그먼트:

• 하나의 Deployment를 여러 세그먼트에 매핑 가능
• 웹, 모바일, API 등 트래픽 소스별로 구분할 때 유용
• 모든 세그먼트는 동일한 트리거 규칙으로 관리됨

3. Automated lifecycle

NetFunnel 세그먼트는 다음 상태를 자동으로 전환합니다.

상태 흐름:

• Inactive: 정상 동작, 큐 비활성 상태
• Turning ON: 임계값 초과 시 API 요청 전송
• Active: 큐 활성화, 트래픽 관리 중
• Cooldown: 메트릭 안정화, 비활성화 대기 중
• Turning OFF: 큐 비활성화를 위한 API 요청 전송

동시 API 요청:

• 여러 세그먼트를 동시에 활성화
• NetFunnel이 요청을 병렬로 처리
• 세그먼트 요청당 5초 타임아웃
• 부분 성공을 안전하게 처리(일부 세그먼트만 성공하고 나머지는 실패할 수 있음)

오류 처리:

• 연결 타임아웃은 세부 정보와 함께 기록
• 인증 실패는 별도로 보고
• 일시적 오류에 대한 재시도 로직 포함
• 로그에 상세한 오류 메시지 기록

메트릭 스냅샷 로깅: 모든 활성화/비활성화 이벤트는 타임스탬프, 세그먼트 상태(ON/OFF), 성공/실패 여부, 현재 CPU·메모리·레플리카 수, 트리거된 임계값 규칙, 쿨다운 상태, 실패 시 오류 사유와 함께 기록됩니다.

Prerequisites

NetFunnel을 활성화하기 전에 다음을 준비해야 합니다.

• Kubernetes 클러스터에 Wave 설치 완료
• NetFunnel 기능이 활성화된 유효한 Wave 라이선스
• 구독 중인 NetFunnel SaaS 계정
• NetFunnel 제공업체로부터 받은 API 자격 증명:
  • Tenant ID
  • Organization ID
  • api.stclab.com(기본 호스트) 접근 권한
• NetFunnel 계정에 사전 설정된 세그먼트(프로젝트와 세그먼트가 미리 존재해야 함)
• Deployment의 CPU, 메모리 데이터를 수집하는 Wave Metrics Agent

Step 1: Configure NetFunnel credentials

Wave와 NetFunnel 간의 연결을 설정합니다.

Access NetFunnel settings

1. Wave 웹 콘솔에 로그인합니다
2. 우측 상단의 Settings 아이콘(톱니바퀴)을 클릭합니다
3. NetFunnel 탭으로 이동합니다
4. 드롭다운에서 클러스터를 선택합니다

Enter API credentials

다음 필드를 설정합니다.

• Enable: 이 클러스터에 대해 NetFunnel 연동을 활성화하려면 ON으로 토글
• Host: NetFunnel API 엔드포인트(기본값: https://api.stclab.com)
• Tenant ID: NetFunnel에서 발급한 조직의 테넌트 식별자
• Organization ID: NetFunnel에서 발급한 조직 ID

예시:

Host: https://api.stclab.com
Tenant ID: abc123-tenant-id
Organization ID: org456-organization-id

Test the connection

1. Test Connection 버튼을 클릭합니다
2. Wave가 NetFunnel API를 호출해 인증 키(clientId, clientSecret)를 가져오고 자격 증명을 검증한 뒤, 성공 또는 오류 메시지를 표시합니다
3. 성공하면 "Connection successful" 메시지가 표시됩니다
4. 실패하면 자격 증명과 api.stclab.com에 대한 네트워크 접근을 확인합니다

Save the configuration

1. Save를 클릭해 자격 증명을 저장합니다
2. 이제 이 클러스터의 Deployment에 대해 NetFunnel 연동이 활성화됩니다

Step 2: Access the deployment

보호하려는 Deployment로 이동합니다.

1. 왼쪽 사이드바에서 Deployments를 선택합니다
2. 드롭다운에서 클러스터를 선택합니다
3. 설정하려는 Deployment를 찾습니다(예: 웹 프론트엔드, API 게이트웨이)
4. Deployment 이름을 클릭해 상세 페이지를 엽니다

Step 3: Configure NetFunnel rules

가상 대기실을 활성화하는 트리거 조건을 설정합니다.

Open the NetFunnel configuration

1. Deployment 상세 페이지에서 NetFunnel 탭으로 이동합니다
2. Trigger Conditions, Segment Mappings, NetFunnel Logs 섹션이 표시됩니다

Configure trigger conditions

Settings 버튼을 클릭해 규칙 설정 모달을 엽니다.

CPU Threshold:

• Enable: CPU 기반 트리거를 활성화하는 토글
• Value: 백분율 입력(0~100)
• 예시: 80(CPU 사용률이 80%를 초과하면 활성화)

Memory Threshold:

• Enable: 메모리 기반 트리거를 활성화하는 토글
• Value: 백분율 입력(0~100)
• 예시: 85(메모리 사용률이 85%를 초과하면 활성화)

Max Replicas Trigger:

• Enable: Deployment가 max replicas에 도달했을 때 활성화하는 토글
• 용도: 스케일링 여력이 소진됐을 때 과부하 방지
• 예시: ON(current_replicas = max_replicas일 때 활성화)

Cooldown Period:

• Value: 초 단위 지속 시간 입력
• Default: 60(1분)
• 목적: 세그먼트가 OFF된 후 빈번한 On/Off 전환 방지
• 예시: 더 보수적으로 전환하려면 300(5분), 트래픽이 매우 안정적이라면 600(10분)

Save the rules

1. Save를 클릭해 트리거 설정을 적용합니다
2. 규칙은 즉시 적용됩니다

Step 4: Map NetFunnel segments

Deployment를 NetFunnel 세그먼트와 연결합니다.

Open segment mapping

1. NetFunnel 탭에서 NetFUNNEL Segments 섹션을 찾습니다
2. Add를 클릭해 매핑 모달을 엽니다

Select a project and segment

다음 필드를 설정합니다.

Project:

• NetFunnel 계정의 모든 프로젝트가 드롭다운으로 표시됩니다
• 사용하려는 세그먼트가 포함된 프로젝트를 선택합니다
• 프로젝트 목록은 자격 증명을 사용해 NetFunnel API에서 가져옵니다

Section Mode:

• 제어 모드 유형을 선택하는 드롭다운
• Section Control: 섹션 기반 관리를 포함한 고급 세그먼트 제어용
• Basic Control: 섹션 없이 단순 활성화하는 용도
• NetFunnel 프로젝트 설정에 맞는 모드를 선택합니다

Segment:

• 선택한 프로젝트의 모든 세그먼트가 드롭다운으로 표시됩니다
• 활성화 및 비활성화할 특정 세그먼트를 선택합니다
• 세그먼트 목록은 선택한 프로젝트와 section mode를 기준으로 가져옵니다

Review segment information

모달에는 다음과 같은 세그먼트 세부 정보가 표시됩니다.

• Max Inflow: 허용되는 최대 동시 요청 수(예: 1000)
• Access Enabled: 세그먼트의 트래픽 허용 여부(Yes/No)
• Active Status: 현재 ON/OFF 상태(Active/Inactive)

이 필드는 읽기 전용이며, 확인을 위해 NetFunnel에서 가져온 값입니다.

Save the segment mapping

1. Save를 클릭해 매핑을 생성합니다
2. Deployment의 세그먼트 목록에 세그먼트가 표시됩니다
3. 다른 트래픽 소스 등 추가 세그먼트가 필요하면 이 과정을 반복합니다

Multiple segment mapping

하나의 Deployment에 여러 세그먼트를 매핑할 수 있습니다.

• 용도: 웹, 모바일, API 트래픽마다 서로 다른 세그먼트 사용
• 동작: 규칙이 트리거되면 모든 세그먼트가 함께 ON/OFF됨
• 설정: 각 세그먼트는 NetFunnel에서 독립적으로 관리되지만, 동일한 Wave 규칙에 의해 활성화됨

예시:

Deployment: ecommerce-frontend
Segments:
  - Project: Production, Segment: Web Queue, Max Inflow: 5000
  - Project: Production, Segment: Mobile Queue, Max Inflow: 3000
  - Project: Production, Segment: API Queue, Max Inflow: 2000

Step 5: Monitor NetFunnel activity

세그먼트의 활성화 및 비활성화 이벤트를 추적합니다.

View NetFunnel logs

Deployment의 NetFunnel 탭에서 NetFunnel Logs 섹션까지 스크롤합니다.

Log Table Columns:

Note: Result 컬럼은 쿨다운 기간 중일 때 "Cooldown" 태그를 함께 표시합니다. Rule 컬럼은 보기 편하도록 모든 트리거 설정(CPU threshold, Memory threshold, Max Replicas, Cooldown seconds)을 하나의 셀에 합쳐서 보여줍니다.

Interpreting logs

활성화 성공:

Timestamp: 2026-02-06 14:30:00
Segment Status: ON
Result: Success
Rule: CPU: 80%, Memory: 85%, Max Replicas: On, Cooldown: 60s
CPU Utilization: 82%
Memory Utilization: 87%
Replicas: 10
Max Replicas: 10

해석: 세 가지 임계값(CPU > 80%, Memory > 85%, Max Replicas 도달)이 모두 초과되어 세그먼트가 정상적으로 ON되었습니다.

쿨다운 기간:

Timestamp: 2026-02-06 14:35:00
Segment Status: OFF
Result: Success (Cooldown)
Rule: CPU: 80%, Memory: 85%, Max Replicas: On, Cooldown: 60s
CPU Utilization: 65%
Memory Utilization: 60%
Replicas: 10
Max Replicas: 10

해석: 메트릭이 임계값 아래로 떨어져 쿨다운이 시작되었습니다(기본값 60초 동안, 또는 설정에 따라 더 길게 세그먼트가 OFF 상태를 유지합니다).

활성화 실패:

Timestamp: 2026-02-06 14:40:00
Segment Status: ON
Result: Fail
(Note: error details are logged in the backend; check Wave service logs for specific error messages)

해석: NetFunnel API 호출이 실패했습니다. 네트워크 연결 상태와 백엔드 로그에서 상세한 오류 사유를 확인하세요.

Example: quick setup for an e-commerce API

프로덕션 이커머스 API를 위한 전체 설정 예시입니다.

# Step 1: Settings -> NetFunnel
Credentials:
  Enable: ON
  Host: https://api.stclab.com
  Tenant ID: ecommerce-prod-tenant
  Organization ID: ecommerce-org-001
 
# Step 2: Deployments -> ecommerce-api -> NetFunnel tab
Trigger Rules:
  CPU Threshold: 80% (enabled)
  Memory Threshold: (disabled)
  Max Replicas: (disabled)
  Cooldown Period: 300 seconds (recommended for production)
 
  # Note: with only the CPU threshold enabled, NetFunnel activates when CPU > 80%.
  # If multiple thresholds were enabled, ALL would need to be exceeded (AND logic).
 
# Step 3: Segment Mapping
Segments:
  - Project: Production E-commerce
    Section Mode: true
    Segment: Checkout Queue
    Max Inflow: 1000
 
  - Project: Production E-commerce
    Section Mode: true
    Segment: Product Browse Queue
    Max Inflow: 5000
 
# Step 4: Test with Load
Behavior:
  - Normal: CPU 50%, 5 pods, segments OFF
  - Traffic spike: CPU 85%, 8 pods
  - Segments turn ON: queue activated
  - Autopilot scales: 8 -> 15 pods
  - CPU drops: 60%, 15 pods
  - Cooldown: 60s with segments ON (or 300s if configured)
  - Segments turn OFF: queue disabled, normal traffic

Troubleshooting

Next steps

NetFunnel 설정을 마쳤다면 다음을 진행하세요.

• 로그 모니터링: 활성화 패턴을 파악하기 위해 NetFunnel 로그를 매일 확인합니다
• 임계값 조정: 관찰된 동작을 바탕으로 트리거 조건을 세밀하게 조정합니다
• 부하 테스트: k6, JMeter, wrk 같은 도구로 트래픽 급증을 재현해 NetFunnel 활성화를 검증합니다
• 다중 Deployment 설정: 트래픽이 많은 다른 서비스도 NetFunnel로 보호합니다
• 알림 설정: NetFunnel 활성화 실패나 활성화 빈도 급증에 대한 알림을 만듭니다
• 세그먼트 설정 검토: max inflow 등 NetFunnel 세그먼트 설정이 요구 사항에 맞는지 확인합니다

도움이 필요하신가요? NetFunnel 로그(Deployment 상세 페이지, NetFunnel 탭, Logs 테이블)를 확인하고, Settings, NetFunnel, Test Connection에서 자격 증명을 다시 테스트하세요. NetFunnel 서비스 오류는 Wave 코어 로그에서 확인하고, API나 세그먼트 문제는 NetFunnel 제공업체에 문의하세요. Wave 라이선스에 NetFunnel 기능 플래그가 포함되어 있는지도 확인하세요.