RustFS 플러그인

RustFS 플러그인은 RustFS 클러스터의 준비 상태, 노드와 드라이브, 용량, 요청 처리, 오브젝트 스캐너 및 백그라운드 힐링 상태를 읽기 전용으로 확인합니다.

주요 기능

• RustFS 상태 API와 관리 API를 이용해 생존 상태와 준비 상태를 구분합니다.
• 노드, 드라이브, 풀·세트 배치와 소프트웨어 버전을 조회합니다.
• 연결된 Prometheus 리소스를 통해 용량, 요청, 프로세스 및 스캐너 메트릭을 표시합니다.
• 스토리지, 스캐너 및 백그라운드 힐링 진단을 구조화된 근거로 제공합니다.
• 용량, 드라이브, 요청 지연 및 프로세스 재시작에 대한 관리 경보 규칙을 제공합니다.

등록 전 확인

1. Konduo 백엔드에서 접근 가능한 RustFS S3/API 주소를 준비합니다. 일반적인 API 포트는 9000입니다.
2. 진단, 토폴로지 및 소프트웨어 인벤토리를 사용하려면 /rustfs/admin/v3/info, /storageinfo, /scanner/status, /background-heal/status를 조회할 수 있는 액세스 키와 시크릿 키를 준비합니다.
3. RustFS 메트릭을 OpenTelemetry Collector 또는 다른 수집 경로를 통해 Prometheus가 수집하도록 구성합니다.
4. Konduo에 Prometheus 리소스를 등록하고 RustFS 리소스의 메트릭 소스로 연결할 준비를 합니다.
5. 자체 서명 인증서를 사용한다면 먼저 신뢰할 수 있는 CA 배포를 검토합니다. 인증서 검증 생략은 통제된 시험 환경에서만 사용합니다.

설정 항목

항목	필수 여부	기본값	설명
endpoint	필수	http://localhost:9000	Konduo 백엔드에서 접근 가능한 RustFS S3/API 기준 주소
timeout_seconds	선택	10	API 요청별 제한 시간이며 1~60초 범위
access_key	조건부	없음	읽기 전용 관리 API용 액세스 키이며 secret_key와 함께 설정
secret_key	조건부	없음	액세스 키와 짝을 이루는 시크릿 키
region	선택	us-east-1	AWS Signature Version 4 서명에 사용하는 리전
tls_insecure_skip_verify	선택	false	HTTPS 서버 인증서 검증 생략

localhost는 Konduo 백엔드가 실행되는 호스트 또는 컨테이너 자신을 가리킵니다. 브라우저에서 열리는 주소라도 백엔드 네트워크에서 접근할 수 없으면 연결 테스트와 진단은 실패합니다.

연결과 버전 호환성

access_key와 secret_key는 함께 설정해야 합니다. 두 값을 생략해도 공개 /health/ready 확인이 가능하며, 이 경로가 없는 1.0.0-alpha.83에서는 /health로 전환합니다. 관리 API 자격 증명이 없으면 관리 API 기반 진단, 토폴로지 및 소프트웨어 인벤토리는 사용할 수 없습니다.

관리 키에는 다음 경로의 조회에 필요한 최소 권한만 부여합니다.

• GET /rustfs/admin/v3/info
• GET /rustfs/admin/v3/storageinfo
• GET /rustfs/admin/v3/scanner/status
• POST /rustfs/admin/v3/background-heal/status

백그라운드 힐 상태 API는 조회 용도이지만 RustFS 프로토콜상 POST를 사용합니다. 플러그인은 수동 힐 시작 API를 호출하지 않습니다. RustFS 버전별 권한 이름이 로컬 문서로 확정되지 않은 경우 임의의 정책 이름을 사용하지 말고, 대상 RustFS 릴리스의 권한 문서에서 위 경로에 필요한 동작을 확인합니다.

1.0.0-alpha.83의 /health는 엔드포인트 생존 여부만 확인하며 별도의 준비 상태 결과를 제공하지 않습니다. 관리 자격 증명이 있으면 플러그인이 /info의 온라인 노드 상태를 추가 근거로 사용합니다. 자격 증명이 없으면 생존 상태가 정상이어도 준비 상태는 미확인으로 유지됩니다.

