Ssl migration guide (#1660)

* First cut at adding migration info

* Added dina's suggestions

* Claire's feedback

Author: kodster28

products/ssl/src/content/ssl-for-saas/versioning.md

@@ -18,19 +18,27 @@ SSL for SaaS v2 removes IP-based routing and its associated problems. Instead, t
 
 To ensure that your service is not disrupted, you need to perform an additional ownership check on every new Custom Hostname. There are three methods to verify ownership: TXT, HTTP, and CNAME. Use TXT and HTTP for pre-validation to validate the Custom Hostname before traffic is proxied by Cloudflare’s edge.
 
-### DNS TXT Record
+### Recommended validation methods
+
+Using a [TXT](#dns-txt-record) or [HTTP](#http-token) validation method helps you avoid downtime during your migration. If you choose to use [CNAME validation](#cname-validation), your domain might fall behind on its [backoff schedule](../validation-backoff-schedule).
+
+#### DNS TXT Record
 
 When creating a Custom Hostname with the TXT method through the [API](https://api.cloudflare.com/#custom-hostname-for-a-zone-create-custom-hostname), a TXT ownership_verification record is provided for your customer to add to their DNS for the ownership validation check. When the TXT record is added, the Custom Hostname will be marked as **Active** in the Cloudflare SSL/TLS app under the Custom Hostnames tab. 
 
-### HTTP Token
+#### HTTP Token
 
 When creating a Custom Hostname with the HTTP through the [API](https://api.cloudflare.com/#custom-hostname-for-a-zone-create-custom-hostname), an HTTP ownership_verification token is provided. HTTP verification is used mainly by organizations with a large deployed base of custom domains with HTTPS support. Serving the HTTP token from your origin web server allows hostname verification before proxying domain traffic through Cloudflare.
 
 Cloudflare sends GET requests to the http_url using `User-Agent: Cloudflare Custom Hostname Verification`.
 
 When the HTTP token is verified, the Custom Hostname will be marked as **Active** in the Cloudflare SSL/TLS app under the Custom Hostnames tab. 
 
-### CNAME Validation
+### Other validation methods
+
+Though you can use [CNAME validation](#cname-validation), we recommend you either use a [TXT](#dns-txt-record) or [HTTP](#http-token) validation method.
+
+#### CNAME Validation
 
 Custom Hostnames can also be validated once Cloudflare detects that the Custom Hostname is a CNAME record pointing to the fallback record configured for the SSL for SaaS domain. Though this is the simplest validation method, it increases the risk of errors. Since a CNAME record would also route traffic to Cloudflare’s edge, traffic may reach our edge before the Custom Hostname has completed validation or the SSL certificate has issued.
 
@@ -48,7 +56,33 @@ SSL for SaaS v2 is functionally equivalent to SSL for SaaS v1, but removes the r
 
 Once the migration has been started for your zone(s), Cloudflare will require every Custom Hostname to pass a hostname verification check. Existing Custom Hostnames that are proxying to Cloudflare with a DNS CNAME record will automatically re-validate and migrate to the new version with no downtime. Any Custom Hostnames created after the start of the migration will need to pass the hostname validation check using one of the validation methods mentioned above. 
 
-Your Cloudflare Account Team will work with you to schedule a migration window for each of your SSL for SaaS zones. After the migration has started and has had some time to progress, Cloudflare will generate a list of Custom Hostnames that failed to migrate and ask for your approval to complete the migration. When you give your approval, the migration will be complete, SSL for SaaS v1 will be disabled for the zone, and any Custom Hostname that has not completed hostname validation will no longer function.
+<Aside type='note'>
+
+You can revert the migration at any time.
+
+</Aside>
+
+### Before the migration
+
+Before your migration, you should:
+
+1. To test validation methods, set up a test zone and ask your Solutions Engineer (SE) to enable SSL for SaaS v2.
+1. Wait for your SE to run our pre-migration tool. This tool groups your hostnames into one of the following statuses:
+    - `test_pending`: In the process of being verified or was unable to be verified and re-queued for verification. A custom hostname will be re-queued 25 times before moving to the `test_failed` status.
+    - `test_active`: Passed CNAME verification
+    - `test_active_apex`: Passed Apex Proxy verification
+    - `test_blocked`: Hostname will be blocked during the migration because hostname belongs to a banned zone. Contact your CSM to verify banned custom hostnames and proceed with the migration.
+    - `test_failed`: Failed hostname verification 25 times
+1. Review the results of our pre-migration tool (run by your Solutions Engineer) using one of the following methods:
+    - Via the API: `https://api.cloudflare.com/client/v4/zones/{zone_tag}/custom_hostnames?hostname_status={status}`
+    - Via a CSV file (provided by your SE)
+    - Via the Cloudflare dashboard:
+    ![Review SSL migration status in the dashboard](..//static/ssl-migration-status.png)
+1. Approve the migration. Your Cloudflare account team will work with you to schedule a migration window for each of your SSL for SaaS zones.
+
+## During the migration
+
+After the migration has started and has had some time to progress, Cloudflare will generate a list of Custom Hostnames that failed to migrate and ask for your approval to complete the migration. When you give your approval, the migration will be complete, SSL for SaaS v1 will be disabled for the zone, and any Custom Hostname that has not completed hostname validation will no longer function.
 
 The migration timeline depends on the number of Custom Hostnames. For example, if a zone has fewer than 10,000 Custom Hostnames, the list can be generated around an hour after beginning the migration. If a zone has millions of Custom Hostnames, it may take up to 24 hours to identify instances that failed to successfully migrate.