제어 평면은 하나의 Go 바이너리, olivares이며, serve 하위 명령의 소수의 플래그와 몇 가지 환경 변수로 구성됩니다 — 방대한 구성 파일이 아닙니다. 기본값은 기본 거부(fail closed)로 선택됩니다: 루프백 바인드, 기본 TLS, 제공되는 자격증명 없음. 아래 모든 것은 바이너리 자체의 명령 정의와 구성 루트에서 가져왔습니다; 소스에서 확인할 수 없는 설정은 여기에 나열되지 않습니다.
실제 소스를 배선하고 실제 키를 관리하는 시크릿은 환경 변수로 참조되는 운영자 보유 파일이나 마운트된 시크릿에 남습니다 — 스토어에 절대 저장되지 않습니다. 실행 가능한 종단간 경로는 자체 호스팅 가이드를 참조하세요; 전체 플래그 목록은 CLI 참조를 참조하세요.
serve 하위 명령
olivares serve는 REST/웹 HTTP 서버와 gRPC 서버를 하나의 프로세스에서 실행하며, 웹 콘솔은 API와 동일 오리진에서 제공됩니다. 일반적인 구성 입력입니다.
| 플래그 | 기본값 | 목적 |
|---|---|---|
--listen | 127.0.0.1:8443 | HTTP 리슨 주소 (REST API + 내장 웹 콘솔). |
--grpc-listen | 127.0.0.1:8444 | gRPC 리슨 주소 (제어 평면 / 수집기 수집). |
--data-dir | $OLIVARES_DATA_DIR 또는 ./olivares-data | 감사 서명 키, TLS 자료, SQLite의 경우 스토어 파일. |
--engine | sqlite | 스토어 엔진: sqlite 또는 postgres. |
--dsn | 비어 있음 (데이터 디렉토리의 SQLite 파일) | 스토어 연결 문자열. |
--checkpoint-interval | 1h | 모든 테넌트 체인에 대해 서명된 감사 체크포인트가 기록되는 빈도. 0으로 비활성화. |
--insecure | 꺼짐 | 평문 HTTP/gRPC 제공. 로컬호스트 개발 전용. |
--seed-demo | 꺼짐 | 합성 샘플 환경 로드. 비루프백 바인드에서 시작 거부. |
TLS는 기본적으로 켜져 있습니다. --tls-cert/--tls-key가 제공되지 않으면 엔진이 데이터 디렉토리에 자체 서명 인증서를 한 번, 사전에 — 리스너가 연결을 수락하기 전에 — 보장하므로 HTTP와 gRPC 서버 모두 동일한 인증서를 사용하며 어느 쪽도 평문으로 폴백하지 않습니다. 인증서 생성 시 SHA-256 지문을 로깅하여 클라이언트가 신뢰하거나 고정할 수 있습니다.
--insecure가 평문을 제공하는 유일한 방법이며, gRPC 경로는 **기본 거부(fail closed)**합니다: --insecure 외에서 서버는 조용히 저하하지 않고 평문 리스너 구성을 거부합니다. 로컬 개발 중 127.0.0.1에 대해서만 사용하세요.
--seed-demo는 공개, 소스 트리 비밀번호의 데모 관리자와 조작된 환경 데이터를 프로비저닝합니다 — 데모와 E2E 전용. 어느 리스너라도 비루프백이면 엔진이 시작을 거부합니다. 일회용 데이터 디렉토리를 사용하세요.
분산 및 상호 TLS 토폴로지를 거버넌스하는 두 번째 계층의 플래그 — --admin-dsn과 --allow-privileged-db-role (Postgres), --grpc-client-ca (수집기 상호 TLS), --region/--known-regions (데이터 잔류) — 는 아래에서 다루며 CLI 참조에서 전체 목록을 확인하세요.
환경 변수
엔진은 부팅 시 소수의 환경 변수를 읽습니다. 아래 것들은 구성 루트와 배선에서 확인되었습니다.
데이터 디렉토리와 소스
| 변수 | 효과 |
|---|---|
OLIVARES_DATA_DIR | --data-dir이 주어지지 않을 때 기본 데이터 디렉토리 (./olivares-data로 폴백). 감사 서명 키, TLS 자료, SQLite 스토어 파일을 보유. 재시작 간 유지. |
OLIVARES_SOURCES_CONFIG | 엔진이 시작되기 전에 실제 관찰 소스, 신원 로스터 제공자, 지식 문서 소스를 배선하는 JSON 파일 경로. |
OLIVARES_SOURCES_CONFIG는 비데모 신호 소스와 로스터 제공자가 해결되는 단일 입력입니다. 운영자의 시크릿 보유 구성이며 의도적으로 스토어 밖에 유지됩니다. 엔진은 부팅 시 이를 읽고 런타임 시작 전에 모든 소스를 등록합니다.
처리는 fail-fast가 아닌 정직합니다. 누락된 변수, 읽을 수 없거나 유효하지 않은 JSON 파일, 구성되었지만 빈 소스 목록 모두 경고하고 빈 구성을 생성합니다 — 엔진은 부팅을 중단하지 않습니다. 구성되지 않은 소스는 크래시하거나 작동하는 척하지 않고 경고를 표면화합니다: 아무것도 배선되지 않으면 접근 맵은 단순히 비어 있습니다. 채우려면 최소 하나의 소스를 구성하세요 — 소스 연결과 협력적 Claude Code 경로는 Claude Code 연결을 참조하세요.
인가 결정 지점
네이티브 속성 기반 및 역할 기반 접근 제어가 항상 거버넌스합니다. 외부 정책 결정 지점(PDP)은 선택 시 내장 RBAC가 이미 내린 결정을 좁히기만 할 수 있는 추가 제한 전용 레이어입니다 — 절대 확대하지 않습니다.
| 변수 | 효과 |
|---|---|
OLIVARES_PDP_ENGINE | 외부 PDP 선택: cedar, opa, 또는 none (비어 있음/none = 네이티브 ABAC만). |
OLIVARES_PDP_CEDAR_FILE | Cedar 엔진: 운영자의 정책 파일 경로. |
OLIVARES_PDP_OPA_URL / _OPA_PATH / _OPA_TOKEN | OPA 엔진: Open Policy Agent 엔드포인트의 기본 URL, 결정 경로, bearer 토큰. |
두 어댑터가 하나의 심 뒤에 있습니다 — 임베디드 Cedar 평가기(순수 Go 경로)와 OPA-over-HTTP 어댑터. OLIVARES_PDP_ENGINE이 엔진을 선택하지만 구성이 유효하지 않으면(읽을 수 없는 Cedar 파일, 잘못된 형식의 OPA 대상), 엔진은 외부 PDP만 비활성화하고, 네이티브 ABAC 엔진과 RBAC 시행을 유지하며, 크게 로깅합니다. 깨진 정책 파일이 요청을 거버넌스 없이 남기거나 평면을 크래시시키지 않습니다. 기본 거부 모델은 거버넌스를 참조하세요.
감사 서명 키
감사 원장은 추가 전용, 해시 체인이며, Ed25519 서명 체크포인트로 앵커됩니다. 이벤트별 서명 키는 부팅 시 해결되며, 모든 관리된 소스에 대해 기본 거부(fail-closed)입니다.
| 변수 | 효과 |
|---|---|
OLIVARES_AUDIT_SIGNING_KEY | 고객 프로비저닝 서명 키, base64, 인라인. |
OLIVARES_AUDIT_SIGNING_KEY_FILE | 키를 보유한 마운트된 시크릿 경로 (선호 — 값이 프로세스 환경에 들어가지 않음). |
OLIVARES_KEY_CUSTODY | 선언된 관리 자세 (byok 또는 cmek). 실제 키 관리가 선언된 것과 일치하지 않는 부팅은 거부됨. |
이들이 모두 설정되지 않으면 키가 첫 부팅 시 데이터 디렉토리에 생성됩니다 — 정직한 단일 노드 / 개발 폴백. 복제본 간 하나의 키 공유(env 값이나 마운트된 시크릿을 통해)는 고가용성에 필수입니다: 그렇지 않으면 각 노드가 자체 키를 생성하고 장애 조치 시 원장이 포크됩니다. 이벤트별 서명은 항상 온박스에서 유지됩니다. KMS 래핑(고객 관리 키) 관리는 OLIVARES_KEY_WRAP을 통해 구성되는 추가 자세입니다; CLI 참조를 참조하세요.
스토어 선택
엔진은 --engine에서 스토어를 선택합니다.
| 엔진 | 사용 시기 | 참고 |
|---|---|---|
sqlite (기본값) | 단일 바이너리, 단일 노드, 에어갭 설치. | 순수 Go 내장 스토어, 외부 의존성 제로. --dsn 없이 스토어 파일은 데이터 디렉토리에 위치. |
postgres | 멀티테넌트 및 스케일아웃 배포. | 행 수준 보안 테넌트 격리 추가. 최소 권한 애플리케이션 역할 필요. |
SQLite가 기본이며 외부 서비스가 필요 없습니다 — 단일 노드 토폴로지를 위한 에어갭 준비, 제로 의존성 스토어이며, 한 명령 Docker Compose 배포가 실행합니다. 멀티테넌트 격리나 수평 스케일이 필요할 때 Postgres로 이동하세요, 그 전에는 아닙니다.
postgres를 선택하면 테넌트를 격리하는 행 수준 보안 백스톱을 옵트인합니다. 엔진은 Postgres 슈퍼유저 또는 BYPASSRLS 역할에 대해 시작을 거부합니다 — 해당 백스톱을 비활성화하게 되므로 — --allow-privileged-db-role이 명시적으로 가드를 재정의하지 않는 한(단일 테넌트 / 일회용만). 전체 교차 테넌트 System 읽기(조직 목록, 멀티테넌트 체크포인트 커버리지)를 위해 --admin-dsn을 통해 전용 NOSUPERUSER BYPASSRLS admin 역할을 제공하세요; 없으면 해당 읽기가 RLS 제한되어 빈 결과를 반환할 수 있습니다. OLIVARES_DB_MAX_CONNS가 노드별 애플리케이션 풀을 제한합니다.
테넌시와 잔류
Postgres에서 단일 인스턴스는 구조적으로 멀티테넌트이며, 행 수준 보안이 각 테넌트의 데이터를 격리합니다. 데이터 잔류는 --region으로 위에 레이어됩니다.
- 단일 리전 (기본값,
--region없음): 잔류 시행 없음. - 리전 범위 (
--region eu,--region us, …): 인스턴스가 자체 리전에 고정된 테넌트만 서비스하며 교차 리전 접근을 기본 거부(fail-closed)로 거부합니다.--known-regions는 전체 배포에서 유효한 리전 코드를 나열합니다; 테넌트의 핀은 이 중 하나여야 하며, 잘못된 리전 구성은 스토어가 열리기 전에 부팅을 실패시킵니다.
감사 체크포인트
--checkpoint-interval은 모든 테넌트 체인에 대해 서명된 체크포인트가 기록되는 빈도를 제어합니다(기본 1h; 0으로 비활성화). 정상 종료 시 스토어가 닫히기 전에 최종 체크포인트가 기록되므로, 체인은 간격뿐 아니라 종료 시에도 앵커됩니다. 서명된 체인이 다운스트림에서 검증되는 방법은 릴리스 검증을 참조하세요.
보안 기본값
이 자세는 serve 외에 구성 없이 적용됩니다. 제품의 기본 자세이며 선택적 강화가 아닙니다.
| 영역 | 기본값 | 의미 |
|---|---|---|
| 자격증명 | 제공 안 됨 | 기본 사용자명이나 비밀번호 없음. 첫 부팅 시 사용자가 없으면 엔진이 단일 사용 설정 토큰을 생성하고 표준 출력에만 출력 — 로그에는 절대 출력하지 않음. |
| 전송 | 기본 TLS | HTTP와 gRPC가 TLS를 통해 제공; 제공되지 않으면 데이터 디렉토리에 자체 서명 인증서가 생성되고 지문이 로깅됨. |
| 바인드 주소 | 루프백 | --listen과 --grpc-listen이 127.0.0.1로 기본 설정. 오프호스트 도달 가능성은 의도적인 운영자 결정. |
| 평문 모드 | 꺼짐 | --insecure가 평문을 제공하는 유일한 방법이며, gRPC 경로는 기본 거부. 로컬호스트 개발 전용. |
| 데모 시딩 | 꺼짐 | --seed-demo는 꺼져 있으며 공개 비밀번호 데모 관리자를 생성하므로 비루프백 바인드를 거부. |
| 텔레메트리 홈 | 꺼짐 | 엔진은 전화하지 않음. 아웃바운드 연결은 구성한 소스에 대해서만 존재 — 이것이 제로 이그레스로 에어갭 제어 평면을 가능하게 함. |
루프백 바인드는 변경할 때까지 엔진이 오프호스트에서 도달할 수 없음을 의미합니다. 게시할 때 — Docker Compose에서 호스트 포트를 매핑하여 — TLS가 이미 켜져 있어 보호합니다; 게시된 바인드와 --insecure를 페어하지 마세요. 새 설치에서 엔진이 일회용 설정 토큰과 함께 FIRST-BOOT SETUP 블록을 표준 출력에 출력합니다(Compose에서 컨테이너 로그에서 읽음); 관리자가 이를 사용하여 첫 사용자를 생성한 다음 인증합니다.
제품이 무엇을 관찰하고, 어디서 거버넌스하고, 커버리지가 어디서 계층화되는지는 정직함과 한계를 읽으세요.