Files
document-haness/docs/virtualization/tech-log-studio/lab-environment-build/setup/setup-create-three-guests-with-cloud-init.md
T

36 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
f972ca27-7e18-41c1-9494-59cc6f676ae2 SETUP create-three-guests-with-cloud-init cloud-init 시드로 게스트 세 대를 만들고 SSH 가 키로 붙게 한다 lab-environment-build 실험대 환경 구성 virtualization 게시 전 https://hyeonworks.com/studio/documents/f972ca27-7e18-41c1-9494-59cc6f676ae2/edit
name version
libvirt (실제 환경에서 확인; 이 Setup이 설치 버전을 고정하지 않음) 12.7.0
name version
Debian GNU/Linux 12 (bookworm)
name version
cloud-init (실제 환경에서 확인; bookworm/latest 이미지라 정확한 버전 미고정) 22.4.2
final/document.md#187-단계-01-게스트-세-대
final/document.md#185-가이드-묶음이-스스로-정한-규약
final/document.md#184-이-부의-출처와-범위
import-head 9465582b5d1630eb4ae7c4e078021486919bf6b6 · uncommitted-working-tree snapshot

cloud-init 시드로 게스트 세 대를 만들고 SSH 가 키로 붙게 한다

Debian 12 클라우드 이미지 한 장 위에 오버레이로 게스트 셋을 만드는 절차다. 운영체제를 설치하지 않고 첫 부팅의 cloud-init 이 사용자와 SSH 키와 호스트명을 채운다. 끝나면 세 게스트가 192.168.122.10 부터 .12 까지를 받는다.

명령은 lab host를 중심으로 실행한다

기본은 [lab host] 다. 예외가 둘이다.

무엇 어디서
base 이미지 · 시드 · DHCP 예약 · virt-install · 붙어 보기 [lab host]
cloud-init schema -c [kc-lab-1] — 검사기가 게스트 안에만 있다
워크스테이션 공개키를 꺼내는 한 줄 [워크스테이션]

게스트에 들어가는 일은 스키마 검사 한 번과 콘솔로 로그를 읽을 때 둘이다. 나머지는 lab host 에서 ssh <게스트> '...' 형태로 원격 실행한다. 게스트에는 lab host 의 개인키도 ~/.ssh/config 도 없어서, 게스트 안에서 다른 게스트로 붙으려 하면 Host key verification failed 로 끝난다.

편집기를 여는 곳은 둘이다. 게스트마다의 #cloud-config 파일과 그 짝인 meta-data 파일이고, 나머지는 조회와 생성이라 CLI 를 그대로 쓴다.

세 게스트의 역할과 주소를 먼저 정한다

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

kc-lab-edge·kc-lab-1·kc-lab-2 세 게스트가 뜨고, lab host 에서 SSH 가 키로 붙는다.

게스트 IP MAC 끝 vCPU 메모리 디스크 무엇이 도나
kc-lab-edge 192.168.122.10 :10 1 1024MB 10 nginx · certbot
kc-lab-1 192.168.122.11 :11 2 5120MB 20 k3s server · Traefik
kc-lab-2 192.168.122.12 :12 2 4096MB 20 k3s agent · Traefik

세 대를 세우는 까닭은 이 실험대의 질문 전부가 「인스턴스가 둘 이상이고 요청이 어느 쪽으로 갈지 모른다」를 전제하기 때문이다. 한 대면 세션 공유도 분단도 노드 상실도 실험이 되지 않는다. 엣지를 따로 둔 까닭은 그 결정을 담은 기록이 갖는다.

기존 VM과 디스크를 건드리기 전에 확인한다

전제는 한 줄이다 — 앞 단계가 끝나 virsh list 가 sudo 없이 돈다.

세 게스트 전체를 되돌리는 절차는 아직 검증하지 않았다. 게스트 삭제 자체뿐 아니라 DHCP 예약과 seed volume까지 함께 정리해야 하므로 생성 절차와 별도로 확인해야 한다.

virsh undefine kc-lab-edge --remove-all-storage

그 줄은 엣지를 VM 으로 두는 까닭을 설명하면서 나오고, 세 게스트를 걷어내는 절차로 적어 둔 것이 아니다. DHCP 예약 세 줄과 풀에 올린 시드 볼륨 세 개를 어떻게 지우는지는 가이드 어디에도 없고 이 실험대도 지워 본 적이 없다. 그래서 이 절차는 되돌리기를 갖지 않는다.

libvirt 연결과 default 네트워크부터 확인한다

가이드 01 에는 바꾸기 전 상태를 보는 단계가 없다. 아래 세 줄은 앞 단계의 확인을 그대로 다시 치는 것이고, 01 이 요구하는 전제가 그 셋이다.

앞 단계가 남긴 세 값이 지금 셸에서도 그대로인지.

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

