Home
MATRIXX Installation and Upgrade
Upgrading Engine Operator-Based MATRIXX Installations
Upgrading cloud native MATRIXX has several stages.
Performing Ancillary Upgrade Tasks
Ancillary upgrade tasks are not mandatory and do not apply to all MATRIXX installations.
Upgrade a Standalone Engine
Use this procedure to manually upgrade a single engine system to the latest release of MATRIXX in a cloud environment.

Welcome
MATRIXX Release Notes
MATRIXX Architecture
MATRIXX Installation and Upgrade
- About MATRIXX Installation and Upgrade
  MATRIXX Installation and Upgrade describes the tasks required to install MATRIXX components as containers using Kubernetes and Helm.
- Cloud Native Infrastructure Requirements
  Cloud native MATRIXX deployments have infrastructure requirements for third-party software versions, Kubernetes pod characteristics, and container characteristics. Nodes running MATRIXX components have operating system, memory, networking, and storage requirements.
- Topology Operator and Engine Operator Feature Differences
  Different MATRIXX features are supported depending on whether your installation is based on Topology Operator or Engine Operator.
- Installing MATRIXX
  A cloud native MATRIXX installation consists of containers installed with the MATRIXX Helm chart in a multi-node Kubernetes cluster (or clusters), requiring MATRIXX images and MATRIXX Engine custom resource definitions and controllers.
- Topology Operator Installation and Upgrade Examples
  These examples show how you can configure the installation of multiple MATRIXX Engines in a single namespace, multiple namespaces in a single cluster, and multiple clusters.
- Configuring MATRIXX
  MATRIXX is configured using Helm properties. Questions and answers in create_config.info files can also provide configuration using configuration sources. For information about how to configure MATRIXX, see the discussions of those topics in MATRIXX Configuration.
- Topology Operator
  The Topology Operator method of MATRIXX Engine pod management utilizes multiple custom resources (CRs) and operator pods working together to manage the installation and upgrade of multiple sub-domains and engines across Kubernetes clusters, including the loading of pricing and taxation data.
- Scaling MATRIXX
  Use Helm and Kubernetes to manually add or remove pods as necessary. You can also use Kubernetes to manage resources available to MATRIXX Engine pods.
- Network Enablers in a Kubernetes Cluster
  For Call Control Framework (CCF), only the deployment of Network Enablers (NEs) in a Kubernetes cluster is different from a standard deployment.
- Deploying Cloud Native CAMEL Gateway
  When deploying CAMEL Gateway as part of the reference architecture, you can use any namespace within the Kubernetes clusters. You can make multiple deployments into multiple namespaces, for example, to have different environments for testing and production.
- Enabling MEF Publishing
  An SSH key, used for password-less SSH login, is required to enable _glossary/mef.html publishing in Kubernetes. A secret holds the SSH private key, and the key is specified in Helm values. The SSH key allows administrators to write to a target directory in a secure manner without having to enter a passphrase.
- Encrypted Interface Engine Replay Overview
  Transport-layer security (TLS) encryption can be enabled for replay between processing and publishing pods and between engines.
- MATRIXX Reference for MongoDB
  Cloud native MATRIXX deployments support MongoDB as an event store using the MongoDB Enterprise Operator for Kubernetes.
- MATRIXX Reference for Apache Kafka
  The Event Streaming Framework provides a connector for sending event stream data to Apache Kafka. Using 5G event streaming also requires Apache Kafka, which is not provided with MATRIXX. You can use a Helm chart to install and configure Apache Kafka.
- MATRIXX Reference for Ingress
  A Kubernetes Ingress exposes HTTP and HTTPS routes from outside the cluster to services within the cluster.
- Debugging and Failure Recovery
  MATRIXX components store log files in persistent storage on the node by default, in a persistent volume (PV) at the location specified in global.storage.localStorageDir property (/home/data by default).
