Proxmox VE を管理するため Terraform に入門した

先日構築した Proxmox VE クラスタを IaC で管理したいと思い、重い腰を上げてついに Terraform に入門した。

Terraform はクラウドリソースを管理するのがメインと思っていたけど、幸いにも Proxmox VE にも対応している。「対応している」よりは「誰かが対応するように Provider というものを作ってくれている」という表現のほうが正しい。

Proxmox VE で VM やコンテナを作るための「Proxmox Provider」というものが公開されている。

Terraform Registry - proxmox

手始めに Proxmox Provider のドキュメントに沿って VM を作成してみる。

Proxmox VE

Terraform 用ユーザ/ロールの作成

Proxmox VE に Terraform が利用するユーザとロールを作成する。クラスタ管理権限を付与することもできるが、必要最低限の権限を割り当てることでセキュリティリスクを低減する。

root@pve1:~# pveum role add TerraformProv -privs "VM.Allocate VM.Clone VM.Config.CDROM VM.Config.CPU VM.Config.Cloudinit VM.Config.Disk VM.Config.HWType VM.Config.Memory VM.Config.Network VM.Config.Options VM.Monitor VM.Audit VM.PowerMgmt Datastore.AllocateSpace Datastore.Audit"
root@pve1:~# pveum user add terraform-prov@pve --password <password>
root@pve1:~# pveum aclmod / -user terraform-prov@pve -role TerraformProv

作成したロールとユーザを確認する。表形式で出力されるが見切れてしまっている。

root@pve1:~# pveum role list
┌───────────────────┬───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
│ roleid            │ privs                                                                                                                 
╞═══════════════════╪═══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════
│ Administrator     │ Datastore.Allocate,Datastore.AllocateSpace,Datastore.AllocateTemplate,Datastore.Audit,Group.Allocate,Permissions.Modif
├───────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
│ NoAccess          │                                                                                                                       
├───────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
│ PVEAdmin          │ Datastore.Allocate,Datastore.AllocateSpace,Datastore.AllocateTemplate,Datastore.Audit,Group.Allocate,Permissions.Modif
├───────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
│ PVEAuditor        │ Datastore.Audit,Pool.Audit,SDN.Audit,Sys.Audit,VM.Audit                                                               
├───────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
│ PVEDatastoreAdmin │ Datastore.Allocate,Datastore.AllocateSpace,Datastore.AllocateTemplate,Datastore.Audit                                 
├───────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
│ PVEDatastoreUser  │ Datastore.AllocateSpace,Datastore.Audit                                                                               
├───────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
│ PVEPoolAdmin      │ Pool.Allocate,Pool.Audit                                                                                              
├───────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
│ PVEPoolUser       │ Pool.Audit                                                                                                            
├───────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
│ PVESDNAdmin       │ SDN.Allocate,SDN.Audit                                                                                                
├───────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
│ PVESysAdmin       │ Permissions.Modify,Sys.Audit,Sys.Console,Sys.Syslog                                                                   
├───────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
│ PVETemplateUser   │ VM.Audit,VM.Clone                                                                                                     
├───────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
│ PVEUserAdmin      │ Group.Allocate,Realm.AllocateUser,User.Modify                                                                         
├───────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
│ PVEVMAdmin        │ VM.Allocate,VM.Audit,VM.Backup,VM.Clone,VM.Config.CDROM,VM.Config.CPU,VM.Config.Cloudinit,VM.Config.Disk,VM.Config.HWT
├───────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
│ PVEVMUser         │ VM.Audit,VM.Backup,VM.Config.CDROM,VM.Config.Cloudinit,VM.Console,VM.PowerMgmt                                        
├───────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
│ TerraformProv     │ Datastore.AllocateSpace,Datastore.Audit,VM.Allocate,VM.Audit,VM.Clone,VM.Config.CDROM,VM.Config.CPU,VM.Config.Cloudini
└───────────────────┴───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────