플러그인은 1.0.0-alpha.83의 직접 JSON 응답과 이후 릴리스에서 사용하는 info 래퍼 응답을 모두 처리합니다. Alpha.83에는 스캐너 상태 API가 없고 백그라운드 힐 상태 처리기가 구현되어 있지 않으므로 해당 진단은 RustFS를 업그레이드하기 전까지 사용 불가로 표시됩니다. 운영에 적용할 때는 대상 RustFS 버전으로 연결, 진단 및 메트릭 검증 절차를 수행합니다.

region은 SigV4 자격 증명 범위에 포함됩니다. RustFS 또는 앞단 프록시가 기대하는 리전과 다르면 올바른 키를 사용해도 403이 발생할 수 있습니다. 리전뿐 아니라 시스템 시각, 키 상태, 요청 호스트와 프록시의 경로 재작성 여부도 함께 확인합니다.

모니터링 준비

RustFS의 관측 메트릭을 Prometheus 호환 소스로 내보낸 뒤 해당 prometheus-plugin 인스턴스를 RustFS 리소스에 연결합니다. 플러그인은 rustfs-plugin-prometheus-pack-v1의 v4 매핑을 통해 최신 RustFS 메트릭과 1.0.0-alpha.83의 OTLP 메트릭 이름을 함께 지원합니다.

OpenTelemetry Collector의 Prometheus exporter에 namespace: rustfs를 설정하면 alpha.83이 내보내는 rustfs_* 계측 이름에 namespace가 한 번 더 붙어 rustfs_rustfs_*로 노출됩니다. v4 매핑은 namespace가 붙은 형태와 붙지 않은 형태를 모두 처리하지만, 새 구성에서는 불필요한 중복 접두어를 피하는 편이 이해하기 쉽습니다.

:8889/metrics 같은 Collector exporter 주소는 Prometheus가 수집할 대상이지 Prometheus 쿼리 API가 아닙니다. Prometheus가 이 주소를 수집하도록 설정한 뒤 그 Prometheus의 prometheus-plugin 인스턴스를 연결해야 합니다. 관리 API의 /rustfs/admin/v3/metrics 응답은 Prometheus 텍스트 수집 대상으로 사용하지 않습니다.

Alpha.83은 용량, 버킷·오브젝트, 요청 처리율 및 요청 지연 메트릭을 제공하지만 드라이브 상태와 스캐너 메트릭은 제공하지 않습니다. 누락된 시계열을 0으로 간주하지 않으며 관련 패널과 경보에는 데이터 없음이 표시됩니다.

등록 및 검증 절차

1. RustFS 리소스에서 endpoint, 요청 제한 시간과 보안 설정을 입력합니다.
2. 관리 API 기능을 사용할 경우 액세스 키, 시크릿 키와 서명 리전을 함께 입력합니다.
3. 연결 테스트를 실행합니다. 실패하면 저장을 반복하기 전에 응답 상태와 백엔드 로그의 실패 분류를 확인합니다.
4. 연결 테스트가 성공하면 리소스를 저장하고 요약 화면에서 마지막 점검 시각과 다음 갱신 시각이 움직이는지 확인합니다.
5. Alpha.83에서 상태가 미확인이면 관리 자격 증명을 설정한 뒤 /info의 온라인 노드 근거가 수집되는지 확인합니다.
6. Prometheus 대상 화면에서 Collector 또는 RustFS reporter 대상이 UP인지 확인합니다.
7. 해당 Prometheus 리소스를 RustFS의 메트릭 소스로 연결하고 용량과 런타임 패널에 최신 시계열이 표시되는지 확인합니다.
8. 스토리지 진단에서 노드·드라이브 배치와 용량이 관리 API 응답과 일치하는지 확인합니다.
9. 관리 경보 규칙을 검토하고 실제 증설 소요 시간과 지연 목표에 맞게 임계값을 조정합니다.

연결 테스트 성공, 상태 점검 성공, Prometheus 수집 성공은 서로 다른 검증입니다. 셋 중 하나의 성공을 나머지 경로의 정상 증거로 사용하지 않습니다.

운영 화면

