MATLAB Production Server in Kubernetes

The matlab-production-server-on-kubernetes repository contains utilities for using MATLAB® Production Server™ in a Kubernetes® cluster.

Introduction

This guide helps you automate the process of running MATLAB Production Server in a Kubernetes cluster by using a Helm® chart. The chart is a collection of YAML files that define the resources you need to deploy MATLAB Production Server in Kubernetes. Once you deploy the server, you can manage it using the kubectl command-line tool.

For more information about MATLAB Production Server, see the MATLAB Production Server documentation.

For more information about Kubernetes, see the Kubernetes documentation.

Requirements

Before starting, you need the following:

• MATLAB Production Server license that meets the following conditions:
  • Linked to a MathWorks Account.
  • Concurrent license type. To check your license type, see MathWorks License Center.
  • Configured to use a network license manager. The license manager must be accessible from the Kubernetes cluster where you deploy MATLAB Production Server but must not be installed in the cluster.
• Network access to the MathWorks container registry, containers.mathworks.com
• Git™
• Docker®
• Running Kubernetes cluster that meets the following conditions:
  • Uses Kubernetes version 1.28 or later.
  • Each MATLAB Production Server container in the Kubernetes cluster requires at least 1 CPU core and 2 GiB RAM.
• kubectl command-line tool that can access your Kubernetes cluster
• Helm package manager to install Helm charts that contain preconfigured Kubernetes resources for MATLAB Production Server
  • Uses Helm version v3.14 or later.

If you do not have a license, please contact your MathWorks representative here or request a trial license.

Quick Start

The Quick Start option is recommended for the following cases:

• You are deploying MATLAB Production Server R2024b or newer
• You don't require significant changes to the Helm chart
• You are not running MATLAB Production server on Kubernetes as part of a CI/CD workflow For CI/CD workflows, we recommend that you cache docker images in your private container registry. For more complex workflows, use the Deployment Steps

The Quick Start option only requires you to download a single file, rather than cloning the full GitHub repository. For more complex workflows, use the Deployment Steps

1. Download the values-overrides.yaml file containing configuration options that apply across all release deployments from the MATLAB Production Server on Kubernetes GitHub repository. You can use the cURL command below or click the "Download Raw File" icon.

   curl -O https://raw.githubusercontent.com/mathworks-ref-arch/matlab-production-server-on-kubernetes/main/values-overrides.yaml
   

2. Complete the steps in Provide Mapping for Deployable Archives.

3. Before installing the chart, first set parameters that state your agreement to the MathWorks cloud reference architecture license and specify the address of the network license manager. In the top-level values-overrides.yaml file, set these parameters:

   To accept the license terms, set global > agreeToLicense to "yes". To specify the address of the license server, set global > licenseServer using the format port_number@host.

   Next, install the Helm chart for MATLAB Production Server by using the following helm install command:

    ```
    helm install -f <path/to/values-overrides.yaml> [-n <k8s-namespace>] --generate-name oci://containers.mathworks.com/matlab-prodserver-k8s --version 1.1.0
    ```
   

4. After the deployment is complete, upload the MATLAB Production Server deployable archive to your network file server or Azure file share. All users must have read permission to the deployable archive.

Deployment Steps

Clone GitHub® Repository that Contains Helm Chart

The MATLAB Production Server on Kubernetes GitHub repository contains Helm charts that reference Ubuntu-based Docker container images for MATLAB Production Server deployment.

1. Clone the MATLAB Production Server on Kubernetes GitHub repository to your machine.

   git clone https://github.com/mathworks-ref-arch/matlab-production-server-on-kubernetes.git
   

   This repository includes Helm chart folders for each supported MATLAB Production Server release and a values-overrides.yaml file containing configuration options that apply across all release deployments.

2. Navigate to the Helm chart folder for the release you want to use. Replace <release> with the release version, for example, R2024b.

   cd matlab-production-server-on-kubernetes/releases/<release>/matlab-prodserver
   

   This folder contains two files that together define the Helm chart used to deploy MATLAB Production Server.

   • Chart.yaml — Contains metadata about the Helm chart.
   • values.yaml — Contains release-specific configuration options for the deployment.

Pull Container Images for MATLAB Production Server and MATLAB Runtime

1. Pull the container image for MATLAB Production Server to your machine.

   docker pull containers.mathworks.com/matlab-production-server:<release-tag>
   

   • containers.mathworks.com is the name of the container registry.
   • matlab-production-server is the name of the repository.
   • <release-tag> is the tag name of the MATLAB Production Server release, for example, r2024b.

   The values.yaml file specifies these values in the productionServer section, in the registry, repository, and tag variables, respectively.

2. Pull the container image for MATLAB Runtime to your machine.

   docker pull containers.mathworks.com/matlab-runtime:<release-tag>
   

   • containers.mathworks.com is the name of the container registry.
   • matlab-runtime is the name of the repository.
   • <release-tag> is the tag name of the MATLAB Runtime release. Update this value to the release version of the MATLAB Runtime you are using, for example, r2024b. MATLAB Production Server supports MATLAB Runtime versions up to six releases back from the MATLAB Production Server version you are using.

   The values.yaml file specifies these values in the matlabRuntime section, in the registry, repository, and tag variables, respectively.

Upload Container Images to Private Registry

After you pull the MATLAB Production Server and MATLAB Runtime container images to your system, upload them to a private container registry that your Kubernetes cluster can access.

