diff --git a/howtos/cloud-image/README.md b/docs/guides/cloud-image.md
similarity index 63%
rename from howtos/cloud-image/README.md
rename to docs/guides/cloud-image.md
index 288e21ee..6a338055 100644
--- a/howtos/cloud-image/README.md
+++ b/docs/guides/cloud-image.md
@@ -1,10 +1,13 @@
-# HOW-TO Create a VM from a Cloud Image
+---
+layout: page
+title: Create a VM from a Cloud Image
+parent: Guides
+subcategory: Virtual Environment
+description: |-
+ This guide explains how to create a VM from a cloud image.
+---
-> [!NOTE]
-> Examples below use the following defaults:
->
-> - a single Proxmox node named `pve`
-> - local storages named `local` and `local-lvm`
+# Create a VM from a Cloud Image
## Download a public cloud image from URL
@@ -27,7 +30,7 @@ resource "proxmox_virtual_environment_vm" "centos_vm" {
disk {
datastore_id = "local-lvm"
- file_id = proxmox_virtual_environment_file.centos_cloud_image.id
+ file_id = proxmox_virtual_environment_download_file.centos_cloud_image.id
interface = "virtio0"
iothread = true
discard = "on"
@@ -35,31 +38,47 @@ resource "proxmox_virtual_environment_vm" "centos_vm" {
}
}
-resource "proxmox_virtual_environment_file" "centos_cloud_image" {
+resource "proxmox_virtual_environment_download_file" "centos_cloud_image" {
content_type = "iso"
datastore_id = "local"
node_name = "pve"
-
- source_file {
- # you may download this image locally on your workstation and then use the local path instead of the remote URL
- path = "https://cloud.centos.org/centos/8-stream/x86_64/images/CentOS-Stream-GenericCloud-8-20231113.0.x86_64.qcow2"
- file_name = "centos8.img"
-
- # you may also use the SHA256 checksum of the image to verify its integrity
- checksum = "b9ba602de681e493b020825db0ee30602a46ef92"
- }
+ url = "https://cloud.centos.org/centos/8-stream/x86_64/images/CentOS-Stream-GenericCloud-8-20231113.0.x86_64.qcow2"
+ file_name = "centos8.img"
}
```
Ubuntu cloud images are available at [cloud-images.ubuntu.com](https://cloud-images.ubuntu.com/). Ubuntu cloud images are in `qcow2` format as well, but stored with `.img` extension, so they can be directly uploaded to Proxmox without renaming.
-Just update the `source_file` block in the example above to use the Ubuntu image URL:
-
```terraform
- source_file {
- path = "https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img"
- ...
+resource "proxmox_virtual_environment_vm" "ubuntu_vm" {
+ name = "test-ubuntu"
+ node_name = "pve"
+
+ initialization {
+ user_account {
+ # do not use this in production, configure your own ssh key instead!
+ username = "user"
+ password = "password"
+ }
}
+
+ disk {
+ datastore_id = "local-lvm"
+ file_id = proxmox_virtual_environment_download_file.ubuntu_cloud_image.id
+ interface = "virtio0"
+ iothread = true
+ discard = "on"
+ size = 20
+ }
+}
+
+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"
+
+}
```
For [large images](https://registry.terraform.io/providers/bpg/proxmox/latest/docs/resources/virtual_environment_file#important-notes), you may want to use a dedicated temporary directory [configured](https://registry.terraform.io/providers/bpg/proxmox/latest/docs#tmp_dir) for provider via `tmp_dir` attribute, instead of system's default temporary directory. This is especially useful if you are deploying from a container with limited disk space.
diff --git a/howtos/cloud-init/README.md b/docs/guides/cloud-init.md
similarity index 75%
rename from howtos/cloud-init/README.md
rename to docs/guides/cloud-init.md
index f20b08a3..2eeff976 100644
--- a/howtos/cloud-init/README.md
+++ b/docs/guides/cloud-init.md
@@ -1,16 +1,23 @@
-# HOW-TO Configure a VM with Cloud-Init
+---
+layout: page
+title: Configure a VM with Cloud-Init
+parent: Guides
+subcategory: Virtual Environment
+description: |-
+ This guide explains how to use the Proxmox provider to create and manage virtual machines using cloud-init.
+---
-> [!NOTE]
-> Examples below use the following defaults:
->
-> - a single Proxmox node named `pve`
-> - local storages named `local` and `local-lvm`
+# Configure a VM with Cloud-Init
## Native Proxmox Cloud-Init support
Proxmox supports Cloud-Init natively, so you can use the `initialization` block to configure your VM:
```terraform
+data "local_file" "ssh_public_key" {
+ filename = "./id_rsa.pub"
+}
+
resource "proxmox_virtual_environment_vm" "ubuntu_vm" {
name = "test-ubuntu"
node_name = "pve"
@@ -43,6 +50,14 @@ resource "proxmox_virtual_environment_vm" "ubuntu_vm" {
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"
+}
```
Note that many cloud images do not have `qemu-guest-agent` installed by default, so you won't be able to retrieve the dynamic IP address of the VM from Proxmox, as this is agent's responsibility. You can use the `ip_config` block to configure a static IP address instead.
@@ -54,6 +69,10 @@ Because of several limitations of the native Proxmox cloud-init support, you may
In order to use a custom cloud-init configuration, you need to create a `cloud-config` snippet file and pass it to the VM as a `user_data_file_id` parameter. You can use the `proxmox_virtual_environment_file` resource to create the file. Make sure the "Snippets" content type is enabled on the target datastore in Proxmox before applying the configuration below.
```terraform
+data "local_file" "ssh_public_key" {
+ filename = "./id_rsa.pub"
+}
+
resource "proxmox_virtual_environment_file" "cloud_config" {
content_type = "snippets"
datastore_id = "local"
@@ -126,4 +145,16 @@ resource "proxmox_virtual_environment_vm" "ubuntu_vm" {
}
}
+
+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"
+}
+
+output "vm_ipv4_address" {
+ value = proxmox_virtual_environment_vm.ubuntu_vm.ipv4_addresses[1][0]
+}
```
diff --git a/howtos/setup-proxmox-for-tests/README.md b/docs/guides/setup-proxmox-for-tests.md
similarity index 92%
rename from howtos/setup-proxmox-for-tests/README.md
rename to docs/guides/setup-proxmox-for-tests.md
index ce55d53d..bb64190c 100644
--- a/howtos/setup-proxmox-for-tests/README.md
+++ b/docs/guides/setup-proxmox-for-tests.md
@@ -1,4 +1,13 @@
-# Setup VM with proxmox to run examples and acceptance tests
+---
+layout: page
+title: Setup a VM with Proxmox
+parent: Guides
+subcategory: Virtual Environment
+description: |-
+ This guide will help you setup a proxmox node in VM using virt-manager for a job.
+---
+
+# Setup VM with Proxmox to run examples and acceptance tests
## Who
@@ -8,7 +17,7 @@ Contributors
To test changes, it's best to try it on real proxmox cluster. There is dedicated `make example` command that will try to apply changes defined in `example` directory. Most resources have its examples declarations there. For example, if you add new resource, you could add new file with example resource there (ideally after adding tests). If nothing breaks, apply works fine, new resource is created and all other resources are fine, then likely change is safe.
-But – proxmox node setup can be tricky task for some contributors.
+But, proxmox node setup can be tricky task for some contributors.
## Preconditions
diff --git a/howtos/cloud-image/centos-qcow2/main.tf b/examples/guides/cloud-image/centos-qcow2/main.tf
similarity index 53%
rename from howtos/cloud-image/centos-qcow2/main.tf
rename to examples/guides/cloud-image/centos-qcow2/main.tf
index a8e88dfe..4d202674 100644
--- a/howtos/cloud-image/centos-qcow2/main.tf
+++ b/examples/guides/cloud-image/centos-qcow2/main.tf
@@ -12,7 +12,7 @@ resource "proxmox_virtual_environment_vm" "centos_vm" {
disk {
datastore_id = "local-lvm"
- file_id = proxmox_virtual_environment_file.centos_cloud_image.id
+ file_id = proxmox_virtual_environment_download_file.centos_cloud_image.id
interface = "virtio0"
iothread = true
discard = "on"
@@ -20,14 +20,10 @@ resource "proxmox_virtual_environment_vm" "centos_vm" {
}
}
-resource "proxmox_virtual_environment_file" "centos_cloud_image" {
+resource "proxmox_virtual_environment_download_file" "centos_cloud_image" {
content_type = "iso"
datastore_id = "local"
node_name = "pve"
-
- source_file {
- # you may download this image locally on your workstation and then use the local path instead of the remote URL
- path = "https://cloud.centos.org/centos/8-stream/x86_64/images/CentOS-Stream-GenericCloud-8-20231113.0.x86_64.qcow2"
- file_name = "centos8.img"
- }
+ url = "https://cloud.centos.org/centos/8-stream/x86_64/images/CentOS-Stream-GenericCloud-8-20231113.0.x86_64.qcow2"
+ file_name = "centos8.img"
}
diff --git a/howtos/cloud-init/cutom/provider.tf b/examples/guides/cloud-image/centos-qcow2/provider.tf
similarity index 68%
rename from howtos/cloud-init/cutom/provider.tf
rename to examples/guides/cloud-image/centos-qcow2/provider.tf
index 374c699b..c7914fa7 100644
--- a/howtos/cloud-init/cutom/provider.tf
+++ b/examples/guides/cloud-image/centos-qcow2/provider.tf
@@ -2,7 +2,7 @@ terraform {
required_providers {
proxmox = {
source = "bpg/proxmox"
- version = "0.45.0"# x-release-please-version
+ version = "0.45.1" # x-release-please-version
}
}
}
@@ -11,7 +11,7 @@ provider "proxmox" {
endpoint = var.virtual_environment_endpoint
api_token = var.virtual_environment_token
ssh {
- agent = true
- username = "root"
+ agent = true
+ username = "terraform"
}
}
diff --git a/howtos/cloud-image/centos-qcow2/variables.tf b/examples/guides/cloud-image/centos-qcow2/variables.tf
similarity index 100%
rename from howtos/cloud-image/centos-qcow2/variables.tf
rename to examples/guides/cloud-image/centos-qcow2/variables.tf
diff --git a/howtos/cloud-image/debian-from-storage/main.tf b/examples/guides/cloud-image/debian-from-storage/main.tf
similarity index 100%
rename from howtos/cloud-image/debian-from-storage/main.tf
rename to examples/guides/cloud-image/debian-from-storage/main.tf
diff --git a/howtos/cloud-image/debian-from-storage/provider.tf b/examples/guides/cloud-image/debian-from-storage/provider.tf
similarity index 68%
rename from howtos/cloud-image/debian-from-storage/provider.tf
rename to examples/guides/cloud-image/debian-from-storage/provider.tf
index 440cb6d6..c7914fa7 100644
--- a/howtos/cloud-image/debian-from-storage/provider.tf
+++ b/examples/guides/cloud-image/debian-from-storage/provider.tf
@@ -2,7 +2,7 @@ terraform {
required_providers {
proxmox = {
source = "bpg/proxmox"
- version = "0.45.1"# x-release-please-version
+ version = "0.45.1" # x-release-please-version
}
}
}
@@ -11,7 +11,7 @@ provider "proxmox" {
endpoint = var.virtual_environment_endpoint
api_token = var.virtual_environment_token
ssh {
- agent = true
- username = "root"
+ agent = true
+ username = "terraform"
}
}
diff --git a/howtos/cloud-image/debian-from-storage/variables.tf b/examples/guides/cloud-image/debian-from-storage/variables.tf
similarity index 100%
rename from howtos/cloud-image/debian-from-storage/variables.tf
rename to examples/guides/cloud-image/debian-from-storage/variables.tf
diff --git a/howtos/cloud-image/ubuntu-img/main.tf b/examples/guides/cloud-image/ubuntu-img/main.tf
similarity index 57%
rename from howtos/cloud-image/ubuntu-img/main.tf
rename to examples/guides/cloud-image/ubuntu-img/main.tf
index f142aa7c..b1f4e04d 100644
--- a/howtos/cloud-image/ubuntu-img/main.tf
+++ b/examples/guides/cloud-image/ubuntu-img/main.tf
@@ -12,7 +12,7 @@ resource "proxmox_virtual_environment_vm" "ubuntu_vm" {
disk {
datastore_id = "local-lvm"
- file_id = proxmox_virtual_environment_file.ubuntu_cloud_image.id
+ file_id = proxmox_virtual_environment_download_file.ubuntu_cloud_image.id
interface = "virtio0"
iothread = true
discard = "on"
@@ -20,13 +20,10 @@ resource "proxmox_virtual_environment_vm" "ubuntu_vm" {
}
}
-resource "proxmox_virtual_environment_file" "ubuntu_cloud_image" {
+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"
- source_file {
- # you may download this image locally on your workstation and then use the local path instead of the remote URL
- path = "https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img"
- }
}
diff --git a/howtos/cloud-image/ubuntu-img/provider.tf b/examples/guides/cloud-image/ubuntu-img/provider.tf
similarity index 68%
rename from howtos/cloud-image/ubuntu-img/provider.tf
rename to examples/guides/cloud-image/ubuntu-img/provider.tf
index 440cb6d6..c7914fa7 100644
--- a/howtos/cloud-image/ubuntu-img/provider.tf
+++ b/examples/guides/cloud-image/ubuntu-img/provider.tf
@@ -2,7 +2,7 @@ terraform {
required_providers {
proxmox = {
source = "bpg/proxmox"
- version = "0.45.1"# x-release-please-version
+ version = "0.45.1" # x-release-please-version
}
}
}
@@ -11,7 +11,7 @@ provider "proxmox" {
endpoint = var.virtual_environment_endpoint
api_token = var.virtual_environment_token
ssh {
- agent = true
- username = "root"
+ agent = true
+ username = "terraform"
}
}
diff --git a/howtos/cloud-image/ubuntu-img/variables.tf b/examples/guides/cloud-image/ubuntu-img/variables.tf
similarity index 100%
rename from howtos/cloud-image/ubuntu-img/variables.tf
rename to examples/guides/cloud-image/ubuntu-img/variables.tf
diff --git a/howtos/cloud-init/cutom/cloud-config.tf b/examples/guides/cloud-init/custom/cloud-config.tf
similarity index 100%
rename from howtos/cloud-init/cutom/cloud-config.tf
rename to examples/guides/cloud-init/custom/cloud-config.tf
diff --git a/howtos/cloud-init/cutom/main.tf b/examples/guides/cloud-init/custom/main.tf
similarity index 100%
rename from howtos/cloud-init/cutom/main.tf
rename to examples/guides/cloud-init/custom/main.tf
diff --git a/howtos/cloud-image/centos-qcow2/provider.tf b/examples/guides/cloud-init/custom/provider.tf
similarity index 68%
rename from howtos/cloud-image/centos-qcow2/provider.tf
rename to examples/guides/cloud-init/custom/provider.tf
index 440cb6d6..c7914fa7 100644
--- a/howtos/cloud-image/centos-qcow2/provider.tf
+++ b/examples/guides/cloud-init/custom/provider.tf
@@ -2,7 +2,7 @@ terraform {
required_providers {
proxmox = {
source = "bpg/proxmox"
- version = "0.45.1"# x-release-please-version
+ version = "0.45.1" # x-release-please-version
}
}
}
@@ -11,7 +11,7 @@ provider "proxmox" {
endpoint = var.virtual_environment_endpoint
api_token = var.virtual_environment_token
ssh {
- agent = true
- username = "root"
+ agent = true
+ username = "terraform"
}
}
diff --git a/howtos/cloud-init/cutom/variables.tf b/examples/guides/cloud-init/custom/variables.tf
similarity index 100%
rename from howtos/cloud-init/cutom/variables.tf
rename to examples/guides/cloud-init/custom/variables.tf
diff --git a/howtos/cloud-init/native/main.tf b/examples/guides/cloud-init/native/main.tf
similarity index 100%
rename from howtos/cloud-init/native/main.tf
rename to examples/guides/cloud-init/native/main.tf
diff --git a/examples/guides/cloud-init/native/provider.tf b/examples/guides/cloud-init/native/provider.tf
new file mode 100644
index 00000000..c7914fa7
--- /dev/null
+++ b/examples/guides/cloud-init/native/provider.tf
@@ -0,0 +1,17 @@
+terraform {
+ required_providers {
+ proxmox = {
+ source = "bpg/proxmox"
+ version = "0.45.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/howtos/cloud-init/native/variables.tf b/examples/guides/cloud-init/native/variables.tf
similarity index 100%
rename from howtos/cloud-init/native/variables.tf
rename to examples/guides/cloud-init/native/variables.tf
diff --git a/howtos/README.md b/howtos/README.md
deleted file mode 100644
index be80daf6..00000000
--- a/howtos/README.md
+++ /dev/null
@@ -1,12 +0,0 @@
-# HOW-TOs
-
-A collection of HOW-TOs for common tasks.
-
-## Virtual Machines
-
-- [Create a VM from a Cloud Image](./cloud-image/README.md)
-- [Configure a VM with Cloud-Init](./cloud-init/README.md)
-
-## Contributors
-
-- [Setup VM with proxmox to run examples and acceptance tests](./setup-proxmox-for-tests/README.md)
diff --git a/howtos/cloud-init/native/provider.tf b/howtos/cloud-init/native/provider.tf
deleted file mode 100644
index 440cb6d6..00000000
--- a/howtos/cloud-init/native/provider.tf
+++ /dev/null
@@ -1,17 +0,0 @@
-terraform {
- required_providers {
- proxmox = {
- source = "bpg/proxmox"
- version = "0.45.1"# x-release-please-version
- }
- }
-}
-
-provider "proxmox" {
- endpoint = var.virtual_environment_endpoint
- api_token = var.virtual_environment_token
- ssh {
- agent = true
- username = "root"
- }
-}
diff --git a/templates/data-sources.md.tmpl b/templates/data-sources.md.tmpl
index 21cbe496..285a1199 100644
--- a/templates/data-sources.md.tmpl
+++ b/templates/data-sources.md.tmpl
@@ -14,7 +14,7 @@ description: |-
{{ if .HasExample -}}
## Example Usage
-{{ printf "{{tffile %q}}" .ExampleFile }}
+{{ codefile "terraform" .ExampleFile }}
{{- end }}
{{ .SchemaMarkdown | trimspace }}
diff --git a/templates/guides/cloud-image.md.tmpl b/templates/guides/cloud-image.md.tmpl
new file mode 100644
index 00000000..a0bc89af
--- /dev/null
+++ b/templates/guides/cloud-image.md.tmpl
@@ -0,0 +1,30 @@
+---
+layout: page
+title: Create a VM from a Cloud Image
+parent: Guides
+subcategory: Virtual Environment
+description: |-
+ This guide explains how to create a VM from a cloud image.
+---
+
+# Create a VM from a Cloud Image
+
+## Download a public cloud image from URL
+
+Proxmox does not natively support QCOW2 images, but provider can do the conversion for you.
+
+Example of how to create a CentOS 8 VM from a "generic cloud" `qcow2` image. CentOS 8 images are available at [cloud.centos.org](https://cloud.centos.org/centos/8-stream/x86_64/images/):
+
+{{ codefile "terraform" "examples/guides/cloud-image/centos-qcow2/main.tf" }}
+
+Ubuntu cloud images are available at [cloud-images.ubuntu.com](https://cloud-images.ubuntu.com/). Ubuntu cloud images are in `qcow2` format as well, but stored with `.img` extension, so they can be directly uploaded to Proxmox without renaming.
+
+{{ codefile "terraform" "examples/guides/cloud-image/ubuntu-img/main.tf" }}
+
+For [large images](https://registry.terraform.io/providers/bpg/proxmox/latest/docs/resources/virtual_environment_file#important-notes), you may want to use a dedicated temporary directory [configured](https://registry.terraform.io/providers/bpg/proxmox/latest/docs#tmp_dir) for provider via `tmp_dir` attribute, instead of system's default temporary directory. This is especially useful if you are deploying from a container with limited disk space.
+
+## Create a VM from an exiting image on Proxmox
+
+If you already have a cloud image on Proxmox, you can use it to create a VM:
+
+{{ codefile "terraform" "examples/guides/cloud-image/debian-from-storage/main.tf" }}
diff --git a/templates/guides/cloud-init.md.tmpl b/templates/guides/cloud-init.md.tmpl
new file mode 100644
index 00000000..cd290285
--- /dev/null
+++ b/templates/guides/cloud-init.md.tmpl
@@ -0,0 +1,28 @@
+---
+layout: page
+title: Configure a VM with Cloud-Init
+parent: Guides
+subcategory: Virtual Environment
+description: |-
+ This guide explains how to use the Proxmox provider to create and manage virtual machines using cloud-init.
+---
+
+# Configure a VM with Cloud-Init
+
+## Native Proxmox Cloud-Init support
+
+Proxmox supports Cloud-Init natively, so you can use the `initialization` block to configure your VM:
+
+{{ codefile "terraform" "examples/guides/cloud-init/native/main.tf" }}
+
+Note that many cloud images do not have `qemu-guest-agent` installed by default, so you won't be able to retrieve the dynamic IP address of the VM from Proxmox, as this is agent's responsibility. You can use the `ip_config` block to configure a static IP address instead.
+
+## Custom Cloud-Init configuration
+
+Because of several limitations of the native Proxmox cloud-init support, you may want to use a custom Cloud-Init configuration instead. This would allow you to adjust the VM configuration to your needs, and also install the `qemu-guest-agent` and additional packages.
+
+In order to use a custom cloud-init configuration, you need to create a `cloud-config` snippet file and pass it to the VM as a `user_data_file_id` parameter. You can use the `proxmox_virtual_environment_file` resource to create the file. Make sure the "Snippets" content type is enabled on the target datastore in Proxmox before applying the configuration below.
+
+{{ codefile "terraform" "examples/guides/cloud-init/custom/cloud-config.tf" }}
+
+{{ codefile "terraform" "examples/guides/cloud-init/custom/main.tf" }}
diff --git a/templates/guides/setup-proxmox-for-tests.md.tmpl b/templates/guides/setup-proxmox-for-tests.md.tmpl
new file mode 100644
index 00000000..bb64190c
--- /dev/null
+++ b/templates/guides/setup-proxmox-for-tests.md.tmpl
@@ -0,0 +1,96 @@
+---
+layout: page
+title: Setup a VM with Proxmox
+parent: Guides
+subcategory: Virtual Environment
+description: |-
+ This guide will help you setup a proxmox node in VM using virt-manager for a job.
+---
+
+# Setup VM with Proxmox to run examples and acceptance tests
+
+## Who
+
+Contributors
+
+## Motivation
+
+To test changes, it's best to try it on real proxmox cluster. There is dedicated `make example` command that will try to apply changes defined in `example` directory. Most resources have its examples declarations there. For example, if you add new resource, you could add new file with example resource there (ideally after adding tests). If nothing breaks, apply works fine, new resource is created and all other resources are fine, then likely change is safe.
+
+But, proxmox node setup can be tricky task for some contributors.
+
+## Preconditions
+
+Be sure to install `go` and `terraform` on your system first.
+
+## Linux (Debian/Ubuntu) with virt-manager
+
+Goal is to have a proxmox node in VM using for a job. This text assumes some linux knowledge. Tested on Debian 12 bookworm and proxmox VE 8.1. For other distros, with any luck steps should be similar.
+
+1. `sudo apt-get install virt-manager`.
+
+2. Download some proxmox image from , currently latest is `proxmox-ve_8.1-1.iso`.
+
+3. Run `virt-manager` and "create a new virtual machine", use a file you just downloaded, choose debian as a operating system, leave default network settings.
+
+4. Give it enough RAM and disk size (required minimum is unknown for make example though I used 4GB on my 8GB laptop and 30GB disk size with success).
+
+5. Proceed forward with installation, choose whatever you want for timezone, country, password, domain, email. Don't change other default settings.
+
+6. After installation, log in using password from previous step and `root` username (it's proxmox default). Run: `ip a` to get assigned ip (this also appears during installation). In my case it is `192.168.122.43`.
+
+ It may look like this:
+
+ ```txt
+ root@proxmox:~# ip a
+ 1: lo: mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
+ link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
+ inet 127.0.0.1/8 scope host lo
+ valid_lft forever preferred_lft forever
+ inet6 ::1/128 scope host noprefixroute
+ valid_lft forever preferred_lft forever
+ 2: enp1s0: mtu 1500 qdisc pfifo_fast master vmbr0 state UP group default qlen 1000
+ link/ether 52:54:00:b3:22:f5 brd ff:ff:ff:ff:ff:ff
+ 3: vmbr0: mtu 1500 qdisc noqueue state UP group default qlen 1000
+ link/ether 52:54:00:b3:22:f5 brd ff:ff:ff:ff:ff:ff
+ inet 192.168.122.43/24 scope global vmbr0
+ valid_lft forever preferred_lft forever
+ inet6 fe80::5054:ff:feb3:22f5/64 scope link
+ valid_lft forever preferred_lft forever
+ ```
+
+7. (Optional) On **your** computer, there should be new interface created mapped to that one you see on proxmox. Again `ip a`:
+
+ ```txt
+ ...
+
+ 8: virbr0: mtu 1500 qdisc noqueue state UP group default qlen 1000
+ link/ether 52:54:00:ca:65:49 brd ff:ff:ff:ff:ff:ff
+ inet 192.168.122.1/24 brd 192.168.122.255 scope global virbr0
+ valid_lft forever preferred_lft forever
+
+ ...
+
+ ```
+
+8. (Optional) You can SSH into proxmox node:
+
+ ```bash
+ ssh root@192.168.122.43
+ ```
+
+ You can also use browser and visit console at .
+
+9. Create `terraform.tfvars` file (it will be git ignored file) in `example` folder with credentials for you new proxmox node.
+
+ ```txt
+ # example/terraform.tfvars
+ virtual_environment_username = "root@pam"
+ virtual_environment_endpoint = "https://192.168.122.43:8006/"
+ virtual_environment_password = "your password from step 5"
+
+ ```
+
+10. Now you can run `make example`.
+
+11. If you see error with proxmox_virtual_environment_file: the datastore "local" does not support content type "snippets"; supported content types are: [backup iso vztmpl], you need to enable them, see .
diff --git a/templates/resources.md.tmpl b/templates/resources.md.tmpl
index c47c826b..35cb1c01 100644
--- a/templates/resources.md.tmpl
+++ b/templates/resources.md.tmpl
@@ -14,7 +14,7 @@ description: |-
{{ if .HasExample -}}
## Example Usage
-{{ printf "{{tffile %q}}" .ExampleFile }}
+{{ codefile "terraform" .ExampleFile }}
{{- end }}
{{ .SchemaMarkdown | trimspace }}
@@ -24,5 +24,5 @@ description: |-
Import is supported using the following syntax:
-{{ printf "{{codefile \"shell\" %q}}" .ImportFile }}
+{{ codefile "shell" .ImportFile }}
{{- end }}
diff --git a/tools/tools.go b/tools/tools.go
index 016a4baf..8f1b36f2 100644
--- a/tools/tools.go
+++ b/tools/tools.go
@@ -28,6 +28,7 @@ import (
// Temporary: while migrating to the TF framework, we need to copy the generated docs to the right place
// for the resources / data sources that have been migrated.
+//go:generate cp -R ../build/docs-gen/guides/ ../docs/guides/
//go:generate cp ../build/docs-gen/data-sources/virtual_environment_version.md ../docs/data-sources/
//go:generate cp ../build/docs-gen/data-sources/virtual_environment_hagroup.md ../docs/data-sources/
//go:generate cp ../build/docs-gen/data-sources/virtual_environment_hagroups.md ../docs/data-sources/