qemu:///system 인가, default 가 active 인가, 그리고 virsh list --all 이 sudo 없이 통과하는가. 세 게스트를 아직 안 만들었으면 마지막 표는 비어 있다.

이 셋 가운데 하나라도 어긋난 채로 virt-install 을 치면 증상이 「VM 이 목록에 없다」나 「IP 를 못 받는다」로 나타나고, 원인은 이 단계가 아니라 앞 단계에 있다. 어긋난 값을 만든 곳으로 돌아간다 — 연결 URI 와 네트워크와 그룹이 각각 다른 번호다.

cloud-init 시드와 오버레이로 세 VM을 만든다

1. base 이미지를 받는다

목적 — 게스트 셋의 디스크가 올라탈 Debian 12 genericcloud 이미지 한 장을 풀 디렉터리에 둔다. 운영체제를 설치하지 않는다.

cd /var/lib/libvirt/images
sudo curl -fL --output /var/lib/libvirt/images/base.qcow2 \
https://cloud.debian.org/images/cloud/bookworm/latest/debian-12-genericcloud-amd64.qcow2
qemu-img info /var/lib/libvirt/images/base.qcow2

정상이면 세 줄을 본다. file format: 이 qcow2 인가, virtual size: 가 disk size: 보다 훨씬 큰가, backing file: 줄이 없는가. 가운데 것은 qcow2 가 희소 파일이라 그렇게 나오는 쪽이 정상이다.

게스트 셋의 디스크가 전부 이 파일 위의 오버레이라, base 뒤에 또 무엇이 붙어 있으면 사슬이 한 겹 더 생긴다. base 는 아무것도 뒤에 두지 않는다.

실패하면 받다 끊기면 오류 페이지를 저장해서 file format: 이 raw 로 읽힌다. 형식이 틀린 채로 진행하면 증상이 virt-install 이 아니라 게스트가 부팅을 못 하는 것으로 나타나 원인을 찾기 어려워진다. 지우고 다시 받는다.

2. cloud-init 파일에 넣을 값 셋을 모은다

목적 — 다음 단계의 파일에 넣을 공개키 둘과 콘솔 비밀번호 하나를 손에 든다.

cat ~/.ssh/id_ed25519.pub

ssh-ed25519 ... 로 시작하는 줄이 나오면 키가 이미 있으니 ② 를 건너뛴다. No such file or directory 면 키가 없는 것이고, ② 로 만든 뒤 ① 을 다시 친다.

ssh-keygen -t ed25519 -N '' -f ~/.ssh/id_ed25519
cat ~/.ssh/id_ed25519.pub
openssl rand -base64 18

정상이면 ssh-ed25519 ... 로 시작하는 줄 둘과 base64 한 줄이 화면에 나온다. 셋 다 다음 단계에서 붙여 넣으므로 창을 닫지 않는다.

자리표시자를 문서에 남기지 않고 값을 찾는 명령을 함께 둔다. ④ 의 비밀번호는 cloud-init 의 plain_text_passwd 로 들어가고, 키가 안 들어갔을 때 게스트로 들어가는 유일한 통로가 된다. 이 문서에는 그 값을 싣지 않는다.

①②를 나눠 둔 까닭 — 이 실험대는 [ -f ~/.ssh/id_ed25519.pub ] || ssh-keygen … 한 줄로 쳤다. 그 형태는 「있으면 두고 없으면 만든다」를 단축 평가에 접어 넣어서, 배울 것보다 [ -f … ] 와 || 를 먼저 읽게 만든다. 나눠 두면 키가 이미 있는지가 ① 의 출력에 그대로 보이고, 만드는 명령은 그때만 친다. 이 나눈 형태는 이 실험대에서 치지 않았다.

실패하면 ③ 만 워크스테이션에서 친다. lab host 에서 두 번 쳐서 같은 키를 두 줄 넣으면 워크스테이션에서는 게스트에 못 붙는다.

3. 게스트마다 cloud-init 파일을 쓴다

목적 — 게스트가 첫 부팅에서 읽을 #cloud-config 를 게스트 이름별로 하나씩 만든다.

deploy/lab/cloud-init/kc-lab.yaml.example 원본 파일은 현재 자료에 포함돼 있지 않아 그대로 복사해 사용할 수 없다. 따라서 아래 절차에서는 확인된 cloud-config 항목을 직접 파일에 작성한다. 템플릿 파일과 완전히 같은 내용이라고 단정하지 않는다.

nano kc-lab-1.yaml

② __ 로 둘러싼 세 곳에 2번의 ①③④ 출력을 넣는다.

#cloud-config
hostname: kc-lab-1
fqdn: kc-lab-1
manage_etc_hosts: true

users:
  - name: donghyeon
    groups: [sudo]
    shell: /bin/bash
    sudo: ['ALL=(ALL) NOPASSWD:ALL']
    lock_passwd: false
    plain_text_passwd: __CONSOLE_PW__
    ssh_authorized_keys:
      - __LAB_HOST_KEY__
      - __WORKSTATION_KEY__

