diff --git a/website/docs/guides/multitenancy.html.markdown b/website/docs/guides/multitenancy.html.markdown
index 69a28d05e..184f415e3 100644
--- a/website/docs/guides/multitenancy.html.markdown
+++ b/website/docs/guides/multitenancy.html.markdown
@@ -18,7 +18,7 @@ NSX also introduced NSX VPCs, offering a second level of tenancy and cloud consu
## NSX Project Creation and Reference
-NSX Project objects can be created and referenced with the `nsxt_policy_project` [resource](../r/policy_project.html.markdown) and [data source](../d/policy_project.html.markdown).
+NSX Project objects can be created and referenced with the `nsxt_policy_project` [resource](../resources/policy_project.html.markdown) and [data source](../data-sources/policy_project.html.markdown).
For example, an NSX multi-tenancy Project could be created as below:
diff --git a/website/docs/guides/upgrade.html.markdown b/website/docs/guides/upgrade.html.markdown
new file mode 100644
index 000000000..4f5304666
--- /dev/null
+++ b/website/docs/guides/upgrade.html.markdown
@@ -0,0 +1,168 @@
+---
+layout: "nsxt"
+page_title: "VMware NSX Terraform Provider NSX upgrade support"
+description: |-
+ VMware NSX Terraform Provider NSX upgrade support
+---
+
+# NSX Provider for NSX Upgrade
+
+NSX Terraform Provider offers support for [upgrading NSX components](https://docs.vmware.com/en/VMware-NSX/4.1/upgrade/GUID-E04242D7-EF09-4601-8906-3FA77FBB06BD.html).
+
+The provider support consists of several resources and data sources which can perform a complete upgrade cycle.
+The NSX Terraform provider support upgrades for NSX on ESX hosts, NSX Edge appliances, and NSX manager appliances.
+
+**NOTE:** The upgrade process using the Terraform NSXT provider assumes that the Terraform NSX provider uses NSX upgrade
+components exclusively. Therefore, concurrent changess to upgrade components via other means, e.g. UI, might fail the process.
+**NOTE:** The NSX upgrade process should start each upgrade with a clean state. So whenever an upgrade is executed, e.g.
+from v3.2.3 to v4.1.1 the Terraform state file should be retained until the upgrade is completed. Then, if the same plan
+is used later on to upgrade from v4.1.1 to v4.2.0, the Terraform state file should be deleted prior to applying the plan.
+
+## Upgrade process steps
+
+### Preparation for upgrade
+
+Upgrade preparation consists of several actions, and is performed using [nsxt_upgrade_prepare](../resources/upgrade_prepare.html.markdown):
+* Uploading the upgrade and precheck bundles.
+* Acceptance of the user agreement.
+* Reporting of failed pre-checks.
+
+**NOTE:** Only one `nsxt_upgrade_prepare` resource should be used in the upgrade plan.
+
+```hcl
+resource "nsxt_upgrade_prepare" "prepare_res" {
+ upgrade_bundle_url = "http://url-to-upgrade-bundle.mub"
+ precheck_bundle_url = "http://url-to-precheck-bundle.pub"
+ accept_user_agreement = true
+}
+```
+
+**NOTE:** Acceptance of the license agreement is required to initiate the upgrade process.
+**NOTE:** Precheck bundle is usable only while upgrading a NSX manager of version v4.1.1 and above.
+
+### Acknowledgement of upgrade issues and warnings
+
+The preparation stage may result with various warnings which would halt the upgrade process. These warnings can be
+suppressed with the [nsxt_upgrade_precheck_acknowledge](../resources/upgrade_precheck_acknowledge.html.markdown) resource.
+
+For example:
+```
+There are unacknowledged warnings in precheck: [backupOperationCheck], please address these errors from NSX or using nsxt_upgrade_precheck_acknowledge resource
+```
+
+The resource uses the `precheck_ids` to conclude which prechecks are safe to ignore for this upgrade cycle.
+The `nsxt_upgrade_precheck_acknowledge` resource requires the `target_version` from the `nsxt_upgrade_prepare` resource
+to make sure that the acknowledged warnings are from the correct execution, and to enforce execution of the
+`nsxt_upgrade_precheck_acknowledge` resource after preparation is complete.
+
+The [nsxt_upgrade_prepare_ready](../data-sources/upgrade_prepare_ready.html.markdown) data source verifies that the preparation phase of the upgrade was concluded
+successfully and enable the execution of the upgrade.
+
+```hcl
+resource "nsxt_upgrade_precheck_acknowledge" "test" {
+ precheck_ids = ["backupOperationCheck", "pUBCheck"]
+ target_version = nsxt_upgrade_prepare.prepare_res.target_version
+}
+
+data "nsxt_upgrade_prepare_ready" "ready" {
+ upgrade_prepare_id = nsxt_upgrade_prepare.prepare_res.id
+ depends_on = [nsxt_upgrade_precheck_acknowledge.test]
+}
+```
+
+### Running the upgrade
+
+In order to configure and execute upgrade of NSXT edges, hosts, and managers, use [nsxt_upgrade_run](../resources/upgrade_run.html.markdown) resource.
+
+This resource will start with configuration of upgrade unit groups and upgrade plan settings for `EDGE`and `HOST`
+components. Host component groups may be created within this resource with custom host lists and attributes, or it can
+use the predefined groups which NSX provides.
+
+Following the configuration of the edge, host groups, it will execute the upgrade for each component. If there are
+either `EDGE` or `HOST` groups excluded from the upgrade, the corresponding component will be paused after enabled
+groups get upgraded. At the same time, `MP` upgrade won't be processed, because that requires `EDGE` and `HOST` to be
+fully upgraded. Refer to the exposed attribute for current upgrade state details. For example, check `upgrade_plan`
+for current upgrade plan, which also includes the plan not specified in this resource and `state` for upgrade status of
+each component and UpgradeUnitGroups in the component. For more details, please check NSX admin guide.
+
+In the example below, host_group `HostWithDifferentSettings` will use different settings than the defaulted ones. The
+group configuration is initiated with the `nsxt_upgrade_run` while the other groups in this example are predefined and
+consumed using the data sources `nsxt_edge_upgrade_group` and `nsxt_host_upgrade_group`.
+
+**NOTE:** Only one `nsxt_upgrade_run` resource should be used in the upgrade plan.
+
+```hcl
+resource "nsxt_upgrade_run" "run" {
+ upgrade_prepare_ready_id = data.nsxt_upgrade_prepare_ready.ready.id
+
+ edge_group {
+ id = data.nsxt_edge_upgrade_group.eg1.id
+ enabled = false
+ }
+
+ edge_group {
+ id = data.nsxt_edge_upgrade_group.eg2.id
+ enabled = true
+ }
+
+ host_group {
+ id = data.nsxt_host_upgrade_group.hg1.id
+ parallel = true
+ }
+ host_group {
+ display_name = "HostWithDifferentSettings"
+ parallel = false
+ hosts = ["375c260d-3196-487c-b5eb-046de958f6af"]
+ }
+
+ host_group {
+ display_name = "OtherHostsWithDifferentSettings"
+ parallel = true
+ rebootless_upgrade = false
+ hosts = ["2fa96cdc-6b82-4284-a69a-18a21a6b6d0c", "1a59801d-6e80-401f-b2cb-ebb47f866c05"]
+ }
+
+ edge_upgrade_setting {
+ parallel = true
+ post_upgrade_check = true
+ }
+
+ host_upgrade_setting {
+ parallel = true
+ post_upgrade_check = true
+ }
+}
+```
+
+### Post upgrade checks
+
+Upgrade post check data sources can be used to examine the results of the edge and host upgrades, to cunclude if the
+upgrade has completed successfully.
+
+The example below uses Terraform `check` to test the upgrade results.
+
+```hcl
+data "nsxt_upgrade_postcheck" "pc1" {
+ upgrade_run_id = nsxt_upgrade_run.run.id
+ type = "EDGE"
+}
+
+data "nsxt_upgrade_postcheck" "pc2" {
+ upgrade_run_id = nsxt_upgrade_run.run.id
+ type = "HOST"
+}
+
+check "edge_post_check" {
+ assert {
+ condition = data.nsxt_upgrade_postcheck.pc1.failed_group == null
+ error_message = "test"
+ }
+}
+
+check "host_post_check" {
+ assert {
+ condition = data.nsxt_upgrade_postcheck.pc2.failed_group == null
+ error_message = "test"
+ }
+}
+```