docs: updated import hosts, clusters, and virtual_machine (#2257)

- Updates to clarify the import of `vsphere_hosts` resources. - Updates to clarify the import of `vsphere_compute_cluster` resources. - Updates to clarify the `vm` path in the import of a `virtual_machine` resources. Signed-off-by: Jared Burns <[email protected]> Co-authored-by: Ryan Johnson <[email protected]>
hashicorp · Sep 9, 2024 · 46c4ce8 · 46c4ce8
1 parent ec1481e
commit 46c4ce8
Show file tree

Hide file tree

Showing 4 changed files with 129 additions and 21 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,6 +1,6 @@
 # <!-- markdownlint-disable first-line-h1 no-inline-html -->
 
-## 2.9.1 (Not Released)
+## 2.9.1 (September 9, 2024)
 
 BUG FIX:
 
@@ -10,8 +10,15 @@ BUG FIX:
 
 DOCUMENTATION:
 
-* `resource/vsphere_virtual_machine`: Updates to clarify assignment of `network_interface`.
-  ([#2256]https://github.com/hashicorp/terraform-provider-vsphere/pull/2256)
+* `resource/vsphere_virtual_machine`: Updates to clarify assignment of `network_interface`
+  resources. ([#2256]https://github.com/hashicorp/terraform-provider-vsphere/pull/2256)
+* `resource/vsphere_host`: Updates to clarify import of `vsphere_hosts`.
+  ([#2257]https://github.com/hashicorp/terraform-provider-vsphere/pull/2257)
+* `resource/vsphere_compute_cluster`: Updates to clarify import of `vsphere_compute_cluster`
+  resources. ([#2257]https://github.com/hashicorp/terraform-provider-vsphere/pull/2257)
+* `resource/vsphere_virtual_machine`: Updates to clarify the `vm` path in the import of
+  `virtual_machine` resources.
+  ([#2257]https://github.com/hashicorp/terraform-provider-vsphere/pull/2257)
 
 ## 2.9.0 (September 3, 2024)
 

diff --git a/website/docs/r/compute_cluster.html.markdown b/website/docs/r/compute_cluster.html.markdown
@@ -55,9 +55,9 @@ variable "datacenter" {
 
 variable "hosts" {
   default = [
-    "esxi01.example.com",
-    "esxi02.example.com",
-    "esxi03.example.com",
+    "esxi-01.example.com",
+    "esxi-02.example.com",
+    "esxi-03.example.com",
   ]
 }
 
@@ -66,15 +66,15 @@ data "vsphere_datacenter" "datacenter" {
 }
 
 data "vsphere_host" "host" {
-  count         = length(var.hosts)
-  name          = var.hosts[count.index]
+  for_each      = toset(var.hosts)
+  name          = each.value
   datacenter_id = data.vsphere_datacenter.datacenter.id
 }
 
 resource "vsphere_compute_cluster" "compute_cluster" {
   name            = "terraform-compute-cluster-test"
   datacenter_id   = data.vsphere_datacenter.datacenter.id
-  host_system_ids = [data.vsphere_host.host.*.id]
+  host_system_ids = [for host in data.vsphere_host.host : host.id]
 
   drs_enabled          = true
   drs_automation_level = "fullyAutomated"
@@ -578,7 +578,41 @@ path to the cluster, via the following command:
 
 [docs-import]: https://www.terraform.io/docs/import/index.html
 
+```hcl
+variable "datacenter" {
+  default = "dc-01"
+}
+
+data "vsphere_datacenter" "datacenter" {
+  name = var.datacenter
+}
+
+resource "vsphere_compute_cluster" "compute_cluster" {
+  name            = "cluster-01"
+  datacenter_id   = data.vsphere_datacenter.datacenter.id
+}
+```
+
+~> **NOTE:** When you import a cluster, all managed settings are returned. Ensure all settings are set correctly in resource. For example:
+
+```hcl
+resource "vsphere_compute_cluster" "compute_cluster" {
+  name                      = "cluster-01"
+  datacenter_id             = data.vsphere_datacenter.datacenter.id
+  vsan_enabled              = true
+  vsan_performance_enabled  = true
+  host_system_ids           = [for host in data.vsphere_host.host : host.id]
+  dpm_automation_level      = "automated"
+  drs_automation_level      = "fullyAutomated"
+  drs_enabled               = true
+  ha_datastore_apd_response = "restartConservative"
+  ha_datastore_pdl_response = "restartAggressive"
+  ... etc.
 ```
+
+All information will be added to the Terraform state after import.
+
+```console
 terraform import vsphere_compute_cluster.compute_cluster /dc-01/host/cluster-01
 ```
 

diff --git a/website/docs/r/host.html.markdown b/website/docs/r/host.html.markdown
@@ -23,12 +23,12 @@ data "vsphere_datacenter" "datacenter" {
 }
 
 data "vsphere_host_thumbprint" "thumbprint" {
-  address = "esx-01.example.com"
+  address  = "esx-01.example.com"
   insecure = true
 }
 
 resource "vsphere_host" "esx-01" {
-  hostname = "esx-01.example.com"
+  hostname   = "esx-01.example.com"
   username   = "root"
   password   = "password"
   license    = "00000-00000-00000-00000-00000"
@@ -50,17 +50,17 @@ data "vsphere_compute_cluster" "cluster" {
 }
 
 data "vsphere_host_thumbprint" "thumbprint" {
-  address = "esx-01.example.com"
+  address  = "esx-01.example.com"
   insecure = true
 }
 
 resource "vsphere_host" "esx-01" {
-  hostname = "esx-01.example.com"
-  username = "root"
-  password = "password"
-  license  = "00000-00000-00000-00000-00000"
+  hostname   = "esx-01.example.com"
+  username   = "root"
+  password   = "password"
+  license    = "00000-00000-00000-00000-00000"
   thumbprint = data.vsphere_host_thumbprint.thumbprint.id
-  cluster  = data.vsphere_compute_cluster.cluster.id
+  cluster    = data.vsphere_compute_cluster.cluster.id
   services {
     ntpd {
       enabled     = true
@@ -131,12 +131,71 @@ connections and require vCenter Server.
 ## Importing
 
 An existing host can be [imported][docs-import] into this resource by supplying
-the host's ID. An example is below:
+the host's ID.
 
 [docs-import]: /docs/import/index.html
 
+Obtain the host's ID using the data source. For example:
+
+```hcl
+data "vsphere_datacenter" "datacenter" {
+  name = "dc-01"
+}
+
+data "vsphere_host" "host" {
+  name          = "esx-01.example.com"
+  datacenter_id = data.vsphere_datacenter.datacenter.id
+}
+
+output "host_id" {
+  value = data.vsphere_host.host.id
+}
+```
+
+Next, create a resource configuration, For example:
+
+```hcl
+data "vsphere_datacenter" "datacenter" {
+  name = "dc-01"
+}
+
+data "vsphere_host_thumbprint" "thumbprint" {
+  address = "esx-01.example.com"
+  insecure = true
+}
+
+resource "vsphere_host" "esx-01" {
+  hostname   = "esx-01.example.com"
+  username   = "root"
+  password   = "password"
+  thumbprint = data.vsphere_host_thumbprint.thumbprint.id
+  datacenter = data.vsphere_datacenter.datacenter.id
+}
+```
+
+~> **NOTE:** When you import hosts, all managed settings are returned. Ensure all settings are set correctly in resource. For example:
+
+```hcl
+resource "vsphere_host" "esx-01" {
+  hostname   = "esx-01.example.com"
+  username   = "root"
+  password   = "password"
+  license    = "00000-00000-00000-00000-00000"
+  thumbprint = data.vsphere_host_thumbprint.thumbprint.id
+  cluster    = data.vsphere_compute_cluster.cluster.id
+  services {
+    ntpd {
+      enabled     = true
+      policy      = "on"
+      ntp_servers = ["pool.ntp.org"]
+    }
+}
 ```
+
+All information will be added to the Terraform state after import.
+
+```console
 terraform import vsphere_host.esx-01 host-123
 ```
 
-The above would import the host with ID `host-123`.
+The above would import the host `esx-01.example.com` with the host ID `host-123`.
diff --git a/website/docs/r/virtual_machine.html.markdown b/website/docs/r/virtual_machine.html.markdown
@@ -1639,13 +1639,21 @@ An existing virtual machine can be [imported][docs-import] into the Terraform st
 
 [docs-import]: /docs/import/index.html
 
-**Example**:
+**Examples**:
+
+Import a virtual machine resource named `foo` located in the `dc-01` datacenter.
 
 ```
 terraform import vsphere_virtual_machine.vm /dc-01/vm/foo
 ```
 
-In this example, a virtual machine resource named `foo` located in the `dc-01` datacenter is imported.
+~> **NOTE:** The `vm` portion of the path is required by vSphere. If the virtual machine is located in a folder, the folder path needs to be included. This is because vSphere organizes virtual machines within a datacenter under the `vm` folder, and any additional folders created within the `vm` folder must be included in the path.
+
+If the virtual machine `foo` is in a folder named `bar`, the import command would be:
+
+```
+terraform import vsphere_virtual_machine.vm /dc-01/vm/bar/foo
+```
 
 ### Additional Importing Requirements