3.2. virtctl 및 libguestfs CLI 툴 사용

PDF

virtctl 명령줄 툴을 사용하여 OpenShift Virtualization 리소스를 관리할 수 있습니다.

libguestfs 명령줄 툴을 사용하여 VM(가상 머신) 디스크 이미지에 액세스하고 수정할 수 있습니다. virtctl libguestfs 명령을 사용하여 libguestfs를 배포합니다.

3.2.1. virtctl 설치

RHEL(Red Hat Enterprise Linux) 9, Linux, Windows 및 MacOS 운영 체제에 virtctl 을 설치하려면 virtctl 바이너리 파일을 다운로드하여 설치합니다.

RHEL 8에 virtctl 을 설치하려면 OpenShift Virtualization 리포지토리를 활성화한 다음 kubevirt-virtctl 패키지를 설치합니다.

3.2.1.1. RHEL 9, Linux, Windows 또는 macOS에 virtctl 바이너리 설치

OpenShift Container Platform 웹 콘솔에서 운영 체제의 virtctl 바이너리를 다운로드한 다음 설치할 수 있습니다.

프로세스

웹 콘솔의 가상화 개요 페이지로 이동합니다.
Download virtctl 링크를 클릭하여 운영 체제의 virtctl 바이너리를 다운로드합니다.
install virtctl:
- RHEL 9 및 기타 Linux 운영 체제의 경우:
  1. 아카이브 파일의 압축을 풉니다.
    $ tar -xvf <virtctl-version-distribution.arch>.tar.gz
  2. 다음 명령을 실행하여 virtctl 바이너리를 실행할 수 있도록 합니다.
    $ chmod +x <path/virtctl-file-name>
  3. virtctl 바이너리를 PATH 환경 변수의 디렉터리로 이동합니다.
    다음 명령을 실행하여 경로를 확인할 수 있습니다.
    $ echo $PATH
  4. KUBECONFIG 환경 변수를 설정합니다.
    $ export KUBECONFIG=/home/<user>/clusters/current/auth/kubeconfig
- Windows의 경우:
  1. 아카이브 파일의 압축을 풉니다.
  2. 추출된 폴더 계층 구조로 이동하고 virtctl 실행 파일을 두 번 클릭하여 클라이언트를 설치합니다.
  3. virtctl 바이너리를 PATH 환경 변수의 디렉터리로 이동합니다.
    다음 명령을 실행하여 경로를 확인할 수 있습니다.
    C:\> path
- macOS의 경우:
  1. 아카이브 파일의 압축을 풉니다.
  2. virtctl 바이너리를 PATH 환경 변수의 디렉터리로 이동합니다.
    다음 명령을 실행하여 경로를 확인할 수 있습니다.
    echo $PATH

3.2.1.2. RHEL 8에 virtctl RPM 설치

OpenShift Virtualization 리포지토리를 활성화하고 kubevirt-virtctl 패키지를 설치하여 RHEL(Red Hat Enterprise Linux) 8에 virtctl RPM 패키지를 설치할 수 있습니다.

사전 요구 사항

클러스터의 각 호스트는 RHSM(Red Hat Subscription Manager)에 등록되어 있어야 하며 유효한 OpenShift Container Platform 서브스크립션이 있어야 합니다.

프로세스

subscription-manager CLI 툴을 사용하여 다음 명령을 실행하여 OpenShift Virtualization 리포지토리를 활성화합니다.
```
# subscription-manager repos --enable cnv-4.15-for-rhel-8-x86_64-rpms
```
다음 명령을 실행하여 kubevirt-virtctl 패키지를 설치합니다.
```
# yum install kubevirt-virtctl
```

3.2.2. virtctl 명령

virtctl 클라이언트는 OpenShift Virtualization 리소스를 관리하는 명령줄 유틸리티입니다.

참고

VM(가상 머신) 명령은 별도로 지정하지 않는 한 VMI(가상 머신 인스턴스)에도 적용됩니다.

3.2.2.1. virtctl information 명령

virtctl information 명령을 사용하여 virtctl 클라이언트에 대한 정보를 봅니다.

표 3.1. 정보 명령
명령	설명
`virtctl version`	`virtctl` 클라이언트 및 서버 버전을 확인합니다.
`virtctl help`	`virtctl` 명령 목록을 확인합니다.
`virtctl <command> -h\|--help`	특정 명령의 옵션 목록을 확인합니다.
`virtctl 옵션`	`virtctl` 명령에 대한 글로벌 명령 옵션 목록을 확인합니다.

3.2.2.2. VM 정보 명령