• 요약: 핵심 지표와 준비 상태, 노드, 용량, 드라이브, 스캐너 및 힐링에 대한 조치 중심 점검 항목
• 용량: 원시·사용·가용 용량 비교와 드라이브별 사용률
• 워크로드: 오브젝트, 버킷별 사용량, 전체·실패 요청률 및 P95 지연
• 런타임: RustFS 프로세스 CPU 및 상주 메모리
• 스토리지 진단: 상태, 용량, 풀·세트·디스크 배치, 관측 최신성, 스캔·힐링 상태를 묶은 드라이브별 카드
• 스캐너 진단: 요약, 활성화·최신성 근거 카드 및 구조화된 현재 메트릭
• 백그라운드 힐링 진단: 상태, 대기열, 활성·재시도 작업, 실패 및 오브젝트 진행률을 보여주는 요약과 근거 카드
• 토폴로지: 클러스터 노드와 소속 드라이브 관계

진단 탭은 다른 기본 리소스 플러그인과 같은 핵심 지표, 요약 테이블 및 적층 근거 카드 패턴을 사용합니다. 스캐너와 백그라운드 힐링 응답을 구분되지 않은 원시 JSON으로 표시하지 않습니다.

경보 규칙

rustfs-alert-rules-v1은 다음 8개 규칙을 기본으로 활성화합니다.

규칙	심각도	기본 조건	지속 조건	우선 확인 항목
사용 가능 용량 사용률 높음	경고	15분 구간에서 85% 이상	10분	증가 추이, 수명 주기 정책, 증설 소요 시간
사용 가능 용량 사용률 심각	심각	5분 구간에서 95% 이상	3분	쓰기·힐링 여유 확보, 즉시 증설 또는 안전한 정리
드라이브 오프라인	심각	2분 구간에서 1개 이상	1분	노드, 디스크 경로, 파일시스템, 하드웨어, 힐링
드라이브 사용률 높음	경고	드라이브별 15분 구간에서 85% 이상	10분	드라이브 편차, 배치, 증설 여유
드라이브 사용률 심각	심각	드라이브별 5분 구간에서 95% 이상	3분	해당 드라이브의 쓰기·힐링 여유
요청 P95 지연 높음	경고	10분 구간에서 1초 이상	5분	요청량, 디스크, 스캐너·힐링, 네트워크
요청 P95 지연 심각	심각	5분 구간에서 3초 이상	2분	스토리지 포화, 네트워크 오류, 클라이언트 제한 시간
프로세스 반복 재시작	경고	30분 동안 2회 이상	1분	종료 사유, 메모리 압박, 스토리지 초기화 실패

일반 생존·준비 상태 경보는 Prometheus up이 아니라 Konduo Core의 직접 상태 및 런타임 점검이 담당합니다. Alpha.83에서 제공되지 않는 드라이브 메트릭은 경보 조건을 0으로 만들지 않고 데이터 없음으로 남습니다.

진단 결과 해석

상태 또는 근거	의미	다음 확인
생존 정상, 준비 상태 미확인	상태 경로는 응답하지만 준비 상태를 확정할 근거가 부족함	관리 자격 증명과 /info 온라인 노드 상태
관리 API 사용 불가	자격 증명이 없거나 권한·서명·버전 호환 문제가 있음	응답 상태, 서명 리전, 시스템 시각, API 경로와 RustFS 버전
드라이브 데이터 없음	대상 버전이 메트릭을 내보내지 않거나 Prometheus 매핑이 일치하지 않음	/storageinfo, Prometheus 원본 메트릭과 매핑 규칙
스캐너 또는 힐링 사용 불가	대상 버전에 상태 API가 없거나 처리기가 구현되지 않음	RustFS 버전과 해당 API 지원 여부
메트릭 근거 오래됨	RustFS 상태와 별개로 수집 또는 조회가 지연됨	Prometheus target, 수집 주기, 마지막 샘플 시각

미확인, 사용 불가, 데이터 없음은 정상 또는 0과 같은 의미가 아닙니다. 직접 API 상태와 시계열 수집 상태를 분리해 판단합니다.

대표 점검 절차

용량 경보가 발생할 때

1. 원시·사용·가용 용량과 사용 가능 용량 기준 사용률을 함께 확인합니다.
2. 드라이브별 사용률 편차와 오프라인 드라이브를 확인합니다.
3. 요청량, 오브젝트 증가, 스캐너와 힐링 활동이 같은 시각에 변했는지 비교합니다.
4. 쓰기와 힐링에 필요한 여유를 고려해 증설 또는 삭제 가능한 데이터 정리 시점을 결정합니다.

