Add docs about using lifecycle when recreating instance groups (#2620)

<!-- This change is generated by MagicModules. -->
/cc @rileykarson

google/resource_compute_instance_group_test.go

@@ -40,6 +40,39 @@ func TestAccComputeInstanceGroup_basic(t *testing.T) {
 	})
 }
 
+func TestAccComputeInstanceGroup_rename(t *testing.T) {
+	t.Parallel()
+
+	var instanceName = fmt.Sprintf("instancegroup-test-%s", acctest.RandString(10))
+	var instanceGroupName = fmt.Sprintf("instancegroup-test-%s", acctest.RandString(10))
+	var backendName = fmt.Sprintf("instancegroup-test-%s", acctest.RandString(10))
+	var healthName = fmt.Sprintf("instancegroup-test-%s", acctest.RandString(10))
+
+	resource.Test(t, resource.TestCase{
+		PreCheck:     func() { testAccPreCheck(t) },
+		Providers:    testAccProviders,
+		CheckDestroy: testAccComputeInstanceGroup_destroy,
+		Steps: []resource.TestStep{
+			{
+				Config: testAccComputeInstanceGroup_rename(instanceName, instanceGroupName, backendName, healthName),
+			},
+			{
+				ResourceName:      "google_compute_instance_group.basic",
+				ImportState:       true,
+				ImportStateVerify: true,
+			},
+			{
+				Config: testAccComputeInstanceGroup_rename(instanceName, instanceGroupName+"2", backendName, healthName),
+			},
+			{
+				ResourceName:      "google_compute_instance_group.basic",
+				ImportState:       true,
+				ImportStateVerify: true,
+			},
+		},
+	})
+}
+
 func TestAccComputeInstanceGroup_recreatedInstances(t *testing.T) {
 	t.Parallel()
 
@@ -359,6 +392,69 @@ func testAccComputeInstanceGroup_basic(instance string) string {
 	}`, instance, instance, instance)
 }
 
+func testAccComputeInstanceGroup_rename(instance, instanceGroup, backend, health string) string {
+	return fmt.Sprintf(`
+data "google_compute_image" "my_image" {
+	family  = "debian-9"
+	project = "debian-cloud"
+}
+
+resource "google_compute_instance" "ig_instance" {
+	name = "%s"
+	machine_type = "n1-standard-1"
+	can_ip_forward = false
+	zone = "us-central1-c"
+	boot_disk {
+		initialize_params {
+			image = "${data.google_compute_image.my_image.self_link}"
+		}
+	}
+
+	network_interface {
+		network = "default"
+	}
+}
+
+resource "google_compute_instance_group" "basic" {
+	name = "%s"
+	zone = "us-central1-c"
+	instances = [ "${google_compute_instance.ig_instance.self_link}" ]
+	named_port {
+		name = "http"
+		port = "8080"
+	}
+
+	named_port {
+		name = "https"
+		port = "8443"
+	}
+
+	lifecycle {
+		create_before_destroy = true
+	}
+}
+
+resource "google_compute_backend_service" "default_backend" {
+	name      = "%s"
+	port_name = "https"
+	protocol  = "HTTPS"
+
+	backend {
+		group = "${google_compute_instance_group.basic.self_link}"
+	}
+
+	health_checks = [
+		"${google_compute_https_health_check.healthcheck.self_link}",
+	]
+}
+
+resource "google_compute_https_health_check" "healthcheck" {
+	name         = "%s"
+	request_path = "/health_check"
+}
+`, instance, instanceGroup, backend, health)
+}
+
 func testAccComputeInstanceGroup_update(instance string) string {
 	return fmt.Sprintf(`
 	data "google_compute_image" "my_image" {

website/docs/r/compute_instance_group.html.markdown

@@ -12,9 +12,11 @@ Creates a group of dissimilar Compute Engine virtual machine instances.
 For more information, see [the official documentation](https://cloud.google.com/compute/docs/instance-groups/#unmanaged_instance_groups)
 and [API](https://cloud.google.com/compute/docs/reference/latest/instanceGroups)
 
-## Example Usage
+-> Recreating an instance group that's in use by another resource will give a
+`resourceInUseByAnotherResource` error. You can avoid this error with a
+Terraform `lifecycle` block as outlined in the example below.
 
-### Empty instance group
+## Example Usage - Empty instance group
 
 ```hcl
 resource "google_compute_instance_group" "test" {
@@ -25,7 +27,7 @@ resource "google_compute_instance_group" "test" {
 }
 ```
 
-### With instances and named ports
+### Example Usage - With instances and named ports
 
 ```hcl
 resource "google_compute_instance_group" "webservers" {
@@ -51,6 +53,71 @@ resource "google_compute_instance_group" "webservers" {
 }
 ```
 
+### Example Usage - Recreating an instance group in use
+Recreating an instance group that's in use by another resource will give a
+`resourceInUseByAnotherResource` error. Use `lifecycle.create_before_destroy`
+as shown in this example to avoid this type of error.
+
+```hcl
+resource "google_compute_instance_group" "staging_group" {
+  name = "staging-instance-group"
+  zone = "us-central1-c"
+  instances = [ "${google_compute_instance.staging_vm.self_link}" ]
+  named_port {
+    name = "http"
+    port = "8080"
+  }
+
+  named_port {
+    name = "https"
+    port = "8443"
+  }
+
+  lifecycle {
+    create_before_destroy = true
+  }
+}
+
+data "google_compute_image" "debian_image" {
+  family  = "debian-9"
+  project = "debian-cloud"
+}
+
+resource "google_compute_instance" "staging_vm" {
+  name = "staging-vm"
+  machine_type = "n1-standard-1"
+  zone = "us-central1-c"
+  boot_disk {
+    initialize_params {
+      image = "${data.google_compute_image.debian_image.self_link}"
+    }
+  }
+
+  network_interface {
+    network = "default"
+  }
+}
+
+resource "google_compute_backend_service" "staging_service" {
+  name      = "staging-service"
+  port_name = "https"
+  protocol  = "HTTPS"
+
+  backend {
+    group = "${google_compute_instance_group.staging_group.self_link}"
+  }
+
+  health_checks = [
+    "${google_compute_https_health_check.staging_health.self_link}",
+  ]
+}
+
+resource "google_compute_https_health_check" "staging_health" {
+  name         = "staging-health"
+  request_path = "/health_check"
+}
+```
+
 ## Argument Reference
 
 The following arguments are supported: