Home
MATRIXX Installation and Upgrade
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.
Commands
An Admin Service command performs an action in a MATRIXX deployment. Command definitions describe how a command can be called, where it can be executed, and what actions it takes there. Commands discovered in a namespace can vary depending on what is installed in that namespace.
Command Definition
Command definitions describe how a command can be called, where it can be executed, and what actions it takes.
Arguments and Flags
Arguments and flags can be used to provide information beyond a command name.

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.
- 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.
  - Installation and Configuration
    Install, upgrade, and apply configuration for the Admin Service using Helm commands.
  - General Configuration Properties
    admin_service/r_as_helm_properties.html#reference_wvt_ywj_4bc__table_ijl_fhr_4bc describes the properties available for configuring the Admin Service as installed in your Kubernetes cluster.
  - Application Configuration Properties
    admin_service/r_as_app_properties.html#reference_vrd_ztx_qbc__table_c3c_l5x_qbc describes the properties available for configuring Admin Service as an application.
  - Role-Based Access Control
    The Admin Service permissions to run commands in the Kubernetes cluster across all namespaces must be limited to necessary permissions.
  - Required Roles
    If the Admin Service has been secured with OAuth 2.0 authorization, for example with Keycloak, the user roles described in admin_service/c_as_required_roles.html#concept_umg_tjq_jcc__table_kpq_nkq_jcc must be created and assigned to the appropriate users.
  - Admin Service Data Handling
    The Admin Service retains data from commands and performs related housekeeping and sizing tasks.
  - Metrics
    Admin Service exposes metrics to Prometheus if the monitoring.enabled property is set to true. These include the standard Kubernetes and Go metrics as well as some additional application-specific metrics.
  - Admin Service in the MATRIXX Deployment
    Install the Admin Service before you install MATRIXX, or run helm upgrade of the MATRIXX Helm chart after installing the Admin Service. The MATRIXX Helm chart creates AdminCommand custom resources as long as the Admin Service CRDs have been installed first.
  - Commands
    An Admin Service command performs an action in a MATRIXX deployment. Command definitions describe how a command can be called, where it can be executed, and what actions it takes there. Commands discovered in a namespace can vary depending on what is installed in that namespace.
    - Command Discovery
      Commands discovered in a namespace can vary depending on what is installed in that namespace.
    - Command Definition
      Command definitions describe how a command can be called, where it can be executed, and what actions it takes.
      - Basic Information
        The first part of a command definition describes how the command can be executed, including the command name and any arguments it can take. This is the interface to the user. admin_service/r_as_cmd_def_basic.html#reference_ij3_fjz_rbc__table_qrf_t2z_rbc describes the properties available for specifying this information.
      - Arguments and Flags
        Arguments and flags can be used to provide information beyond a command name.
      - Resource Selector
        Part of the command definition is describing the namespace (and cluster, where there is more than one cluster) where the command is executed. The resource you select in the namespace depends on the function of the command.
      - Command Executor
        Command execution can be one of three types:
      - Restrictions
        If the Admin Service is secured with OAuth, you can limit the execution of individual commands by the user roles.
      - Sub-Commands
        A command is typically made up of a noun and a verb. The noun is the object of the command and the verb is what is done to that object.
    - File Support
      Commands can create files as output that must be available to the user.
    - Duplicate Command Behavior
      You may need to run the same command in different locations.
    - Merging Commands
      Commands with the same name are merged by the Admin Service, such as in the following scenarios:
  - Security
    The Admin Service manages access to a MATRIXX installation. Users are restricted to well-defined commands, based on both what the commands do and the role of the user in your organization.
  - Admin Service Command Line Tool
    You run Admin Service commands using a command line interface (CLI).
  - Troubleshooting
    If something goes wrong with Admin Service, the problem is likely to be either at the level of the command or the larger Admin Service application.
- 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

Arguments and Flags

Arguments and flags can be used to provide information beyond a command name.

Arguments

Command Argument Properties describes the properties available for specifying command arguments.

Table 1. Command Argument Properties
Name	Description
name	The name of the argument.
type	The value type. Valid values are `boolean`, `string`, and `int`.
description	A description of the argument, used as the help message for the command in the CLI.
mandatory	When set to `true`, the argument must always be supplied.
defaultValue	(Optional) The value used if none is specified.

Warning: Do not follow an optional argument with a mandatory one. Because there is no way of knowing an argument has not been supplied, a subsequent value would be taken for the optional one.

The following shows the definition of an argument used in a hypothetical mtxctl export 100 command:

command:  
name: export
  description: Export some data
  arguments:
    - name: numberOfRecords
      type: int
      mandatory: true
      description: The number of records to export

Flags

Flags are similar to arguments but can be passed in any order. They typically have a small finite set of valid values. Command Flag Properties describes the properties available for specifying command flags.

Table 2. Command Flag Properties
Property	Description
name	The name of the flag.
shortName	A shorter name of the flag, typically a single character.
type	The value type. Valid values are `boolean`, `string`, and `int`.
description	A description of the flag, used as the help message for the command in the CLI.
mandatory	When set to `true`, the flag must always be supplied.
defaultValue	(Optional) The value used if none is specified by the user.

The following shows the definition of two flags used in a hypothetical mtxctl export -e 1 --subdomain 1 command:

command:
  name: export
  description: Export some data
  flags:
    - name: engine
      shortName: e
      type: int
      mandatory: false
      defaultValue: 1
      description: The Engine id
    - name: subdomain
      shortName: s
      type: int
      mandatory: false
      defaultValue: 1
      description: The Subscriber Domain id

A flag is more appropriate than an argument for some Boolean values. For example, a flag can be used to enable some functionality that is disabled by default.