ssh_pwauth: false
package_update: true
packages: [curl, nftables]

③ 다른 게스트는 hostname 과 fqdn 두 줄만 kc-lab-2 와 kc-lab-edge 로 바꿔 같은 방법으로 만든다.

정상이면 lab host 의 현재 디렉터리에 kc-lab-1.yaml 과 kc-lab-2.yaml 과 kc-lab-edge.yaml 셋이 생긴다.

세 가지가 의도적이다.

무엇 왜
NOPASSWD:ALL k3s 설치와 장애 주입이 비대화식으로 돌아야 한다. 비밀번호를 물으면 멈춘다
plain_text_passwd cloud-init 이 실패했을 때의 유일한 탈출구. 키가 안 들어가면 SSH 가 막히므로 콘솔로 들어가 로그를 봐야 한다
키 두 개 lab host 에서 자동화가 돌고, 워크스테이션에서는 ProxyJump 로 직접 붙는다

들여쓰기에는 공백만 사용한다. YAML 문법 오류와 cloud-init 스키마 오류는 별개이므로 파일을 만든 뒤 두 검사를 나눠 실행한다. cloud-init이 사용자나 SSH 키 설정을 적용하지 못하면 결과적으로 SSH 접속 실패가 먼저 보일 수 있으므로, 게스트에서는 cloud-init status --long과 로그도 함께 확인한다. 설정 파일은 내용 자체를 확인할 수 있도록 편집기로 작성한다.

이 실험대는 값 셋을 한 번에 치환했다.

sed -i \
  -e "s|__LAB_HOST_KEY__|$(cat ~/.ssh/id_ed25519.pub)|" \
  -e "s|__WORKSTATION_KEY__|<워크스테이션에서 복사해 온 값>|" \
  -e "s|__CONSOLE_PW__|$(openssl rand -base64 18)|" \
  kc-lab-1.yaml

실패하면 sudo: 줄은 4번이 적은 대로 문자열 형태로 고쳐 쓴다. 그대로 두면 부팅은 되고 스키마 검사만 거절한다.

4. cloud-init 파일을 검사한다

목적 — 자리표시자가 남았는지, 공개키가 둘 들어갔는지, cloud-config 로 유효한지를 시드를 굽기 전에 본다.

grep -c '__' kc-lab-1.yaml
grep -c 'ssh-ed25519\|ssh-rsa' kc-lab-1.yaml

정상이면 0 과 2. 첫 줄이 0 이 아니면 __LAB_HOST_KEY__ 같은 문자열이 남아 있고, 둘째 줄이 2 가 아니면 키 하나가 안 들어갔다. 두 숫자가 맞아야 시드를 만든다.

첫 파일에서는 여기까지다. cloud-config 스키마까지 보는 검증기는 cloud-init schema 인데, 2026-09-17 이 실험대에서 관측한 게스트의 cloud-init 은 22.4.2 였다. 하지만 base URL이 bookworm/latest 이므로 다음 다운로드도 같은 cloud-init 버전이라는 계약은 없다. 첫 파일을 쓰는 시점에는 게스트가 아직 없다. lab host 에 cloud-init 이 깔려 있는지는 원본 가이드에 적혀 있지 않고 재지도 않았으며, yamllint 은 이 실험대에 없다. 게스트가 한 대라도 뜬 뒤에는 둘째 파일부터 그 검증기로 본다. 파일을 보내고, 들어가고, 검사하고, 지운다.

scp kc-lab-2.yaml donghyeon@192.168.122.11:~/
ssh donghyeon@192.168.122.11
chmod 600 ~/kc-lab-2.yaml
cloud-init schema -c ~/kc-lab-2.yaml
rm ~/kc-lab-2.yaml
exit

실제 확인한 결과 — 통과하면 한 줄이 나온다.

Valid cloud-config: /home/donghyeon/kc-lab-edge.yaml

통과하면 유효하다는 한 줄만 나오고, 아니면 Invalid cloud-config 아래에 어느 키가 왜 틀렸는지가 나열된다. deprecated 경고와 error 는 다르다 — 경고는 지금 동작한다.

YAML 문법이 맞는 것과 cloud-config 스키마가 맞는 것은 다르다. 예를 들어 users를 user로 잘못 적어도 YAML 파싱 자체는 성공할 수 있으므로 cloud-init schema로 한 번 더 확인한다. 게스트가 기대한 사용자나 SSH 키를 만들지 못했다면 cloud-init status --long과 로그에서 적용 결과를 확인한다.

이 파일에는 콘솔 비밀번호가 평문으로 들어 있다. /tmp 가 아니라 자기 홈에 600 으로 두고 검사가 끝나면 바로 지운다. scp 가 만드는 동안에는 파일이 잠깐 기본 권한으로 놓이므로 ⑤ 를 바로 뒤에 둔다.

