Template 플러그인 스캐폴드

Template 플러그인은 운영 대상 플러그인이 아니라 CE 플러그인 개발을 시작하기 위한 스캐폴드입니다. 새 리소스 플러그인을 만들 때 필요한 매니페스트, 스키마, 대시보드, 메트릭 카탈로그, 매핑팩, 알림 규칙, 관리형 수집 예시를 한 곳에 모아 둡니다.

특징

• resource_manager와 managed_metric_collector 기준 구현을 보여줍니다.
• 호스트 렌더링 대시보드, 모니터링 경로, 메트릭 경로, 매핑팩 경로 뼈대를 포함합니다.
• 플러그인이 소유하는 다국어 메시지, 스키마 메타데이터, 적합성 테스트 구조를 제공합니다.
• canonical live/history Diagnostic Finding 예제와 별도의 운영자 실행 갱신 액션을 포함합니다.
• 실제 제품 플러그인을 만들 때 식별자, 모듈 경로, 매니페스트, 경로 응답, 메트릭 수집기를 교체하는 기준점으로 사용합니다.

사용 전 확인

• 이 스캐폴드는 런타임 배포 대상이 아닙니다.
• 새 플러그인으로 복사한 뒤 PluginMap과 구현 인터페이스를 실제 기능에 맞게 줄이거나 확장합니다.
• 템플릿 샘플 메트릭은 예시이므로 실제 대상 시스템 수집 로직으로 교체해야 합니다.
• 비동기 작업 예시는 결과가 일회성이며 플러그인 재시작 시 사라져도 되는 경우에만 유지하고, 재개나 감사 보존이 필요하면 영속 저장소를 사용합니다.

운영 팁

• Core나 프론트엔드에 플러그인별 분기를 추가하기보다 스키마와 경로 기여 정보로 표현합니다.
• 메트릭 수집은 샘플 생산만 담당하고, 스케줄링과 원격 쓰기는 Core 경계를 사용합니다.
• Prometheus를 원격 쓰기 대상으로 검증할 때는 Prometheus를 --web.enable-remote-write-receiver 옵션으로 실행합니다.
• 새 플러그인은 README와 매뉴얼 소스를 함께 추가해 운영자가 기능 경계를 바로 확인할 수 있게 합니다.
• diagnostics/summary와 diagnostics/history는 읽기 전용으로 취급하고, diagnostics/summary/run은 명시적인 운영자 액션에서만 호출합니다.

메모리 기반 비동기 결과 예시

스캐폴드는 선택적으로 사용할 수 있는 두 가지 제한된 백그라운드 작업 형태를 제공합니다. 부수효과 작업은 실제 결과가 대상 시스템에 남으므로 짧은 완료 메타데이터만 보관합니다. 결과형 작업은 가벼운 상태 메타데이터보다 결과 페이로드를 먼저 만료시키며, sliding idle 만료, 절대 만료 상한, 개수/바이트 한도를 함께 적용합니다.

상태, 결과, 삭제 요청은 작업 ID와 리소스 인스턴스 ID를 함께 검증합니다. 결과가 상태 메타데이터보다 먼저 만료되면 result_available=false와 result_expired=true로 이를 명시합니다. 모든 내역은 플러그인 프로세스 메모리에만 존재하므로 플러그인을 재시작하면 사라집니다.

개발자가 교체해야 할 것

• 플러그인 ID, Go 모듈/패키지 경로, 매니페스트 설명, 구현 인터페이스 목록을 실제 플러그인에 맞게 바꿉니다.
• 설정 스키마는 대상 시스템 접속 정보와 민감 정보 필드를 중심으로 다시 정의합니다.
• 대시보드, 진단, 모니터링 경로는 실제 운영자가 볼 근거와 업무 흐름을 기준으로 재작성합니다.
• 메트릭 카탈로그와 매핑팩은 실제 익스포터/관리형 수집기가 제공하는 메트릭 이름과 라벨을 기준으로 작성합니다.
• 알림 규칙팩은 Core 가용성을 중복하지 않고 플러그인 도메인 위험만 다루도록 설계합니다.

문서 작성 기준

• README는 개발자와 운영 설계자가 기능 경계, 경로, 메트릭, 알림, 확장 경계를 확인하는 문서로 씁니다.
• 매뉴얼 소스는 최종 사용자와 운영자를 위한 설명으로, 화면에서 무엇을 보고 어떤 판단을 해야 하는지 서술합니다.
• 공통 플러그인 등록, 메트릭 소스 연결, RBAC 같은 절차는 Core 문서에 두고 매뉴얼에는 플러그인별 차이만 씁니다.
• 에디션별 확장이 필요하면 공통 동작과 확장 지점을 분리해 문서화합니다.