Host Network

장기 운영되는 host는 DHCP보다 static IP가 다루기 쉽습니다. 이 문서는 bare-metal, VM, Proxmox node 같은 host에 static IP를 적용하는 흐름을 설명합니다.

핵심은 두 파일의 역할을 구분하는 것입니다.

  • inventory.toml: Ansible이 지금 접속할 host catalog
  • host/network.vars.yml: netplan으로 적용할 static network 설정

1. 전체 과정

1-1. 작업의 핵심

DHCP로 먼저 붙은 host를 static IP로 전환할 때는 아래 순서로 진행합니다.

1-2. 단계 요약

1. inventory.toml에 host 추가
   ansible_host는 지금 SSH 가능한 IP로 둔다.

2. host/network.vars.yml에 static IP 설정 추가
   interface, addresses, gateway, DNS 등을 적는다.

3. inventory.yml 렌더링
   Ansible이 inventory.toml 변경을 읽게 한다.

4. host/network/apply 실행
   netplan 파일을 쓰고 새 IP로 SSH가 열리는지 확인한다.

5. 성공 후 inventory.toml의 ansible_host를 static IP로 갱신
   이후부터 Ansible은 새 static IP로 접속한다.

6. inventory.yml 재렌더링 및 validate

명령으로 보면 아래 흐름입니다.

1-3. 명령 흐름

make site/inventory/render SITE=tirosh-home
make host/network/apply SITE=tirosh-home HOST_TARGET_NAME=gpu-01 ASK_PASS=true ASK_BECOME_PASS=true

# apply 성공 후 inventory.toml의 ansible_host를 static IP로 변경
make site/inventory/render SITE=tirosh-home
make validate SITE=tirosh-home

2. inventory.toml에 host 추가

2-1. ansible_host의 의미

inventory.toml에는 Ansible이 접속할 host를 추가합니다. static IP를 적용하기 전이라면 ansible_host는 아직 최종 static IP가 아니라 현재 SSH 가능한 DHCP IP여야 합니다.

예를 들어 gpu-01이 현재 DHCP로 172.31.0.205을 받았고, 최종 static IP를 172.31.0.25으로 바꾸려는 상황입니다.

2-2. Bare-metal host 예시

[baremetals.gpu-01]
ansible_host = "172.31.0.205"
ansible_user = "tirosh"
ansible_become_user = "root"
rke2_node_labels = [
  "node.tirosh.dev/role=gpu",
  "node.tirosh.dev/site=tirosh-home",
  "node.tirosh.dev/model=dgx-spark",
]
workloads = ["gpu"]
rke2 = { cluster = "gpu", role = "agent" }

VM도 같은 방식으로 host catalog에 들어갈 수 있습니다. 다만 VM의 IP를 OpenTofu/cloud-init으로 관리한다면 netplan playbook이 아니라 VM catalog에서 관리하는 편이 더 자연스럽습니다.

2-3. VM host 예시

[vms.argocd]
ansible_host = "172.31.0.10"
ansible_user = "tirosh"
ansible_become_user = "root"
proxmox_vm_name = "argocd"
workloads = ["k3s", "argocd"]

수정 후 Ansible inventory를 렌더링합니다.

2-4. Inventory 렌더링

make site/inventory/render SITE=tirosh-home

3. host/network.vars.yml에 static IP 추가

3-1. 파일의 역할

host/network.vars.yml에는 netplan에 적용할 static network 설정을 둡니다.

공통값은 host_network_defaults에 둡니다.

3-2. 공통 기본값

host_network_defaults:
  renderer: networkd
  netplan_file: 99-tirosh-static.yaml
  apply: true
  dhcp4: false
  dhcp6: false
  nameservers:
    - 1.1.1.1
    - 8.8.8.8
  search_domains: []

host별 설정은 host_network_hosts 아래에 host alias별로 추가합니다. alias는 inventory.toml의 host 이름과 같아야 합니다.

3-3. Host별 static IP

host_network_hosts:
  gpu-01:
    interface: enP7s7
    addresses:
      - 172.31.0.25/16
    gateway4: 172.31.0.1

addresses는 netplan 형식입니다. host IP와 subnet prefix를 함께 적습니다.

3-4. Prefix 선택

  • 일반 LAN: 172.31.0.25/16 또는 172.31.0.25/24
  • 특수한 point-to-point 구성: /32

현재 172.31.0.0 대역이 255.255.0.0 netmask라면 /16을 사용합니다. /32는 일반 LAN static IP 표현이 아닙니다.

4. network apply 실행

4-1. 한 대씩 적용

host별로 하나씩 적용합니다. 여러 대를 한 번에 바꾸면 장애 지점을 분리하기 어렵습니다.

make host/network/apply SITE=tirosh-home HOST_TARGET_NAME=gpu-01 ASK_PASS=true ASK_BECOME_PASS=true

playbook은 아래 작업을 수행합니다.

4-2. Playbook 작업

1. host_network_hosts.<host> 설정 검증
2. /etc/netplan/<netplan_file> 백업
3. static netplan 파일 작성
4. netplan generate
5. netplan apply
6. 새 IP의 SSH port 대기

새 IP에서 SSH가 열리면 apply가 성공한 것입니다.

5. 성공 후 inventory 갱신

5-1. ansible_host 변경

static IP 적용이 성공하면 inventory.toml의 ansible_host를 새 static IP로 바꿉니다.

[baremetals.gpu-01]
ansible_host = "172.31.0.25"

그 다음 inventory를 다시 렌더링하고 site validation을 실행합니다.

5-2. 렌더링과 검증

make site/inventory/render SITE=tirosh-home
make validate SITE=tirosh-home

이제 이후 Ansible 명령은 새 static IP로 접속합니다.

6. 실패 시 확인

6-1. Inventory를 아직 바꾸지 않기

host/network/apply가 새 IP SSH 대기 단계에서 실패하면 아직 inventory.toml을 새 IP로 바꾸지 않습니다. 먼저 아래를 확인합니다.

6-2. 점검 항목

  • interface가 실제 uplink interface인지 확인합니다.
  • addresses의 subnet prefix가 site network와 맞는지 확인합니다.
  • gateway4가 같은 subnet에서 reachable한지 확인합니다.
  • 기존 DHCP IP로 SSH가 아직 가능한지 확인합니다.
  • 현장 console에서 /etc/netplan/99-tirosh-static.yaml을 확인합니다.
  • Docker가 설치된 host라면 docker0 같은 bridge가 아니라 실제 physical interface를 대상으로 삼았는지 확인합니다.

6-3. 기억할 원칙

ansible_host는 "최종적으로 가져야 할 IP"가 아니라 "Ansible이 지금 접속할 주소"입니다. 그래서 static IP 적용 전에는 현재 DHCP IP, 적용 성공 후에는 새 static IP를 넣습니다.