virtctl 을 사용하여 VM(가상 머신) 및 VMI(가상 머신 인스턴스)에 대한 정보를 볼 수 있습니다.

표 3.2. VM 정보 명령
명령	설명
`virtctl fslist <vm_name>`	게스트 머신에서 사용 가능한 파일 시스템을 확인합니다.
`virtctl guestosinfo <vm_name>`	게스트 머신의 운영 체제에 대한 정보를 봅니다.
`virtctl userlist <vm_name>`	게스트 머신에서 로그인한 사용자를 확인합니다.

3.2.2.3. VM 매니페스트 생성 명령

virtctl create 명령을 사용하여 가상 머신, 인스턴스 유형 및 기본 설정에 대한 매니페스트를 생성할 수 있습니다.

표 3.3. VM 매니페스트 생성 명령
명령	설명
`virtctl create vm`	`VirtualMachine` (VM) 매니페스트를 생성합니다.
`virtctl create vm --name <vm_name>`	VM 매니페스트를 생성하여 VM의 이름을 지정합니다.
`virtctl create vm --instancetype <instancetype_name>`	기존 클러스터 전체 인스턴스 유형을 사용하는 VM 매니페스트를 생성합니다.
`virtctl create vm --instancetype=virtualmachineinstancetype/<instancetype_name>`	기존 네임스페이스 인스턴스 유형을 사용하는 VM 매니페스트를 생성합니다.
`virtctl create instancetype --cpu_value> --memory <memory_value> --name <instancetype_name>`	클러스터 전체 인스턴스 유형에 대한 매니페스트를 생성합니다.
`virtctl create instancetype --cpu_value> --memory <memory_value> --name <instancetype_name> --namespace <namespace_value>`	네임스페이스가 지정된 인스턴스 유형에 대한 매니페스트를 생성합니다.
`virtctl create preference --name <preference_name>`	클러스터 전체 VM 기본 설정에 대한 매니페스트를 생성하여 기본 설정 이름을 지정합니다.
`virtctl create preference --namespace <namespace_value>`	네임스페이스가 지정된 VM 기본 설정에 대한 매니페스트를 생성합니다.

3.2.2.4. VM 관리 명령

virtctl VM(가상 머신) 관리 명령을 사용하여 VM(가상 머신) 및 VMI(가상 머신 인스턴스)를 관리하고 마이그레이션합니다.

표 3.4. VM 관리 명령
명령	설명
`virtctl start <vm_name>`	VM을 시작합니다.
`virtctl start --paused <vm_name>`	일시 중지된 상태에서 VM을 시작합니다. 이 옵션을 사용하면 VNC 콘솔에서 부팅 프로세스를 중단할 수 있습니다.
`virtctl stop <vm_name>`	VM을 중지합니다.
`virtctl stop <vm_name> --grace-period 0 --force`	VM을 강제로 중지합니다. 이 옵션을 사용하면 데이터 불일치 또는 데이터 손실이 발생할 수 있습니다.
`virtctl pause vm <vm_name>`	VM 일시 중지. 머신 상태는 메모리에 유지됩니다.
`virtctl unpause vm <vm_name>`	VM 일시 중지를 해제합니다.
`virtctl migrate <vm_name>`	VM 마이그레이션.
`virtctl migrate-cancel <vm_name>`	VM 마이그레이션을 취소합니다.
`virtctl restart <vm_name>`	VM을 다시 시작합니다.

3.2.2.5. VM 연결 명령

virtctl 연결 명령을 사용하여 포트를 노출하고 VM(가상 머신) 및 VMI(가상 머신 인스턴스)에 연결합니다.

표 3.5. VM 연결 명령
명령	설명
`virtctl console <vm_name>`	VM의 직렬 콘솔에 연결합니다.
`virtctl expose vm <vm_name> --name <service_name> --type <ClusterIP\|NodePort\|LoadBalancer> --port <port>`	VM의 지정된 포트를 전달하고 서비스를 노드의 지정된 포트에 노출하는 서비스를 생성합니다. 예: `virtctl expose vm rhel9_vm --name rhel9-ssh --type NodePort --port 22`
`virtctl scp -i <ssh_key> <file_name> <user_name>@<vm_name>`	시스템에서 VM으로 파일을 복사합니다. 이 명령은 SSH 키 쌍의 개인 키를 사용합니다. VM은 공개 키를 사용하여 구성해야 합니다.
`virtctl scp -i <ssh_key> <user_name@<vm_name>:<file_name> .`	VM에서 시스템으로 파일을 복사합니다. 이 명령은 SSH 키 쌍의 개인 키를 사용합니다. VM은 공개 키를 사용하여 구성해야 합니다.
`virtctl ssh -i <ssh_key> <user_name>@<vm_name>`	VM을 사용하여 SSH 연결을 엽니다. 이 명령은 SSH 키 쌍의 개인 키를 사용합니다. VM은 공개 키를 사용하여 구성해야 합니다.
`virtctl vnc <vm_name>`	VM의 VNC 콘솔에 연결합니다. `virt-viewer` 가 설치되어 있어야 합니다.
`virtctl vnc --proxy-only=true <vm_name>`	포트 번호를 표시하고 VNC 연결을 통해 뷰어를 사용하여 VM에 수동으로 연결합니다.
`virtctl vnc --port=<port-number> <vm_name>`	해당 포트를 사용할 수 있는 경우 지정된 포트에서 프록시를 실행할 포트 번호를 지정합니다. 포트 번호를 지정하지 않으면 프록시는 임의의 포트에서 실행됩니다.

