Ansible 에서 proxmox_kvm 모듈 사용하기

Proxmox 란 ?

Proxmox Virtual Environment 는 가상화 관리를 위한 오픈 소스 소프트웨어 서버, 호스팅 되는 타입2 하이퍼 바이저로 리눅스와 윈도우를 포함한 운영체제 들을 x64 하드웨어에서 구동한다.
수정된 우분투 LTS 커널을 갖춘 데비안 기반 리눅스 배포판, 가상 머신과 컨ㄴ테이너의 디플로이와 관리를 가능하게 한다.

는 기본적인 설명인데, 관련 자료가 많이 없다. 들리는 바에 의하면 대기업에서 쓰기엔 적절치 않고 적당한 규모의 회사에서 사용하기에 좋은 툴이라고 한다.

 

모듈 사용 설정

awx 에서 proxmox_kvm 을 사용하기 위해서 awx/collections 에 모듈 사용을 requirements.yml 로 추가한다.

---
collections:
  - name: community.general
    version: '4.1.0'

proxmox_kvm 은 community.general collections 에 포함되어 있고 해당 콜렉션을 사용하겠다고 명시하여 proxmox_kvm 을 사용할 수 있게 된다.

https://docs.ansible.com/ansible/latest/collections/community/general/proxmox_kvm_module.html

community.general.proxmox_kvm module – Management of Qemu(KVM) Virtual Machines in Proxmox VE cluster — Ansible Documentatio

공식 문서의 주소는 위와 같으며 실제 모듈을 사용하는 예시를 잘 보여주고 있다. 해당 문서에서 발췌하여 아래에서 clone, delete, get, update 등의 동작을 예시로 설명하려고 한다.

 

Token, Host 설정

---
proxmox_api_host: proxmox_api.host.net
proxmox_user: proxmox_user
proxmox_token_id: proxmox_token_id
proxmox_api_token_secret: proxmox_token_secret_key

proxmox_kvm을 사용하기 위해서는 proxmox cluster 에 접근할 수 있는 user와 token 그리고 권한을 부여 받아야 한다.
proxmox 관리자로부터 부여받은 user, token 값을 해당 변수로 지정해주었다. user와 token 을 부여받았다고 하더라도, 해당 user가 수행할 동작에 대한 권한이 있어야 가능하다.

proxmox_api_host 에 대해 주의할 점은 포트와 http 를 생략하고 적어야 한다는 점이다. 
기본적으로 proxmox는 8006 포트를 사용하는데, 해당 모듈에서 자동으로 8006 포트와 통신을 시도하는 것으로 확인되었다.
만약 proxmox_api_host 의 주소가 https://proxmox_api.host.net:8006 이라면 해당 값에는 proxmox_api.host.net 만 적어주면 된다.

아래에서는 간단한 CRUD 에 대해 어떻게 사용하는지 정리하려고 한다. 그 외에 복잡한 동작은 아래의 사용예시에서 공식문서를 참고하여 수정해 나가면서 사용하면 될 것 같다.

 

VM Clone

---
# vm 생성
- name: Clone Vm
  community.general.proxmox_kvm:
    api_user: "{{ proxmox_user }}"
    api_token_id: "{{ proxmox_token_id }}"
    api_token_secret: "{{ proxmox_api_token_secret }}"
    api_host: "{{ proxmox_api_host }}"
    clone: "target-host-name"
    name: "clone-host-name"
    node: "clone-node"
    timeout: 500

해당 코드는 VM을 Clone 하는 코드이며, 기존에 proxmox 서버에 clone 파라미터 (target-host-name) 에 적힌 값을 가지고 있는 VM이 이미 존재해야 한다. 
즉 clone(target-host-name) VM 을 name (clone-host-name) 을 가진 VM 으로 복제하는 것이다.
api_user, api_token_id, api_token_secret 을 통해 해당 API 를 사용할 유저 정보를 전달하고, api_host 는 proxmox 주소로 볼 수 있다.

해당 API 를 호출하고 AWX 로그를 확인해보면 response 로 vmid 와 msg 를 뿌려준다.
vmid 는 Clone 된 VM의 id 값을 가지고 있고 이번 로그에서 보면 120 을 가지고 있다. msg 에는 수행 결과에 대한 간단한 메세지 정보를 주는데, 102번 VM을 clone 하여 120번 을 생성했다고 안내해주고 있다.

 