이 실험대는 접속과 리다이렉션과 권한 설정을 두 줄에 몰아넣었다.

ssh donghyeon@192.168.122.11 'umask 077; cat > ~/kc-lab-2.yaml'  < kc-lab-2.yaml
ssh donghyeon@192.168.122.11 'cloud-init schema -c ~/kc-lab-2.yaml; rm -f ~/kc-lab-2.yaml'

명령 수가 둘에서 다섯으로 늘고 행동 하나가 명령 하나가 된다. umask 077 이 chmod 600 으로 바뀌는 것 하나가 다르다. 이 다섯 줄 형태는 이 실험대에서 치지 않았다.

:::warning

sudo 는 리스트가 아니라 문자열로 쓴다. 게스트의 cloud-init 22.4.2 스키마 검사기가 리스트 형태를 거부한다.

:::

sudo: ['ALL=(ALL) NOPASSWD:ALL']     # 거부된다
sudo: "ALL=(ALL) NOPASSWD:ALL"       # 통과한다
Error: Cloud config schema errors: users.0: {'name': 'donghyeon', 'groups':
['sudo'], 'shell': '/bin/bash', ...} is not valid under any of the given schemas

실패하면 검사기는 어느 키가 문제인지 안 알려 준다. users.0 전체를 통째로 찍고 어느 스키마에도 안 맞는다고만 하므로 키를 하나씩 바꿔 가며 좁혀야 한다. 게다가 리스트 형태도 부팅은 된다 — kc-lab-1 과 kc-lab-2 가 그 상태로 NOPASSWD sudo 가 멀쩡히 돌고 있다. 검사기만 거부하므로 「검사는 실패했는데 왜 되지」로 읽히기 쉽다.

5. 시드 ISO 를 만들어 풀에 올린다

목적 — user-data 와 meta-data 를 cidata 라벨이 붙은 볼륨 하나로 묶어 libvirt 풀에 올린다.

nano meta-kc-lab-1
instance-id: kc-lab-1-20260912
local-hostname: kc-lab-1

kc-lab-1- 뒤의 20260912 는 예시 값이다. 원래 명령은 거기에 에폭 초를 넣었다. 값 자체에 뜻은 없고, cloud-init 이 이전 실행과 다른 인스턴스로 알아보게 이전 값과 겹치지 않게 둔다. 날짜든 에폭 초든 저번과 다르기만 하면 된다.

xorrisofs -quiet -output seed-kc-lab-1.iso -volid CIDATA -joliet -rock \
  -graft-points /user-data=kc-lab-1.yaml /meta-data=meta-kc-lab-1
virsh vol-create-as default seed-kc-lab-1.iso "$(stat -c%s seed-kc-lab-1.iso)" --format raw
virsh vol-upload --pool default seed-kc-lab-1.iso seed-kc-lab-1.iso
virsh vol-list default
virsh vol-info --pool default seed-kc-lab-1.iso
stat -c%s seed-kc-lab-1.iso

정상이면 default 풀에 seed-kc-lab-1.iso 가 잡히고 Capacity 가 방금 만든 로컬 파일 크기와 같다.

시드는 cidata 라벨과 user-data, meta-data 파일을 포함해야 한다. vol-create-as는 볼륨만 만들고 실제 ISO 내용은 vol-upload가 채우므로 두 단계를 모두 수행한다. 업로드가 빠지면 libvirt 목록에는 볼륨 이름이 있어도 유효한 NoCloud 시드가 되지 않는다. instance-id는 게스트를 다시 만들 때 바꿔 cloud-init이 새 인스턴스로 처리하도록 한다.

이 실험대는 meta-data 를 명령으로 만들었다.

printf 'instance-id: kc-lab-1-%s\nlocal-hostname: kc-lab-1\n' "$(date +%s)" > meta-kc-lab-1

배울 것이 instance-id: 와 local-hostname: 두 키인데 그 형태는 서식 문자와 명령 치환을 먼저 읽게 만든다. 나머지 네 줄은 시드를 굽고 볼륨을 올리는 일이 명령 자체의 목적이라 그대로 둔다.

실패하면 게스트가 뜨고도 호스트명이 localhost 면 ④ 의 뒷줄을 빠뜨렸는지 본다.

6. DHCP 예약을 먼저 넣는다

목적 — 게스트 셋의 MAC 에 주소를 못 박아 IP 가 매번 바뀌지 않게 한다.

:::warning

이 단계가 게스트 생성보다 먼저다. 순서가 반대면 게스트가 동적 대역에서 아무 주소나 받아 버리고, 그 뒤에 예약을 넣어도 이미 잡은 리스가 유지된다. 되돌리려면 리스 만료를 기다리거나 게스트를 재시작해야 한다.

:::

virsh net-update default add ip-dhcp-host \
  "<host mac='52:54:00:aa:bb:10' name='kc-lab-edge' ip='192.168.122.10'/>" \
  --live --config
