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 |
|
|
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/autostartyes,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의 동작을 설명한 것이다. 이 세 항목을 이 실험대에서 각각 따로 재현하지는 않았다. - 만드는 명령은 구축할 때 친 것을 옮긴 것이라, 지금 다시 쳐도 같은 상태가 되는지는 확인되지 않았다.