Frequently asked questions

This topic provides answers to several frequently asked questions about upgrade. It includes FAQs for:

All upgrades

The following FAQs are specific to all upgrades.

Why would you rerun export?

You must rerun export if:

  • The previous attempt to run export failed (for example, because the old installation processes were not running).
  • You have made a change to the old installation that you also want to apply to the new installation.
  • You updated the configuration in the old installation to resolve a warning or error reported when you ran upgrade.
Note   If you rerun export, you must rerun all subsequent steps (upgrade and apply).

What happens if you change the old API Gateway installation after running export?

If you make any changes to the old API Gateway installation after running export and you do not need these changes to be included in the new 7.5.3 installation, you do not need to take any action.

If you do want the changes to be included in the new 7.5.3 installation, you must rerun export, possibly on all nodes, depending on the changes made. For example, if you deploy a new configuration to a group of API Gateways, you must rerun export on all nodes that run instances in that group.

Note   If you rerun export, you must rerun all subsequent steps (upgrade and apply).

If you rerun export, and therefore upgrade and apply, on the first Admin Node Manager, you have cleaned your topology, so you must rerun apply on all other nodes.

Why would you rerun upgrade?

You must rerun upgrade if:

Note   When upgrading very large configurations, the default memory settings might not be sufficient for upgrade to run successfully (see Out of memory error when running upgrade).

Why would you rerun apply?

You must rerun apply if:

Why would you run clean?

You might choose to run clean if:

  • Issues occurred during the upgrade process and you want to restart the upgrade.
  • You need to restart the upgrade to capture new changes made to the old API Gateway installation.
Note   The export --force command also triggers a full clean of the export, upgrade, and apply outputs, but in addition it also attempts to run export; while the clean command only cleans the outputs.

Single-node upgrades

The following FAQs are specific to single-node upgrades.

What happens if you rerun export when you have already run apply?

In a single-node domain, if you have previously run export successfully and try to rerun export, you are prompted to rerun with the --force option. This cleans the export, upgrade, and apply outputs, and then reruns export on the node. You must then rerun upgrade and apply on the node. The --force option is not required for upgrade or apply as the outputs have already been cleaned.

Note   Before you rerun export, you must ensure that any processes in the new 7.5.3 installation are stopped, and that the processes in the old installation are running.

What happens if you rerun upgrade when you have already run apply?

In a single-node domain, if you have previously run upgrade successfully, and try to rerun, you are prompted to rerun with the --force option. This cleans the upgrade and apply command outputs, and then reruns upgrade on the node. You must then rerun apply on the node. The --force option is not required for apply as the output has already been cleaned.

Note   The upgrade command runs offline and does not require any API Gateway processes to be running.

What happens if you rerun apply?

In a single-node domain, if you have previously run apply successfully, and try to rerun, you are prompted to rerun apply with the --force option. This cleans the apply command output, and then reruns apply on the node.

Note   If any API Gateway processes are running in the old or new installation, you are prompted to stop them before apply --force can succeed.

What happens if you run clean?

If you run clean on a single-node domain, you are back to the start of the sysupgrade process. To redo the upgrade, you must:

  1. Run export.
Note   Before you run export, you must ensure that all processes in the new 7.5.3 installation are stopped, and that all processes in the old installation are running.
  1. Run upgrade.
  2. Shut down all processes in the old installation.
  3. Run apply.

Multi-node upgrades

The following FAQs are specific to multi-node upgrades. The example topology referenced in these FAQs is as follows:

Example multi-node topology

Which is the first Admin Node Manager?

In a multi-node domain, the Admin Node Manager that has the domain CA private key file is considered the first Admin Node Manager. To determine if an Admin Node Manager is the first Admin Node Manager, check if the following file exists on the node:

apigateway/groups/certs/private/domain.p12

In the old installation, the first Admin Node Manager is always the first Node Manager created in the domain. In the new installation, the first Admin Node Manager is always the first node on which you run apply, and that node must be an Admin Node Manager in the old API Gateway domain.

Tip   The first Admin Node Manager does not have to be on the same node in the old and new API Gateway installations, but this is the simplest approach.

For example, in a three-node domain with Admin Node Managers on NodeA and NodeC (and none on NodeB), where NodeA is the first Admin Node Manager in the old installation, the first Admin Node Manager can be on NodeC in the new installation (if you run apply on NodeC first). However, the first Admin Node Manager cannot be on NodeB in the new installation, as NodeB was not an Admin Node Manager in the old installation.

What happens if you rerun export on the first Admin Node Manager and have already run apply?

