본문으로 건너뛰기

Intel Platform — Collector API Key 운영자 가이드

Intel Platform 의 8개 collector 가 외부 API 호출에 사용하는 키를 Vault → External Secrets Operator (ESO) → K8s Secret → gend-api Pod env 경로로 주입하는 방법입니다.

현재 prod 실제 상태 (2026-07-21 확인)
  • ESO 경로가 아직 적용돼 있지 않습니다 — intel-collector-keys ExternalSecret 리소스가 prod 에 없고, 동명의 K8s Secret 은 수동 생성본입니다. 즉 아래 §1 대로 Vault 만 갱신하면 Pod 에 반영되지 않습니다. ESO 를 적용(§2)하기 전까지는 kubectl patch secret intel-collector-keys 로 K8s Secret 을 직접 갱신 후 §3 재시작이 실효 경로입니다.
  • 8개 키 중 실값은 GEND_FRED_API_KEY, GEND_SEC_USER_AGENT (+별도 Secret 의 GEND_DART_API_KEY) 뿐이며 ECOS/NAVER/POLYGON/YOUTUBE/KIPRIS 는 빈 문자열 — 해당 collector 소스는 키 발급·주입 전까지 실행 불가입니다.
IntelSource.vault_secret_path 필드 규약

소스별 vault_secret_path 로 Vault 를 직접 참조시키는 경우, resolver 는 해당 KV2 secret 안의 api_key 필드를 읽습니다 (services/intel/vault_resolver.py). 본 문서의 공유 경로(secret/gend/intel-collector-keys)처럼 GEND_* 필드명으로 저장된 secret 을 가리키면 해석에 실패해 항상 env fallback 됩니다. per-source Vault 참조를 쓰려면 secret/intel/<collector>/<source_id> 경로에 api_key=<값> 필드로 저장하세요.

키 매트릭스​

Collectorenv var발급처가이드
dartGEND_DART_API_KEYopendart.fss.or.kr회원가입 → API 키 발급 (무료)
sec_edgarGEND_SEC_USER_AGENT(자체)"이름 email@example.com" 형식 — SEC 요구. 키 발급 아님
fredGEND_FRED_API_KEYresearch.stlouisfed.org/docs/apiAPI key request 무료
ecosGEND_ECOS_API_KEYecos.bok.or.kr한국은행 ECOS API key
naver_newsGEND_NAVER_CLIENT_ID + GEND_NAVER_CLIENT_SECRETdevelopers.naver.comNaver 검색 API 신청
polygonGEND_POLYGON_API_KEYpolygon.io무료 tier 가능 (한도 5 req/min)
youtubeGEND_YOUTUBE_API_KEYconsole.cloud.google.comYouTube Data API v3 활성화 + 키 발급
kiprisGEND_KIPRIS_API_KEYkipris.or.krKIPRIS plus 신청

rss, pykrx 는 키 불필요 (공개 스크래핑).

