AIM-Intelligence/sla-bench-shooter-airgapped

SLA-Bench Shooter — Guardian Latency SLA (Air-Gap Bundle)

에어갭(인터넷 차단) K3S 환경에 반입해서 쓰는, 배포된 Guardian API 의 지연(latency) SLA 측정 도구다. 웹 UI 에 엔드포인트와 API 키만 넣으면 바로 측정이 시작된다 — 데이터 생성도, 모델 다운로드도, 인터넷 접속도 필요 없다.

	값
필요 환경	k3s (또는 임의의 k8s), local-path storageClass, RAM ~2Gi, CPU ~2
GPU	불필요 — 모델을 띄우지 않는다. 남이 운영하는 Guardian 을 밖에서 호출하는 클라이언트다
외부 포트	30001/tcp (NodePort)
인터넷	설치·구동 모두 불필요
데이터셋	이미지에 내장 (200 / 1,000 / 5,000 토큰 × 6종, 12,000 프롬프트)

---

📁 저장소 구성

노드 종류에 맞는 zip 하나만 받으면 된다. 이미지 tar 와 매니페스트는 두 zip 이 완전히 동일하고, 다른 것은 설치 절차 문서와 변종 표시뿐이다.

파일	크기	어느 노드에
sla-shooter-2026.08.11-k3s-airgapped.zip	~102MB	control-plane (k3s server) — 한 번에 설치
sla-shooter-2026.08.11-k3s-agent-airgapped.zip	~102MB	k3s-agent (워커) — 두 단계 설치
SHA256SUMS.txt	—	무결성 체크섬

sha256sum -c SHA256SUMS.txt

🚀 설치

설치는 두 단계이고, 서로 다른 노드를 요구할 수 있다:

	무엇	어디서	왜
①	이미지 import	shooter 를 돌릴 그 노드	k3s ctr 는 자기 노드의 containerd 에만 넣고, 매니페스트는 imagePullPolicy: Never 다
②	매니페스트 적용	클러스터 API 에 닿는 곳	k3s-agent(워커) 노드에는 kubeconfig 가 없어 k3s kubectl 이 동작하지 않는다

① control-plane(k3s server) 노드에 설치 — 한 번에

unzip sla-shooter-2026.08.11-k3s-airgapped.zip
cd sla-shooter
sudo ./install.sh

② k3s-agent(워커) 노드에 설치 — 두 단계 ⭐

# ①-a 워커 노드에서
unzip sla-shooter-2026.08.11-k3s-agent-airgapped.zip
cd sla-shooter
sudo ./install.sh        # 이미지 import 후, 남은 명령을 노드 이름과 함께 출력한다

# ①-b control-plane 노드에서 (같은 zip 을 두고)
NODE_NAME=<워커 노드 이름> sudo ./scripts/deploy.sh

각 zip 안의 QUICKSTART.md 에 그 변종의 절차만 적혀 있다. install.sh 는 어느 zip 이든 실제 노드 종류를 스스로 감지해 맞게 동작하고, zip 변종과 노드가 다르면 그 사실을 알려준다 — 잘못된 zip 을 풀어도 잘못 설치되지는 않는다.

install.sh 는 agent 노드임을 스스로 감지해서 ② 를 건너뛰고 안내만 한다. kubeconfig 를 워커로 가져오면 한 번에 끝낼 수도 있다: KUBECONFIG=/root/k3s.yaml sudo -E ./install.sh

노드 고정이 필수다. 이미지는 import 한 노드에만 있으므로 Deployment 에 nodeSelector 가 걸려 있고, 설치 스크립트가 그 노드에 라벨 (sla-bench.starfort.io/shooter=true)을 붙인다. 고정하지 않으면 파드가 이미지 없는 노드로 스케줄되어 ErrImageNeverPull 로 죽는다. 결과 PVC(local-path)도 노드 로컬이라 고정은 결과 보존에도 필요하다.

접속은 NodePort 30001 — 파드가 어느 노드에 있든 아무 노드 IP 로 들어갈 수 있다: http://<any-node-ip>:30001/. 브라우저가 다른 호스트면 방화벽/보안그룹에서 30001/tcp 를 열어야 한다.

⚠ 30001 은 사내 OpenAI-adapter(Portico) 번들이 쓰는 범위(30001–30100)와 겹친다. 한 클러스터에 둘 다 올리려면 한쪽 nodePort 를 옮겨야 한다 (k8s/30-service.yaml).

🌐 외부 Guardian 호출 (아웃바운드)

측정 대상이 외부 인스턴스의 Starfort Guardian API 라면, "에어갭"은 설치에 인터넷이 필요 없다는 뜻이고 측정은 당연히 그 대상에 닿아야 한다. 파드에서 확인:

sudo k3s kubectl -n sla-bench exec deploy/sla-shooter -- \
  python -c "import socket;print(socket.gethostbyname('<guardian-host>'))"

이름이 안 풀리면 coredns 나 사내 DNS 문제다(급하면 Base URL 에 IP 를 직접 넣고 Verify TLS 를 끈다). UI 의 Test connection 이 이 전부를 한 번에 확인해 준다.

