MATRIXX SBA Gateway Overview

MATRIXX 5G Integration provides information about integrating MATRIXX Digital Commerce with 5G network consumers using MATRIXX Service Based Architecture (SBA) Gateway and messaging services. Upgrades and version pinning are also covered.

SBA Gateway JAR File

The MATRIXX Service Based Architecture (SBA) Gateway is packaged as an executable JAR file that the MATRIXX Digital Commerce platform uses to implement 5G network functions (NFs) for enabling 5G applications to communicate with MATRIXX Engine.

SBA Gateway provides Service Based Interfaces (SBIs) for connecting and integrating with MATRIXX Engine. SBA Gateway provides the following SBIs through a 5G charging function (CHF) interface to the NF consumer:

  • Nchf_ConvergedCharging — N40 (as defined in 3GPP TS 32.291 v15.5.0) for SMF consumers for:
    • Authorizing and reauthorizing quota.
    • Generating notifications based on change conditions that are valid during rating or when the CHF terminates the charging service. This includes anything that triggers a Charging Notify message, for example plan changes and balance top-ups.
  • Nchf_SpendingLimitControl — N28 (as defined in 3GPP TS 29.594 v15.4.0) for PCF consumers for:
    • Subscribing and unsubscribing to spending limit reporting. For more information on implementing MATRIXX Digital Commerce with 5G policy, see the discussion about 5g policy overview in MATRIXX Policy.
    • Generating notification on charges to subscribed policy counter status(s).
The Figure 1 shows the main components that are included in the SBA Gateway executable JAR file.
Figure 1. SBA Gateway Components
The SBA Gateway executable JAR includes ActiveMQ, TLS, mAuthor, and various libraries and logic needed for a 5G network function

Table 1 lists the files, specifications, and libraries included in the SBA Gateway JAR file, which are loaded upon start-up.

Table 1. Contents of SBA Gateway
Directory Description
/opt/mtx/conf/nf.yaml Contains a network function configuration. Configuration in the nf.yaml file overrides the default SBA configuration.
/opt/mtx/conf/specs Contains Open API (Swagger) files, such as the TS32291_Nchf_ConvergedCharging.yaml file. These files are used when mapping JSON to or from an MDC (MATRIXX data container) or when validating incoming requests.
/opt/mtx/conf/mappings Contains Dynamic Message Mapper configuration files to map JSON to/from MDCs, such as ChargingDataRequest-<version>-mapping.yaml (where version is the MATRIXX Digital Commerce version number).
/opt/mtx/lib Contains Java implementations of network functions, such as sba-5gc-networkfunctions-chf-<version>.jar (where version is the MATRIXX Digital Commerce version number).
/opt/mtx/lib/groovy Contains Groovy implementations of network functions, such as NRF.groovy.

5G SBA Network Topology

Figure 2 shows a network topology of a 5G deployment with two SBA Gateways.

Figure 2. Network Topology for 5G SBA Gateway
SBA Gateway registers with NRF upon startup.

The following SBIs are provided by the NRF and used by SBA Gateway:

  • Nnrf_NFManagment (as defined in 3GPP TS 29.510 v15.5.0) for registering a new NF instance.
  • Nnrf_AccessToken (as defined in 3GPP TS 29.510 v15.5.0) for requesting an OAuth token, if required.

SBA Gateway connects to the TRA-RT-(SI/DR) and registers its URI with the network repository function (NRF) upon startup. This URI is configurable and would typically be the URI of an external HTTP load balancer. SBA Gateway sends a heartbeat to the NRF, according to the heartbeat interval it has received from the NRF when it registers. SBA Gateway de-registers from the NRF upon shutdown. SBA Gateway supports the ability to register with multiple NRFs.

Note: In cloud-native deployments, a single SBA Gateway connection is routed via a Kubernetes service which provides load balancing and failover to multiple TRA-RT-(SI/DR) instances. MATRIXX recommends this configuration. The SBA Gateway can also be configured to connect to multilple specific hosts outside of a Kubernetes cluster. For more information about engine connection details, see the discussion about common SBA configuration.

SBA Gateway converts 5G JSON messages to and from MATRIXX MDCs and forwards these incoming requests to the TRA. In turn, the TRA routes requests to the correct sub-domain and returns responses to the correct SBA Gateway instance. Messages that are initiated by MATRIXX Engine are sent to SBA Gateway through ActiveMQ.

The SBA Gateway itself acts as the Charging Function (CHF) interface to the MATRIXX Engine as the CCS, which performs rating, charging, and balance management. The MATRIXX Engine as CCS also publishes logs and statistics to Fluentd and Promethus. The PCFs and SMFs are part of your 5G network, and are external to MATRIXX Digital Commerce.

Figure 3 shows how the SBA Gateway works with the other components of a MATRIXX converged charging server. The TRA-RT-(SI/DR) between the SBA Gateway and the MATRIXX Engine has been omitted from this diagram.
Figure 3. MATRIXX 5G Policy and Charging Components
Diagram of MATRIXX Engine connecting to an external PCF and external SMF.

How you deploy the SBA Gateway is determined by your MATRIXX Digital Commerce environment requirements. A single SBA Gateway can provide both Nchf_ConvergedCharging and Nchf_SpendingLimitControl at the same time, and that may suffice for a test environment or small MATRIXX Digital Commerce implementation. However if you expect a significant amount of traffic, you may dedicate one SBA Gateway to traffic for Nchf_ConvergedCharging and another for Nchf_SpendingLimitControl. For reliability or security reasons you may implement SBA Gateways as HA pairs dedicated for either Nchf_ConvergedCharging or Nchf_SpendingLimitControl.

You specify the type of traffic an SBA Gateway supports using the nfType and specifications properties in the nf.yaml file. For details, see the discussion about CHF configuration.

5G Network Functions in a MATRIXX Engine installation with Docker and Kubernetes

Network function implementations are Java/Groovy classes that implement an SBI interface in SBA Gateway. On startup, SBA Gateway loads any JAR files in the lib directory and loads Groovy scripts in the groovy directory that implements this interface.

Using the SBI interface, NF implementations can register URIs and implement NF service logic. Logic that is common to all network functions is provided by SBA Gateway, and a set of default configurations, which can be overridden, if required.

SBA Gateway docker containers can be created from the Docker image directly with a command similar to the following:

docker run <path>sba-gateway:version

where version is the docker tag for the SBA Gateway image. This requires mounting the nf directory as a volume containing configuration information.

Network functions can also themselves create 5G function containers from the base SBA Gateway image. Figure 4 shows Docker images are created from network functions.

Figure 4. Docker Images Created from Network Functions
Network functions create Docker images from base SBA Gateway image.

Containerized 5G network functions can also be managed by Kubernetes. Kubernetes is an open-source platform for building, running and orchestrating containers in cloud-native deployments. It automates the deployment (and redeployment, to recover from failure or outage) of containers, and assists in scaling and management. Docker containers for the 5G SBA functions, such as CHF, can run in Kubernetes pods in the same cluster as MATRIXX Engine.

For details on running 5G functions in containers, see the discussion about 5G functions in a Docker-Kubernetes MATRIXX deployment in MATRIXX Cloud Native Installation and Upgrade.

Deliverables for Production Installations

The following artifacts are delivered for production installations:

  • CHF Docker image: sba-5gc-networkfunctions-chf:<tag> (where tag is the latest official release version).
  • Leader sidecar Docker image: sba-5gc-networkfunctions-leadersidecar:<tag> (where tag is the latest official release version).