권장 경로 — admin UI 에서 키 관리 (#2460)​

/admin/intel-sources 페이지의 "수집기 API 키" 섹션에서 kubectl 없이 키를 설정합니다:

수집기 API 키 패널 (prod 실화면) — collector 별 사용 소스 배지와 키 설정/회전 버튼

  1. 대상 collector 행의 키 설정(또는 회전) 클릭 → 발급받은 키 입력 → 저장
  2. 키는 DB 에 Fernet 암호문으로 저장되며 (GEND_PROVIDER_KEY_ENC_KEY 마스터키, #1853 과 공유) pod 재시작 없이 즉시 수집에 반영됩니다
  3. 저장 후에는 말미 4자 힌트만 표시 — 원문은 어떤 화면/API 에도 다시 노출되지 않습니다
  4. "사용 소스" 배지: DB (UI 관리) > 환경변수 > 미설정 — 키 해석 순서는 DB → IntelSource.vault_secret_path → env 입니다

삭제 시 env/Vault 폴백으로 동작하며, 폴백이 없으면 해당 collector 는 실행되지 않습니다.

naver_news 는 2-credential — 키 다이얼로그에서 CLIENT_ID + CLIENT_SECRET 를 함께 입력합니다 (#2499 부터 둘 다 UI 관리, 최초 설정 시 SECRET 필수·이후 키만 회전 가능). 한계: Dagster 자산 중 env 를 직접 읽는 intel_ohlcv_minute/intel_trades (Polygon 분봉·체결, 현재 미가동) 는 env 경로가 필요합니다.

레거시 경로 — K8s Secret/env 주입​

아래 절차는 UI 도입 전 방식이며, env 폴백을 쓰거나 UI 를 쓸 수 없는 환경에서만 필요합니다.

1. Vault 에 키 등록​

# AKS prod
kubectl --context aks-genos-prod exec -n gend vault-0 -- sh
vault login <root-token>

vault kv put secret/gend/intel-collector-keys \
    GEND_SEC_USER_AGENT="GenD Intel <ops@example.com>" \
    GEND_FRED_API_KEY="..." \
    GEND_ECOS_API_KEY="..." \
    GEND_NAVER_CLIENT_ID="..." \
    GEND_NAVER_CLIENT_SECRET="..." \
    GEND_POLYGON_API_KEY="..." \
    GEND_YOUTUBE_API_KEY="..." \
    GEND_KIPRIS_API_KEY="..."

일부 키만 발급된 경우 — Vault path 에 일부 키만 PUT 해도 됨. ESO 는 missing key 시 해당 entry fail. IntelSource 인스턴스화 시 ValueError("...API key 필요") 발생 — Prometheus 알람 가능.

2. ExternalSecret 적용​

kubectl apply -f infra/external-secrets/intel-collector-keys-externalsecret.yaml

ESO 가 1분마다 Vault polling → K8s Secret intel-collector-keys 생성.

3. gend-api 재시작 (env 픽업)​

kubectl rollout restart deploy/gend-api -n gend
kubectl rollout status deploy/gend-api -n gend --timeout=120s

4. 검증​

POD=$(kubectl get pod -n gend -l app=gend-api -o name | head -1 | cut -d/ -f2)
kubectl exec -n gend "$POD" -c gend-api -- bash -c 'env | grep -E "GEND_(SEC|FRED|ECOS|NAVER|POLYGON|YOUTUBE|KIPRIS)" | sed "s/=.*/=***/"'

8개 env 확인되면 IntelSource row 의 collector_type 에 따라 자동으로 픽업됩니다.

IntelSource 등록​

키 주입 완료 후 collector 별 IntelSource row 를 등록해야 Dagster sensor 가 실제 실행:

-- 예: SEC EDGAR 분기보고서
INSERT INTO intel_sources (id, name, collector_type, domain, params_json, schedule_cron, enabled, last_status)
VALUES (gen_random_uuid(), 'sec-edgar-10k', 'sec_edgar', 'filings',
        '{"form_types": ["10-K", "10-Q"]}', '0 */2 * * *', true, 'idle');

또는 UI /admin/intel-sources 에서 등록합니다 (admin 전용 — Intel 수집기 관리 참조).

financials 도메인은 corp_codes 필수

domain='financials' (DART 재무제표) 소스는 params_json 에 8자리 DART 고유번호를 반드시 지정해야 합니다 — 누락 시 매 실행이 ValueError 로 last_status=failed 가 됩니다 (2026-07 prod 에서 1개월+ 방치된 실사례).

{"corp_codes": ["00126380", "00164779", "00266961", "00877059"]}

(예시는 삼성전자·SK하이닉스·NAVER·삼성바이오로직스. 고유번호는 DART corpCode API 또는 기존 intel_filings.corp_code 값에서 확인.)

corp_codes 설정으로 수집→Bronze(iceberg.bronze.intel_financials_raw) 까지 동작합니다. Silver intel_financials 반영은 financials 전용 normalizer 구현(#2459) 전까지 미지원 — 조회는 Trino Bronze 테이블 사용.

Troubleshooting​

증상원인조치
intel-collector-keys Secret 없음Vault path 미등록 또는 ESO 가 sync 안 함kubectl describe externalsecret -n gend intel-collector-keys
Pod env 에 키 없음gend-api 재시작 안 함kubectl rollout restart deploy/gend-api -n gend
ValueError: collector 는 API key 필요Vault entry 누락해당 키만 vault kv patch 로 추가
IntelSource last_status=failedcollector 인증 거부 / 키 만료kubectl logs deploy/gend-api -n gend | grep -i intel

참고​