diff --git a/docs/guides/clone-vm.md b/docs/guides/clone-vm.md new file mode 100644 index 00000000..0df882d1 --- /dev/null +++ b/docs/guides/clone-vm.md @@ -0,0 +1,114 @@ +--- +layout: page +page_title: "Clone a VM" +subcategory: Guides +description: |- + This guide explains how to create a VM template and then clone it to another VM. +--- + +# Clone a VM + +## Create a VM template + +VM templates in Proxmox provide an efficient way to create multiple identical VMs. Templates act as a base image that can be cloned to create new VMs, ensuring consistency and reducing the time needed to provision new instances. When a VM is created as a template, it is read-only and can't be started, but can be cloned multiple times to create new VMs. + +You can create a template directly in Proxmox by setting the `template` attribute to `true` when creating the VM resource: + +```terraform +resource "proxmox_virtual_environment_vm" "ubuntu_template" { + name = "ubuntu-template" + node_name = "pve" + + template = true + + machine = "q35" + bios = "ovmf" + description = "Managed by Terraform" + + agent { + enabled = true + } + + cpu { + cores = 2 + } + + memory { + dedicated = 2048 + } + + efi_disk { + datastore_id = "local" + file_format = "raw" + type = "4m" + } + + disk { + datastore_id = "local-lvm" + file_id = proxmox_virtual_environment_download_file.ubuntu_cloud_image.id + interface = "virtio0" + iothread = true + discard = "on" + size = 20 + } + + initialization { + ip_config { + ipv4 { + address = "dhcp" + } + } + + user_data_file_id = proxmox_virtual_environment_file.user_data_cloud_config.id + } + + network_device { + bridge = "vmbr0" + } + +} + +resource "proxmox_virtual_environment_download_file" "ubuntu_cloud_image" { + content_type = "iso" + datastore_id = "local" + node_name = "pve" + + url = "https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img" +} +``` + +Once you have a template, you can clone it to create new VMs. The cloned VMs will inherit all the configuration from the template but can be customized further as needed. + +```terraform +resource "proxmox_virtual_environment_vm" "ubuntu_clone" { + name = "ubuntu-clone" + node_name = "pve" + + clone { + vm_id = proxmox_virtual_environment_vm.ubuntu_template.id + } + + agent { + enabled = true + } + + memory { + dedicated = 768 + } + + initialization { + dns { + servers = ["1.1.1.1"] + } + ip_config { + ipv4 { + address = "dhcp" + } + } + } +} + +output "vm_ipv4_address" { + value = proxmox_virtual_environment_vm.ubuntu_clone.ipv4_addresses[1][0] +} +``` diff --git a/examples/guides/clone-vm/clone.tf b/examples/guides/clone-vm/clone.tf new file mode 100644 index 00000000..61a94bed --- /dev/null +++ b/examples/guides/clone-vm/clone.tf @@ -0,0 +1,31 @@ +resource "proxmox_virtual_environment_vm" "ubuntu_clone" { + name = "ubuntu-clone" + node_name = "pve" + + clone { + vm_id = proxmox_virtual_environment_vm.ubuntu_template.id + } + + agent { + enabled = true + } + + memory { + dedicated = 768 + } + + initialization { + dns { + servers = ["1.1.1.1"] + } + ip_config { + ipv4 { + address = "dhcp" + } + } + } +} + +output "vm_ipv4_address" { + value = proxmox_virtual_environment_vm.ubuntu_clone.ipv4_addresses[1][0] +} diff --git a/examples/guides/clone-vm/cloud-config.tf b/examples/guides/clone-vm/cloud-config.tf new file mode 100644 index 00000000..386479ca --- /dev/null +++ b/examples/guides/clone-vm/cloud-config.tf @@ -0,0 +1,34 @@ +data "local_file" "ssh_public_key" { + filename = "./id_rsa.pub" +} + +resource "proxmox_virtual_environment_file" "user_data_cloud_config" { + content_type = "snippets" + datastore_id = "local" + node_name = "pve" + + source_raw { + data = <<-EOF + #cloud-config + hostname: test-ubuntu + users: + - default + - name: ubuntu + groups: + - sudo + shell: /bin/bash + ssh_authorized_keys: + - ${trimspace(data.local_file.ssh_public_key.content)} + sudo: ALL=(ALL) NOPASSWD:ALL + runcmd: + - apt update + - apt install -y qemu-guest-agent net-tools + - timedatectl set-timezone America/Toronto + - systemctl enable qemu-guest-agent + - systemctl start qemu-guest-agent + - echo "done" > /tmp/cloud-config.done + EOF + + file_name = "user-data-cloud-config.yaml" + } +} diff --git a/examples/guides/clone-vm/provider.tf b/examples/guides/clone-vm/provider.tf new file mode 100644 index 00000000..09ba265e --- /dev/null +++ b/examples/guides/clone-vm/provider.tf @@ -0,0 +1,17 @@ +terraform { + required_providers { + proxmox = { + source = "bpg/proxmox" + version = "0.69.1" # x-release-please-version + } + } +} + +provider "proxmox" { + endpoint = var.virtual_environment_endpoint + api_token = var.virtual_environment_token + ssh { + agent = true + username = "terraform" + } +} diff --git a/examples/guides/clone-vm/template.tf b/examples/guides/clone-vm/template.tf new file mode 100644 index 00000000..76c5f102 --- /dev/null +++ b/examples/guides/clone-vm/template.tf @@ -0,0 +1,60 @@ +resource "proxmox_virtual_environment_vm" "ubuntu_template" { + name = "ubuntu-template" + node_name = "pve" + + template = true + + machine = "q35" + bios = "ovmf" + description = "Managed by Terraform" + + agent { + enabled = true + } + + cpu { + cores = 2 + } + + memory { + dedicated = 2048 + } + + efi_disk { + datastore_id = "local" + file_format = "raw" + type = "4m" + } + + disk { + datastore_id = "local-lvm" + file_id = proxmox_virtual_environment_download_file.ubuntu_cloud_image.id + interface = "virtio0" + iothread = true + discard = "on" + size = 20 + } + + initialization { + ip_config { + ipv4 { + address = "dhcp" + } + } + + user_data_file_id = proxmox_virtual_environment_file.user_data_cloud_config.id + } + + network_device { + bridge = "vmbr0" + } + +} + +resource "proxmox_virtual_environment_download_file" "ubuntu_cloud_image" { + content_type = "iso" + datastore_id = "local" + node_name = "pve" + + url = "https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img" +} diff --git a/examples/guides/clone-vm/variables.tf b/examples/guides/clone-vm/variables.tf new file mode 100644 index 00000000..62017de9 --- /dev/null +++ b/examples/guides/clone-vm/variables.tf @@ -0,0 +1,10 @@ +variable "virtual_environment_endpoint" { + type = string + description = "The endpoint for the Proxmox Virtual Environment API (example: https://host:port)" +} + +variable "virtual_environment_token" { + type = string + description = "The token for the Proxmox Virtual Environment API" + sensitive = true +} diff --git a/examples/guides/cloud-image/centos-qcow2/variables.tf b/examples/guides/cloud-image/centos-qcow2/variables.tf index 97cb64fa..62017de9 100644 --- a/examples/guides/cloud-image/centos-qcow2/variables.tf +++ b/examples/guides/cloud-image/centos-qcow2/variables.tf @@ -6,4 +6,5 @@ variable "virtual_environment_endpoint" { variable "virtual_environment_token" { type = string description = "The token for the Proxmox Virtual Environment API" + sensitive = true } diff --git a/examples/guides/cloud-image/debian-from-storage/variables.tf b/examples/guides/cloud-image/debian-from-storage/variables.tf index 97cb64fa..62017de9 100644 --- a/examples/guides/cloud-image/debian-from-storage/variables.tf +++ b/examples/guides/cloud-image/debian-from-storage/variables.tf @@ -6,4 +6,5 @@ variable "virtual_environment_endpoint" { variable "virtual_environment_token" { type = string description = "The token for the Proxmox Virtual Environment API" + sensitive = true } diff --git a/templates/guides/clone-vm.md.tmpl b/templates/guides/clone-vm.md.tmpl new file mode 100644 index 00000000..58047205 --- /dev/null +++ b/templates/guides/clone-vm.md.tmpl @@ -0,0 +1,21 @@ +--- +layout: page +page_title: "Clone a VM" +subcategory: Guides +description: |- + This guide explains how to create a VM template and then clone it to another VM. +--- + +# Clone a VM + +## Create a VM template + +VM templates in Proxmox provide an efficient way to create multiple identical VMs. Templates act as a base image that can be cloned to create new VMs, ensuring consistency and reducing the time needed to provision new instances. When a VM is created as a template, it is read-only and can't be started, but can be cloned multiple times to create new VMs. + +You can create a template directly in Proxmox by setting the `template` attribute to `true` when creating the VM resource: + +{{ codefile "terraform" "examples/guides/clone-vm/template.tf" }} + +Once you have a template, you can clone it to create new VMs. The cloned VMs will inherit all the configuration from the template but can be customized further as needed. + +{{ codefile "terraform" "examples/guides/clone-vm/clone.tf" }}