3.2.2.6. VM 내보내기 명령

virtctl vmexport 명령을 사용하여 VM, VM 스냅샷 또는 PVC(영구 볼륨 클레임)에서 내보낸 볼륨을 생성, 다운로드 또는 삭제합니다. 특정 매니페스트에는 OpenShift Virtualization에서 사용할 수 있는 형식으로 디스크 이미지를 가져오기 위해 엔드포인트에 대한 액세스 권한을 부여하는 헤더 시크릿도 포함되어 있습니다.

표 3.6. VM 내보내기 명령
명령	설명
`virtctl vmexport create <vmexport_name> --vm\|snapshot\|pvc=<object_name>`	`VirtualMachineExport` CR(사용자 정의 리소스)을 생성하여 VM, VM 스냅샷 또는 PVC에서 볼륨을 내보냅니다. `--` VM : VM의 PVC를 내보냅니다. `--snapshot`: `VirtualMachineSnapshot` CR에 포함된 PVC를 내보냅니다. `--PVC`: PVC를 내보냅니다. 선택 사항: `--ttl=1h` 는 실시간 시간을 지정합니다. 기본 기간은 2시간입니다.
`virtctl vmexport delete <vmexport_name>`	`VirtualMachineExport` CR을 수동으로 삭제합니다.
`virtctl vmexport download <vmexport_name> --output=<output_file> --volume=<volume_name>`	`VirtualMachineExport` CR에 정의된 볼륨을 다운로드합니다. `--output` 은 파일 형식을 지정합니다. 예: `disk.img.gz`. `--volume` 은 다운로드할 볼륨을 지정합니다. 하나의 볼륨만 사용할 수 있는 경우 이 플래그는 선택 사항입니다. 선택 사항: `--keep-vme` 는 다운로드 후 `VirtualMachineExport` CR을 유지합니다. 기본 동작은 다운로드 후 `VirtualMachineExport` CR을 삭제하는 것입니다. `--insecure` 는 비보안 HTTP 연결을 활성화합니다.
`virtctl vmexport download <vmexport_name> --<vm\|snapshot\|pvc>=<object_name> --output=<output_file> --volume=<volume_name>`	`VirtualMachineExport` CR을 생성한 다음 CR에 정의된 볼륨을 다운로드합니다.
`virtctl vmexport 다운로드 내보내기 --manifest`	기존 내보내기에 대한 매니페스트를 검색합니다. 매니페스트에는 헤더 보안이 포함되지 않습니다.
`virtctl vmexport download export --manifest --vm=example`	VM 예제에 대한 VM 내보내기를 생성하고 매니페스트를 검색합니다. 매니페스트에는 헤더 보안이 포함되지 않습니다.
`virtctl vmexport download export --manifest --snap=example`	VM 스냅샷 예에 대한 VM 내보내기를 생성하고 매니페스트를 검색합니다. 매니페스트에는 헤더 보안이 포함되지 않습니다.
`virtctl vmexport download export --manifest --include-secret`	기존 내보내기에 대한 매니페스트를 검색합니다. 매니페스트에는 헤더 보안이 포함됩니다.
`virtctl vmexport download export --manifest --manifest-output-format=json`	기존 내보내기에 대한 매니페스트를 json 형식으로 검색합니다. 매니페스트에는 헤더 보안이 포함되지 않습니다.
`virtctl vmexport download export --manifest --include-secret --output=manifest.yaml`	기존 내보내기에 대한 매니페스트를 검색합니다. 매니페스트에는 헤더 보안이 포함되어 있으며 지정된 파일에 씁니다.

3.2.2.7. VM 메모리 덤프 명령

virtctl memory-dump 명령을 사용하여 PVC에 VM 메모리 덤프를 출력할 수 있습니다. 기존 PVC를 지정하거나 --create-claim 플래그를 사용하여 새 PVC를 생성할 수 있습니다.

