Frequently asked questions
14 minute read
All upgrades
The following FAQs are specific to all upgrades.
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.7 installation, you do not need to take any action.
If you do want the changes to be included in the new 7.7 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 rerunexport
, 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:
- You have rerun
export
. - The previous attempt to run
upgrade
failed with errors.
Note
When upgrading very large configurations, the default memory settings might not be sufficient forupgrade
to run successfully. See Out of memory error when running upgrade.
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 rerunexport
, you must rerun all subsequent steps (upgrade
and apply
).
How to increase timeouts for apply
Increasing the timeout for node managers to prevent errors being returned when you run the apply command during an upgrade.
-
Stop all 7.7
vshell
processes. -
Back up previous 7.7 upgrade directories:
mv apigateway/upgrade_backup apigateway/upgrade_backup.old mv apigateway/upgrade/bin/out apigateway/upgrade/bin/out.old
-
Reset topology if it’s not already clean:
./managedomain --reset --username admin --password changeme
-
Amend the following templates configurations with the desired value for
maxTransTimeout
inPrimaryStore.xml
before runningsysupgrade
steps on each node/host.- Node Manager:
apigateway/system/conf/templates/
- Node Manager:
apigateway/system/conf/templates/VordelNodeManager/
- API Gateway:
apigateway/system/conf/templates/FactoryConfiguration-VordelGateway.fed
- API Gateway:
apigateway/system/conf/templates/FactoryConfiguration-VordelGateway/
Note
On Linux systems, you can install the unzip package, which is very useful to check timeouts in
.fed
archive files. For example,zipgrep maxTransTimeout FactoryConfiguration-VordelGateway.fed
- Node Manager:
-
Run the export command on all nodes.
-
Amend
maxTransTimeout
to the desired value in the exported configurationPrimaryStore.xml
:- Node Manager:
apigateway/upgrade/bin/out/export/esnm/conf/fed/
. For Admin Node Managers, it might be require to apply factor based on the maximum number of instances in a group. - API Gateway:
apigateway/upgrade/bin/out/export/esgroups/groups/group-2/f5304aa6-a0f5-4643-88b7-8cef992924e4/
. Group and configuration IDs will vary. - API Gateway:
apigateway/upgrade/bin/out/export/esgroups/groups/group-2/f5304aa6-a0f5-4643-88b7-8cef992924e4.fed
. Group and configuration IDs will vary.
- Node Manager:
-
If topology has multiple Admin node managers, run the apply step for the Admin node manager nodes first.
Why would you rerun apply
?
You must rerun apply
if:
- You have rerun
export
orupgrade
. - The previous attempt to run
apply
failed with errors (for example, if you specified the wrong--anm_host
parameter).
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
Theexport --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 rerunexport
, you must ensure that any processes in the new 7.7 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
Theupgrade
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 beforeapply --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:
- Run
export
. Before you runexport
, you must ensure that all processes in the new 7.7 installation are stopped, and that all processes in the old installation are running. - Run
upgrade
. - Shut down all processes in the old installation.
- Run
apply
.
Multi-node upgrades
The following FAQs are specific to multi-node upgrades. The example topology referenced in these FAQs is as follows:
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 runapply
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 rerunexport
, you must ensure that all processes in the new 7.7 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:
- Rerun
upgrade
on NodeA. You might also need to rerunexport
andupgrade
on other nodes. We recommend using thestatus
command on all other nodes to ensure that all nodes are at the same stage before proceeding. - Shut down all processes in the old installation on all nodes.
- Rerun
apply
on NodeA. - Rerun
apply
on all other nodes, in any order. This step is necessary because runningexport --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 rerunexport
, you must ensure that all processes in the new 7.7 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:
- Rerun
upgrade
on NodeC. - Shut down all processes in the old installation on all nodes.
- Start up the processes in the new 7.7 installation on other nodes, especially the Admin Node Manager on NodeA, as this must be running before you can proceed to the next step.
- Rerun
apply
on NodeC. Because you ranapply
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
Theupgrade
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:
- Shut down all processes in the old installation on all nodes. You might also need to rerun
upgrade
on other nodes. We recommend using thestatus
command on all other nodes to ensure that all nodes are at the same stage before proceeding. - Rerun
apply
on NodeA. - Rerun
apply
on all other nodes, in any order. This step is necessary because runningupgrade --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
Theupgrade
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:
- Shut down all processes in the old installation on all nodes.
- Shut down all processes in the new 7.7 installation on NodeC (for example, any processes started by a previous
apply
). - Start up the processes in the new 7.7 installation on other nodes, especially the Admin Node Manager on NodeA, as this must be running before you can proceed to the next step.
- Rerun
apply
on NodeC. Because you ranapply
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 beforeapply --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:
- Leave all processes in the new 7.7 installation running on NodeA.
- Shut down all processes in the new 7.7 installation on all other nodes (the processes in the old installation should already be down).
- 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 beforeapply --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:
- Run
export
on NodeA. Before you runexport
, you must ensure that all processes in the new 7.7 installation are stopped on all nodes, and that all processes in the old installation are running on all nodes. - Run
upgrade
on NodeA. You might also need to rerunexport
andupgrade
on other nodes. We recommend using thestatus
command on all other nodes to ensure that all nodes are at the same stage before proceeding. - Shut down all processes in the old installation on all nodes.
- Run
apply
on NodeA. - Run
apply
on all other nodes, in any order. This step is necessary because runningclean
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:
- Run
export
on NodeC. Before you runexport
, you must ensure that all processes in the new 7.7 installation are stopped on all nodes, and that all processes in the old installation are running on all nodes. - Run
upgrade
on NodeC. - Shut down all processes in the old installation on all nodes.
- Start up the processes in the new 7.7 installation on other nodes, especially the Admin Node Manager on NodeA, as this must be running before you can proceed to the next step.
- Run
apply
on NodeC. If you ranapply
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 and metrics database upgrades
The following FAQs are specific to upgrading API Gateway Analytics and your metrics database.
What should you upgrade first - API Gateway or API Gateway Analytics?
If you are upgrading from 7.4.0 and later versions, you should upgrade API Gateway Analytics before upgrading API Gateway using the sysupgrade
command.
Do you need to run managedomain
to enable metrics?
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. This is because the configuration is migrated when the API Gateways are upgraded.