VM Update

---
# vm update
- name: Update VM configuration
  community.general.proxmox_kvm:
    api_user: "{{ proxmox_user }}"
    api_token_id: "{{ proxmox_token_id }}"
    api_token_secret: "{{ proxmox_api_token_secret }}"
    api_host: "{{ proxmox_api_host }}"
    name: "update-vm"
    node: "target-vm-node"
    cores: 8
    memory: 16384
    update: true
    timeout: 500

Update 는 간단하다. 해당 API가 호출되는 api user, token 정보를 넘겨준 뒤 Update 할 VM 이 위치한 노드를 적어주고, 해당 VM 의 이름(name)을 적어준다. 
그리고 업데이트할 정보를 적어주면 되는데, 여기서는 cores, memory 를 적어주었다. 해당 task 를 수행하면 VM 정보가 업데이트 된다.

 

VM Get Information

---
# vm 조회
- name: Get VM
  community.general.proxmox_kvm:
    api_user: "{{ proxmox_user }}"
    api_token_id: "{{ proxmox_token_id }}"
    api_token_secret: "{{ proxmox_api_token_secret }}"
    api_host: "{{ proxmox_api_host }}"
    name: "target-vm-name"
    node: "target-vm-node"
    state: current
    timeout: 500

사용 방법은 유사하게 api 정보 전달, name과 node 정보를 전달하여 대상 VM 을 선택해준다. 
그리고 state : current 를 전달하여 현재 상태 정보를 요청하는 API 를 호출하면 response 의 msg 에 해당 정보를 간단하게 표시해주며, status 값을 같이 보내주게 된다.
정지되어 있는 Vm 을 호출했을 때 status: stopped 를 반환하는 것을 확인하였다.

 

VM Remove

---
# vm 삭제
- name: Remove VM
  community.general.proxmox_kvm:
    api_user: "{{ proxmox_user }}"
    api_token_id: "{{ proxmox_token_id }}"
    api_token_secret: "{{ proxmox_api_token_secret }}"
    api_host: "{{ proxmox_api_host }}"
    name: "target-vm-name"
    node: "target-vm-node"
    state: absent
    timeout: 500

Vm 정보를 Get 하는것과 state 정보만 다르다. 정보를 받아올 때는 current 값을 넘겨주었지만 삭제할 때는 absent 를 넣어주었다.
주의할 점은 VM 상태가 stopped 상태여야 삭제가 가능하다는 것이다. 혹은 force: yes 옵션을 주어 강제로 삭제하는 방법도 있다.
정지 상태가 아니거나 force 옵션이 없다면 실행 중인 VM 이라는 msg 를 주면서 정상적으로 삭제되지 않는다.

 

VM Start & Stop

---
# vm 시작
- name: Start VM
  community.general.proxmox_kvm:
    api_user: "{{ proxmox_user }}"
    api_token_id: "{{ proxmox_token_id }}"
    api_token_secret: "{{ proxmox_api_token_secret }}"
    api_host: "{{ proxmox_api_host }}"
    name: "target-vm-name"
    node: "target-vm-node"
    state: started
    timeout: 500
    
# vm 중지
- name: Stop VM
  community.general.proxmox_kvm:
    api_user: "{{ proxmox_user }}"
    api_token_id: "{{ proxmox_token_id }}"
    api_token_secret: "{{ proxmox_api_token_secret }}"
    api_host: "{{ proxmox_api_host }}"
    name: "target-vm-name"
    node: "target-vm-node"
    state: stopped
    timeout: 500

지정된 VM의 start 혹은 stop 도 동일하게 API를 통해 사용할 수 있다.
조회, 삭제와 마찬가지로 state의 값을 변경하면 되는데 시작 시에는 started, 종료 시에는 stopped 를 넣어주면 된다.

 

---

공식문서에 정말 다양하고 많은 동작이 예시로 기술되어 있다.

앞에서 작성한 예시는 가장 기초적인 CRUD 를 다룬 내용이며, 응용하면 얼마든지 복잡한 인프라에 대한 자동화를 구현할 수 있을 것으로 보인다.