In a multi-node domain, if you have previously run export successfully on the first Admin Node Manager node (for example, NodeA) and try to rerun export, you are prompted to rerun with the --force option. This cleans the export, upgrade, and apply outputs on NodeA, and then reruns export on NodeA. Running export --force on the first Admin Node Manager in a multi-node domain also cleans your topology and domain CA private key and certificate.

Note   Before you rerun export, you must ensure that all processes in the new 7.5.3 installation are stopped on all nodes, and that all processes in the old installation are running on all nodes.

After running export --force on the first Admin Node Manager (for example, NodeA) in a multi-node domain, you must perform the following steps:

  1. Rerun upgrade on NodeA.
Note   You might also need to rerun export and upgrade on other nodes. We recommend using the status command on all other nodes to ensure that all nodes are at the same stage before proceeding.
  1. Shut down all processes in the old installation on all nodes.
  2. Rerun apply on NodeA.
  3. Rerun apply on all other nodes, in any order. This step is necessary because running export --force on NodeA cleans your topology and domain CA private key and certificate.

What happens if you rerun export on a node that is not the first Admin Node Manager and have already run apply?

In a multi-node domain, if you have previously run export successfully on a node that is not the first Admin Node Manager node (for example, NodeC) and try to rerun export, you are prompted to rerun with the --force option. This cleans the export, upgrade, and apply outputs on NodeC, and then reruns export on NodeC. NodeC can be an Admin Node Manager or a Node Manager.

Note   Before you rerun export, you must ensure that all processes in the new 7.5.3 installation are stopped on all nodes, and that all processes in the old installation are running on all nodes.

After running export --force on a node that is not the first Admin Node Manager node (for example, NodeC) in a multi-node domain, you must perform the following steps:

  1. Rerun upgrade on NodeC.
  2. Shut down all processes in the old installation on all nodes.
  3. Start up the processes in the new 7.5.3 installation on other nodes, especially the Admin Node Manager on NodeA, as this must be running before you can proceed to the next step.
  4. Rerun apply on NodeC. Because you ran apply previously on NodeC, this rerun triggers removal of NodeC entries in the topology on the Admin Node Manager on NodeA, before NodeC is registered.

You do not need to rerun commands on other nodes as a result of running export --force on NodeC.

What happens if you rerun upgrade on the first Admin Node Manager and have already run apply?

In a multi-node domain, if you have previously run upgrade successfully on the first Admin Node Manager node (for example, NodeA) and try to rerun upgrade, you are prompted to rerun with the --force option. This cleans the upgrade and apply outputs on NodeA, and then reruns upgrade on NodeA. Running upgrade --force on the first Admin Node Manager in a multi-node domain also cleans your topology and domain CA private key and certificate.

Note   The upgrade command runs offline and does not require any API Gateway processes to be running.

After running upgrade --force on the first Admin Node Manager (for example, NodeA) in a multi-node domain, you must perform the following steps:

  1. Shut down all processes in the old installation on all nodes.
Note   You might also need to rerun upgrade on other nodes. We recommend using the status command on all other nodes to ensure that all nodes are at the same stage before proceeding.
  1. Rerun apply on NodeA.
  2. Rerun apply on all other nodes, in any order. This step is necessary because running upgrade --force on NodeA cleans your topology and domain CA private key and certificate.

What happens if you rerun upgrade on a node that is not the first Admin Node Manager and have already run apply?

In a multi-node domain, if you have previously run upgrade successfully on a node that is not the first Admin Node Manager node (for example, NodeC) and try to rerun upgrade, you are prompted to rerun with the --force option. This cleans the upgrade and apply outputs on NodeC, and then reruns upgrade on NodeC. NodeC can be an Admin Node Manager or a Node Manager.

Note   The upgrade command runs offline and does not require any API Gateway processes to be running.

After running upgrade --force on a node that is not the first Admin Node Manager node (for example, NodeC) in a multi-node domain, you must perform the following steps:

  1. Shut down all processes in the old installation on all nodes.
  2. Shut down all processes in the new 7.5.3 installation on NodeC (for example, any processes started by a previous apply).
  3. Start up the processes in the new 7.5.3 installation on other nodes, especially the Admin Node Manager on NodeA, as this must be running before you can proceed to the next step.
  4. Rerun apply on NodeC. Because you ran apply previously on NodeC, this rerun triggers removal of NodeC entries in the topology on the Admin Node Manager on NodeA, before NodeC is registered.

You do not need to rerun commands on other nodes as a result of running upgrade --force on NodeC.

