Files
document-haness/docs/virtualization/tech-log-studio/lab-environment-build/setup/setup-prepare-the-lab-host-for-virtualization.md
T

23 KiB

id, kind, slug, title, topic, topicName, project, status, studio, pinnedVersions, source, sourceRevision
id kind slug title topic topicName project status studio pinnedVersions source sourceRevision
7c66a553-0008-4294-a27a-687bd1bda0c1 SETUP prepare-the-lab-host-for-virtualization lab host 에 가상화 패키지를 깔고 virsh 가 sudo 없이 돌게 만든다 lab-environment-build 실험대 환경 구성 virtualization 게시 전 https://hyeonworks.com/studio/documents/7c66a553-0008-4294-a27a-687bd1bda0c1/edit
name version
libvirt (실제 환경에서 확인; pacman 설치는 버전 미고정) 12.7.0
name version
QEMU (실제 환경에서 확인; pacman 설치는 버전 미고정) 11.1.1
final/document.md#186-단계-00-lab-host-가상화-준비
final/document.md#185-가이드-묶음이-스스로-정한-규약
final/document.md#184-이-부의-출처와-범위
import-head 9465582b5d1630eb4ae7c4e078021486919bf6b6 · uncommitted-working-tree snapshot

lab host 에 가상화 패키지를 깔고 virsh 가 sudo 없이 돌게 만든다

물리 기계 한 대를 게스트를 올릴 수 있는 상태로 바꾸는 절차다. 가상화 패키지 넷을 깔고, libvirt 소켓을 켜고, 사용자를 libvirt 그룹에 넣고, 연결 URI 를 시스템 단위로 고정한다. 끝나면 virsh list --all 이 sudo 없이 통과한다.

이 단계의 명령은 lab host에서 실행한다

명령은 전부 [lab host] 에서 친다. 게스트가 아직 없어서 다른 셸 표시가 나오지 않는다.

sudo 가 붙는 곳은 둘이다. 패키지를 깔 때와 systemd 유닛을 만질 때이고, virsh 는 3번이 끝나면 sudo 없이 돈다. 그 뒤로 sudo virsh 를 치면 root 환경으로 돌아 사용자 홈의 설정을 못 보므로, 붙이지 않는 쪽이 맞는 형태다.

표시 어느 기계 어떻게 들어가나
[lab host] test-server. virsh 가 도는 곳 ssh test-server

편집기를 여는 곳은 4번 한 단계다. ~/.config/libvirt/libvirt.conf 를 열어 uri_default 하나를 둔다. LIBVIRT_DEFAULT_URI 환경 변수가 필요한 별도 도구가 있을 때만 실제 로그인 셸의 rc 파일을 추가로 만진다. 이 호스트는 /bin/zsh 이므로 그런 경우에도 ~/.bashrc 를 기본값처럼 쓰지 않는다.

libvirt와 KVM을 쓸 수 있는 host 상태를 만든다

가이드 00 의 「이 단계가 끝나면」은 한 줄이다.

virsh list 가 sudo 없이 돌고, VM 을 만들 수 있는 상태가 된다.

그 한 줄이 요구하는 것을 풀면 여덟이다.

무엇 값
저장소 ~/workspace/keycloak-pattern — 뒤 단계의 deploy/... 상대경로가 이 디렉터리 기준이다
패키지 (Arch) qemu-full · libvirt · virt-install · dnsmasq
패키지 (Debian/Ubuntu) qemu-system-x86 · libvirt-daemon-system · virtinst · cloud-image-utils
판 번호 libvirt 12.7.0 · QEMU emulator version 11.1.1
유닛 libvirtd.socket — .service 가 아니다
그룹 donghyeon libvirt wheel
연결 URI ~/.config/libvirt/libvirt.conf의 uri_default = "qemu:///system"
가상 네트워크 default / active / autostart yes → virbr0 · 192.168.122.0/24

네 패키지가 하는 일이 서로 다르다.

무엇 하는 일
qemu 실제로 가상 기계를 돌리는 것
libvirt qemu 를 관리하는 층 (virsh 가 여기 붙는다)
virt-install VM 을 만드는 명령
dnsmasq 가상 네트워크의 DHCP·DNS

