KVM MCP 서버

간단하고 직관적인 인터페이스를 통해 KVM 가상 머신을 관리할 수 있는 강력한 JSON-RPC 서버입니다. 이 서버는 표준화된 프로토콜을 사용하여 KVM 가상 머신을 중앙에서 제어하고 모니터링할 수 있는 방법을 제공합니다.

이 프로젝트를 선택한 이유는?

KVM 가상 머신을 관리하려면 일반적으로 virsh , virt-install , qemu-system 과 같은 여러 명령줄 도구를 사용해야 합니다. 이 프로젝트의 목표는 다음과 같습니다.

VM 관리 간소화 : 모든 VM 작업에 대한 단일 통합 인터페이스 제공
원격 제어 활성화 : JSON-RPC를 통해 VM의 원격 관리를 허용합니다.
VM 작업 자동화 : VM 관리 작업을 스크립팅하고 자동화하기 쉽게 만듭니다.
VM 구성 표준화 : 인프라 전반에 걸쳐 일관된 VM 설정을 보장합니다.
성능 최적화 : 효율적인 리소스 관리 및 캐싱 전략 구현

특징

VM 수명 주기 관리 :
- 사용자 정의 가능한 매개변수로 새 VM 만들기
- VM 시작/중지/재부팅
- 사용 가능한 모든 VM을 상태와 함께 나열합니다.
- 자동 상태 추적 및 복구
네트워크 관리 :
- 브리지를 사용하여 VM 네트워킹 구성
- brforvms 브리지 지원
- 자동 네트워크 인터페이스 구성
- IP 주소 추적 및 관리
스토리지 관리 :
- 구성 가능한 VM 디스크 저장 위치
- 다양한 디스크 포맷 지원(qcow2)
- 구성 가능한 디스크 크기
- 자동 디스크 정리 및 관리
디스플레이 관리 :
- 그래픽 액세스를 위한 VNC 지원
- 자동 VNC 포트 할당
- VM 디스플레이를 찾고 연결하는 도구
- 디스플레이 상태 추적 및 복구
설치 지원 :
- ISO 이미지에서 네트워크 설치
- CDROM에서 로컬 설치
- 다양한 OS 변형 지원
- 자동 설치 구성
성능 최적화 :
- 연결 오버헤드를 줄이기 위한 libvirt의 연결 풀링
- 향상된 응답성을 위한 VM 정보 캐싱
- 더 나은 동시성을 위한 비동기 처리
- 진단 및 문제 해결을 위한 고급 로깅
- 적절한 리소스 정리를 위한 우아한 종료 처리
- 자동 연결 복구 및 검증
- API 작업에 대한 속도 제한
- 성능 지표 수집

성능 이점

연결 풀링

대기 시간 단축 : libvirt 연결을 반복적으로 열고 닫는 오버헤드를 제거합니다.
리소스 효율성 : 재사용 가능한 연결 풀을 유지하여 시스템 리소스 사용량을 줄입니다.
자동 복구 : 끊어진 연결을 자동으로 감지하고 교체합니다.
구성 가능한 풀 크기 : 작업 부하에 따라 연결 수를 조정합니다.

캐싱

더 빠른 응답 시간 : 일반적인 작업에 대한 libvirt에 대한 반복적인 쿼리를 줄입니다.
구성 가능한 TTL : 필요에 따라 캐시 만료일을 설정합니다.
선택적 우회 : 최신 데이터가 필요한 작업에 대해 캐시를 우회하는 옵션
자동 무효화 : VM 상태가 변경되면 캐시가 자동으로 무효화됩니다.

비동기 처리

향상된 동시성 : 여러 요청을 동시에 처리합니다.
더 나은 리소스 활용 : 시스템 리소스의 효율적인 사용
비차단 작업 : 장기 실행 작업은 서버를 차단하지 않습니다.
우아한 종료 : 종료 중 리소스의 적절한 정리

모니터링 및 진단

구조화된 로깅 : 분석을 위한 쉽게 분석할 수 있는 로그 형식
성능 측정 항목 : 작업 타이밍 및 리소스 사용량 추적
오류 추적 : 문제 해결을 위한 자세한 오류 로깅
리소스 모니터링 : 연결 풀 사용량 및 캐시 효율성 추적

구성

서버는 JSON 구성 파일( config.json )을 사용하여 기본값과 경로를 저장합니다. 이를 통해 서버의 이식성과 사용자 지정이 더욱 쉬워집니다. 구성에는 다음이 포함됩니다.

지엑스피1

사용자 환경 요구 사항에 맞게 이 값을 수정할 수 있습니다. 이 구성은 다음 형식을 사용하여 환경 변수 재정의를 지원합니다.

