Skip to content

Commit

Permalink
Merge pull request #1229 from ksamoray/upgrade_doc
Browse files Browse the repository at this point in the history
Upgrade guide document
  • Loading branch information
ksamoray authored Jul 11, 2024
2 parents 1cdc366 + dd154f4 commit f1556b6
Show file tree
Hide file tree
Showing 4 changed files with 232 additions and 4 deletions.
32 changes: 30 additions & 2 deletions nsxt/data_source_nsxt_upgrade_prepare_ready.go
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand All @@ -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 {
Expand All @@ -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)
Expand Down
2 changes: 1 addition & 1 deletion website/docs/guides/multitenancy.html.markdown
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
200 changes: 200 additions & 0 deletions website/docs/guides/upgrade.html.markdown
Original file line number Diff line number Diff line change
@@ -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"
}
}
```
2 changes: 1 addition & 1 deletion website/docs/r/upgrade_prepare.html.markdown
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down

0 comments on commit f1556b6

Please sign in to comment.