From dd154f4306160c24fa766884ef45968e4144dbb0 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 --- .../data_source_nsxt_upgrade_prepare_ready.go | 32 ++- .../docs/guides/multitenancy.html.markdown | 2 +- website/docs/guides/upgrade.html.markdown | 200 ++++++++++++++++++ website/docs/r/upgrade_prepare.html.markdown | 2 +- 4 files changed, 232 insertions(+), 4 deletions(-) create mode 100644 website/docs/guides/upgrade.html.markdown diff --git a/nsxt/data_source_nsxt_upgrade_prepare_ready.go b/nsxt/data_source_nsxt_upgrade_prepare_ready.go index 795fdadbc..05744fd31 100644 --- a/nsxt/data_source_nsxt_upgrade_prepare_ready.go +++ b/nsxt/data_source_nsxt_upgrade_prepare_ready.go @@ -8,6 +8,8 @@ import ( "github.com/hashicorp/terraform-plugin-sdk/v2/helper/schema" nsxModel "github.com/vmware/vsphere-automation-sdk-go/services/nsxt-mp/nsx/model" + "github.com/vmware/vsphere-automation-sdk-go/services/nsxt-mp/nsx/upgrade" + "golang.org/x/exp/slices" ) func dataSourceNsxtUpgradePrepareReady() *schema.Resource { @@ -25,6 +27,24 @@ func dataSourceNsxtUpgradePrepareReady() *schema.Resource { } } +func getPrechecksText(m interface{}, precheckIDs []string) (string, error) { + precheckText := "" + connector := getPolicyConnector(m) + client := upgrade.NewUpgradeChecksInfoClient(connector) + checkInfoResults, err := client.List(nil, nil, nil, nil, nil, nil) + if err != nil { + return "", err + } + for _, checkInfo := range checkInfoResults.Results { + for _, ci := range checkInfo.PreUpgradeChecksInfo { + if slices.Contains(precheckIDs, *ci.Id) { + precheckText += fmt.Sprintf(" Component: %s, code: %s, description: %s\n", *checkInfo.ComponentType, *ci.Id, *ci.Description) + } + } + } + return precheckText, nil +} + func dataSourceNsxtUpgradePrepareReadyRead(d *schema.ResourceData, m interface{}) error { precheckErrors, err := getPrecheckErrors(m, nil) if err != nil { @@ -44,10 +64,18 @@ func dataSourceNsxtUpgradePrepareReadyRead(d *schema.ResourceData, m interface{} } var errMessage string if len(precheckFailureIDs) > 0 { - errMessage += fmt.Sprintf("There are failures in precheck: %s, please check their status from nsxt_upgrade_prepare resource and address these failures on NSX", precheckFailureIDs) + preCheckText, err := getPrechecksText(m, precheckFailureIDs) + if err != nil { + errMessage += fmt.Sprintf("Error while reading precheck failures text: %v", err) + } + errMessage += fmt.Sprintf("There are failures in prechecks:\n%s\nPlease check their status from nsxt_upgrade_prepare resource and address these failures on NSX", preCheckText) } if len(unacknowledgedWarningIDs) > 0 { - errMessage += fmt.Sprintf("\nThere are unacknowledged warnings in precheck: %s, please address these errors from NSX or using nsxt_upgrade_precheck_acknowledge resource", unacknowledgedWarningIDs) + preCheckText, err := getPrechecksText(m, unacknowledgedWarningIDs) + if err != nil { + errMessage += fmt.Sprintf("Error while reading precheck failures text: %v", err) + } + errMessage += fmt.Sprintf("\nThere are unacknowledged warnings in prechecks:\n%s\nPlease address these errors from NSX or using nsxt_upgrade_precheck_acknowledge resource", preCheckText) } if len(errMessage) > 0 { return fmt.Errorf(errMessage) 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..387d76fa9 --- /dev/null +++ b/website/docs/guides/upgrade.html.markdown @@ -0,0 +1,200 @@ +--- +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. + +### Checking the readiness for upgrade + +When preparation is complete, it is required to validate the readiness for upgrade using the +[nsxt_upgrade_prepare_ready](../data-sources/upgrade_prepare_ready.html.markdown) data source. +When NSX preparation results with failures or warnings, the data source will fail the upgrade. +Warnings should be acknowledged as described below. + +For example: +``` +Error: +There are unacknowledged warnings in prechecks: + Component: EDGE, code: pUBCheck, description: Checks if new version of pub available on VMware Download site. + Component: MP, code: backupOperationCheck, description: Warns if backup is not taken recently and blocks management plane upgrade if backup is in progress + +Please address these errors from NSX or using nsxt_upgrade_precheck_acknowledge resource +``` + +Prechecks which are in `failure' or in warning state can also be obtained from the `nsxt_upgrade_prepare` resource, +using its `failed_prechecks` attribute. + +### Acknowledgement of upgrade issues and warnings + +The execution of `nsxt_upgrade_prepare` and `nsxt_upgrade_prepare_ready` could result with various warnings which would +halt the upgrade process. However, warnings can be suppressed with the [nsxt_upgrade_precheck_acknowledge](../resources/upgrade_precheck_acknowledge.html.markdown) 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 source verifies that the preparation phase of the upgrade was concluded successfully +and enable the execution of the upgrade. In case that there are still open issues, these will raise as described above. + +```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. + +The order of the groups within the `nsxt_upgrade_run` resource defined the order of the upgrade execution. + +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 + } + + data "nsxt_policy_host_transport_node" "host_transport_node1" { + display_name = "host_transport_node1" + } + + host_group { + display_name = "HostWithDifferentSettings" + parallel = false + hosts = [data.nsxt_policy_host_transport_node.host_transport_node1.id] + } + + data "nsxt_policy_host_transport_node" "host_transport_node2" { + display_name = "host_transport_node2" + } + + data "nsxt_policy_host_transport_node" "host_transport_node3" { + display_name = "host_transport_node3" + } + + host_group { + display_name = "OtherHostsWithDifferentSettings" + parallel = true + rebootless_upgrade = false + hosts = [ + data.nsxt_policy_host_transport_node.host_transport_node2.id, + data.nsxt_policy_host_transport_node.host_transport_node3.id] + } + + 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 = "Edge group upgrade check failed" + } +} + +check "host_post_check" { + assert { + condition = data.nsxt_upgrade_postcheck.pc2.failed_group == null + error_message = "Host group upgrade check failed" + } +} +``` diff --git a/website/docs/r/upgrade_prepare.html.markdown b/website/docs/r/upgrade_prepare.html.markdown index be9c4ca5d..dc27cf4a2 100644 --- a/website/docs/r/upgrade_prepare.html.markdown +++ b/website/docs/r/upgrade_prepare.html.markdown @@ -49,7 +49,7 @@ In addition to arguments listed above, the following attributes are exported: * `failed_prechecks` - (Computed) Failed prechecks from running pre-upgrade check. * `id` - ID of the failed precheck. * `message` - Message of the failed precheck. - * `type` - Type of the failed precheck, possible values are `warning` and `failure`. + * `type` - Type of the failed precheck, possible values are `WARNING` and `FAILURE`. * `needs_ack` - Boolean value which identifies if acknowledgement is required for the precheck. * `needs_resolve` - Boolean value identifies if resolution is required for the precheck. * `acked` - Boolean value which identifies if precheck has been acknowledged.