org_id 조건으로 해당 조직에 범위가 지정됩니다. 대용량 이벤트와 평가가 저장되는 ClickHouse에서는 엔진 수준의 강력한 격리가 적용됩니다. 각 조직은 조직별 행 정책이 있는 전용 읽기 전용 ClickHouse 사용자를 가지므로, 신뢰할 수 없는 분석 SQL도 다른 테넌트의 행을 읽을 수 없습니다. PostgreSQL에서는 읽기 전용 쿼리 경로(/queries/run)에 행 수준 보안이 추가적인 방어 계층을 제공하여, 애플리케이션 수준 필터가 누락되더라도 해당 경로에서 볼 수 있는 데이터를 제한합니다. 서버의 쓰기 연결은 테이블 소유자로 실행되므로 동일한 앱 수준 org_id 범위 지정을 통해 작동합니다.
테넌트 생명 주기는 운영자가 관리하며, 멤버가 일상적으로 수행하는 모든 작업은 대시보드에서 셀프 서비스로 처리됩니다. 조직과 그 멤버십은 서버 이미지 내에 포함되어 기존 서버 파드 내부에서 실행되는 agenteye-orgctl CLI로 생성 및 관리됩니다. 테넌트 생성 및 삭제는 의도적으로 대시보드와 HTTP API에서 제외됩니다. 테넌트 생명 주기를 위한 HTTP API나 대시보드 버튼은 존재하지 않으며, 애플리케이션 표면이 아닌 클러스터/파드 셸 접근을 통해서만 수행할 수 있습니다.
조직 내에서 멤버는 대시보드와 API를 통해 모든 작업을 수행합니다. 로그인, 소속 조직 간 전환, 자신의 API 키 관리, 대시보드 및 저장된 쿼리 구성, 조직의 알림 설정 등이 가능합니다. 역할 구분이 명확합니다. 운영자는 CLI를 통해 테넌트와 멤버를 프로비저닝하고 해제하며, 멤버는 UI를 통해 테넌트 내의 모든 작업을 수행합니다.
단일 테넌트 배포에서는 이 내용이 필요하지 않습니다. 단일 테넌트 설치는 별도의 운영자 작업 없이 실행됩니다. 모든 데이터, 사용자, 키는 자동으로 프로비저닝되는 기본 default 조직에 저장됩니다. 두 번째 조직을 추가하려는 경우에만 이 가이드가 필요합니다.
사전 요구 사항
두 번째 조직을 생성하기 전에(기본 내장default 조직은 별도 작업 불필요):
- PostgreSQL 15+. 조직-멤버십 스키마는 PostgreSQL 15+에서 필요한 컬럼 목록
ON DELETE SET NULL외래 키를 사용합니다. 두 번째 조직을 프로비저닝하기 전에 PostgreSQL을 업그레이드하세요. - 강력하고 안정적인
ORG_CH_SECRET. 각 조직의 ClickHouse 비밀번호는HMAC(ORG_CH_SECRET, org_id)로 파생되므로, 공개적으로 알려진 기본 개발 값을 사용하면 조직별 자격 증명이 외부에 노출될 수 있습니다.agenteye-orgctl org create는ORG_CH_SECRET가 설정되지 않았거나 기본 개발 값으로 남아 있는 경우 실행을 거부합니다. 먼저 고유한 값을 설정하세요(배포 → 환경 변수 및 Kubernetes의 경우 Kubernetes 가이드 §2.6 참고). 모든 서버 레플리카에서 동일한 값을 유지하고 임의로 변경하지 마세요. 변경하면 다음 시작 시 재프로비저닝될 때까지 모든 조직의 ClickHouse 사용자가 고아 상태가 됩니다.
CLI 실행
agenteye-orgctl은 서버와 동일한 이미지에 포함됩니다(agenteye-server와 함께). 별도의 파드, Job, 또는 Deployment를 배포할 필요가 없으며, 이미 실행 중인 서버 파드 내부에서 exec으로 실행합니다. 따라서 서버가 사용하는 것과 동일한 DATABASE_URL, CLICKHOUSE_URL, ORG_CH_SECRET을 읽습니다.
Kubernetes:
agenteye-orgctl <args> 형태로 표시합니다. 실제 사용 시 배포 환경에 맞게 위의 두 줄 중 하나를 앞에 붙이세요.
명령어 참조
조직
| 명령어 | 설명 |
|---|---|
org create --slug <slug> --name <name> | 새 조직을 생성합니다. ORG_CH_SECRET이 설정되지 않았거나 기본 개발 값으로 남아 있는 경우 실행을 거부합니다(먼저 고유한 값을 설정하세요, 사전 요구 사항 참고). 조직의 읽기 전용 ClickHouse 사용자와 행 정책을 프로비저닝합니다. |
org list | 모든 조직(slug, 이름, 생명 주기 상태)을 나열합니다. |
org rename --slug <slug> --name <new name> | 조직의 표시 이름을 변경합니다. URL과 키에 사용되는 slug는 변경되지 않습니다. |
org delete --slug <slug> | 조직을 소프트 삭제하고 ClickHouse 사용자를 삭제합니다. 데이터는 보존됩니다. 접근 권한을 취소하고 조직별 ClickHouse 자격 증명을 해제하지만, 이벤트를 삭제하지는 않습니다. 운영자가 되돌릴 수 있으며, 삭제 전 안전한 첫 번째 단계입니다. |
org purge --slug <slug> | 되돌릴 수 없는 데이터 삭제. 조직이 이미 delete 상태여야 합니다. 기본 내장 default 조직에는 절대 허용되지 않습니다. 테넌트의 데이터를 완전히 삭제해야 할 때만 사용하세요. |
멤버
| 명령어 | 설명 |
|---|---|
member add --org <slug> --email <email> [--set <permission-set>] [--add perm1,perm2] [--remove perm3] [--protected] | 조직에 멤버를 추가합니다. 선택적으로 기본 제공 권한 세트에서 시작하여 개별 권한을 추가/제거할 수 있습니다. --protected는 대시보드에서 멤버를 제거하거나 권한을 낮출 수 없도록 고정합니다(아래 참고). 새 멤버는 첫 번째 대시보드 로그인 시 OTP를 받습니다. |
member list --org <slug> | 조직의 멤버를 나열합니다. 출력 컬럼은 EMAIL, SET(멤버가 시작한 기본 제공 세트, 또는 -), PROT(멤버의 보호 여부), PERMISSIONS(유효 권한)입니다. 이메일 뒤에 *가 표시된 경우 인스턴스 관리자로 모든 조직에 접근할 수 있습니다. |
member update --org <slug> --email <email> [--set ...] [--add ...] [--remove ...] [--protected | --unprotect] | 멤버의 권한 및/또는 보호 플래그를 변경합니다. --set은 기본 제공 세트로 대체하고, --add / --remove는 개별 권한을 조정하며, --protected / --unprotect는 보호를 전환합니다. --protected/--unprotect만 전달하면(권한 플래그 없이) 보호만 변경되고 기존 권한은 그대로 유지됩니다. |
member remove --org <slug> --email <email> | 조직에서 멤버를 제거합니다. 멤버가 보호 상태인 경우 거부됩니다. 먼저 --unprotect를 적용하세요. (한 사람이 여러 조직의 멤버일 수 있으며, 이 명령은 지정된 조직에만 영향을 줍니다.) |
보호된 멤버 (제거 불가능한 조직 관리자)
보호 기능은 조직이 실수로 자기 관리 권한을 잃지 않도록 보장합니다. 기본적으로 조직의 관리자는 대시보드의 셀프 서비스 사용자 페이지에서 서로를 추가하고 제거할 수 있으므로, 마지막 관리자를 제거하여 관리할 수 있는 사람이 없는 조직이 될 수 있습니다.
member update --org acme --email owner@acme.example --unprotect를 실행한 후 제거하거나 권한을 낮추세요. 이를 통해 모든 조직에 조직 멤버가 잠글 수 없는 최소 하나의 관리자가 유지되면서, 테넌트 제어는 운영자 전용으로 유지됩니다. 보호는 조직별로 적용되며, 한 조직에서 누군가를 보호해도 다른 조직의 멤버십에는 영향을 주지 않습니다.
기본 제공 권한 세트
--set은 조직별로 적용되는 세 가지 기본 제공 세트 중 하나를 허용합니다:
| 세트 | 대상 |
|---|---|
admin | 조직 내 전체 접근 권한. 조직의 API 키와 사용자 관리를 포함합니다. |
standard | 일상적인 사용: 쿼리 읽기 및 실행, 대시보드 구성, 인시던트 확인. |
read-only | 조직의 데이터와 대시보드에 대한 보기 전용 접근. |
--set으로 세트를 선택한 후, API Keys에 나열된 개별 권한 토큰을 사용하여 --add / --remove로 세부 조정하세요. 권한 토큰은 API 키에 사용되는 것과 동일합니다.
실습 예시
새acme 테넌트를 프로비저닝하고, 첫 번째 관리자를 추가하고, 키를 발급한 후 조직을 해제합니다.
1. 조직 생성 (ORG_CH_SECRET이 설정되지 않았거나 기본 개발 값이 아닌 강력하고 안정적인 값으로 미리 설정되어야 합니다):
/acme/sessions) 아래에서 UI를 통해 모든 작업을 수행합니다.
3. 조직별 API 키 발급 (대시보드에서):
운영자는 CLI에서 조직별 데이터 키를 발급하지 않습니다. Alice(또는 keys:create 권한이 있는 조직 멤버)가 대시보드의 Keys 페이지에서 acme 조직의 수집기/대시보드 키를 생성합니다. 그녀가 생성하는 모든 키는 자동으로 해당 조직으로 스탬프가 찍히며, acme의 데이터만 읽거나 쓸 수 있습니다. API Keys를 참고하세요.
4. 나중에 멤버 조정:
default 조직 불가):
kubectl -n agenteye exec deploy/server -- 접두사를 docker compose exec server로 대체하세요.
책임 분담
조직 멤버가 일상적으로 필요한 모든 것은 대시보드와 API에서 셀프 서비스로 제공되며, 현재 조직으로 자동 범위가 지정됩니다:- 조직별 API 키는 대시보드에서 조직 멤버가 생성하고 관리합니다(또는
keys:create를 가진 키를 사용하여 키 API를 통해). CLI는 데이터 키를 발급하지 않습니다. API Keys를 참고하세요. - 조직 전환은 대시보드에 내장되어 있으며, 멤버는 조직 전환기에서 소속 조직 간에 전환할 수 있고, 조직 범위의 페이지는
/<org-slug>/…아래에 있습니다. - 대시보드, 저장된 쿼리, 알림, 모든 데이터 사용은 UI와 API에서 전적으로 이루어지며, 멤버의 현재 조직으로 범위가 지정됩니다.
agenteye-orgctl을 사용하는 운영자는 조직 + 멤버 생명 주기만 소유합니다. 조직 생성/이름 변경/삭제/퍼지, 멤버 추가/나열/업데이트/제거가 해당됩니다.
참고 항목
- 배포:
ORG_CH_SECRET및 기타 서버 환경 설정. - Kubernetes 배포: §2.6에서 첫 번째 멀티 테넌트 조직 전에
agenteye-org-ch-secretSecret을 생성합니다. - API Keys: 조직별 키 모델과
--add/--remove에 사용되는 권한 토큰. - 문제 해결: 멀티 테넌트 프로비저닝 및 ClickHouse 격리 문제.