From f11aef0f2ecdc9b2cb937142249ea430ac543453 Mon Sep 17 00:00:00 2001 From: Kobi Samoray Date: Sun, 12 May 2024 14:53:01 +0300 Subject: [PATCH] Upgrade guide document Add a document describing the upgrade process. Signed-off-by: Kobi Samoray --- .../docs/guides/multitenancy.html.markdown | 2 +- website/docs/guides/upgrade.html.markdown | 168 ++++++++++++++++++ 2 files changed, 169 insertions(+), 1 deletion(-) create mode 100644 website/docs/guides/upgrade.html.markdown 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" + } +} +```