root@pve1:~# pveum user list
┌────────────────────┬─────────┬──────────────────┬────────┬────────┬───────────┬────────┬──────┬──────────┬────────────┬────────┐
│ userid             │ comment │ email            │ enable │ expire │ firstname │ groups │ keys │ lastname │ realm-type │ tokens │
╞════════════════════╪═════════╪══════════════════╪════════╪════════╪═══════════╪════════╪══════╪══════════╪════════════╪════════╡
│ root@pam           │         │ nnstt1@gmail.com │ 1      │      0 │           │        │      │          │ pam        │        │
├────────────────────┼─────────┼──────────────────┼────────┼────────┼───────────┼────────┼──────┼──────────┼────────────┼────────┤
│ terraform-prov@pve │         │                  │ 1      │      0 │           │        │      │          │ pve        │        │
└────────────────────┴─────────┴──────────────────┴────────┴────────┴───────────┴────────┴──────┴──────────┴────────────┴────────┘

デフォルトでたくさんのロールが作られていた。

認証情報としては API キーも利用できるみたいだが、今回はユーザ名/パスワードを利用した。 API キーについては Proxmox Wiki に利用方法が記載されている。

Proxmox VE 側の準備はこれだけでよかった。

Terraform

インストール

terraform コマンドすら打ったことないので、インストールからおこなう。参照したドキュメントはこちら。

# リポジトリ追加
$ sudo dnf config-manager --add-repo https://rpm.releases.hashicorp.com/RHEL/hashicorp.repo

# インストール
$ sudo dnf -y install terraform

# バージョン確認
$ terraform -version
Terraform v1.2.6
on linux_amd64

# タブ補完
$ terraform -install-autocomplete

VM 作成

Terraform から Proxmox VE に VM を作成してみる。 main.tf ファイルを作成して Proxmox Provider を使うように設定する。

proxmox プロバイダブロックには仮想ホストの URL を記載する。

proxmox_vm_qemu リソースブロックには VM の名前 (name) とターゲットノード (target_node) の指定が必須。

VM の作成には「ISO」「クローン」「PXE ブート」の3通りある。今回は「ISO」から作成するため、iso を指定した。

terraform {
  required_providers {
    proxmox = {
      source  = "telmate/proxmox"
      version = "~> 2.9.10"
    }
  }
}

provider "proxmox" {
  pm_api_url = "https://pve1.nnstt1.home:8006/api2/json"
}

resource "proxmox_vm_qemu" "resource-name" {
  name        = "terraform-test"
  target_node = "pve1"
  iso         = "Fedora-Server-dvd-x86_64-36-1.5.iso"
}

main.tf を作成したら terraform init コマンドで作業ディレクトリを準備する。

$ terraform init

Initializing the backend...

Initializing provider plugins...
- Finding telmate/proxmox versions matching "~> 2.9.10"...
- Installing telmate/proxmox v2.9.10...
- Installed telmate/proxmox v2.9.10 (self-signed, key ID A9EBBE091B35AFCE)

Partner and community providers are signed by their developers.
If you'd like to know more about provider signing, you can read about it here:
https://www.terraform.io/docs/cli/plugins/signing.html

Terraform has created a lock file .terraform.lock.hcl to record the provider
selections it made above. Include this file in your version control repository
so that Terraform can guarantee to make the same selections by default when
you run "terraform init" in the future.

Terraform has been successfully initialized!

You may now begin working with Terraform. Try running "terraform plan" to see
any changes that are required for your infrastructure. All Terraform commands
should now work.

If you ever set or change modules or backend configuration for Terraform,
rerun this command to reinitialize your working directory. If you forget, other
commands will detect it and remind you to do so if necessary.

次に terraform plan コマンドで実行計画を作成する。