virsh net-update default add ip-dhcp-host \
  "<host mac='52:54:00:aa:bb:11' name='kc-lab-1' ip='192.168.122.11'/>" \
  --live --config
virsh net-update default add ip-dhcp-host \
  "<host mac='52:54:00:aa:bb:12' name='kc-lab-2' ip='192.168.122.12'/>" \
  --live --config
virsh net-dumpxml default | grep -E "host mac|range start"

정상이면 넣을 때 한 줄이 나오고, 확인하면 네 줄이 나온다.

Updated network default persistent config and live state
<range start='192.168.122.2' end='192.168.122.254'/>
<host mac='52:54:00:aa:bb:11' name='kc-lab-1' ip='192.168.122.11'/>
<host mac='52:54:00:aa:bb:12' name='kc-lab-2' ip='192.168.122.12'/>
<host mac='52:54:00:aa:bb:10' name='kc-lab-edge' ip='192.168.122.10'/>

persistent config 와 live state 두 마디가 다 나와야 --live --config 가 제대로 먹었다. <host> 세 줄은 MAC 끝 두 자리와 IP 끝 숫자가 짝이 맞는지 본다. <range> 줄은 예약이 아니라 동적 대역이라, 예약한 주소가 그 안에 들어 있어도 상관없다.

아직 게스트가 없어도 예약은 들어간다. 예약은 「이 MAC 이 나타나면 이 IP 를 줘라」이지 「지금 있는 게스트에게 줘라」가 아니다. MAC 은 7번의 virt-install --network mac= 에 쓸 값을 여기서 미리 정한다. --live 만 주면 재부팅에 사라지고 --config 만 주면 지금 반영되지 않는다.

2026-09-17 실제로 이미 있는 예약을 다시 넣었을 때는 이렇게 거부됐다. 오류처럼 보이지만 이미 들어가 있다는 뜻이라 그냥 넘어가면 된다.

error: Requested operation is not valid: there is an existing dhcp host entry
in network 'default' that matches "<host mac='52:54:00:aa:bb:12' ... />"

실패하면 확인은 <host mac=...> 로 한다. ip-dhcp-host 는 net-update 의 섹션 이름이라 XML 안에 그 문자열이 없고, 그것으로 grep 하면 예약이 멀쩡히 들어가 있어도 아무것도 안 나온다. 세 줄을 셸 반복문으로 돌리지도 않는다 — zsh 는 따옴표 없는 변수를 단어로 나누지 않아서 XML error: Cannot use host name '' 로 끝난다. 값을 그대로 세 번 치는 쪽이 안전하다. 재부팅 뒤에도 남는지는 비활성 정의를 따로 본다.

virsh net-dumpxml --inactive default

7. 게스트 셋을 만든다

목적 — base 이미지 위의 오버레이 디스크와 시드 볼륨을 붙여 세 게스트를 띄운다.

virt-install --name kc-lab-1 --memory 5120 --vcpus 2 \
  --disk size=20,backing_store=/var/lib/libvirt/images/base.qcow2 \
  --disk vol=default/seed-kc-lab-1.iso,device=disk,bus=virtio,readonly=on \
  --network network=default,mac=52:54:00:aa:bb:11 \
  --import --os-variant debian12 --noautoconsole
virt-install --name kc-lab-2 --memory 4096 --vcpus 2 \
  --disk size=20,backing_store=/var/lib/libvirt/images/base.qcow2 \
  --disk vol=default/seed-kc-lab-2.iso,device=disk,bus=virtio,readonly=on \
  --network network=default,mac=52:54:00:aa:bb:12 \
  --import --os-variant debian12 --noautoconsole
virt-install --name kc-lab-edge --memory 1024 --vcpus 1 \
  --disk size=10,backing_store=/var/lib/libvirt/images/base.qcow2 \
  --disk vol=default/seed-kc-lab-edge.iso,device=disk,bus=virtio,readonly=on \
  --network network=default,mac=52:54:00:aa:bb:10 \
  --import --os-variant debian12 --noautoconsole

MAC 은 6번에서 예약한 값을 한 글자도 다르지 않게 쓴다.

정상이면 엣지 생성 출력이다.

Starting install...
Allocating 'kc-lab-edge.qcow2'                              |  10 GB  00:00
Creating domain...                                          |         00:00
Domain creation completed.

Domain creation completed. 한 줄을 본다. 그 위 Allocating 이 00:00 으로 즉시 끝나는 쪽이 정상이다 — 오버레이라 10GB 를 실제로 쓰지 않는다.

virt-install 은 VM 을 만드는 것 자체가 목적인 명령이라 옵션이 길어도 이 형태로 둔다. 여기서 준 값이 곧 게스트의 정체다 — 이름, 메모리, vCPU, 오버레이 디스크, 시드 볼륨, 예약해 둔 MAC. --disk size=20,backing_store=... 는 복사가 아니라 오버레이라, base 를 읽기 전용으로 두고 변경분만 새 파일에 쌓으므로 20GB 짜리를 둘 만들어도 실제 디스크는 몇백 MB 만 쓴다.

