Upgrade MATRIXX Engine and Traffic Routing Agent

MATRIXX Engine and engine-level Traffic Routing Agents (TRA-PROCs and TRA-PUBs) can be updated once all MATRIXX gateways and web apps have been updated and are running pinned to the pre-upgrade version.

Before you begin

When upgrading MATRIXX installations with CCF enabled, NEs must be upgraded before engines, TRA-PROCs, and TRA-PUBs are upgraded.

About this task

This procedure updates the engine and engine-level TRA components for a standby engine in a matrixx-s1e2 namespace.

Procedure

Stop the standby engine, delete MtxEngine custom resource (CR), and delete the engine-operator deployment with commands similar to the following:
```
stop_engine -s 1 -e 2 --namespace matrix-s1e2
kubectl delete mtxengine engine-s1e2 --namespace matrixx-s1e2
kubectl delete deploy engine-operator
```
Examine the configuration of the pre-upgrade version and edit matrixx-s1e2_values.yaml to add any new parameters introduced in the upgrade version.
Make any other necessary changes to the configuration files in your configuration source image, rebuild the image, and upload it to your image repository.
For more information, see the discussion about applying engine configuration changes in MATRIXX Configuration.
Specify the new versions of the images with global.topology properties in matrixx-s1e2_values.yaml to apply updated configuration.

Upgrade the engines, TRA-PROCs, and TRA-PUBs with the following command:

helm upgrade ag1 matrixx/matrixx --namespace matrixx-s1e2 -f matrixx-s1e2_values.yaml --version matrixx_version

If this is the first engine in the chain to be upgraded, and this is an upgrade to a new release (rather than a maintenance or configuration upgrade), load pricing data with the following steps:
1. Wait for the engine to reach PRE_INIT state.
2. Copy the pricing file to shared storage accessible by an engine processing pod.
3. On the processing pod, load pricing using the load_pricing.py command:
```
kubectl exec -it pod_name --namespace matrixx-s1e2 – /bin/bash -c "load_pricing.py -f /path/pricing_file_name --local"
```
4. If US taxation is enabled, load the tax data on the processing pod using the load_tax.py command:
```
kubectl exec -it pod_name --namespace matrixx-s1e2 – /bin/bash -c "load_tax.py -f /path/tax_file_name --local"
```
When the engine reaches the STANDBY state a new checkpoint is generated. Run validateCheckpoint.jar in on the pod to detect any errors in the database checkpoint with the following command:
```
kubectl exec -it pod_name --namespace matrixx-s1e2 – /bin/bash -c "java -Dconfig=/opt/mtx/conf/mtx_config.xml -jar /opt/mtx/bin/validateCheckpoint.jar checkpoint_folder"
```
Where pod_name is the name of the pod, such as ckpt-s2e4-0, and checkpoint_folder is the folder containing the database checkpoint. For example:
```
kubectl exec -it ckpt-s2e4-0 --namespace matrixx-s1e2 – /bin/bash -c "java -Dconfig=/opt/mtx/conf/mtx_config.xml -jar /opt/mtx/bin/validateCheckpoint.jar /shared/checkpoints/mtx_ckpt_v5241.15.1658853220"
```
Retrieve the output from validateCheckpoint.jar from the /home/mtx directory on the pod with the following command:
```
kubectl cp matrixx-s1e2/pod_name:/home/mtx/validation_log_name destination_filename
```
Where validation_log_name is the name of the validateCheckpoint.jar output file, and destination_filename is the destination path and filename outside of the pod. For example (line break added for readability):
```
kubectl cp matrixx-ns2/ckpt-s2e4-0:/home/mtx/validateCheckpoint_20220726_174359.log \
/home/mtx/validateCheckpoint_20220726_174359.log
```
Note: The validateCheckpoint.jar program produces warnings that TriggerTime and NextMaintenanceTime values are overdue for each subscriber or group in the database. These artifacts of the upgrade process can be ignored.
The kubectl cp command might have the following output:
```
tar: Removing leading `/' from member names
```
This can be ignored. The file is copied normally.
For more information about validateCheckpoint.jar, see the discussion about validateCheckpoint.jar in MATRIXX Administration.
Resolve any errors before upgrading other engines.

What to do next

Repeat these steps for the matrixx-s1e1 namespace.