Home
MATRIXX Installation and Upgrade
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.
Multiple Engines
The other examples show installation of one sub-domain containing two engines and performing an upgrade with custom engine configuration. In those examples, the engine configuration change is at the subdomain-level which results in both engines in the sub-domain being upgraded.
Upgrading One Engine at a Time
When upgrading, you may want to have some additional control over when each individual MATRIXX Engine is upgraded. This requires some additional steps.

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.
  - Single Namespace
    These examples show installation and upgrade of Topology Operator masters, agents, and MATRIXX Engines s1e1 and s1e2 in the matrixx namespace.
  - Multiple Namespaces in a Single Cluster
    These examples show installation and upgrade of Topology Operator masters, agents, and MATRIXX Engines s1e1 and s1e2 in four separate namespaces.
  - Multiple Clusters
    These examples show installation and upgrade of Topology Operator masters, agents, and MATRIXX Engines s1e1 and s1e2 in two separate clusters.
  - Multiple Clusters with Dynamic Provisioning
    Deploying across multiple clusters on platforms such as Amazon EKS is more difficult because you do not know the external addresses ahead of time. This example uses Helm to create the load balancer services (with the required annotations), allow the IP addresses to be dynamically provisioned, and then updates the configuration after IP addresses have been assigned.
  - Multiple Engines
    The other examples show installation of one sub-domain containing two engines and performing an upgrade with custom engine configuration. In those examples, the engine configuration change is at the subdomain-level which results in both engines in the sub-domain being upgraded.
    - Upgrading All Engines Sequentially
      By default, the subdomain-operator upgrades all required MATRIXX Engines sequentially with no additional input.
    - Upgrading One Engine at a Time
      When upgrading, you may want to have some additional control over when each individual MATRIXX Engine is upgraded. This requires some additional steps.
  - Multiple Sub-Domains
    Installation and upgrade of multiple sub-domain deployments is an extension of the processes shown in the single sub-domain examples.
  - Multiple Domains
    Topology Operator also supports multiple domain MATRIXX installations. In the way that earlier examples were extended from one sub-domain to multiple sub-domains, the configuration and required commands can be extended from one domain to multiple domains.
  - Gateway Proxy, RS Gateway, and Site-Level TRAs
    Gateway Proxy, RS Gateway, and the site-level Traffic Routing Agent (TRA-DR) occupy their own namespaces in a multi-namespace deployment.
  - Using Topology Operator with Multus CNI
    Service meshes or Kubernetes container network interface (CNI) plug-ins, such as Multus, allow MATRIXX to connect to separate networks for transaction processing and operations and maintenance (O&M).
  - Using Topology Operator with Taxation
    Enable taxation in Topology Operator-based MATRIXX deployments by setting global.features.tax to true and setting tax-controller.enabled to true. (Taxation is disabled by default.)
  - Multi-Tenant Deployments
    This example shows installation and configuration of a two-tenant MATRIXX deployment with MATRIXX Engines in four separate namespaces. In this example, two tenants are defined at the level of the domain, and both are configured in one sub-domain, but only one tenant is configured in the other sub-domain.
  - Using Topology Operator with Call Control Framework
    This section includes examples for how to configure the installation of Call Control Framework (CCF) in Topology Operator-based MATRIXX deployments.
  - Reverting an Update
    Use the helm rollback command to revert to a previous configuration or MATRIXX Engine version.
- 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.
- 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

Upgrading One Engine at a Time

When upgrading, you may want to have some additional control over when each individual MATRIXX Engine is upgraded. This requires some additional steps.

Procedure

Upgrade the s1e1 engine.

Upgrade the s1e1 engine namespace:

helm --kube-context context1 upgrade mtx-engine-s1 matrixx/matrixx -n matrixx-engine-s1 -f base.yaml -f topology-upgrade_version.yaml -f cluster1.yaml --version upgrade_version

Upgrade the namespace containing the agents, but not the masters:

helm --kube-context context2 upgrade mtx-operators matrixx/matrixx -n matrixx-operators -f base.yaml -f topology-upgrade_version.yaml -f cluster2.yaml --version upgrade_version

Then upgrade the namespace containing the masters, skipping the s1e2 MtxEngine CR:
```
helm --kube-context context1 upgrade mtx-operators matrixx/matrixx -n matrixx-operators -f base.yaml -f topology-upgrade_version.yaml -f cluster1.yaml --set global.topology.domains[0].subdomains[0].engines[1].skip=true --version upgrade_version
```
The Helm --set option allows you to temporarily modify configuration values from the command prompt rather than editing topology-upgrade_version.yaml.

Subdomain-operator-s1updates only the s1e1 MtxEngine CR, skipping the s1e2 MtxEngine CR. Engine-operator-s1e1 instance acts upon the updated s1e1 MtxEngine CR to upgrade the engine.

Upgrade the s1e2 engine.

Upgrade the s1e2 engine namespace:

helm --kube-context context2 upgrade mtx-engine-s1 matrixx/matrixx -n matrixx-engine-s1 -f base.yaml -f topology-upgrade_version.yaml -f cluster2.yaml --version upgrade_version

Upgrade the namespace containing the masters:
```
helm --kube-context context1 upgrade mtx-operators matrixx/matrixx -n matrixx-operators -f base.yaml -f topology-upgrade_version.yaml -f cluster1.yaml --version upgrade_version
```
Subdomain-operator-s1 updates the s1e2 MtxEngine CR. Engine-operator-s1e2 acts upon the updated s1e2 MtxEngine CR to upgrade the engine.