The upgrade/migrate check validates a host against the prerequisites for a target Cloud Exchange version before you install, upgrade, or migrate. The check is read-only. Nothing on the host is changed.
You run the check from the command line with the ce_healthcheck script. It prints a result for each prerequisite and ends with an overall verdict.
Cloud Exchange v7.0.0 and later can also run the check from the UI. For details, refer to General Settings. Use the command line for versions prior to 7.0.0, or on a host where Cloud Exchange is not installed yet.
Prerequisites
- Root access on the host. The check must run with
sudo. - Python 3.6 or later on the host.
- Outbound HTTPS access from the host to
raw.githubusercontent.com/netskopeoss/ta_cloud_exchange, to download the script and the check definitions.
Download the Upgrade/Migrate Check Script
Download the script and the check definitions to the Cloud Exchange installation directory.
- Go to the Cloud Exchange installation directory:
- Containerized Deployment: The
ta_cloud_exchangedirectory that has thedocker-compose.ymlfile. - Cloud Exchange as a VM: The
/opt/cloudexchange/cloudexchangedirectory.
- Containerized Deployment: The
- Run these commands to download the script and the check definitions, and to make the script executable:
curl -fsSL -O https://raw.githubusercontent.com/netskopeoss/ta_cloud_exchange/main/ce_healthcheck chmod +x ce_healthcheck
Run the upgrade/migrate check from the installation directory. The check detects the deployment type and the installed version from the files in that directory.
Run the Upgrade/Migrate Check
The check detects the run context, the deployment type, and the installed version from the host, and prints them before it runs the checks. Nothing is prompted for. You can override any detected value with the options listed in Options.
Standalone Deployment
- In the installation directory, run this command:
sudo python3 ./ce_healthcheck
- Review the result of each check on the screen. The check also saves a detailed report as
ce_healthcheck_report.jsonin the current folder. - Read the summary and the overall verdict at the end of the output. For details, refer to Understand the Results.
If you do not specify a version, the check validates the host against the latest Cloud Exchange version that the check definitions cover. To validate against a specific version, add the --target-version option. For example:
sudo python3 ./ce_healthcheck --target-version 7.0.0
HA Deployment
Run the check on every node of the cluster. Each node reports its own results, including whether that node can reach the other nodes on the HA ports.
- On the first node, go to the installation directory and run the command that matches the state of the node:
- Existing HA cluster: Run
sudo python3 ./ce_healthcheck. The check detects the HA deployment. - Nodes you have not set up yet: Run
sudo python3 ./ce_healthcheck --deployment HA. A node that has no HA configuration cannot be detected as HA, so you set the deployment type yourself.
- Existing HA cluster: Run
- Review the results on the screen, and fix any failed item.
- Repeat these steps on every other node of the cluster.
On a node that has no HA configuration yet, the check cannot test the connection to the other nodes, so the HA peer node connectivity check shows Not applicable. After you set up the cluster, run the check again on every node.
Options
The check accepts these options:
| Option | Description |
|---|---|
--deployment SA|HA | Set the deployment type instead of detecting it. |
--target-version <version> | Set the Cloud Exchange version to validate against. |
--mode install|upgrade|migrate | Set the run context instead of detecting it. The migrate context runs the same checks as install. |
--list-versions | List the Cloud Exchange versions that can be selected. |
--html <path> | Save a shareable HTML report. |
--report <path> | Save the detailed JSON report to a specific location. |
--manifest-path <path> | Use a local file for the check definitions instead of downloading them. |
--json | Print the full report on the screen in JSON format instead of the results. |
--quiet | Suppress the detected-value notes. |
Sample Commands
Run these commands in the Cloud Exchange installation directory. Replace 7.0.0 with the Cloud Exchange version that you want to validate against.
| Use Case | Command |
|---|---|
| Check a host before you install Cloud Exchange as a standalone deployment. | sudo python3 ./ce_healthcheck --mode install --deployment SA --target-version 7.0.0 |
| Check a host before you install it as a node of an HA cluster. | sudo python3 ./ce_healthcheck --mode install --deployment HA --target-version 7.0.0 |
| Check an existing deployment before you upgrade it. | sudo python3 ./ce_healthcheck --mode upgrade --target-version 7.0.0 |
| Check the new machine before you migrate to it. | sudo python3 ./ce_healthcheck --mode migrate --target-version 7.0.0 |
| Check an existing host against the version that is installed on it. | sudo python3 ./ce_healthcheck --target-version <installed_version> |
| See which Cloud Exchange versions the check covers. | ./ce_healthcheck --list-versions |
| Save a shareable HTML report and the JSON report in a location that you choose. | sudo python3 ./ce_healthcheck --html ./ce_healthcheck_report.html --report ./ce_healthcheck_report.json |
| Run the check from a script, and read the full report in JSON format. | sudo python3 ./ce_healthcheck --json --quiet |
| Run the check on a host that reaches the internet through a proxy. | sudo HTTPS_PROXY=http://<proxy_host>:<proxy_port> python3 ./ce_healthcheck |
When to Run the Upgrade/Migrate Check
- Before you install, upgrade, or migrate a deployment, and again after you have addressed any reported item.
- After a change to the host, such as resizing the machine, adding disk, or a change to firewall or proxy rules.
- Before you open a support case about a failed install or upgrade, so that Netskope Support can see the state of the host.
Understand the Results
Every check reports one of five results.
| Result | Meaning | What to Do |
|---|---|---|
| Pass | The host meets this requirement. | No action required. |
| Warning | The requirement is met, but something needs your attention. For example, a value is below the recommended level rather than below the required minimum, or a required port is already in use by the Cloud Exchange service that is meant to own it. | Review the item and the corrective measure shown with it. A warning does not block an upgrade. |
| Failed | The host does not meet a mandatory requirement. The install or upgrade is expected to fail, or to leave the deployment in a poor state. | Fix the item using the corrective measure shown with it, then run the check again. |
| Not applicable | The check does not apply to this host, such as the HA cluster checks on a standalone deployment, or the Podman checks on a host that runs Docker. | No action required. |
| Not verified | The check could not be completed on this host, so the requirement is neither confirmed nor ruled out. For example, a version could not be read, or a command could not be run. | Review the reason listed with the item. Treat it as unconfirmed, not as a pass. |
The check ends with a count of each result, followed by an overall verdict.
| Verdict | Meaning |
|---|---|
| This host meets the prerequisites for Cloud Exchange version. | Every applicable check passed. You can proceed. |
| This host meets the mandatory prerequisites for Cloud Exchange version. Review the warnings above before proceeding. | Nothing mandatory failed, but some items need your attention. |
| Verified n of total checks for Cloud Exchange version; n could not be verified. No mandatory prerequisite failed. Review the items above before proceeding. | Nothing mandatory failed, but part of the host was not assessed. Review the unverified items before proceeding. |
| One or more prerequisite checks have failed. Please ensure the minimum system requirements are met to proceed further. | Do not proceed. Address every failed item and run the check again. |
| None of the prerequisite checks for Cloud Exchange version could be verified on this host. This is not a pass. | Nothing was actually assessed. Run the check again after the conditions needed to perform it are in place. |
The check exits with code 0 when no check failed, and with code 1 when at least one check failed. It exits with code 2 when it could not run.
When you run the check from the UI on an HA deployment, nodes that could not be reached are called out separately and are not included in the totals.
Reports
- JSON report: A detailed record of the run, including the measured values collected from the host. The check saves it as
ce_healthcheck_report.jsonin the current folder after every run. Use the--reportoption to save it in another location. Attach this report to a support case. - HTML report: A readable summary of the run that opens in any browser, listing every check, its result, and its corrective measure. The check saves it only when you use the
--htmloption. Use this report to share results with your team.
Both reports include details about the host, and only the root user can read them. Use sudo to open or copy a report. Store and share the reports with the same care as any other system record.
If the Check Cannot Run
| Message | What to Do |
|---|---|
| This check must run as root, the same way setup does. | Run the check again with sudo. |
| Could not download the upgrade/migrate check definitions from url. | The host has no outbound internet access, or a proxy or firewall blocks it. Allow access to raw.githubusercontent.com/netskopeoss/ta_cloud_exchange, and then run the check again. |
| Cloud Exchange version version does not exist in these check definitions, so this host was not validated. | Select a version that is covered. Run ./ce_healthcheck --list-versions to see which versions are available. |
| Could not read the upgrade/migrate check definitions from path. | Make sure that the path you gave to --manifest-path exists and that you can read the file. |