1. Tag the images with information about your private registry by using docker tag.

2. Push the images to your private registry by using docker push.

3. In the values-overrides.yaml file, set the global > images > registry variable to the name of your private registry.

4. If your private registry requires authentication, create a Kubernetes Secret that your pod can use to pull the image from the private registry. For more information, see Pull an Image from a Private Registry in the Kubernetes documentation.

5. In the values-overrides.yaml file, set the global > images > pullSecret variable to the name of the Kubernetes Secret you created.

Provide Mapping for Deployable Archives

Deploying MATLAB Production Server requires a running Kubernetes cluster. From the Kubernetes cluster that you use for MATLAB Production Server, provide a mapping from the storage location where you want to store MATLAB Production Server deployable archives (CTF files) to a storage resource in your cluster. You can store the deployable archives on the network file system or on the cloud. After the MATLAB Production Server deployment is complete, the deployable archives that you store in the mapped location are automatically deployed to the server.

To specify mapping, in the top-level values-overrides.yaml file, under matlabProductionServerSettings, set values for the variables under autoDeploy.

To specify the storage location for storing deployable archives, under autoDeploy, set volumeType to one of the following:

• "nfs" — Store archives to a location on the network file system. Specify values for the server and path variables. Specify the hostname of your NFS server in the server variable and the location of your deployable archives in the path variable. For more information about the nfs option, see Volumes in the Kubernetes documentation.
• "pvc" — Store archives to a persistent volume by using a Persistent Volume Claim. Specify a value for the claimName variable. To use this option, you must have an existing Persistent Volume Claim that is already bound to its underlying storage volume.
• "azurefileshare" — Store archives to a file share using Azure™ Files. Specify values for shareName and secretName variables. To use this option, you must have an existing file share and Kubernetes secret used to access the file share. For details about Azure file shares, see Create and use a volume with Azure Files in Azure Kubernetes Service (AKS) in the Azure documentation.

The default value for volumeType is "empty". However, to access deployable archives, you must set volumeType to one of the previously described options.

Install Helm Chart

The Helm chart for MATLAB Production Server is located in the repository in /releases/<release>/matlab-prodserver. To install the Helm chart for the MATLAB Production Server release that you want to deploy, use the helm install command. Install the chart in a separate Kubernetes namespace. For more information about Kubernetes namespaces, see Share a Cluster with Namespaces in the Kubernetes documentation.

Before installing the chart, first set parameters that state your agreement to the MathWorks cloud reference architecture license and specify the address of the network license manager. In the top-level values-overrides.yaml file, set these parameters:

• To accept the license terms, set global > agreeToLicense to "yes".
• To specify the address of the license server, set global > licenseServer using the format port_number@host.

Then, install the Helm chart for MATLAB Production Server by using the helm install command:

helm install -f <path/to/values-overrides.yaml> [-n <k8s-namespace>] --generate-name <path/to/chart directory>

After you install the chart, the pod takes a few minutes to initialize because the installation consists of approximately 10 GB of container images.

The deployment name is deployment.apps/matlab-production-server. You can use the kubectl get command to confirm that MATLAB Production Server is running. The name of the service that enables network access to the pod is service/matlab-production-server.

Upload Deployable Archive

After the deployment is complete, upload the MATLAB Production Server deployable archive to your network file server or Azure file share. All users must have read permission to the deployable archive.

Manage External Access Using Ingress

You can manage access to MATLAB Production Server by specifying an Ingress controller. The Ingress controller also acts as a load balancer and is the preferred way to expose MATLAB Production Server services in production. This reference architecture assumes that you have an existing Ingress controller already running on the Kubernetes cluster. Specify controller options in the ingressController variable of the values-overrides.yaml file or use the default values. You can enable inbound HTTPS connections by using an Ingress controller TLS termination.

Test Client Access Using Port Forwarding

To test that the deployment was successful, first, use port forwarding to map the port that is running MATLAB Production Server inside the cluster (default = 9910) to a port that is available outside the cluster.

To add port forwarding, use the kubectl port-forward command. This example maps the default internal port 9910 to port 19910. Clients from any IP address can then access the svc/matlab-production-server service from outside the cluster by connecting to port 19910.

kubectl port-forward --address 0.0.0.0 --namespace=<k8s-namespace> svc/matlab-production-server 19910:9910 &

Then, test the server connection by using a curl command. This example tests the connection to the health check API by accessing the mapped port (19910) on the localhost. If curl is installed on a different machine, replace localhost with the hostname for that machine.

curl localhost:19910/api/health

Sample JSON output for a successful connection: {"status": "ok"}

Update Server Configuration Properties

The default server configuration properties are stored in a ConfigMap located at /releases/<release>/matlab-prodserver/templates/mps-2-configmap.yaml. To update server properties, you can update mps-2-configmap.yaml or values.yaml. To apply the updated server properties to the deployment, see helm upgrade and kubectl scale.

Execute Deployed Functions

To evaluate MATLAB functions deployed on the server, see Client Programming. Starting in R2022a, asynchronous request execution is supported, in addition to existing support for synchronous request execution.

Request Enhancements

To suggest additional features or capabilities, see Request Reference Architectures.

Get Technical Support

If you require assistance, contact MathWorks Technical Support.

License

MATHWORKS CLOUD REFERENCE ARCHITECTURE LICENSE © 2024 The MathWorks, Inc.