Add v21 upgrade docs

docs/upgrading_to_v21.0.md

@@ -0,0 +1,62 @@
+# Upgrading to v21.0
+
+The v20.0 release of *kubernetes-engine* is a backwards incompatible
+release for the Hub, Anthos Config Management (ACM), and Config Sync modules.
+
+### Hub module rewrite
+The old [Hub submodule](https://github.com/terraform-google-modules/terraform-google-kubernetes-engine/tree/v20.0.0/modules/hub)
+has been renamed to `hub-legacy` and deprecated. It is replaced with a new [fleet membership](https://github.com/terraform-google-modules/terraform-google-kubernetes-engine/tree/master/modules/fleet-membership)
+module to handle registering GKE clusters to [fleets](https://cloud.google.com/anthos/multicluster-management/fleets) using the native API.
+
+The new module doesn't relies exclusively on native Terraform resources and should therefore be more robust.
+
+### Migrating
+For GKE clusters registered using the old module, you should update your configuration as follows:
+
+```diff
+  module "register" {
+-   source           = "terraform-google-modules/kubernetes-engine/google//modules/hub"
+-   version          = "~> 20.0"
++   source           = "terraform-google-modules/kubernetes-engine/google//modules/fleet-membership"
++   version          = "~> 21.0"
+
+    project_id       = "my-project-id"
+    cluster_name     = "my-cluster-name"
++   membership_name  = "gke-hub-membership"
+    location         = module.gke.location
+-   cluster_endpoint = module.gke.endpoint
+  }
+```
+
+You also need to follow these migration steps:
+
+1. Remove the old module from your state:
+
+    terraform state rm module.register
+
+2. Remove the cluster from the fleet:
+
+    gcloud container fleet memberships delete gke-hub-membership-name
+
+3. Apply the new configuration to re-register the cluster:
+
+    terraform apply
+
+#### Legacy module
+**The native API only supports registering GKE clusters**. Therefore, the old hub module is preserved as `hub-legacy`.
+
+You can continue using it by updating your configuration to point to the new location.
+
+```diff
+  module "hub" {
+-   source           = "terraform-google-modules/kubernetes-engine/google//modules/hub"
+-   version          = "~> 20.0"
++   source           = "terraform-google-modules/kubernetes-engine/google//modules/hub-legacy"
++   version          = "~> 21.0"
+
+    project_id       = "my-project-id"
+    cluster_name     = "my-cluster-name"
+    location         = module.gke.location
+    cluster_endpoint = module.gke.endpoint
+  }
+```