드라이브가 오프라인일 때

1. 스토리지 진단에서 영향받은 노드, 풀, 세트와 디스크 경로를 찾습니다.
2. 노드 상태, 마운트, 파일시스템, 하드웨어와 네트워크를 확인합니다.
3. 복구 후 백그라운드 힐링 대기열, 실패 및 진행률을 확인합니다.
4. 힐링이 끝나기 전에 용량 경보와 요청 오류가 함께 발생하는지 관찰합니다.

요청 지연이 증가할 때

1. 전체 요청률, 실패 요청률과 P95 지연을 같은 구간에서 비교합니다.
2. 드라이브 사용률, 오프라인 상태와 호스트 CPU·메모리를 확인합니다.
3. 스캐너 또는 힐링 활동과 지연 증가 시각을 비교합니다.
4. 네트워크 오류와 클라이언트 제한 시간을 확인한 뒤 병목 근거에 따라 조치합니다.

문제 해결

증상	확인 순서
연결 테스트가 400으로 실패	endpoint 형식과 필수값 조합을 확인하고, 브라우저 콘솔의 상태 코드만 보지 말고 API 응답 본문과 Konduo 백엔드 로그의 검증 오류를 확인
관리 API가 403을 반환	액세스 키·시크릿 키 조합, 서명 region, Konduo 백엔드와 RustFS의 시각 동기화, 프록시의 Host·경로 재작성, 대상 API 권한을 확인
리소스 상태가 미확인	Alpha.83의 /health 제한을 확인하고 관리 자격 증명으로 /info 온라인 노드 근거를 조회할 수 있는지 확인
모든 메트릭 패널이 비어 있음	Collector :8889/metrics를 Prometheus 리소스로 직접 등록하지 않았는지 확인하고 Prometheus target, RustFS 리소스와의 연결, 매핑팩 적용을 확인
rustfs_rustfs_*만 보임	Collector exporter의 namespace: rustfs로 접두어가 중복된 상태이며 v4 매핑 사용 여부를 확인하고 새 구성에서는 namespace 제거를 검토
일부 패널이나 경보만 데이터 없음	대상 RustFS 버전이 해당 메트릭을 제공하는지 확인하고 Prometheus의 실제 이름·라벨과 매핑 규칙을 비교
스캐너·힐링 진단이 사용 불가	Alpha.83의 API 미지원인지 확인하고 지원 릴리스로 업그레이드한 뒤 다시 실행
HTTPS 연결만 실패	인증서 체인과 서버 이름을 먼저 수정하고, 통제된 시험 환경에서만 인증서 검증 생략 사용

안전 경계

CE 플러그인은 조회만 수행합니다. 서비스 재시작·중지, 풀 변경, 버킷·오브젝트 변경, 수동 힐 시작 및 수명 주기 변경은 제공하지 않습니다. 진단 결과에는 액세스 키나 시크릿 키가 포함되지 않습니다.

---

RustFS Enterprise 확장

RustFS Enterprise 확장은 Community RustFS 리소스 플러그인에 다중 신호 이상징후 규칙과 읽기 전용 MCP 설명자를 추가합니다. 연결, SigV4 관리 조회, 상태 점검, 진단, 토폴로지, 메트릭, 대시보드 및 관리 경보 규칙은 계속 Community 플러그인이 소유합니다.

사용 전 확인

• Community RustFS 리소스 연결이 정상이어야 합니다. 운영 상세 정보가 필요하면 읽기 전용 관리 API 자격 증명을 설정합니다.
• RustFS 매핑 팩을 사용해 Prometheus 호환 메트릭 소스를 리소스에 연결해야 합니다.
• Enterprise 기능 mcp.gateway와 anomaly.engine이 활성화되어야 합니다.
• 이상징후 규칙 조회에는 viewer 역할과 rustfs-plugin.anomaly.read 권한이 필요합니다.
• MCP 호출자에게 허용된 MCP 읽기 범위와 대상 RustFS 리소스 인스턴스 접근 권한을 모두 부여해야 합니다.