📊 측정 — 엔드포인트와 키만

1. Target — Base URL 과 API key 입력. 배포처가 준 curl 의 전체 URL 을 그대로 붙여넣어도 된다 (/v1/guard/api 가 붙어 있으면 알아서 떼어낸다).

2. Test connection — 닿는지 · 키가 먹는지 · 응답 모양을 읽을 수 있는지 확인.

3. Datasets — 이미지에 이미 들어 있다. 생성 단계 없음:

   데이터셋	프롬프트	토큰	무엇을 재는가
   pii-phone-200 / -1K / -5K	3,000 / 2,000 / 1,000	200 / 1,000 / 5,000	탐지가 걸리는 경로(게이트+추출)의 지연
   no-pii-200 / -1K / -5K	3,000 / 2,000 / 1,000	200 / 1,000 / 5,000	탐지가 걸리지 않는 경로 — 그 길이의 바닥값

   같은 토큰 길이로 둘을 짝지어 돌리면, 두 P95 의 차이가 곧 탐지 작업의 비용이다.

4. Start run — 동시 사용자를 1 → 4 → 8 → 16 → 32 로 올리며 잰다.

5. Results — 리포트를 보고 .zip(리포트 + config + 스테이지별 CSV 전량) 다운로드.

리포트는 지연만 다룬다: 데이터셋별 baseline P95 · SLA 한도 · 프론티어(P95 가 한도 안에 머문 최대 동시성) · 스테이지별 P50/P95/×u1/P99/max · 오류율 · 처리량 안정도.

⏱ 측정 요청에는 타임아웃이 없다

Guardian 이 3분을 쓰면 3분으로 기록된다. 느린 응답을 잘라 실패로 세면 P95 가 "살아남은 요청만의 통계"가 되어, 정작 SLA 를 못 지키는 구간이 가장 빨라 보이는 역설이 생긴다.

무엇	기본값
측정 요청	무제한 (LOCUST_TIMEOUT_S=<초> 로만 굳이 상한을 걸 수 있다)
스테이지 종료 후 드레인	max(60s, P95한도×6) · u1 구간 300s — 창이 닫혀도 진행 중 요청은 끝까지 기다렸다 기록한다
Test connection / sanity check	connect 10s + read 600/300s (0 = 무제한)
브라우저 ↔ shooter	없음 — 런은 백그라운드, 탭을 닫아도 계속된다

🔐 보안

• API 키는 디스크에 쓰이지 않는다. 그 런의 프로세스 환경에만 있고, 모든 산출물 (config.json·리포트)에는 sf_a…15 (67 chars) 처럼 마스킹된 형태로만 남는다.
• UI 는 기본적으로 인증이 없다(사내망 전제). 토큰을 걸려면 zip 안 secret.example.yaml 을 참고해 Secret 을 만들고 k8s/20-deployment.yaml 의 SHOOTER_TOKEN 주석을 푼다. 보기 전용은 SHOOTER_READONLY=1.
• 런은 한 번에 하나. 두 런이 같은 배포를 동시에 때리면 서로의 부하를 자기 동시성인 줄 알고 재게 된다 — 스케일링 누락이 아니라 측정 정합성이다.

🧰 업데이트 / 제거 / 결과 반출

sudo ./scripts/update.sh                      # 새 zip 을 풀고 실행 — 결과 PVC 보존
sudo ./scripts/uninstall.sh                   # 앱만 제거, 결과는 남김
KEEP_RESULTS=0 sudo ./scripts/uninstall.sh    # 결과·네임스페이스까지 제거
./scripts/results.sh                          # 브라우저 없이 결과를 tar 로 꺼내기

🩺 자주 걸리는 것

증상	조치
파드가 ImagePullBackOff	이미지 import 를 건너뛴 것. imagePullPolicy: Never 는 의도적이다 — 당길 레지스트리가 없다
PVC 가 Pending	local-path storageClass 가 없다. k3s kubectl get sc 로 확인 후 k8s/10-pvc.yaml 수정
kube-system 파드까지 전부 ContainerCreating + blob not found	노드의 containerd 콘텐츠 저장소가 깨진 것. sudo systemctl stop k3s && sudo rm -rf /var/lib/rancher/k3s/agent/containerd && sudo systemctl start k3s 후 재설치
Test connection 이 read timeout	배포가 그만큼 느린 것. 측정 요청엔 타임아웃이 없으니 실측은 가능하다. PROBE_READ_TIMEOUT_S 를 올리면 된다

자세한 런북은 zip 안의 INSTALL.md (설치 · 방화벽 · 측정 · 타임아웃 · 문제해결 · 업데이트/제거 · 재빌드).

🛠 재빌드

guardian-benchmark 레포에서 한 줄:

./shooter/build.sh --bundle
# → shooter/dist/sla-shooter-2026.08.11-{k3s,k3s-agent}-airgapped.zip + SHA256SUMS.txt

데이터셋 생성만 HuggingFace 토크나이저를 받아야 하므로 네트워크가 되는 쪽에서 빌드한다(seed 42 고정 — 어느 머신에서 만들어도 같은 파일). 그래서 이미지에 구워 넘긴다.