# k8s-cp1 VM 네트워크 접속 불가 트러블슈팅

> 작성일: 2026-03-05

## 증상

- `virsh domifaddr k8s-cp1` 결과에 IP가 표시되지 않음
- VM에 SSH 접속 불가

## 원인 분석

### 원인 1: 네트워크 대역 불일치

VM은 `virbr0` (libvirt 기본 NAT 네트워크, **198.51.100.0/24**)에 연결되어 있었지만,
cloud-init network-config에서는 **203.0.113.70/24**를 할당하고 있었다.

```
# virt-install 시 사용된 네트워크
--network bridge=virbr0    ← 198.51.100.0/24 대역 (libvirt 기본 NAT)

# cloud-init network-config에 설정된 IP
addresses: 203.0.113.70/24  ← 203.0.113.0/24 대역 (호스트 LAN)
```

브릿지 대역과 VM IP 대역이 다르므로 통신 자체가 불가능했다.

### 원인 2: user-data.yaml `#cloud-config` 헤더 누락

```yaml
# 잘못된 형식 (헤더 없음)
hostname: k8s-cp1
users:
  - name: kube
    ...

# 올바른 형식
#cloud-config          ← 이 줄이 반드시 있어야 함
hostname: k8s-cp1
users:
  - name: kube
    ...
```

`#cloud-config` 헤더가 없으면 cloud-init이 파일을 cloud-config 형식으로 인식하지 못해,
사용자 생성 및 SSH 키 주입이 수행되지 않았다.
ping은 되지만 SSH 인증이 실패하는 현상의 원인이었다.

### 원인 3: 베이스 이미지 오염

`ubuntu2404-base.qcow2`는 이전에 이미 cloud-init이 한 번 실행된 이미지였다.
cloud-init은 기본적으로 **첫 번째 부팅에서만** 실행되므로, 이 이미지를 복사해서 VM을 만들면
새로운 cloud-init ISO를 넣어도 무시된다.

| 이미지 | 용도 |
|--------|------|
| `noble-server-cloudimg-amd64.img` | 원본 클라우드 이미지 (cloud-init 미실행) |
| `ubuntu2404-base.qcow2` | 이전에 사용된 이미지 (cloud-init 이미 실행됨) |

## 해결 과정

### 1단계: 네트워크를 virbr0 → br-host (호스트 브릿지)로 변경

호스트에 이미 `br-host` 브릿지가 구성되어 있었다 (eth0 → br-host, 203.0.113.2/24).
VM을 `br-host`에 연결하면 로컬 네트워크(203.0.113.0/24) 대역을 직접 사용할 수 있다.

```
--network bridge=virbr0  →  --network bridge=br-host
```

### 2단계: user-data.yaml에 `#cloud-config` 헤더 추가

```bash
sudo vi /var/lib/libvirt/cloud-init/k8s-cp1-user-data.yaml
# 첫 줄에 #cloud-config 추가
```

### 3단계: cloud-init ISO 재생성

```bash
sudo cloud-localds /var/lib/libvirt/cloud-init/k8s-cp1-cidata.iso \
  /var/lib/libvirt/cloud-init/k8s-cp1-user-data.yaml \
  --network-config /var/lib/libvirt/cloud-init/k8s-cp1-network-config.yaml
```

### 4단계: 원본 이미지에서 디스크 새로 생성 후 VM 재생성

```bash
# 기존 VM 삭제
sudo virsh destroy k8s-cp1
sudo virsh undefine k8s-cp1

# 원본 클라우드 이미지에서 복사 (cloud-init 미실행 상태)
sudo cp /var/lib/libvirt/images/noble-server-cloudimg-amd64.img \
       /var/lib/libvirt/images/k8s-cp1.qcow2
sudo qemu-img resize /var/lib/libvirt/images/k8s-cp1.qcow2 20G

# br-host 브릿지로 VM 생성
sudo virt-install \
  --name k8s-cp1 \
  --memory 2048 \
  --vcpus 2 \
  --disk path=/var/lib/libvirt/images/k8s-cp1.qcow2,format=qcow2 \
  --disk path=/var/lib/libvirt/cloud-init/k8s-cp1-cidata.iso,device=cdrom \
  --os-variant ubuntu24.04 \
  --network bridge=br-host,model=virtio \
  --graphics none \
  --console pty,target_type=serial \
  --noautoconsole \
  --import
```

### 5단계: 접속 확인

```bash
ssh kube@203.0.113.70   # 성공
```

## 교훈

1. **cloud-init network-config의 IP 대역은 연결할 브릿지 대역과 반드시 일치해야 한다**
2. **user-data.yaml 첫 줄에 `#cloud-config`이 없으면 cloud-init이 동작하지 않는다**
3. **cloud-init은 첫 부팅에서만 실행된다** — 설정 변경 시 반드시 원본(미사용) 이미지에서 디스크를 새로 복사해야 한다