:::warning

이 실험대에서는 --cloud-init으로 연결한 시드에서 기대한 NoCloud 데이터소스를 확인하지 못했다. 반면 seed ISO를 bus=virtio 디스크로 붙인 구성에서는 게스트의 cloud-init status --long에서 DataSourceNoCloud [seed=/dev/vdb]를 확인했다. 따라서 현재 절차는 실제로 확인한 virtio seed 방식을 사용한다. 현재 증거만으로 --cloud-init 경로가 기대대로 동작하지 않은 원인을 특정하지 않는다.

:::

실패하면 XML error: Cannot use host name '' 이 나오면 6번의 예약이 빈 이름으로 들어간 것이니 그 세 줄을 값 그대로 다시 친다.

이 실험대에서 사용한 VM 사양과 주소

게스트 셋의 배치다. 디스크는 전부 base 이미지 위의 오버레이이고 복사가 아니다.

게스트 IP · MAC 끝 vCPU · 메모리 · 디스크 무엇이 도나
kc-lab-edge 192.168.122.10 · :10 1 · 1024MB · 10GB nginx · certbot
kc-lab-1 192.168.122.11 · :11 2 · 5120MB · 20GB k3s server · Traefik
kc-lab-2 192.168.122.12 · :12 2 · 4096MB · 20GB k3s agent · Traefik

이미지와 시드 쪽 값이다.

무엇 값
base 이미지 /var/lib/libvirt/images/base.qcow2 — Debian 12 genericcloud amd64
게스트 OS Debian GNU/Linux 12 (bookworm)
디스크 base 위의 오버레이(backing_store=). 복사가 아니다
시드 seed-<이름>.iso — CIDATA 라벨 · user-data·meta-data · bus=virtio
cloud-init 패키지 [curl, nftables]
스키마 검사기 2026-09-17 관측: cloud-init 22.4.2 · bookworm/latest 사용으로 재다운로드 버전은 미고정

메모리는 처음 만들 때 세 대 다 3584MB 였고, 실험을 늘리면서 실제로 5120MB 와 4096MB 로 재배분했다. 세 게스트의 배정 합은 5120+4096+1024 = 10,240MB 이고, 호스트 RAM 은 11,648MiB 다. 배정 합이 더 작아서 배정률은 10240/11648 = 87.9% 이고, 배정하지 않고 남은 것이 1,408MiB 다. 그래서 이 배치는 「Guest configured memory 총량이 Host physical RAM보다 크다」는 Memory Overcommit 에 해당하지 않는다.

호스트 RAM 11,648MiB 는 2026-09-10 에 이 호스트에서 free -m | head -2 로 받은 Mem: 행의 total 이다. free -m 은 MiB 로 찍으므로, 자기 호스트에서 이 배치를 다시 잡을 때도 같은 명령으로 재고 MiB 로 읽는다.

표의 메모리 칸은 virt-install --memory에 준 값이다. 2026-09-10 기록에서는 kc-lab-2의 dommemstat actual이 3120MB로 나왔지만, 그 원인은 당시 확인되지 않았다. 2026-09-21에는 dominfo와 dommemstat을 나란히 읽어 configured/current/actual이 모두 4096MiB인 것을 확인했다. virtio-balloon 장치는 실제로 존재하지만 장치 존재만으로 과거 3120MB의 원인을 balloon이라고 귀속하지 않는다.

vCPU 합은 2 + 2 + 1 = 5 이고 이 호스트의 논리 코어는 8 이다. libvirt 는 vCPU 합이 논리 코어 수를 넘어도 막지 않으므로, 더 크게 잡아도 virt-install 은 통과한다. 여유를 둘지는 이 표에서 정한다.

세 VM이 뜨고 SSH가 키로 붙는지 확인한다

확인 ① 세 게스트가 떴고 cloud-init 이 제 일을 했는가

도메인 셋이 돌고 있는지, 그리고 게스트 안이 시드대로 채워졌는지.

virsh list --all
ssh donghyeon@192.168.122.11 'hostname; cat /etc/os-release | head -1'

실측

 Id   Name          State
-----------------------------
 2    kc-lab-1      running
 4    kc-lab-2      running
 5    kc-lab-edge   running

kc-lab-1
PRETTY_NAME="Debian GNU/Linux 12 (bookworm)"

세 가지다. State 가 세 대 다 running 인가(shut off 면 아직 안 뜬 것이고 Id 칸이 - 로 비어 있다), SSH 가 비밀번호를 묻지 않고 통과했는가, hostname 이 kc-lab-1 인가 localhost 인가.

