프로젝트 소개

netbox-ceph는 netbox-proxbox의 형제 NetBox 플러그인입니다. 이 플러그인은 proxbox-api를 통해 Proxmox가 관리하는 Ceph 인벤토리를 미러링하며, netbox-proxbox의 백엔드 컨텍스트, 브랜치 수명 주기, 엔드포인트 관계 및 작업 컨벤션을 재사용합니다. v1 반영 인벤토리는 의도적으로 읽기 전용으로 설계되었습니다. 반영 인벤토리 (v1) 이 플러그인은 클러스터, 데몬, OSD, 풀, 파일 시스템, CRUSH 규칙, 플래그, 상태 확인, 플러그인 설정 및 읽기 전용 RGW/S3 및 RBD 반영 인벤토리를 제공합니다. 동기화는 POST /api/plugins/ceph/clusters/{id}/sync/를 통해 실행되며, 7200초의 타임아웃을 가진 CephSyncJob이 큐에 추가됩니다. resources 매개변수를 ["pools", "osds"]와 같은 리스트나 쉼표로 구분된 문자열로 전달할 수 있으며, 생략 시 기본 전체 동기화가 실행됩니다. 대기 중인 실행 내역은 NetBox의 핵심 Jobs UI에 표시됩니다. 희망 상태 제어 평면 (v2) Ceph v2는 별도로 게이트가 설정된 희망 상태 평면을 추가합니다. 여기에는 불변의 엔드포인트 및 구성 리비전 바인딩 플랜, 검증 결과, 2인 승인 감사 기록, 적용/복구 실행, 드리프트 기록, 메트릭 스냅샷 및 타입 지정된 proxbox-api 클라이언트가 포함됩니다. 원시 승인 토큰은 승인 응답과 직후의 적용 요청 사이에만 존재하며, NetBox에 의해 저장, 로그 기록, 직렬화 또는 렌더링되지 않습니다. 희망 상태 모델을 통해 운영자는 풀, CephFS, RBD 및 RGW/S3에 대해 NetBox 우선의 의도(크기, 자동 확장, CRUSH 규칙, 애플리케이션, 쿼터, 압축, CephFS 메타데이터/데이터 풀, MDS 배치, RBD 이미지 레이아웃/기능, RBD 스냅샷 보호, RGW 토폴로지, S3 사용자 및 버킷)를 선언할 수 있습니다. 이는 NetBox 소유의 의도 기록으로 유용하게 활용됩니다. 현재 strict proxbox-ceph-v2-2026-07 라이터는 풀과 CephFS 행에 대해서만 변이 생성을 허용합니다. 각 지원 행에는 정확한 execution_node가 필요하며, 풀 페이로드는 proxbox-api 이슈 #258에서 수용되는 필드로 제한되고, CephFS 생성은 pg_num 및 add_storage로 제한됩니다. RBD 및 RGW/S3 의도는 조회 가능하지만, 라이터 지원이 제공될 때까지 Generate 작업 액션은 의도적으로 제외되었습니다. 승인 흐름 및 권한 요청자는 커스텀 request 및 apply 권한을 보유해야 하며, approve 권한을 가진 다른 작업자가 오케스트레이터를 통해 단일 Approve & apply 작업을 수행합니다. 마이그레이션 0007_ceph_plan_bound_approvals는 레거시 권한을 폐지하고, 엔드포인트/프로바이더/노드/구성 스냅샷을 추가하며, 만료되는 승인 발행 리스를 생성하고, 승인당 하나의 로컬 실행을 강제합니다. 설치 pip install netbox-ceph로 설치하고, configuration.py의 PLUGINS에 "netbox_proxbox"와 "netbox_ceph"를 모두 추가한 후 평소와 같이 NetBox 마이그레이션을 실행하십시오. 범위 및 안전 주의사항 v1 범위 제외 사항: Ceph Dashboard API 직접 통합, Prometheus 메트릭 수집, 외부 비 Proxmox Ceph 클러스터, 반영 인벤토리에 대한 NetBox-to-Ceph 쓰기 작업. 셸 또는 직접적인 Proxmox API 폴백은 존재하지 않습니다. 권장 배포 순서: 일치하는 백엔드 계약을 먼저 배포하고, NetBox를 백업한 뒤 마이그레이션하고, request/apply/approve 권한을 신중하게 부여하며, 레거시 지원 의도에 정확한 실행 노드를 입력하고, 스테이징 환경에서 전체 흐름을 검증하십시오. 이러한 게이트와 인증된 actor-header 게이트웨이 제어가 완료될 때까지 모든 Proxmox 엔드포인트의 allow_writes 플래그를 비활성화 상태로 유지하십시오. 호환성 및 프로젝트 상태 저장소에는 Apache-2.0 라이선스, PyPI 메타데이터, 호환성 메타데이터, GitHub Actions CI, 릴리스 검증, 문서 게시, NetBox v4.6.4를 위한 스크린샷 캡처 및 페이지 커버리지 워크플로우가 포함되어 있습니다. Digest-pinned Docker 설치 스모크 테스트는 공식 NetBox v4.7.0 GA를 커버하며, 정확한 소스 통합 테스트는 하위 호환 가능한 v4.5.8에서 v4.6.6 범위를 커버합니다. NetBox v4.7.0 GA 메타데이터는 호환성 경고 없이 GA 기준으로 허용되지만, 4.7.1 및 이후 버전은 fail closed 처리됩니다. CI는 GA 소스 리비전 5f06007e4c9bacc93ce17c1e645fc1143d60df3d를 고정합니다. 전체 문서는 프로젝트 문서 사이트에 게시되어 있으며, 모델 및 필드 참조는 docs/models.md, 버전 표는 COMPATIBILITY.md, 인증 증거는 CERTIFICATION.md에서 확인할 수 있고, 버그 및 기능 요청은 GitHub Issues를 통해 처리됩니다.