What happens if you rerun apply on the first Admin Node Manager?

In a multi-node domain, if you have previously run apply successfully on the first Admin Node Manager node (for example, NodeA) and try to rerun apply, you are prompted to rerun with the --force option. This cleans the apply output on NodeA and then reruns apply on NodeA. Running apply --force on the first Admin Node Manager in a multi-node domain also cleans your topology and domain CA private key and certificate.

Note   If any API Gateway processes are running in the old or new installation, you are prompted to stop them before apply --force can succeed.

After running apply --force on the first Admin Node Manager (for example, NodeA) in a multi-node domain, you must perform the following steps:

  1. Leave all processes in the new 7.5.3 installation running on NodeA.
  2. Shut down all processes in the new 7.5.3 installation on all other nodes (the processes in the old installation should already be down).
  3. Rerun apply on all other nodes, in any order.

What happens if you rerun apply on a node that is not the first Admin Node Manager?

In a multi-node domain, if you have previously run apply successfully on a node that is not the first Admin Node Manager (for example, NodeC) and try to rerun apply, you are prompted to rerun with the --force option. This cleans the apply outputs on NodeC, and then reruns apply on NodeC. NodeC can be an Admin Node Manager or a Node Manager.

Note   If any API Gateway processes are running in the old or new installation, you are prompted to stop them before apply --force can succeed.

You do not need to rerun commands on other nodes as a result of running apply --force on NodeC.

What happens if you run clean on the first Admin Node Manager?

In a multi-node domain, if you run clean successfully on the first Admin Node Manager (for example, NodeA), this cleans the export, upgrade, and apply outputs on NodeA. It also cleans your topology and domain CA private key and certificate.

To redo the upgrade on NodeA, you must perform the following:

  1. Run export on NodeA.
Note   Before you run export, you must ensure that all processes in the new 7.5.3 installation are stopped on all nodes, and that all processes in the old installation are running on all nodes.
  1. Run upgrade on NodeA.
Note   You might also need to rerun export and upgrade on other nodes. We recommend using the status command on all other nodes to ensure that all nodes are at the same stage before proceeding.
  1. Shut down all processes in the old installation on all nodes.
  2. Run apply on NodeA.
  3. Run apply on all other nodes, in any order. This step is necessary because running clean on NodeA cleans your topology and domain CA private key and certificate.

What happens if you run clean on a node that is not the first Admin Node Manager?

In a multi-node domain, if you run clean successfully on a node that is not the first Admin Node Manager (for example, NodeC), this cleans the export, upgrade, and apply outputs on NodeC. Your topology and domain CA private key and certificate still exist on another Admin Node Manager node (for example, NodeA).

To redo the upgrade on the node you have cleaned, you must perform the following steps:

  1. Run export on NodeC.
Note   Before you run export, you must ensure that all processes in the new 7.5.3 installation are stopped on all nodes, and that all processes in the old installation are running on all nodes.
  1. Run upgrade on NodeC.
  2. Shut down all processes in the old installation on all nodes.
  3. Start up the processes in the new 7.5.3 installation on other nodes, especially the Admin Node Manager on NodeA, as this must be running before you can proceed to the next step.
  4. Run apply on NodeC. If you ran apply previously on NodeC, this rerun triggers removal of NodeC entries in the topology on the Admin Node Manager on NodeA, before NodeC is registered.

You do not need to rerun commands on other nodes as a result of running clean on NodeC.

API Gateway Analytics upgrades

The following FAQs are specific to API Gateway Analytics upgrades.

What should you upgrade first - your 7.5.3 API Gateway domain or your API Gateway Analytics server?

This depends on the version of API Gateway Analytics you are upgrading from:

  • If you are upgrading from 7.4.0 and later versions, we recommend that you upgrade API Gateway Analytics before upgrading API Gateway using the sysupgrade command.
  • If you are upgrading from versions earlier than 7.4.0, we recommend that you upgrade API Gateway Analytics after upgrading API Gateway using the sysupgrade command.

For more information, see Upgrade API Gateway Analytics.

Do you need to run managedomain to enable metrics?

If you are upgrading from a pre-7.4.0 API Gateway domain, you must run managedomain to enable metrics. You must run managedomain for each Node Manager in the domain to enable metrics. You must then restart each Node Manager.

If you are upgrading from a 7.4.0 or later API Gateway domain where the Node Managers are configured to write to the database, you do not need to run managedomain for each Node Manager as the configuration is migrated when the API Gateways are upgraded.

For more information, see Step 9 – Enable metrics using managedomain.

Related Links