사전 요구 사항

PVC 볼륨 모드는 FileSystem 이어야 합니다.
PVC는 메모리 덤프를 포함할 수 있을 만큼 커야 합니다.
PVC 크기를 계산하는 공식은 (VMMemorySize + 100Mi) * FileSystemOverhead 입니다. 여기서 100Mi 는 메모리 덤프 오버헤드입니다.

다음 명령을 실행하여 HyperConverged 사용자 정의 리소스에서 핫 플러그 기능 게이트를 활성화해야 합니다.

$ oc patch hyperconverged kubevirt-hyperconverged -n openshift-cnv \
  --type json -p '[{"op": "add", "path": "/spec/featureGates", \
  "value": "HotplugVolumes"}]'

메모리 덤프 다운로드

virtctl vmexport download 명령을 사용하여 메모리 덤프를 다운로드해야 합니다.

$ virtctl vmexport download <vmexport_name> --vm|pvc=<object_name> \
  --volume=<volume_name> --output=<output_file>

표 3.7. VM 메모리 덤프 명령
명령	설명
`virtctl memory-dump get <vm_name> --claim-name=<pvc_name>`	VM의 메모리 덤프를 PVC에 저장합니다. 메모리 덤프 상태가 `VirtualMachine` 리소스의 `status` 섹션에 표시됩니다. 선택 사항: `--create-claim` 은 적절한 크기로 새 PVC를 생성합니다. 이 플래그에는 다음과 같은 옵션이 있습니다. `--storage-class=<storage_class&` gt; : PVC의 스토리지 클래스를 지정합니다. `--access-mode=<access_mode&gt`; : `ReadWriteOnce` 또는 `ReadWriteMany` 를 지정합니다.
`virtctl memory-dump get <vm_name>`	동일한 PVC를 사용하여 `virtctl memory-dump` 명령을 재실행합니다. 이 명령은 이전 메모리 덤프를 덮어씁니다.
`virtctl memory-dump remove <vm_name>`	메모리 덤프 제거. 대상 PVC를 변경하려면 메모리 덤프를 수동으로 제거해야 합니다. 이 명령은 VM과 PVC 간의 연결을 제거하여 메모리 덤프가 `VirtualMachine` 리소스의 `status` 섹션에 표시되지 않습니다. PVC에는 영향을 미치지 않습니다.

3.2.2.8. 핫플러그 및 핫 플러그 해제 명령

virtctl 을 사용하여 실행 중인 VM(가상 머신) 및 VMI(가상 머신 인스턴스)에서 리소스를 추가하거나 제거합니다.

표 3.8. 핫플러그 및 핫 플러그 해제 명령
명령	설명
`virtctl addvolume <vm_name> --volume-name=<datavolume_or_PVC> [--persist] [--serial=<label>]`	데이터 볼륨 또는 PVC(영구 볼륨 클레임)를 핫플러그합니다. 선택 사항: `--persist` 는 VM에 가상 디스크를 영구적으로 마운트합니다. 이 플래그는 VMI에는 적용되지 않습니다. `--serial=<label&` gt;은 VM에 레이블을 추가합니다. 라벨을 지정하지 않으면 default 레이블은 데이터 볼륨 또는 PVC 이름입니다.
`virtctl removevolume <vm_name> --volume-name=<virtual_disk>`	가상 디스크 핫 플러그를 해제합니다.
`virtctl addinterface <vm_name> --network-attachment-definition-name <net_attach_def_name> --name <interface_name>`	Linux 브리지 네트워크 인터페이스를 핫 플러그로 연결합니다.
`virtctl removeinterface <vm_name> --name <interface_name>`	Linux 브리지 네트워크 인터페이스를 핫 플러그 해제합니다.

3.2.2.9. 이미지 업로드 명령

virtctl image-upload 명령을 사용하여 VM 이미지를 데이터 볼륨에 업로드합니다.

표 3.9. 이미지 업로드 명령
명령	설명
`virtctl image-upload dv <datavolume_name> --image-path=</path/to/image> --no-create`	VM 이미지를 이미 존재하는 데이터 볼륨에 업로드합니다.
`virtctl image-upload dv <datavolume_name> --size=<datavolume_size> --image-path=</path/to/image>`	요청된 크기의 새 데이터 볼륨에 VM 이미지를 업로드합니다.

3.2.3. virtctl을 사용하여 libguestfs 배포

virtctl guestfs 명령을 사용하여 libguestfs-tools 및 연결된 PVC(영구 볼륨 클레임)를 사용하여 대화형 컨테이너를 배포할 수 있습니다.

