From 4806958d40f43014ac2fa81974a8cb0c5ccd24f4 Mon Sep 17 00:00:00 2001
From: Frederik Bosch <f.bosch@genkgo.nl>
Date: Wed, 11 Mar 2020 13:56:30 +0100
Subject: [PATCH] Enhance documentation, split into multiple files, start with
 adding argument references

---
 README.md                | 343 ++-------------------------------------
 docs/cloud_init_guide.md | 219 +++++++++++++++++++++++++
 docs/index.md            |  10 ++
 docs/installation.md     |  41 +++++
 docs/provider.md         |  34 ++++
 docs/provisioner.md      |  20 +++
 docs/resource_lxc.md     |   1 +
 docs/resource_vm_qemu.md |  50 ++++++
 docs/terraforminit.md    |  27 ---
 9 files changed, 389 insertions(+), 356 deletions(-)
 create mode 100644 docs/cloud_init_guide.md
 create mode 100644 docs/index.md
 create mode 100644 docs/installation.md
 create mode 100644 docs/provider.md
 create mode 100644 docs/provisioner.md
 create mode 100644 docs/resource_lxc.md
 create mode 100644 docs/resource_vm_qemu.md
 delete mode 100644 docs/terraforminit.md

diff --git a/README.md b/README.md
index 26e73475..26d6ad88 100644
--- a/README.md
+++ b/README.md
@@ -1,338 +1,23 @@
 [![Build Status](https://travis-ci.com/Telmate/terraform-provider-proxmox.svg?branch=master)](https://travis-ci.com/Telmate/terraform-provider-proxmox)
 
-# Proxmox 4 Terraform
+# Terraform provider plugin for Proxmox
 
-Terraform provider plugin for proxmox
+This repository provides both a Terraform provider and provisioner for the [Promox virtualization platform](https://pve.proxmox.com/pve-docs/). 
 
+## Getting started
 
-## Working prototype
+In order to get started, use [the documentation included in this repository](docs/index.md). The documentation contains
+a list of the options for both the provider and the provisioner. Moreover, there are some guides available how to combine
+options and start specific VMs.
 
+## Contributing
 
-## Go Install
+When contributing, please also add documentation to help other users.
 
-```
-go install github.com/Telmate/terraform-provider-proxmox/cmd/terraform-provider-proxmox
-go install github.com/Telmate/terraform-provider-proxmox/cmd/terraform-provisioner-proxmox
-```
-Note: this plugin is both a provider and provisioner in one, which is why it needs two install commands.
+## Useful links
 
-## Build local source
-
-Requires https://github.com/Telmate/proxmox-api-go
-
-```
-make
-make install
-```
-
-Recommended ISO builder https://github.com/Telmate/terraform-ubuntu-proxmox-iso
-
-## Credentials
-
-```bash
-# Credentials and URL optionally defined in the environment
-export PM_API_URL="https://xxxx.com:8006/api2/json"
-export PM_USER=user@pam
-export PM_PASS=password
-```
-If a 2FA OTP code is required
-```bash
-# Optional 2FA OTP code
-export PM_OTP=otpcode
-```
-
-## Run
-
-```
-terraform init
-terraform plan
-terraform apply
-```
-
-### Sample file
-
-main.tf:
-```
-provider "proxmox" {
-  pm_tls_insecure = true
-  /*
-    // Credentials here or environment
-    pm_api_url = "https://proxmox-server01.example.com:8006/api2/json"
-    pm_password = "secret"
-    pm_user = "terraform-user@pve"
-    //Optional
-    pm_otp = "otpcode"
-  */
-}
-
-/* Uses cloud-init options from Proxmox 5.2 */
-resource "proxmox_vm_qemu" "cloudinit-test" {
-  name = "tftest1.xyz.com"
-  desc = "tf description"
-  target_node = "proxmox1-xx"
-
-  clone = "ci-ubuntu-template"
-
-  # The destination resource pool for the new VM
-  pool = "pool0"
-
-  storage = "local"
-  cores = 3
-  sockets = 1
-  memory = 2560
-  disk_gb = 4
-  nic = "virtio"
-  bridge = "vmbr0"
-
-  ssh_user = "root"
-  ssh_private_key = <<EOF
------BEGIN RSA PRIVATE KEY-----
-private ssh key root
------END RSA PRIVATE KEY-----
-EOF
-
-  os_type = "cloud-init"
-  ipconfig0 = "ip=10.0.2.99/16,gw=10.0.2.2"
-
-  sshkeys = <<EOF
-ssh-rsa AAAAB3NzaC1kj...key1
-ssh-rsa AAAAB3NzaC1kj...key2
-EOF
-
-  provisioner "remote-exec" {
-    inline = [
-      "ip a"
-    ]
-  }
-}
-
-/* Null resource that generates a cloud-config file per vm */
-data "template_file" "user_data" {
-  count    = var.vm_count
-  template = file("${path.module}/files/user_data.cfg")
-  vars = {
-    pubkey   = file("~/.ssh/id_rsa.pub")
-    hostname = "vm-${count.index}"
-    fqdn     = "vm-${count.index}.${var.domain_name}"
-  }
-}
-resource "local_file" "cloud_init_user_data_file" {
-  count    = var.vm_count
-  content  = data.template_file.user_data[count.index].rendered
-  filename = "${path.module}/files/user_data_${count.index}.cfg"
-}
-
-resource "null_resource" "cloud_init_config_files" {
-  count = var.vm_count
-  connection {
-    type     = "ssh"
-    user     = "${var.pve_user}"
-    password = "${var.pve_password}"
-    host     = "${var.pve_host}"
-  }
-
-  provisioner "file" {
-    source      = local_file.cloud_init_user_data_file[count.index].filename
-    destination = "/var/lib/vz/snippets/user_data_vm-${count.index}.yml"
-  }
-}
-
-/* Configure cloud-init User-Data with custom config file */
-resource "proxmox_vm_qemu" "cloudinit-test" {
-  depends_on = [
-    null_resource.cloud_init_config_files,
-  ]
-
-  name = "tftest1.xyz.com"
-  desc = "tf description"
-  target_node = "proxmox1-xx"
-
-  clone = "ci-ubuntu-template"
-
-  # The destination resource pool for the new VM
-  pool = "pool0"
-
-  storage = "local"
-  cores = 3
-  sockets = 1
-  memory = 2560
-  disk_gb = 4
-  nic = "virtio"
-  bridge = "vmbr0"
-
-  ssh_user = "root"
-  ssh_private_key = <<EOF
------BEGIN RSA PRIVATE KEY-----
-private ssh key root
------END RSA PRIVATE KEY-----
-EOF
-
-  os_type = "cloud-init"
-  ipconfig0 = "ip=10.0.2.99/16,gw=10.0.2.2"
-
-  /*
-    sshkeys and other User-Data parameters are specified with a custom config file.
-    In this example each VM has its own config file, previously generated and uploaded to
-    the snippets folder in the local storage in the Proxmox VE server.
-  */
-  cicustom = "user=local:snippets/user_data_vm-${count.index}.yml"
-
-  provisioner "remote-exec" {
-    inline = [
-      "ip a"
-    ]
-  }
-}
-
-/* Uses custom eth1 user-net SSH portforward */
-resource "proxmox_vm_qemu" "prepprovision-test" {
-  name = "tftest1.xyz.com"
-  desc = "tf description"
-  target_node = "proxmox1-xx"
-
-  clone = "terraform-ubuntu1404-template"
-
-  # The destination resource pool for the new VM
-  pool = "pool0"
-
-  cores = 3
-  sockets = 1
-  # Same CPU as the Physical host, possible to add cpu flags
-  # Ex: "host,flags=+md-clear;+pcid;+spec-ctrl;+ssbd;+pdpe1gb"
-  cpu = "host"
-  numa = false
-  memory = 2560
-  scsihw = "lsi"
-  # Boot from hard disk (c), CD-ROM (d), network (n)
-  boot = "cdn"
-  # It's possible to add this type of material and use it directly
-  # Possible values are: network,disk,cpu,memory,usb
-  hotplug = "network,disk,usb"
-  # Default boot disk
-  bootdisk = "virtio0"
-  # HA, you need to use a shared disk for this feature (ex: rbd)
-  hastate = ""
-  
-  #Display
-  vga {
-    type = "std"
-    #Between 4 and 512, ignored if type is defined to serial
-    memory = 4
-  }
-  
-  network {
-    id = 0
-    model = "virtio"
-  }
-  network {
-    id = 1
-    model = "virtio"
-    bridge = "vmbr1"
-  }
-  disk {
-    id = 0
-    type = virtio
-    storage = local-lvm
-    storage_type = lvm
-    size = 4G
-    backup = true
-  }
-  # Serial interface of type socket is used by xterm.js
-  # You will need to configure your guest system before being able to use it
-  serial {
-    id = 0
-    type = "socket"
-  }
-  preprovision = true
-  ssh_forward_ip = "10.0.0.1"
-  ssh_user = "terraform"
-  ssh_private_key = <<EOF
------BEGIN RSA PRIVATE KEY-----
-private ssh key terraform
------END RSA PRIVATE KEY-----
-EOF
-
-  os_type = "ubuntu"
-  os_network_config = <<EOF
-auto eth0
-iface eth0 inet dhcp
-EOF
-
-  connection {
-    type = "ssh"
-    user = "${self.ssh_user}"
-    private_key = "${self.ssh_private_key}"
-    host = "${self.ssh_host}"
-    port = "${self.ssh_port}"
-  }
-
-  provisioner "remote-exec" {
-    inline = [
-      "ip a"
-    ]
-  }
-
-  provisioner "proxmox" {
-    action = "sshbackward"
-  }
-}
-
-```
-### Provider usage
-You can start from either an ISO or clone an existing VM.
-
-Optimally, you could create a VM resource you will use a clone base with an ISO, and make the rest of the VM resources depend on that base "template" and clone it.
-
-Interesting parameters:
-**preprovision** - to enable or disable internal pre-provisioning (e.g. if you already have another way to provision VMs). Conflicts with: `ssh_forward_ip`, `ssh_user`, `ssh_private_key`, `os_type`, `os_network_config`.
-**os_type** -
-* cloud-init  - from Proxmox 5.2
-* ubuntu -(https://github.com/Telmate/terraform-ubuntu-proxmox-iso)
-* centos - (TODO: centos iso template)
-
-**ssh_forward_ip** - should be the IP or hostname of the target node or bridge IP. This is where proxmox will create a port forward to your VM with via a user_net. (for pre-cloud-init provisioning)
-
-### Cloud-Init
-
-Cloud-init VMs must be cloned from a cloud-init ready template.
-See: https://pve.proxmox.com/wiki/Cloud-Init_Support
-
-* ciuser - User name to change ssh keys and password for instead of the image’s configured default user.
-* cipassword - Password to assign the user.
-* searchdomain - Sets DNS search domains for a container.
-* nameserver - Sets DNS server IP address for a container.
-* sshkeys - public ssh keys, one per line
-* ipconfig0 - [gw=<GatewayIPv4>] [,gw6=<GatewayIPv6>] [,ip=<IPv4Format/CIDR>] [,ip6=<IPv6Format/CIDR>]
-* ipconfig1 - optional, same as ipconfig0 format
-
-Alternatively, cloud-init configuration can be customized with config files that reside in a volume in the Proxmox VE server. Use the attribute `cicustom` to indicate the location of these files. 
-
-* cicustom - location of cloud-config files that Proxmox will put in the generated cloud-init config iso image, e.g. `cicustom = "user=local:snippets/user_data.yaml"`. For more info about this attribute, see the details of the parameter `--cicustom` in the section "Custom Cloud-Init Configuration" from the [Proxmox Cloud-Init support](https://pve.proxmox.com/wiki/Cloud-Init_Support) page.
-
-### Preprovision (internal alternative to Cloud-Init)
-
-There is a pre-provision phase which is used to set a hostname, intialize eth0, and resize the VM disk to available space. This is done over SSH with the ssh_forward_ip, ssh_user and ssh_private_key.
-
-Disk resize is done if the file /etc/auto_resize_vda.sh exists. Source: https://github.com/Telmate/terraform-ubuntu-proxmox-iso/blob/master/auto_resize_vda.sh
-
-### Provisioner usage
-
-
-Remove the temporary net1 adapter.
-Inside the VM this usually triggers the routes back to the provisioning machine on net0.
-```
-  provisioner "proxmox" {
-    action = "sshbackward"
-  }
-
-```
-
-Replace the temporary net1 adapter with a new persistent net1.
-```
-  provisioner "proxmox" {
-    action = "reconnect"
-    net1 = "virtio,bridge=vmbr0,tag=99"
-  }
-
-```
-If net1 needs a config other than DHCP you should prior to this use provisioner "remote-exec" to modify the network config.
+* [Proxmox](https://www.proxmox.com/en/)
+* [Proxmox documentation](https://pve.proxmox.com/pve-docs/)
+* [Terraform](https://www.terraform.io/)
+* [Terraform documentation](https://www.terraform.io/docs/index.html)
+* [Recommended ISO builder](https://github.com/Telmate/terraform-ubuntu-proxmox-iso)
diff --git a/docs/cloud_init_guide.md b/docs/cloud_init_guide.md
new file mode 100644
index 00000000..b16b6520
--- /dev/null
+++ b/docs/cloud_init_guide.md
@@ -0,0 +1,219 @@
+# Cloud Init Guide
+
+## Sample file
+
+main.tf:
+```
+/* Uses cloud-init options from Proxmox 5.2 */
+resource "proxmox_vm_qemu" "cloudinit-test" {
+  name = "tftest1.xyz.com"
+  desc = "tf description"
+  target_node = "proxmox1-xx"
+
+  clone = "ci-ubuntu-template"
+
+  # The destination resource pool for the new VM
+  pool = "pool0"
+
+  storage = "local"
+  cores = 3
+  sockets = 1
+  memory = 2560
+  disk_gb = 4
+  nic = "virtio"
+  bridge = "vmbr0"
+
+  ssh_user = "root"
+  ssh_private_key = <<EOF
+-----BEGIN RSA PRIVATE KEY-----
+private ssh key root
+-----END RSA PRIVATE KEY-----
+EOF
+
+  os_type = "cloud-init"
+  ipconfig0 = "ip=10.0.2.99/16,gw=10.0.2.2"
+
+  sshkeys = <<EOF
+ssh-rsa AAAAB3NzaC1kj...key1
+ssh-rsa AAAAB3NzaC1kj...key2
+EOF
+
+  provisioner "remote-exec" {
+    inline = [
+      "ip a"
+    ]
+  }
+}
+
+/* Null resource that generates a cloud-config file per vm */
+data "template_file" "user_data" {
+  count    = var.vm_count
+  template = file("${path.module}/files/user_data.cfg")
+  vars = {
+    pubkey   = file("~/.ssh/id_rsa.pub")
+    hostname = "vm-${count.index}"
+    fqdn     = "vm-${count.index}.${var.domain_name}"
+  }
+}
+resource "local_file" "cloud_init_user_data_file" {
+  count    = var.vm_count
+  content  = data.template_file.user_data[count.index].rendered
+  filename = "${path.module}/files/user_data_${count.index}.cfg"
+}
+
+resource "null_resource" "cloud_init_config_files" {
+  count = var.vm_count
+  connection {
+    type     = "ssh"
+    user     = "${var.pve_user}"
+    password = "${var.pve_password}"
+    host     = "${var.pve_host}"
+  }
+
+  provisioner "file" {
+    source      = local_file.cloud_init_user_data_file[count.index].filename
+    destination = "/var/lib/vz/snippets/user_data_vm-${count.index}.yml"
+  }
+}
+
+/* Configure cloud-init User-Data with custom config file */
+resource "proxmox_vm_qemu" "cloudinit-test" {
+  depends_on = [
+    null_resource.cloud_init_config_files,
+  ]
+
+  name = "tftest1.xyz.com"
+  desc = "tf description"
+  target_node = "proxmox1-xx"
+
+  clone = "ci-ubuntu-template"
+
+  # The destination resource pool for the new VM
+  pool = "pool0"
+
+  storage = "local"
+  cores = 3
+  sockets = 1
+  memory = 2560
+  disk_gb = 4
+  nic = "virtio"
+  bridge = "vmbr0"
+
+  ssh_user = "root"
+  ssh_private_key = <<EOF
+-----BEGIN RSA PRIVATE KEY-----
+private ssh key root
+-----END RSA PRIVATE KEY-----
+EOF
+
+  os_type = "cloud-init"
+  ipconfig0 = "ip=10.0.2.99/16,gw=10.0.2.2"
+
+  /*
+    sshkeys and other User-Data parameters are specified with a custom config file.
+    In this example each VM has its own config file, previously generated and uploaded to
+    the snippets folder in the local storage in the Proxmox VE server.
+  */
+  cicustom = "user=local:snippets/user_data_vm-${count.index}.yml"
+
+  provisioner "remote-exec" {
+    inline = [
+      "ip a"
+    ]
+  }
+}
+
+/* Uses custom eth1 user-net SSH portforward */
+resource "proxmox_vm_qemu" "prepprovision-test" {
+  name = "tftest1.xyz.com"
+  desc = "tf description"
+  target_node = "proxmox1-xx"
+
+  clone = "terraform-ubuntu1404-template"
+
+  # The destination resource pool for the new VM
+  pool = "pool0"
+
+  cores = 3
+  sockets = 1
+  # Same CPU as the Physical host, possible to add cpu flags
+  # Ex: "host,flags=+md-clear;+pcid;+spec-ctrl;+ssbd;+pdpe1gb"
+  cpu = "host"
+  numa = false
+  memory = 2560
+  scsihw = "lsi"
+  # Boot from hard disk (c), CD-ROM (d), network (n)
+  boot = "cdn"
+  # It's possible to add this type of material and use it directly
+  # Possible values are: network,disk,cpu,memory,usb
+  hotplug = "network,disk,usb"
+  # Default boot disk
+  bootdisk = "virtio0"
+  # HA, you need to use a shared disk for this feature (ex: rbd)
+  hastate = ""
+  
+  #Display
+  vga {
+    type = "std"
+    #Between 4 and 512, ignored if type is defined to serial
+    memory = 4
+  }
+  
+  network {
+    id = 0
+    model = "virtio"
+  }
+  network {
+    id = 1
+    model = "virtio"
+    bridge = "vmbr1"
+  }
+  disk {
+    id = 0
+    type = virtio
+    storage = local-lvm
+    storage_type = lvm
+    size = 4G
+    backup = true
+  }
+  # Serial interface of type socket is used by xterm.js
+  # You will need to configure your guest system before being able to use it
+  serial {
+    id = 0
+    type = "socket"
+  }
+  preprovision = true
+  ssh_forward_ip = "10.0.0.1"
+  ssh_user = "terraform"
+  ssh_private_key = <<EOF
+-----BEGIN RSA PRIVATE KEY-----
+private ssh key terraform
+-----END RSA PRIVATE KEY-----
+EOF
+
+  os_type = "ubuntu"
+  os_network_config = <<EOF
+auto eth0
+iface eth0 inet dhcp
+EOF
+
+  connection {
+    type = "ssh"
+    user = "${self.ssh_user}"
+    private_key = "${self.ssh_private_key}"
+    host = "${self.ssh_host}"
+    port = "${self.ssh_port}"
+  }
+
+  provisioner "remote-exec" {
+    inline = [
+      "ip a"
+    ]
+  }
+
+  provisioner "proxmox" {
+    action = "sshbackward"
+  }
+}
+
+```
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 00000000..18daf2d0
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,10 @@
+# Documentation: Terraform provider plugin for Proxmox
+
+## Table of contents
+
+1. [Install Terraform plugin](installation.md) 
+1. [Terraform Provider](provider.md) 
+1. [Terraform VM Qemu Resource](resource_vm_qemu.md) 
+1. [Terraform LXC Resource](resource_lxc.md) 
+1. [Terraform Provisioner](provisioner.md) 
+1. [Cloud Init Guide](cloud_init_guide.md) 
diff --git a/docs/installation.md b/docs/installation.md
new file mode 100644
index 00000000..bce543f1
--- /dev/null
+++ b/docs/installation.md
@@ -0,0 +1,41 @@
+# How to get terraform to recognize third party provider
+
+Third-party plugins (both providers and provisioners) can be manually installed into the user plugins directory, 
+located at `%APPDATA%\terraform.d\plugins` on Windows and `~/.terraform.d/plugins` on other systems. Plugins come
+with executables that have to be placed in the plugin directory.
+
+## Compile the executables with Go
+
+In order to build the required executables, [install Go](https://golang.org/doc/install) first. Then clone this
+repository. Then run the following commands inside the cloned repository. Since this plugin is both a provider and 
+provisioner in one, there are two install commands.
+
+```
+go install github.com/Telmate/terraform-provider-proxmox/cmd/terraform-provider-proxmox
+go install github.com/Telmate/terraform-provider-proxmox/cmd/terraform-provisioner-proxmox
+```
+
+Then create the executables. They are placed in the `bin` folder inside the repository.
+
+```
+make
+```
+
+## Copy executables to plugin directory
+
+You need to copy these executables to the ~/.terraform.d directory which will also need to have a plugins directory 
+created.
+
+```shell
+mkdir ~/.terraform.d/plugins
+cp bin/terraform-provider-proxmox ~/.terraform.d/plugins
+cp bin/terraform-provisioner-proxmox ~/.terraform.d/plugins
+```
+
+## Initialize Terraform
+
+Now the plugin is installed, you can simply create a new terraform directory and do usual terraforming.
+
+```
+terraform init
+```
diff --git a/docs/provider.md b/docs/provider.md
new file mode 100644
index 00000000..5529b958
--- /dev/null
+++ b/docs/provider.md
@@ -0,0 +1,34 @@
+# Terraform Provider
+
+A Terraform provider is responsible for understanding API interactions and exposing resources. The Proxmox provider
+uses the Proxmox API. This provider exposes two resources: [proxmox_vm_qemu](resource_vm_qemu.md) and [proxmox_lxc](resource_lxc.md).
+
+## Creating the connection
+
+When connecting to the Proxmox API, the provider has to know at least three parameters: the URL, username and password.
+One can supply fields using the provider syntax in Terraform. It is recommended to pass secrets through environment 
+variables.
+
+```
+export PM_PASS=password
+```
+
+```tf
+provider "proxmox" {
+    pm_api_url = "https://proxmox-server01.example.com:8006/api2/json"
+    pm_user = "terraform-user@pve"
+}
+```
+
+## Argument Reference
+
+The following arguments are supported in the provider block:
+
+* `pm_api_url` - (Required; or use environment variable `PM_API_URL`) This is the target Proxmox API endpoint.
+* `pm_user` - (Required; or use environment variable `PM_USER`) The user, maybe required to include @pam.
+* `pm_password` - (Required; or use environment variable `PM_PASS`) The password.
+* `pm_otp` - (Optional; or use environment variable `PM_OTP`) The  2FA OTP code.
+* `pm_tls_insecure` - (Optional) Disable TLS verification while connecting.
+* `pm_parallel` - (Optional; defaults to 4) Allowed simultaneous Proxmox processes (e.g. creating resources).
+
+Additionally, one can set the `PM_OTP_PROMPT` environment variable to prompt for OTP 2FA code (if required).
diff --git a/docs/provisioner.md b/docs/provisioner.md
new file mode 100644
index 00000000..d1602531
--- /dev/null
+++ b/docs/provisioner.md
@@ -0,0 +1,20 @@
+# Provisioner usage
+
+Remove the temporary net1 adapter.
+Inside the VM this usually triggers the routes back to the provisioning machine on net0.
+```
+  provisioner "proxmox" {
+    action = "sshbackward"
+  }
+
+```
+
+Replace the temporary net1 adapter with a new persistent net1.
+```
+  provisioner "proxmox" {
+    action = "reconnect"
+    net1 = "virtio,bridge=vmbr0,tag=99"
+  }
+
+```
+If net1 needs a config other than DHCP you should prior to this use provisioner "remote-exec" to modify the network config.
diff --git a/docs/resource_lxc.md b/docs/resource_lxc.md
new file mode 100644
index 00000000..a41f2984
--- /dev/null
+++ b/docs/resource_lxc.md
@@ -0,0 +1 @@
+# Terraform LXC Resource
diff --git a/docs/resource_vm_qemu.md b/docs/resource_vm_qemu.md
new file mode 100644
index 00000000..0dc481ed
--- /dev/null
+++ b/docs/resource_vm_qemu.md
@@ -0,0 +1,50 @@
+# Terraform VM Qemu Resource
+
+Resources are the most important element in the Terraform language. Each resource block describes one or more 
+infrastructure objects, such as virtual networks, compute instances, or higher-level components such as DNS records.
+
+## Create a Qemu VM resource
+
+You can start from either an ISO or clone an existing VM. Optimally, you could create a VM resource you will use a clone 
+base with an ISO, and make the rest of the VM resources depend on that base "template" and clone it.
+
+## Preprovision
+
+With preprovision you can provision a VM directly from the resource block.
+
+```tf
+resource "proxmox_vm_qemu" "prepprovision-test" {
+    ...
+    preprovision = true
+    os_type = "ubuntu"  // ubuntu, centos or cloud-init
+}
+```
+
+### Preprovision for Linux (Ubuntu / CentOS)
+
+There is a pre-provision phase which is used to set a hostname, intialize eth0, and resize the VM disk to available 
+space. This is done over SSH with the ssh_forward_ip, ssh_user and ssh_private_key. Disk resize is done if the file 
+[/etc/auto_resize_vda.sh](https://github.com/Telmate/terraform-ubuntu-proxmox-iso/blob/master/auto_resize_vda.sh) exists.
+
+
+## Preprovision for Cloud-Init
+
+Cloud-init VMs must be cloned from a [cloud-init ready template](https://pve.proxmox.com/wiki/Cloud-Init_Support).
+
+* ciuser - User name to change ssh keys and password for instead of the image’s configured default user.
+* cipassword - Password to assign the user.
+* cicustom - location of cloud-config files that Proxmox will put in the generated cloud-init config iso image.
+* searchdomain - Sets DNS search domains for a container.
+* nameserver - Sets DNS server IP address for a container.
+* sshkeys - public ssh keys, one per line
+* ipconfig0 - [gw=<GatewayIPv4>] [,gw6=<GatewayIPv6>] [,ip=<IPv4Format/CIDR>] [,ip6=<IPv6Format/CIDR>]
+* ipconfig1 - optional, same as ipconfig0 format
+
+
+## Argument reference
+
+* `cicustom` - (Optional) Location of cloud-config files that Proxmox will put in the generated cloud-init config iso 
+  image, e.g. `cicustom = "user=local:snippets/user_data.yaml"`. For more info about this attribute, see the details of 
+  the parameter `--cicustom` in the section "Custom Cloud-Init Configuration" from the [Proxmox Cloud-Init support](https://pve.proxmox.com/wiki/Cloud-Init_Support) page.
+* `ssh_forward_ip` - (Optional) IP or hostname of the target node or bridge IP. This is where proxmox will create a port
+  forward to your VM with via a user_net. (for pre-cloud-init provisioning).
diff --git a/docs/terraforminit.md b/docs/terraforminit.md
deleted file mode 100644
index 5c89d0aa..00000000
--- a/docs/terraforminit.md
+++ /dev/null
@@ -1,27 +0,0 @@
-# How to get terraform to recognize third party provider
-
-The default installation of terraform has no way of finding custom third party providers. This document shows you how to locate providers so that `terraform init` can find them and copy them to your working terraform directory when creating a new project.
-
-## Locate the provider binaries
-
-Assuming you have followed other directions the deafult locations for these binaries (on a mac at least) are as follows:
-
-```bash
-which terraform-provider-proxmox
-~/go-workspace/bin/terraform-provider-proxmox
-which terraform-provisioner-proxmox
-~/go-workspace/bin/terraform-provisioner-proxmox 
-```
-
-## Copy provider binaries
-
-You need to copy these binaries to the ~/.terraform.d directory which will also need to have a plugins directory created:
-
-```shell
-cd ~/.terraform.d
-mkdir plugins
-cd plugins
-cp ~/go-workspace/bin/terraform-provider-proxmox .
-cp ~/go-workspace/bin/terraform-provisioner-proxmox .
-```
-Once this is done, simply create a new terraform directory and do usual terraforming (terraform init etc)