이 세 줄이 cloud-init 성공의 판정 기준 전부다. 호스트명이 바뀌었다는 것은 시드가 읽혔다는 뜻이고, 시드가 읽혔으면 같은 파일에 있던 SSH 키도 들어갔다는 뜻이다. localhost 가 나오면 SSH 설정을 고치지 말고 시드부터 의심한다. Id 번호가 2 보다 큰 것에는 아무 뜻도 없다 — 만들고 지운 이력이 그렇게 남는다.

확인 ② 엣지가 예약한 IP 를 받았고 cloud-init 이 끝났는가

DHCP 예약이 실제로 먹었는지, 그리고 초기화가 아직 도는 중인지 끝났는지.

ssh kc-lab-edge 'hostname; ip -4 -br addr show enp1s0; cloud-init status'

실측

kc-lab-edge
enp1s0           UP             192.168.122.10/24 metric 100
status: done

세 줄이다. 호스트명이 kc-lab-edge 인가, 주소가 예약한 .10 인가, cloud-init status 가 done 인가.

running 이면 아직 패키지를 받는 중이니 기다린다. 이 실험대에서는 약 50초 걸렸다. error 면 어느 모듈이 실패했는지 길게 본다.

ssh kc-lab-edge 'cloud-init status --long'

확인 ③ 게스트에 못 들어갈 때는 화면을 직접 뜬다

SSH 가 막힌 원인이 시드 쪽인지 그 뒤인지.

virsh screenshot kc-lab-1 /tmp/kc1.ppm

확장자와 무관하게 PNG 로 저장된다.

이미지를 열어 로그인 프롬프트 앞의 호스트명 한 낱말만 본다. localhost login: 인가 kc-lab-1 login: 인가.

localhost 면 cloud-init 이 아예 안 돌았다. 시드를 못 찾았거나(7번의 bus=virtio) YAML 파싱에 실패한 것(3번)이므로 SSH 쪽은 볼 필요가 없다. kc-lab-1 이면 cloud-init 은 돌았고 그 안의 사용자·키 단계에서 틀린 것이라, 콘솔로 들어가 게스트 안의 로그를 본다.

virsh console kc-lab-1
sudo cloud-init status --long
sudo journalctl -u cloud-init -n 50

콘솔 로그인에 쓰는 비밀번호가 2번 ④ 로 만든 값이다. 이 한 장과 이 두 줄이 「SSH 가 안 되는 이유」를 절반으로 줄인다.

세 게스트 생성 확인표

무엇 명령 통과
base 이미지 qemu-img info /var/lib/libvirt/images/base.qcow2 file format: qcow2 · backing file: 줄이 없다
시드 볼륨 virsh vol-info --pool default seed-kc-lab-1.iso Capacity 가 로컬 파일 크기와 같다
예약 virsh net-dumpxml default | grep -E "host mac|range start" <host> 세 줄 · MAC 끝과 IP 끝이 짝
도메인 virsh list --all 세 대 다 running
게스트 안 ssh kc-lab-edge 'hostname; cloud-init status' kc-lab-edge · status: done

VM은 떴는데 SSH가 안 붙을 때

증상 원인 확인
SSH Permission denied (publickey) · hostname 이 localhost cloud-init 이 안 돌았다. 시드를 SATA 로 붙였거나 YAML 파싱 실패 virsh screenshot
user-data 를 고쳤는데 반영 안 됨 instance-id 가 같아 건너뜀 meta-data 의 id 확인
IP 가 매번 바뀐다 DHCP 예약이 --config 없이 들어감 net-dumpxml
XML error: Cannot use host name '' zsh 가 따옴표 없는 변수를 단어 분리하지 않는다 세 줄을 값 그대로 친다
예약 넣을 때 existing dhcp host entry 이미 들어가 있다. 오류가 아니다 net-dumpxml 로 세 줄 확인
시드는 올라갔는데 cloud-init 이 안 돈다 vol-upload 를 빠뜨려 볼륨이 비었다 virsh vol-info --pool default seed-kc-lab-1.iso
qemu-img info 가 raw 라고 한다 내려받기가 끊겨 오류 페이지를 저장했다 다시 받는다
VM 이 느리다 KVM 미사용 앞 단계로

SSH 가 안 붙는 증상 넷을 갈라 보는 방법은 이 표보다 자세한 기록이 따로 있다.