패키지와 사용자 그룹을 바꾸기 전에 확인한다

전제는 가이드가 두 줄로 적었다 — 물리 기계 한 대가 있고, 배포판은 상관없다. 이 실험대는 Arch Linux 로 세웠고 배포판이 다르면 패키지 이름만 달라진다. 앞 단계가 없으므로 이 절차는 다른 무엇도 전제하지 않는다.

이 단계에서 설치·변경하는 항목을 모두 원래 상태로 되돌리는 절차는 아직 검증하지 않았다. 호스트에는 다음 항목이 남는다.

남는 것 어디에
패키지 넷 배포판 패키지 데이터베이스
libvirt 보조 그룹 사용자 계정
libvirtd.socket 활성화 systemd
uri_default 한 줄 ~/.config/libvirt/libvirt.conf
선택적인 셸 환경 변수 실제 로그인 셸의 rc 파일. 이 호스트는 /bin/zsh라 ~/.zshrc
default 네트워크의 autostart libvirt 설정

무엇을 어떤 순서로 걷어내는지는 가이드에 적혀 있지 않고 이 실험대도 걷어내 본 적이 없다. 여기에 되돌리는 명령을 적으려면 지어내야 하므로 적지 않는다.

CPU 가상화와 현재 libvirt 상태부터 확인한다

두 확인은 아무것도 바꾸지 않는다. 기계를 켤 때 먼저 도는 펌웨어와 그 설정 화면을 BIOS(Basic Input/Output System)라고 부르는데, 거기서 가상화가 꺼져 있으면 뒤가 전부 헛일이므로 먼저 본다.

확인 ① CPU 가 하드웨어 가상화 확장을 내놓고 있는가

grep -Eo 'vmx|svm' /proc/cpuinfo | head -1

출력 한 줄이 전부다. vmx(Intel) 또는 svm(AMD) 중 하나가 찍히는가, 아니면 아무것도 안 찍히는가.

찍혔으면 이 호스트에서 KVM 을 쓸 수 있다. 빈 출력은 CPU 가 못 한다는 뜻이 아니라 대개 BIOS 에서 꺼져 있다는 뜻이다. 재부팅해 Intel VT-x 나 AMD-V 를 켜고 다시 잰다. 여기서 막히면 뒤의 어떤 단계도 의미가 없으므로 진행하지 않는다.

확인 ② 커널이 그 확장을 실제로 잡고 있는가

lsmod | grep kvm

출력은 이 실험대에서 캡처해 두지 않았다. 가이드도 줄 모양만 적었다.

kvm_intel   ...
kvm         ...

왼쪽 첫 열의 모듈 이름 두 개. 벤더 모듈(kvm_intel 또는 kvm_amd)과 공용 kvm 이 둘 다 있어야 한다. 셋째 열은 이 모듈을 쓰고 있는 쪽의 수라서, 아직 VM 이 없으면 0 으로 나온다.

두 줄이면 커널이 하드웨어 가상화를 쓸 준비를 마쳤고 virt-install 이 KVM 가속으로 뜬다. kvm 만 있고 벤더 모듈이 없으면 확인 ① 의 BIOS 설정이 커널까지 안 넘어왔다. 아무것도 없으면 확인 ① 로 돌아간다. 모듈을 직접 올려 보면 거부 사유가 그대로 나온다.

sudo modprobe kvm_intel

왜 이걸 먼저 보나 — KVM 없이도 QEMU 는 돌지만 소프트웨어 에뮬레이션이 되어 수십 배 느려진다. 게스트가 뜨긴 뜨는데 느리다면 대개 여기서 갈린다. 그 상태로 게스트 셋을 올리면 원인을 게스트 안에서 찾게 된다.

KVM·libvirt와 기본 네트워크를 준비한다

1. 저장소를 lab host 에 받는다

목적 — 뒤 단계가 deploy/ 아래 파일을 쓴다. 단계 05·06 의 kubectl apply -f deploy/lab/k8s/... 가 그것이고, 경로는 저장소 루트 기준이다.