disk_path 에 대한 VM_DISK_PATH
default_iso 에 대한 VM_DEFAULT_ISO
default_master_image 에 대한 VM_DEFAULT_MASTER_IMAGE
default_name 에 대한 VM_DEFAULT_NAME
default_memory 에 대한 VM_DEFAULT_MEMORY
default_vcpus 에 대한 VM_DEFAULT_VCPUS
default_disk_size 에 대한 VM_DEFAULT_DISK_SIZE
default_os_variant 에 대한 VM_DEFAULT_OS_VARIANT
default_network 를 위한 VM_DEFAULT_NETWORK
ignition.default_hostname 에 대한 VM_IGNITION_DEFAULT_HOSTNAME
ignition.default_user 에 대한 VM_IGNITION_DEFAULT_USER
ignition.default_ssh_key 에 대한 VM_IGNITION_DEFAULT_SSH_KEY
ignition.default_timezone 에 대한 VM_IGNITION_DEFAULT_TIMEZONE
ignition.default_locale 에 대한 VM_IGNITION_DEFAULT_LOCALE
ignition.default_password_hash 에 대한 VM_IGNITION_DEFAULT_PASSWORD_HASH

성능 튜닝

연결 풀 구성

connection_pool = LibvirtConnectionPool(
    max_connections=5,     # Maximum number of connections in the pool
    timeout=30,            # Timeout for getting a connection (seconds)
    uri='qemu:///system'   # Libvirt connection URI
)

캐시 구성

vm_info_cache = VMInfoCache(
    max_size=50,           # Maximum number of VMs to cache
    ttl=60                 # Time-to-live for cache entries (seconds)
)

로깅 구성

logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
    handlers=[
        RotatingFileHandler(
            'kvm_mcp.log',
            maxBytes=10485760,  # 10MB
            backupCount=5
        ),
        logging.StreamHandler()
    ]
)

시작하기

필수 조건

Python 3.6 이상
호스트 시스템에 KVM 및 libvirt 설치
구성된 네트워크 브리지(기본값: brforvms )
VM 스토리지 디렉토리가 생성됨(기본값: /vm/ )
VM 워크로드에 충분한 시스템 리소스

설치

이 저장소를 복제하세요:
git clone https://github.com/yourusername/kvm-mcp.git cd kvm-mcp
가상 환경을 만들고 활성화하세요.
python3 -m venv .venv source .venv/bin/activate
종속성 설치:
pip install -r requirements.txt
서버를 구성하세요:
- 사용자 환경에 맞게 config.json 편집하세요.
- 모든 필수 디렉토리가 있는지 확인하세요
- 네트워크 브리지 구성 확인
- 필요에 따라 성능 설정을 조정하세요

용법

서버를 시작합니다:
python3 kvm_mcp_server.py
JSON-RPC를 사용하여 명령을 전송합니다. 예제 스크립트가 제공됩니다.
- create_vm.sh : 기본 구성을 사용하여 새 VM을 만듭니다.
- get_vnc_ports.sh : 실행 중인 VM에 대한 VNC 포트 찾기

예제 명령

새 VM 만들기

./create_vm.sh

이렇게 하면 config.json 의 기본 구성을 사용하여 새 VM이 생성됩니다. 요청에 이러한 기본 구성을 제공하여 재정의할 수 있습니다.

VNC 포트 찾기

./get_vnc_ports.sh

이렇게 하면 실행 중인 모든 VM과 VNC 포트가 표시되어 해당 디스플레이에 쉽게 연결할 수 있습니다.

캐시 우회를 사용하여 VM 나열

echo '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "list_vms", "arguments": {"no_cache": true}}, "id": 1}' | python3 kvm_mcp_server.py

모니터링 및 문제 해결

로그 파일

kvm_mcp.log : 현재 로그 파일
kvm_mcp.log.1 : 이전 로그 파일(순환됨)
로그에는 타이밍 정보, 연결 풀 상태 및 캐시 적중/누락이 포함됩니다.

성과 지표

연결 풀 사용 통계
캐시 적중률/미스율
작업 타이밍 측정 항목
리소스 활용 통계

일반적인 문제 및 솔루션

연결 풀 소진
- 증상: 응답 시간이 느리거나 연결 오류가 발생합니다.
- 해결 방법: 연결 풀 구성에서 max_connections 늘리세요.
캐시 무효화 문제
- 증상: 오래된 VM 정보
- 해결 방법: no_cache 매개변수를 사용하거나 캐시 TTL을 줄이세요.
리소스 정리
- 증상: 리소스 누수 또는 연결 문제
- 해결 방법: SIGTERM 또는 SIGINT를 사용하여 적절한 종료를 보장합니다.

프로젝트 구조

kvm_mcp_server.py : 메인 서버 구현
config.json : 구성 파일
requirements.txt : Python 종속성
루트 디렉토리의 예제 스크립트
tests/ 디렉토리의 테스트 모음

기여하다

기여를 환영합니다! 풀 리퀘스트를 제출해 주세요.

특허

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.

KVM MCP Server

Integrations