- Upgrading Engine Operator-Based MATRIXX Installations
  Upgrading cloud native MATRIXX has several stages.
  - Upgrading Multi-Site Installations
    Upgrading a multi-site installation involves performing the upgrade steps for each site.
  - Upgrade Prerequisites and Testing Requirements
    The upgrade procedure assumes that you are upgrading a functioning MATRIXX implementation and have completed all the installation prerequisites.
  - Upgrading SBA Gateway
    When upgrading to a new version of SBA Gateway, there are several things you must consider to ensure the upgrade is successful and the correct configuration is applied.
  - Upgrading RS Gateway Extensions
    This is an overview of common situations during RS Gateway extension upgrade due to upgraded Spring Boot versions in MATRIXX version 5280. For specific information about upgrade impacts to your extensions, see the third-party migration documentation.
  - Upgrading Notification Framework Extensions
    This is an overview of common situations during Notification Framework extension upgrade due to upgraded Spring Boot and Apache Camel versions in MATRIXX version 5280. For specific information about upgrade impacts to your extensions, see the third-party migration documentation.
  - Validate Database Checkpoints
    Before upgrading, run the validateCheckpoint.jar program on all MATRIXX Engine pods. The validateCheckpoint.jar program analyzes a MATRIXX checkpoint, detects any errors in the database, and produces a validation report listing internal database statistics and any errors found.
  - Upgrade MATRIXX Gateways and Web Apps
    To upgrade MATRIXX gateways and web apps, adjust settings in matrixx-webapps-gateways_values.yaml to restrict other components and schemas to their pre-upgrade versions, and specify new configuration source image versions to apply updated configuration.
  - Engine Upgrade Order
    In general, MATRIXX Support recommends that you start by upgrading the MATRIXX Engine at the end of your engine chain.
  - 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.
  - Upgrade Site-Level Traffic Routing Agents (TRA-RT/DR)
    After upgrading MATRIXX gateways and web apps, MATRIXX Engine, and engine-level Traffic Routing Agents (TRA-PROCs and TRA-PUBs), upgrade the site-level Traffic Routing Agent (TRA-RT/DR) high availability (HA) pair in the matrixx-tra namespace.
  - Un-Pin the Service Provider Schema Version
    To remove schema version pinning from all MATRIXX gateways and web apps, remove the configuration values that were applied at the start of the upgrade process.
  - Performing Ancillary Upgrade Tasks
    Ancillary upgrade tasks are not mandatory and do not apply to all MATRIXX installations.
    - Upgrade a Standalone Engine
      Use this procedure to manually upgrade a single engine system to the latest release of MATRIXX in a cloud environment.
      - start_single_engine_offline_upgrade.py
        The start_single_engine_offline_upgrade.py script upgrades a single engine deployment to the latest release of MATRIXX.
    - Single-Namespace Upgrade Considerations
      When upgrading more than one MATRIXX component installed in a single namespace, where installed components include MATRIXX Engines and site-level Traffic Routing Agents (TRAs), use versionOverride properties to keep engines and TRAs at pre-upgrade versions until you are ready to upgrade those components.
  - MATRIXX Deployment CI/CD Pipeline
    MATRIXX provides a continuous integration and continuous delivery (CI/CD) pipeline that updates the parameters used to perform installation and upgrade tasks. This pipeline is split into the following repositories:
- Migrating to Topology Operator
  This example shows migration from a MATRIXX version XXXX deployment managed by Engine Operator to a deployment managed by Topology Operator. The same approach applies when migrating from Engine Controller.
- Migration from a Bare Metal to a Cloud Native Deployment
  Migrating from a bare metal MATRIXX deployment to a cloud native deployment (from the same MATRIXX version) requires temporarily using a hybrid platform made up of components from both deployments. This hybrid environment allows migration to the cloud native deployment without disruption of services.
- The Admin Service
  Operations teams can use the Admin Service to administer a MATRIXX deployment with domain-specific commands based on the components that are installed. It allows administration of the installation without providing unrestricted direct access to the Kubernetes cluster. You can secure commands based on user roles and audit command usage.
- Uninstall MATRIXX Engine with Helm
  Use the helm uninstall command to uninstall MATRIXX Engine components installed from the Helm chart.
- Appendixes
MATRIXX Configuration
MATRIXX Security
MATRIXX Integration
MATRIXX Diameter Integration
MATRIXX Call Control Framework Integration
MATRIXX TM Forum Integration
MATRIXX 5G Integration
MATRIXX 5G Event Streaming
MATRIXX Event Streaming
MATRIXX Administration
MATRIXX Web App Administration
MATRIXX Monitoring and Logging
MATRIXX Policy
MATRIXX Kafka CDR Consumer
MATRIXX Pricing and Rating
MATRIXX Pay Now
MATRIXX Subscriber Management
MATRIXX Subscriber Management API
MATRIXX Business API SDK
My MATRIXX Help
MATRIXX Backoffice Customer Tool Help
MATRIXX Third-Party Licenses
Glossary

Upgrade a Standalone Engine

Use this procedure to manually upgrade a single engine system to the latest release of MATRIXX in a cloud environment.

Before you begin

These instructions are a standalone procedure and not coordinated with the other upgrade tasks. This task upgrades an offline engine from a database checkpoint file. For information about tasks that must be completed before upgrading, see the discussion about upgrade prerequisites.

Note: Only compact MATRIXX Data Container (cMDC) checkpoints are supported for single-engine offline upgrades.

Procedure

Stop the engine with one of the two following commands, depending on the type of deployment:

Deployment Type	Command
Topology Operator	`kubectl patch mtxengines.matrixx.matrixx.com engine_pod_name -n namespace -p '{"spec":{"action":"force-stop"}}' --type merge`
Engine Operator	`stop_engine`

Delete the pre-upgrade engine.
Install the upgraded engine with the helm install command.

Stop the newly installed engine, with one of the two following commands, depending on the type of deployment:

Deployment Type	Command
Topology Operator	`kubectl patch mtxengines.matrixx.matrixx.com engine_pod_name -n namespace -p '{"spec":{"action":"force-stop"}}' --type merge`
Engine Operator	`stop_engine`

Copy the new pricing file to the checkpointing pod.
Run start_single_offline_upgrade.py -c last_checkpoint_from_previous_version -p new_pricing_file on the checkpointing pod.
Note: When the script has completed successfully, the following message is displayed in logs:
```
Single engine offline upgrade is successful. Engine is ready to be started.
```

After the script is finished running, start the engine, with one of the two following commands, depending on the type of deployment:

Deployment Type	Command
Topology Operator	`kubectl patch mtxengines.matrixx.matrixx.com engine_pod_name -n namespace -p '{"spec":{"action":"force-start"}}' --type merge`
Engine Operator	`start_engine`

What to do next

For more information about Topology Operator-based deployments, see the discussion about Topology Operator.