① 이미 세웠다 철거한 적이 있으면 무엇이 남아 있는지 먼저 본다.

ls ~/workspace

② 받는다.

git clone https://git.learn.hyeonworks.com/donghyeon.kang/keycloak-pattern.git ~/workspace/keycloak-pattern
cd ~/workspace/keycloak-pattern

정상이면 매니페스트 두 장이 보인다.

ls deploy/lab/k8s/

keycloak-cluster.yaml 과 observability.yaml 이 보이는가만 본다.

이후 단계에서 deploy/... 로 시작하는 상대경로가 나오면 전부 이 디렉터리 안에서 친다. lab host 에 저장소가 없으면 cp: cannot stat 이나 error: the path ... does not exist 로 막히고, 이 실험대가 실제로 그 형태로 겪었다. 한 번 세웠다 철거했으면 이 디렉터리가 없을 수 있다. 철거는 VM 과 디스크와 네트워크만 지우고 저장소는 각자 관리라, ~/workspace 에 cloud-init 시드만 남아 있는 상태가 흔하다. ① 을 먼저 치는 까닭이 여기 있다.

실패하면 ls 가 아무것도 못 찾으면 클론이 실패한 것이니 ② 를 다시 친다. 클론은 됐는데 deploy/lab/k8s/ 가 없으면 다른 브랜치를 받았다.

2. 가상화 패키지를 깐다

목적 — virsh 와 virt-install 을 PATH 에 올리고 가상 네트워크의 DHCP 를 준비한다. PATH 는 셸이 실행 파일을 찾아 다니는 디렉터리 목록을 말한다.

sudo pacman -S --needed qemu-full libvirt virt-install dnsmasq

Debian 이나 Ubuntu 에서는 패키지 이름이 다르다. 이 실험대는 Arch 로 세웠고 아래 줄은 가이드가 다른 배포판을 위해 참고로 적어 둔 것이다. 이 줄은 여기서 직접 실행해 확인한 명령이 아니다.

sudo apt install qemu-system-x86 libvirt-daemon-system virtinst cloud-image-utils
virsh --version
qemu-system-x86_64 --version

정상이면 판 번호 두 줄. 이 실험대는 libvirt 12.7.0 과 QEMU emulator version 11.1.1 이었다. 다만 위 pacman -S --needed 는 Arch 현재 저장소에서 받으므로 이 두 버전을 재설치에도 고정하는 명령이 아니다. frontmatter의 번호도 실제 확인한 버전이지 package pin이 아니다.

여기서 나오는 libvirt 판 번호가 뒤의 옵션 이름을 가른다. 훨씬 낮은 판이면 virt-install --cloud-init 같은 옵션의 동작이 달라질 수 있으니, 다음 단계에서 막힐 때 이 번호를 같이 본다.

실패하면 command not found 면 패키지가 안 깔렸다. 번호가 나오면 깔렸다.

3. libvirt 를 띄우고 권한을 받는다

목적 — 지금 이 셸이 sudo 없이 libvirt 에 붙게 한다.

sudo systemctl enable --now libvirtd.socket
sudo usermod -aG libvirt "$USER"

③ 로그아웃했다 다시 들어온다. 보조 그룹은 로그인할 때 정해지므로 usermod 만으로는 지금 셸에 반영되지 않는다.

groups            # libvirt 가 보여야 한다
virsh list --all  # sudo 없이 돌아야 한다

정상이면 groups 가 이렇게 나왔다.

donghyeon libvirt wheel

virsh list --all 은 머리글만 있는 빈 표를 내놓는다. 아직 VM 을 안 만들었으므로 표가 비어 있는 쪽이 정상이고, 봐야 할 것은 표의 내용이 아니라 명령이 오류 없이 통과했는가다.

libvirtd.service 가 아니라 .socket 을 켠다. 소켓 활성화를 쓰면 데몬이 미리 떠 있지 않아도 virsh가 접속할 때 systemd가 서비스를 시작할 수 있다. 서비스가 재시작되는 동안 listening socket을 systemd가 관리할 수 있다는 장점도 있지만, 이미 맺어진 클라이언트 연결까지 항상 유지된다고 보지는 않는다.