선택적인 드라이브 상태 또는 스캐너 메트릭을 내보내지 않는 RustFS 릴리스에서는 관련 이상징후 규칙을 평가하지 않습니다. 누락된 시계열을 정상 또는 0으로 간주하지 않습니다.

이상징후 규칙

Enterprise 규칙 팩은 다음 여섯 가지 다중 신호 규칙을 제공합니다.

규칙 키	심각도/점수	평가 조건
rustfs.storage_resilience_cascade	심각/0.97	클러스터 용량 사용률 >= 85%이면서 오프라인 드라이브 > 0
rustfs.drive_imbalance_pressure	경고/0.86	클러스터 용량 사용률 < 85%이면서 개별 드라이브 사용률 >= 95%
rustfs.capacity_observation_gap	경고/0.79	오래된 드라이브 용량 관측값 > 0 또는 누락된 관측값 > 0
rustfs.request_path_degradation	심각/0.94	요청 실패율 > 0이면서 P95 지연 >= 1,000ms
rustfs.restart_failure_cascade	심각/0.92	최근 30분 프로세스 재시작 >= 1이면서 요청 실패율 > 0
rustfs.scanner_request_contention	경고/0.84	스캐너 오브젝트 처리율 > 0, 주기 시간 >= 3,600초, P95 지연 >= 1,000ms가 모두 충족

이 규칙은 장애 분류 근거입니다. 단일 시계열 관리 경보를 대체하지 않으며, 용량, 배치, 스캐너 부하 또는 프로세스 설정을 변경하기 전에 영향받은 노드, 드라이브, 요청 및 시간 범위를 확인해야 합니다.

MCP 리소스와 도구

MCP 카탈로그는 다음 12개 읽기 전용 리소스를 제공합니다.

• runtime_probe
• monitoring_overview
• diagnostics_summary
• diagnostics_storage
• diagnostics_scanner
• diagnostics_heal
• topology_summary
• metrics_catalog
• mapping_pack_catalog
• alert_rules
• anomaly_rules
• software_inventory

다음 11개 읽기 전용 도구를 제공합니다.

• runtime_probe
• monitoring_overview
• diagnostics_summary
• diagnostics_storage
• diagnostics_scanner
• diagnostics_heal
• topology_summary
• metrics_query_resolve
• mapping_pack_resolve
• alert_rules
• anomaly_rules

metrics_query_resolve는 필수 logical_metric_key와 선택 query_mode(instant 또는 range), instance_selector를 받습니다. mapping_pack_resolve의 선택 target_metric_source_plugin_id는 현재 prometheus-plugin만 허용합니다.

MCP는 서비스 제어, 버킷 또는 오브젝트 변경, 수동 힐링, 수명 주기 변경, 진단 새로 고침이나 자격 증명을 노출하지 않습니다.

운영 및 장애 대응

1. runtime_probe와 monitoring_overview에서 연결 상태, 메트릭 연결과 최신 수집 시각을 확인합니다.
2. 관리 경보와 이상징후 규칙을 함께 읽고 동일 시간 구간의 근거를 비교합니다.
3. 스토리지, 스캐너, 힐링 및 토폴로지 진단으로 영향받은 노드와 드라이브를 식별합니다.
4. metrics_query_resolve로 관련 논리 메트릭을 해석하고 원시 시계열을 확인합니다.
5. Konduo 외부에서 복구, 배치 또는 용량 변경을 수행하기 전에 진단 근거를 보존합니다.

이상징후 규칙이 보이지 않으면 Enterprise 라이선스와 anomaly.engine, 호출자의 rustfs-plugin.anomaly.read 권한을 확인합니다. MCP 카탈로그가 보이지 않으면 mcp.gateway, MCP 읽기 범위와 리소스 인스턴스 접근 권한을 확인합니다. 규칙이 평가되지 않으면 연결된 Prometheus 소스와 필요한 논리 메트릭을 확인합니다. 특히 드라이브 용량 관측과 스캐너 메트릭은 RustFS 릴리스에 따라 선택적일 수 있습니다.

에디션 경계

이상징후 규칙 팩, MCP 설명자 및 Enterprise 현지화는 Enterprise 오버레이에 둡니다. Community 플러그인은 이 상용 contribution 없이도 독립적으로 설치하고 사용할 수 있습니다.