$ terraform plan
╷
│ Error: your API TokenID username should contain a !, check your API credentials
│ 
│   with provider["registry.terraform.io/telmate/proxmox"],
│   on main.tf line 10, in provider "proxmox":
│   10: provider "proxmox" {
│ 
╵

認証情報を設定し忘れていたためエラーになった。今回は環境変数に認証情報を設定した。

export PM_USER="terraform-prov@pve"
export PM_PASS="password"

認証情報の設定後、再実行。

$ terraform plan

Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
  + create

Terraform will perform the following actions:

  # proxmox_vm_qemu.resource-name will be created
  + resource "proxmox_vm_qemu" "resource-name" {
      + additional_wait           = 0
      + agent                     = 0
      + automatic_reboot          = true
      + balloon                   = 0
      + bios                      = "seabios"
      + boot                      = "c"
      + bootdisk                  = (known after apply)
      + clone_wait                = 0
      + cores                     = 1
      + cpu                       = "host"
      + default_ipv4_address      = (known after apply)
      + define_connection_info    = true
      + force_create              = false
      + full_clone                = true
      + guest_agent_ready_timeout = 100
      + hotplug                   = "network,disk,usb"
      + id                        = (known after apply)
      + iso                       = "Fedora-Server-dvd-x86_64-36-1.5.iso"
      + kvm                       = true
      + memory                    = 512
      + name                      = "terraform-test"
      + nameserver                = (known after apply)
      + numa                      = false
      + onboot                    = false
      + oncreate                  = true
      + preprovision              = true
      + qemu_os                   = "l26"
      + reboot_required           = (known after apply)
      + scsihw                    = (known after apply)
      + searchdomain              = (known after apply)
      + sockets                   = 1
      + ssh_host                  = (known after apply)
      + ssh_port                  = (known after apply)
      + tablet                    = true
      + target_node               = "pve1"
      + unused_disk               = (known after apply)
      + vcpus                     = 0
      + vlan                      = -1
      + vmid                      = (known after apply)
    }

Plan: 1 to add, 0 to change, 0 to destroy.

──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────

Note: You didn't use the -out option to save this plan, so Terraform can't guarantee to take exactly these actions if you run "terraform apply" now.

terraform plan が成功したので terraform apply を実行。

$ terraform apply 

(snip)

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value: yes

proxmox_vm_qemu.resource-name: Creating...
╷
│ Error: error creating VM: 400 Parameter verification failed., error status: {"errors":{"ide2":"invalid format - format error\nide2.file: invalid format - unable to parse volume ID 'Fedora-Server-dvd-x86_64-36-1.5.iso'\n\n"},"data":null} (params: map[agent:0 args: bios:seabios boot:c cores:1 cpu:host description: hotplug:network,disk,usb ide2:Fedora-Server-dvd-x86_64-36-1.5.iso,media=cdrom kvm:true machine: memory:512 name:terraform-test numa:false onboot:false ostype:l26 sockets:1 tablet:true tags: vmid:113])
│ 
│   with proxmox_vm_qemu.resource-name,
│   on main.tf line 14, in resource "proxmox_vm_qemu" "resource-name":
│   14: resource "proxmox_vm_qemu" "resource-name" {
│ 
╵

ide2 のフォーマットが不正で volume ID に変換できずエラーになった模様。

iso に指定した ISO ファイル名が不適切だったみたいで、色々試したところ ISO のフォーマットは<ストレージ名>:iso/<ISO ファイル名>だった。修正した main.tf が以下。

terraform {
  required_providers {
    proxmox = {
      source  = "telmate/proxmox"
      version = "~> 2.9.10"
    }
  }
}

provider "proxmox" {
  pm_api_url = "https://pve1.nnstt1.home:8006/api2/json"
}

resource "proxmox_vm_qemu" "resource-name" {
  name        = "terraform-test"
  target_node = "pve1"
  iso         = "local:iso/Fedora-Server-dvd-x86_64-36-1.5.iso"
}

修正後に terraform apply を再実行。

$ terraform apply 

(snip)

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value: yes

proxmox_vm_qemu.resource-name: Creating...
proxmox_vm_qemu.resource-name: Still creating... [10s elapsed]
proxmox_vm_qemu.resource-name: Creation complete after 10s [id=pve1/qemu/113]

Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

無事に正常終了した。 Proxmox VE からも VM を確認できた。

他にも設定項目があるけど、とりあえず今回はここまで。

Proxmox VE#

Terraform 用ユーザ/ロールの作成#

Terraform#

インストール#

VM 作成#

Proxmox VE

Terraform 用ユーザ/ロールの作成

Terraform

インストール

VM 作成