이 절차에서 실제로 확인한 범위

  • 게스트 세 대의 IP·MAC·vCPU·메모리, Debian GNU/Linux 12 (bookworm), cloud-init status: done, cloud-init 대기 약 50초, 스키마 검사기의 거부 문구, Valid cloud-config 한 줄, 예약을 넣을 때와 다시 넣을 때의 문구, virt-install 의 네 줄 출력.
  • 실제 배치는 처음 만들 때 3584MB 였고, 실험을 늘리면서 5120MB 와 4096MB 로 재배분했다. 세 게스트의 배정 합 10,240MB 는 호스트 RAM 11,648MiB 보다 작고, 배정하지 않고 남은 것이 1,408MiB 다. 「Guest configured memory 총량이 Host physical RAM보다 크다」는 Memory Overcommit 에 해당하지 않는 배치다.
  • kc-lab-1.yaml 을 템플릿에서 어떻게 만드는지가 원본에도 없다. kc-lab.yaml.example 이 반입되지 않아 대조하지 못했다.
  • 2026-09-17 에 확인 ①·②·③ 을 그대로 쳤고 셋 다 위에 실은 대로 나왔다. 세 도메인이 running, 192.168.122.11 의 hostname 이 kc-lab-1 이고 PRETTY_NAME 이 Debian 12, 엣지가 192.168.122.10/24 와 status: done, virsh screenshot 이 .ppm 이름으로 저장하면서 with type of image/png 라고 답하고 file 도 PNG 라고 읽는다. virsh list 의 Id 는 13·15·16 이고 줄 순서도 위와 다른데, 본문이 적은 대로 그 번호에는 뜻이 없다.
  • cloud-init 의 packages 에 certbot 은 없다. 2026-09-17 에 갈렸다. 뜬 게스트가 실제로 받은 user-data 를 열어 보니 packages: [curl, nftables] 한 줄이고, 저장소 템플릿에는 nginx · certbot · python3-certbot-dns-cloudflare 셋이 주석으로 막혀 있다. 넷 중 curl 과 nftables 만 산다. 04 의 표에 kc-lab-edge 가 nginx · certbot 으로 적힌 것은 그 게스트가 끝나면 맡을 역할이지 cloud-init 이 깔아 준 것이 아니다 — nginx 는 03 의 1번이, certbot 은 04 의 1번이 직접 깐다.
sudo grep -n "packages" /var/lib/cloud/instance/user-data.txt
19:packages: [curl, nftables]
  • virsh vol-info · net-dumpxml --inactive · cloud-init status --long 은 2026-09-17 에 쳤다. 볼륨 일곱의 용량과 실제 할당은 이렇다 — 선언한 크기와 디스크가 실제로 먹는 양이 크게 다르다. 오버레이라 쓴 만큼만 먹는다.
base.qcow2             Capacity=3.00 GiB     Allocation=323.25 MiB
kc-lab-1.qcow2         Capacity=20.00 GiB    Allocation=5.40 GiB
kc-lab-2.qcow2         Capacity=20.00 GiB    Allocation=3.85 GiB
kc-lab-edge.qcow2      Capacity=10.00 GiB    Allocation=316.26 MiB
seed-kc-lab-{1,2,edge}.iso   Capacity=370.00 KiB   Allocation=372.00 KiB

net-dumpxml default --inactive에서는 virbr0, 동적 DHCP 대역, 예약 세 줄이 함께 보였다. --inactive 출력에도 예약이 남아 있으므로 해당 예약이 영구 설정에 포함된 것을 확인할 수 있다.

  • 2026-09-17의 cloud-init status --long 마지막 줄은 이 문서의 7번 설명과 일치했다.
status: done
boot_status_code: enabled-by-generator
last_update: Thu, 17 Sep 2026 04:24:22 +0000
detail:
DataSourceNoCloud [seed=/dev/vdb][dsmode=net]

확인할 값은 DataSourceNoCloud [seed=/dev/vdb]다. 현재 구성에서는 seed ISO를 virtio 디스크로 붙였고, cloud-init이 /dev/vdb에서 데이터소스를 읽는 것을 실제 게스트에서 확인했다.

  • 파일을 옮겨 검사하는 다섯 줄 형태와 virsh console 은 가이드가 적어 둔 명령이고 이 실험대가 캡처한 출력이 없다. virsh console 은 대화형이라 비대화식으로 밟지 않았다.
  • 편집기로 kc-lab-1.yaml 과 meta-kc-lab-1 을 여는 형태도 이 실험대가 치지 않았다. 이 실험대는 치환 명령과 서식 출력으로 만들었고, 같은 상태에 닿는지는 다시 재지 않았다.
  • 세 게스트와 seed volume, DHCP 예약을 모두 제거하는 전체 rollback은 아직 끝까지 검증하지 않았다.
  • 2026-09-21에는 kc-lab-1과 kc-lab-2를 실제로 철거한 뒤 이 절차의 cloud-init·qcow2 overlay·DHCP 예약·virt-install 경로로 다시 만들었고, 두 worker가 Debian 12로 부팅해 SSH와 cloud-init을 통과한 뒤 k3s 클러스터에 다시 합류하는 것까지 확인했다. 따라서 worker 두 대의 재생성 경로는 재검증됐다. kc-lab-edge 전체 삭제·재생성은 실제 TLS 종단점과 인증서를 보존하기 위해 이번 재검증에서 수행하지 않았으므로, 세 VM 전체를 한 번에 비운 뒤 다시 만드는 경로까지 확인됐다고 쓰지는 않는다.