실패하면 groups 에 libvirt 가 없으면 usermod 는 됐지만 지금 로그인 세션이 옛 그룹 목록을 들고 있다. usermod -aG 가 고치는 것은 /etc/group 파일이다. 프로세스의 그룹 목록은 로그인할 때 한 번 읽혀 고정되므로 이미 떠 있는 셸에는 소급 적용되지 않는다. 두 곳을 나란히 보면 그 상태가 그대로 드러난다.

id                    # 현재 셸이 들고 있는 그룹 (여기 libvirt 가 보여야 함)
getent group libvirt  # /etc/group 의 실제 내용 (이쪽엔 바로 반영됨)

두 결과가 다르면 재로그인이 필요하다는 뜻이다. 급하면 newgrp libvirt 로 그 셸만 갱신한다.

groups 에 libvirt가 있는데도 virsh가 Permission denied를 내면 그룹만 붙들지 말고 소켓과 libvirt 인증 상태를 함께 본다. 이 실험대에서는 먼저 유닛 상태를 확인했다.

systemctl status libvirtd.socket

4. 연결 URI 를 시스템 단위로 고정한다

목적 — virsh 가 VM 을 만들 곳과 같은 시스템 libvirt 를 보게 한다. 셸 환경 변수에 기대지 않고 libvirt 자체 설정으로 qemu:///system 을 기본 URI 로 둔다.

① libvirt 사용자 설정 디렉터리를 만든다.

mkdir -p ~/.config/libvirt

② 설정 파일을 연다.

nano ~/.config/libvirt/libvirt.conf

③ 다음 줄을 넣는다.

uri_default = "qemu:///system"

④ 저장한 뒤 libvirt 가 실제로 어느 URI 를 고르는지 확인한다.

virsh uri

정상이면 다음처럼 나온다.

qemu:///system

이 파일은 bash·zsh 같은 로그인 셸의 rc 파일과 무관하게 libvirt 클라이언트가 직접 읽는다. 그래서 대화형 셸뿐 아니라 ssh test-server 'virsh …' 같은 비대화식 실행에서도 같은 URI 를 본다.

2026-09-21 재검증에서 이 차이를 다시 확인했다. 실제 로그인 셸은 /bin/zsh 였고, 비대화식 SSH 안의 환경 변수는 비어 있었다.

SHELL=/bin/zsh
LIBVIRT_DEFAULT_URI=
qemu:///system

환경 변수가 비어 있는데도 virsh uri 가 qemu:///system 을 낸 것은 ~/.config/libvirt/libvirt.conf 의 uri_default 가 적용됐기 때문이다. 따라서 .bashrc 와 libvirt 설정을 둘 다 넣어야 한다는 이전 설명은 틀렸다. virsh 의 기본 연결을 고정하는 데 필요한 것은 libvirt 설정 하나다.

LIBVIRT_DEFAULT_URI 환경 변수가 필요한 별도 도구가 있다면 그때 실제 로그인 셸의 rc 파일에 선택적으로 둔다. 먼저 셸부터 확인한다.

getent passwd "$USER"

이 호스트는 /bin/zsh 이므로 그런 경우 ~/.zshrc 를 편집한다. ~/.bashrc 를 무조건 열면 현재 로그인 셸에는 적용되지 않는다.

sudo virsh 와 그냥 virsh 를 섞어 치지 않는다. 이 가이드는 사용자 설정의 qemu:///system 연결을 기준으로 검증한다. 다른 사용자(root 포함)의 설정과 섞으면 같은 명령 이름으로 서로 다른 연결을 볼 수 있다.

5. 기본 네트워크를 켠다

목적 — VM 이 붙을 virbr0 와 192.168.122.0/24 를 지금도 재부팅 뒤에도 있게 한다.

virsh net-list --all

실제 확인한 결과

 Name      State    Autostart   Persistent
--------------------------------------------
 default   active   yes         yes

② default 행의 State 와 Autostart 두 칸 중 하나라도 어긋나면 아래 두 줄로 맞춘다.

virsh net-start default
virsh net-autostart default

