[CDTOOL-1280] [Updated] Migrate an existing Delivery service using a classic domain to one using a versionless domain (#1202)

* docs(guides/domains): rewrote migration guide with new specifics

* updated changelog

* docs(guides/domains): corrected typos & incorrect domain name

Author: rcaril

CHANGELOG.md

@@ -14,7 +14,7 @@
 
 - docs(templates/guides): add a guide for adding a versionless domain to a service using a wildcard tls subscription ([#1194](https://github.com/fastly/terraform-provider-fastly/pull/1194))
 - docs(templates/guides): add a guide for using versionless domains with a Certainly subscription to a new devlivery service ([#1195](https://github.com/fastly/terraform-provider-fastly/pull/1195))
-- docs(templates/guides): add a guide for migrating delivery service classic domain to a versionless domain ([#1196](https://github.com/fastly/terraform-provider-fastly/pull/1196))
+- docs(templates/guides): add a guide for migrating delivery service classic domain to a versionless domain ([#1202](https://github.com/fastly/terraform-provider-fastly/pull/1202))
 - docs(templates/guides): add a guide for linking versionless domains to a service when the domains are not managed in Terraform ([#1199](https://github.com/fastly/terraform-provider-fastly/pull/1199))
 - docs(templates/guides): add a guide for migrating from the deprecated 'fastly_domain_v1' and 'fastly_domain_v1_service_link' resources and data sources  ([#1200](https://github.com/fastly/terraform-provider-fastly/pull/1200))
 - docs(ngwaf/rules): updated list of supported values for the 'operator' field for NGWAF WAF rule conditions ([#1201](https://github.com/fastly/terraform-provider-fastly/pull/1201))

docs/guides/versionless_domain_migration.md

@@ -5,38 +5,31 @@ subcategory: "Guides"
 
 ## Migrate a Delivery service with a classic domain to a versionless domain
 
-Before migrating, your HCL will look something like this, with a domain block inside of your service.
+Before migrating, your HCL will look something like this, with a domain block inside of your service and a TLS subscription.
 
 ```
 resource "fastly_service_vcl" "vcl_example" {
   name = "versionlessdomainexample"
+  backend {
+    address = "127.0.0.1"
+    name    = "localhost"
+  }
   domain {
     name    = "demo.example.com"
     comment = "demo"
   }
-  force_destroy = true
 }
-```
-
-Once you [use the control panel to migrate this domain to a versionless domain](https://www.fastly.com/documentation/guides/getting-started/domains/working-with-domains/migrating-classic-domains/), you will need to update your HCL to match the pattern below.
-You can find the documentation on versionless domain patterns here: https://registry.terraform.io/providers/fastly/fastly/latest/docs/resources/domain. Do not apply your changes before running the import in the next step, as that will result in an error.
 
-```
-resource "fastly_service_vcl" "vcl_example" {
-  name = "versionlessdomainexample"
-  force_destroy = true
-}
-
-resource "fastly_domain" "domain_example" {
-  fqdn       = "demo.example.com"
+resource "fastly_tls_subscription" "migrate_example" {
+  domains = ["demo.example.com"]
+  certificate_authority = "lets-encrypt"
 }
 ```
 
-Before making other changes you will need to import domain using terraform. The Domain ID can using [the Fastly CLI](https://www.fastly.com/documentation/reference/tools/cli/) by running `fastly domain list --fqdn=foo.example.com` and using the Domain ID from the record.
+Before making other changes you will need to import your domain(s) using Terraform. We'll need to run the following import command for each domain:
+> `terraform import fastly_domain.domain_example <domain_id>` 
 
-```
-terraform import fastly_domain.domain_example YOUR_DOMAIN_ID
-```
+The Domain ID can be obtained by using [the Fastly CLI](https://www.fastly.com/documentation/reference/tools/cli/) by running `fastly domain list --fqdn=foo.example.com` and then using the Domain ID from the record.
 
 Terraform should produce a message similar to the following.
 
@@ -52,18 +45,84 @@ The resources that were imported are shown above. These resources are now in
 your Terraform state and will henceforth be managed by Terraform.
 ```
 
-After importing, running `terraform plan` should result in no changes.
+You'll then need to add a `fastly_domain` resource, associating your service, as seen below.   
+  _You can find the documentation on versionless domain patterns here: https://registry.terraform.io/providers/fastly/fastly/latest/docs/resources/domain._ 
+> **Do not apply your changes before running the import in the next step, as that will result in an error.**
+
+```
+resource "fastly_service_vcl" "vcl_example" {
+  name = "versionlessdomainexample"
+  backend {
+    address = "127.0.0.1"
+    name    = "localhost"
+  }
+  domain {
+    name    = "demo.example.com"
+    comment = "demo"
+  }
+}
+
+resource "fastly_tls_subscription" "migrate_example" {
+  domains = ["demo.example.com"]
+  certificate_authority = "lets-encrypt"
+}
+
+resource "fastly_domain" "domain_example" {
+  fqdn       = "demo.example.com"
+  service_id = fastly_service_vcl.vcl_example.id
+}
+```
+
+Once you have added the necessary `fastly_domain` blocks , you can proceed with a `terraform plan` / `terraform apply`. 
 
-Once the import has run successfully, you can assign the domain to a service using the `service_id` field of the domain and then plan and apply.
+You should excpect to see something like this from your `terraform plan` / `terraform apply` commands:
+```
+ # fastly_domain.example will be updated in-place
+  ~ resource "fastly_domain" "example" {
+        id          = "3a2b3c4d5e"
+      + service_id  = "1a2b4c5d6e"
+        # (3 unchanged attributes hidden)
+    }
+```
+
+You now have associated the versionless domain with your service, but we'll still need to remove the classic domain from your HCL. The final step is to remove the `domain` attribute from your `fastly_service_vcl` block, as seen below.
 
 ```
 resource "fastly_service_vcl" "vcl_example" {
   name = "versionlessdomainexample"
-  force_destroy = true
+  backend {
+    address = "127.0.0.1"
+    name    = "localhost"
+  }
+}
+
+resource "fastly_tls_subscription" "migrate_example" {
+  domains = ["demo.example.com"]
+  certificate_authority = "lets-encrypt"
 }
 
 resource "fastly_domain" "domain_example" {
   fqdn       = "demo.example.com"
   service_id = fastly_service_vcl.vcl_example.id
 }
-```
+```
+
+You can now perform the `terraform plan` / `terraform apply` commands. You should expect to see a similar output from Terraform:
+
+```
+  # fastly_service_vcl.migrate_example will be updated in-place
+  ~ resource "fastly_service_vcl" "migrate_example" {
+      ~ active_version     = 1 -> (known after apply)
+      ~ cloned_version     = 1 -> (known after apply)
+        id                 = "1a2b4c5d6e"
+        name               = "versionlessdomainexample"
+        # (11 unchanged attributes hidden)
+
+      - domain {
+          - name    = "demo.example.com" -> null
+            # (1 unchanged attribute hidden)
+        }
+
+        # (1 unchanged block hidden)
+    }
+```

templates/guides/versionless_domain_migration.md

@@ -5,38 +5,31 @@ subcategory: "Guides"
 
 ## Migrate a Delivery service with a classic domain to a versionless domain
 
-Before migrating, your HCL will look something like this, with a domain block inside of your service.
+Before migrating, your HCL will look something like this, with a domain block inside of your service and a TLS subscription.
 
 ```
 resource "fastly_service_vcl" "vcl_example" {
   name = "versionlessdomainexample"
+  backend {
+    address = "127.0.0.1"
+    name    = "localhost"
+  }
   domain {
     name    = "demo.example.com"
     comment = "demo"
   }
-  force_destroy = true
 }
-```
-
-Once you [use the control panel to migrate this domain to a versionless domain](https://www.fastly.com/documentation/guides/getting-started/domains/working-with-domains/migrating-classic-domains/), you will need to update your HCL to match the pattern below.
-You can find the documentation on versionless domain patterns here: https://registry.terraform.io/providers/fastly/fastly/latest/docs/resources/domain. Do not apply your changes before running the import in the next step, as that will result in an error.
 
-```
-resource "fastly_service_vcl" "vcl_example" {
-  name = "versionlessdomainexample"
-  force_destroy = true
-}
-
-resource "fastly_domain" "domain_example" {
-  fqdn       = "demo.example.com"
+resource "fastly_tls_subscription" "migrate_example" {
+  domains = ["demo.example.com"]
+  certificate_authority = "lets-encrypt"
 }
 ```
 
-Before making other changes you will need to import domain using terraform. The Domain ID can using [the Fastly CLI](https://www.fastly.com/documentation/reference/tools/cli/) by running `fastly domain list --fqdn=foo.example.com` and using the Domain ID from the record.
+Before making other changes you will need to import your domain(s) using Terraform. We'll need to run the following import command for each domain:
+> `terraform import fastly_domain.domain_example <domain_id>` 
 
-```
-terraform import fastly_domain.domain_example YOUR_DOMAIN_ID
-```
+The Domain ID can be obtained by using [the Fastly CLI](https://www.fastly.com/documentation/reference/tools/cli/) by running `fastly domain list --fqdn=foo.example.com` and then using the Domain ID from the record.
 
 Terraform should produce a message similar to the following.
 
@@ -52,18 +45,84 @@ The resources that were imported are shown above. These resources are now in
 your Terraform state and will henceforth be managed by Terraform.
 ```
 
-After importing, running `terraform plan` should result in no changes.
+You'll then need to add a `fastly_domain` resource, associating your service, as seen below.   
+  _You can find the documentation on versionless domain patterns here: https://registry.terraform.io/providers/fastly/fastly/latest/docs/resources/domain._ 
+> **Do not apply your changes before running the import in the next step, as that will result in an error.**
+
+```
+resource "fastly_service_vcl" "vcl_example" {
+  name = "versionlessdomainexample"
+  backend {
+    address = "127.0.0.1"
+    name    = "localhost"
+  }
+  domain {
+    name    = "demo.example.com"
+    comment = "demo"
+  }
+}
+
+resource "fastly_tls_subscription" "migrate_example" {
+  domains = ["demo.example.com"]
+  certificate_authority = "lets-encrypt"
+}
+
+resource "fastly_domain" "domain_example" {
+  fqdn       = "demo.example.com"
+  service_id = fastly_service_vcl.vcl_example.id
+}
+```
+
+Once you have added the necessary `fastly_domain` blocks , you can proceed with a `terraform plan` / `terraform apply`. 
 
-Once the import has run successfully, you can assign the domain to a service using the `service_id` field of the domain and then plan and apply.
+You should excpect to see something like this from your `terraform plan` / `terraform apply` commands:
+```
+ # fastly_domain.example will be updated in-place
+  ~ resource "fastly_domain" "example" {
+        id          = "3a2b3c4d5e"
+      + service_id  = "1a2b4c5d6e"
+        # (3 unchanged attributes hidden)
+    }
+```
+
+You now have associated the versionless domain with your service, but we'll still need to remove the classic domain from your HCL. The final step is to remove the `domain` attribute from your `fastly_service_vcl` block, as seen below.
 
 ```
 resource "fastly_service_vcl" "vcl_example" {
   name = "versionlessdomainexample"
-  force_destroy = true
+  backend {
+    address = "127.0.0.1"
+    name    = "localhost"
+  }
+}
+
+resource "fastly_tls_subscription" "migrate_example" {
+  domains = ["demo.example.com"]
+  certificate_authority = "lets-encrypt"
 }
 
 resource "fastly_domain" "domain_example" {
   fqdn       = "demo.example.com"
   service_id = fastly_service_vcl.vcl_example.id
 }
-```
+```
+
+You can now perform the `terraform plan` / `terraform apply` commands. You should expect to see a similar output from Terraform:
+
+```
+  # fastly_service_vcl.migrate_example will be updated in-place
+  ~ resource "fastly_service_vcl" "migrate_example" {
+      ~ active_version     = 1 -> (known after apply)
+      ~ cloned_version     = 1 -> (known after apply)
+        id                 = "1a2b4c5d6e"
+        name               = "versionlessdomainexample"
+        # (11 unchanged attributes hidden)
+
+      - domain {
+          - name    = "demo.example.com" -> null
+            # (1 unchanged attribute hidden)
+        }
+
+        # (1 unchanged block hidden)
+    }
+```