절차

libguestfs-tools를 사용하여 컨테이너를 배포하려면 PVC를 마운트하고 쉘을 연결하려면 다음 명령을 실행합니다.
```
$ virtctl guestfs -n <namespace> <pvc_name> 1
```
1
PVC 이름은 필수 인수입니다. 이를 포함하지 않으면 오류 메시지가 표시됩니다.

3.2.3.1. libguestfs 및 virtctl guestfs 명령

Libguestfs 툴을 사용하면 VM(가상 머신) 디스크 이미지에 액세스하고 수정할 수 있습니다. libguestfs 툴을 사용하여 게스트의 파일을 보고 편집하고, 가상 시스템을 복제 및 빌드하며, 디스크를 포맷하고 크기를 조정할 수 있습니다.

virtctl guestfs 명령과 해당 하위 명령을 사용하여 PVC에서 VM 디스크를 수정, 검사 및 디버깅할 수도 있습니다. 가능한 하위 명령의 전체 목록을 보려면 명령줄에 virt- 을 입력하고 Tab 키를 누릅니다. 예를 들면 다음과 같습니다.

명령	설명
`virt-edit -a /dev/vda /etc/motd`	터미널에서 파일을 대화식으로 편집합니다.
`virt-customize -a /dev/vda --ssh-inject root:string:<public key example>`	ssh 키를 게스트에 삽입하고 로그인을 만듭니다.
`virt-df -a /dev/vda -h`	VM에서 사용하는 디스크 공간 크기를 확인하십시오.
`virt-customize -a /dev/vda --run-command 'rpm -qa > /rpm-list'`	전체 목록이 포함된 출력 파일을 생성하여 게스트에 설치된 모든 RPM의 전체 목록을 확인하십시오.
`virt-cat -a /dev/vda /rpm-list`	터미널에서 `virt-customize -a /dev/vda --run-command 'rpm -qa > /rpm-list'` 명령을 사용하여 생성된 모든 RPM의 출력 파일 목록을 표시합니다.
`virt-sysprep -a /dev/vda`	템플릿으로 사용할 가상 시스템 디스크 이미지를 봉인합니다.

기본적으로 virtctl guestfs 는 VM 디스크를 관리하는 데 필요한 모든 내용으로 세션을 생성합니다. 그러나 이 명령은 동작을 사용자 지정하려는 경우 여러 플래그 옵션도 지원합니다.

플래그 옵션	설명
`--h` 또는 `--help`	`guestfs`에 대한 도움말을 제공합니다.
`<pvc_name>` 인수가 있는 `-n <namespace>` 옵션	특정 네임스페이스에서 PVC를 사용하려면 다음을 수행합니다. `-n <namespace>` 옵션을 사용하지 않는 경우 현재 프로젝트가 사용됩니다. 프로젝트를 변경하려면 `oc project <namespace>`를 사용합니다. `<pvc_name>` 인수를 포함하지 않으면 오류 메시지가 표시됩니다.
`--image string`	`libguestfs-tools` 컨테이너 이미지를 나열합니다. `--image` 옵션을 사용하여 사용자 지정 이미지를 사용하도록 컨테이너를 구성할 수 있습니다.
`--kvm`	`libguestfs-tools` 컨테이너에서 `kvm`이 사용됨을 나타냅니다. 기본적으로 `virtctl guestfs`는 대화형 컨테이너에 대해 `kvm`을 설정하므로 QEMU를 사용하기 때문에 `libguest-tools` 실행 속도가 훨씬 빨라집니다. 클러스터에 `kvm` 지원 노드가 없는 경우 `--kvm=false` 옵션을 설정하여 `kvm`을 비활성화해야 합니다. 설정되지 않은 경우 `libguestfs-tools` Pod는 모든 노드에서 예약할 수 없으므로 보류 중으로 유지됩니다.
`--pull-policy string`	`libguestfs` 이미지의 가져오기 정책을 표시합니다. `pull-policy` 옵션을 설정하여 이미지의 가져오기 정책을 덮어쓸 수도 있습니다.

또한 명령은 다른 pod에서 PVC를 사용 중인지 확인합니다. 이 경우 오류 메시지가 표시됩니다. 그러나 libguestfs-tools 프로세스가 시작되면 동일한 PVC를 사용하는 새 Pod를 방지할 수 없습니다. 동일한 PVC에 액세스하는 VM을 시작하기 전에 활성 virtctl guestfs Pod가 없는지 확인해야 합니다.

참고

virtctl guestfs 명령은 대화형 Pod에 연결된 단일 PVC만 허용합니다.