두 줄을 && 로 잇지 않는다. virsh net-start default 는 이미 active 면 error: network is already active 로 실패한다. A && B 는 A 가 성공했을 때만 B 를 실행하므로, 두 번째로 칠 때는 net-autostart 가 아예 돌지 않는다. 화면에는 둘 다 실패한 것처럼 보이지만 앞선 실행에서 이미 목적을 이룬 상태다. 이 가이드를 두 번 이상 따라 한다면 ; 로 잇고 앞엣것의 실패를 삼킨다.

virsh net-start default 2>/dev/null; virsh net-autostart default

active 이면서 autostart 가 yes 면 지금도, 호스트를 재부팅한 뒤에도 virbr0 와 192.168.122.0/24 가 있다. inactive 면 VM 을 만들어도 DHCP 가 없어 IP 를 못 받는다. autostart 가 no 면 지금은 되고 호스트를 재부팅한 다음 게스트의 SSH 가 전부 실패하는데, 그때 원인을 게스트에서 찾게 된다.

실패하면 --all 을 주는 까닭이 여기 있다. 빼면 inactive 인 네트워크는 아예 목록에 안 나와서 없는 것과 꺼진 것을 구분할 수 없다. net-start default가 already active 말고 다른 사유로 실패하면 먼저 오류 문구를 그대로 읽는다. 이 구성에서는 dnsmasq 설치 여부가 첫 확인 대상이지만, 네트워크 정의나 권한 문제처럼 다른 원인도 있을 수 있다.

이 host에서 확인한 가상화 구성

무엇이 서나 어떤 이름과 값으로
저장소 ~/workspace/keycloak-pattern
패키지 (Arch) qemu-full · libvirt · virt-install · dnsmasq
유닛 libvirtd.socket
보조 그룹 libvirt
연결 URI qemu:///system — ~/.config/libvirt/libvirt.conf 의 uri_default
가상 네트워크 default · active · autostart yes
브리지와 대역 virbr0 · 192.168.122.0/24

대역이 192.168.122.0/24 로 굳으면 다음 단계의 DHCP 예약 세 줄과 그 뒤 모든 단계의 upstream 주소가 그 안에서 정해진다. 게스트 주소를 바꾸고 싶으면 여기서 바꾸는 것이지 게스트 안에서 바꾸는 것이 아니다.

sudo 없이 virsh가 qemu:///system에 붙는지 확인한다

확인 ① virsh 가 sudo 없이 통과하는가

이 셸에서 VM 을 만들 수 있는 상태인지.

virsh uri
virsh net-list --all
virsh list --all

첫 줄이 qemu:///system 인가, 둘째에서 default 가 active 이고 autostart 가 yes 인가, 셋째가 sudo 없이 오류 없이 끝나는가.

셋이 다 통과하면 이 단계는 끝났다. virsh list --all 이 sudo 없이 오류 없이 끝나는 것이 이 단계의 통과 조건 전부이고, 표의 내용은 아직 볼 것이 없다. 빈 표를 「호스트에 아무것도 없다」로 읽지 않는다 — 지금은 만들지 않았으니 비어 있는 것이고, 다음 단계가 끝난 뒤에 같은 명령이 세 줄을 내놓는다.

확인 ② 그룹이 지금 셸에 반영됐는가

usermod 가 파일에만 들어간 것인지, 지금 세션이 들고 있는 목록에도 들어간 것인지.

groups

출력에 libvirt 가 끼어 있는가.

이 가이드의 권한 구성에서는 libvirt 보조 그룹이 현재 셸에 반영돼 있어야 한다. 확인 ①이 Permission denied로 끝났다면 먼저 현재 세션의 그룹 목록과 소켓 권한을 나란히 본다.

lab host 준비 확인표

무엇 명령 통과
가상화 확장 grep -Eo 'vmx|svm' /proc/cpuinfo | head -1 vmx 또는 svm 한 줄
그룹 groups libvirt 가 끼어 있다
연결 URI virsh uri qemu:///system
네트워크 virsh net-list --all default 가 active · autostart yes
빈 목록 virsh list --all sudo 없이 통과. 표가 비어 있어도 된다

다섯 칸이 다 맞으면 다음 단계로 넘어간다.

/dev/kvm이나 libvirt 연결에서 막힐 때

증상 원인 확인
virsh list 에 permission denied 그룹 반영 안 됨 로그아웃과 로그인을 했는가. groups 에 libvirt 가 있는가
만든 VM 이 목록에 없다 URI 가 session virsh uri
sudo 로는 되는데 그냥은 안 된다 세션 인스턴스를 보고 있다 virsh uri
net-start 가 already active 앞서 켜 두었다 virsh net-list --all 의 State
VM 이 극단적으로 느리다 KVM 미사용 lsmod | grep kvm · BIOS
net-start default 실패 dnsmasq 없음 패키지 설치 확인
cp: cannot stat 'deploy/...' lab host 에 저장소가 없다 ls ~/workspace

이 host에서 실제로 확인한 범위

  • 실제 확인한 값은 libvirt 12.7.0, QEMU emulator version 11.1.1, groups 의 세 이름, default 네트워크의 active/autostart yes, virsh uri 의 qemu:///system 이다.
  • lsmod | grep kvm 의 출력을 2026-09-17 에 받았다. 세 줄이고, 마지막 칸이 그 모듈을 쓰는 수다.
kvm_intel             524288  11
kvm                  1490944  6 kvm_intel
irqbypass              16384  1 kvm
  • 이 호스트는 논리 코어 8 이다 — 가이드가 적은 「16 코어 전부」가 아니다. 2026-09-17 에 nproc 이 8, lscpu 가 11th Gen Intel(R) Core(TM) i5-1135G7, 물리 4 코어에 코어당 스레드 2 라고 답했다. 가이드의 그 줄은 다른 기계의 값이다.
nproc
lscpu | grep -E "^Model name|^CPU\(s\):|^Core\(s\)|^Thread\(s\)"
  • systemctl status libvirtd.socket 도 같은 날 쳤다. 보는 줄은 Active 와 Listen 과 Triggers 셋이다.
● libvirtd.socket - libvirt legacy monolithic daemon socket
     Loaded: loaded (/usr/lib/systemd/system/libvirtd.socket; enabled; preset: disabled)
     Active: active (running) since Thu 2026-09-03 19:00:35 KST; 1 week 6 days ago
   Triggers: ● libvirtd.service
     Listen: /run/libvirt/libvirt-sock (Stream)

Triggers 가 libvirtd.service 를 가리키는 것이 소켓 활성화가 걸렸다는 뜻이다. 소켓이 먼저 뜨고 첫 접속이 올 때 서비스가 깨어난다 — 그래서 .service 가 아니라 .socket 을 enable 한다.

  • 패키지, 사용자 그룹, libvirt 유닛, ~/.config/libvirt/libvirt.conf, 네트워크 autostart까지 모두 원래 상태로 되돌리는 전체 rollback은 수행하지 않았다.
  • sudo modprobe kvm_intel 은 막혔을 때 치라고 가이드가 적어 둔 명령이고, 이 실험대에서는 모듈이 이미 올라와 있어 치지 않았다.
  • 2026-09-21 재검증에서는 실제 로그인 셸이 /bin/zsh, 비대화식 SSH의 LIBVIRT_DEFAULT_URI는 빈 값인데도 virsh uri가 qemu:///system임을 다시 확인했다. 따라서 과거 .bashrc까지 함께 수정하던 절차는 current procedure에서 제외했다.
  • Debian과 Ubuntu의 패키지 이름은 가이드가 참고용으로 적어 둔 것이고, 이 실험대는 Arch에서만 확인했다.
  • 보조 그룹이 로그인 시점에 반영된다는 점, virsh net-start 가 이미 active 인 네트워크에 대해 실패할 수 있다는 점, sudo 가 환경 변수를 그대로 넘기지 않는다는 점은 Linux와 libvirt의 동작을 설명한 것이다. 이 세 항목을 이 실험대에서 각각 따로 재현하지는 않았다.
  • 만드는 명령은 구축할 때 친 것을 옮긴 것이라, 지금 다시 쳐도 같은 상태가 되는지는 확인되지 않았다.