Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

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

MATLAB Production Server on Kubernetes
https://github.com/mathworks-ref-arch/matlab-production-server-on-kubernetes

matlab-kubernetes

Last synced: over 1 year ago
JSON representation

MATLAB Production Server on Kubernetes

Awesome Lists containing this project

README 

          
# 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](https://www.mathworks.com/help/mps/index.html).



For more information about Kubernetes, see the [Kubernetes documentation](https://kubernetes.io/docs/home/).



## Requirements

Before starting, you need the following:



*   MATLAB Production Server license that meets the following conditions:

    * Linked to a [MathWorks Account](https://www.mathworks.com/mwaccount/).

    * Concurrent license type. To check your license type, see [MathWorks License Center](https://www.mathworks.com/licensecenter/). 

    * 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™](https://git-scm.com/)

* [Docker®](https://www.docker.com/)

* Running [Kubernetes](https://kubernetes.io/) 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](https://kubernetes.io/docs/reference/kubectl/overview/) command-line tool that can access your Kubernetes cluster

* [Helm](https://helm.sh/) 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](https://www.mathworks.com/company/aboutus/contact_us/contact_sales.html) or [request a trial license](https://www.mathworks.com/campaigns/products/trials.html?prodcode=PR). 



## 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](#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](#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](#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  [-n ] --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 `` with the release version, for example, `R2024b`.

    ```

    cd matlab-production-server-on-kubernetes/releases//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:

    ```

    * `containers.mathworks.com` is the name of the container registry.

    * `matlab-production-server` is the name of the repository.

    * `` 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:

    ```

    * `containers.mathworks.com` is the name of the container registry.

    * `matlab-runtime` is the name of the repository.

    * `` 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](https://docs.docker.com/engine/reference/commandline/tag/).



2. Push the images to your private registry by using [docker push](https://docs.docker.com/engine/reference/commandline/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](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-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](https://kubernetes.io/docs/concepts/storage/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)](https://learn.microsoft.com/en-us/azure/aks/azure-csi-files-storage-provision) 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//matlab-prodserver`. To install the Helm chart for the MATLAB Production Server release that you want to deploy, use the [helm install](https://helm.sh/docs/helm/helm_install/) command. Install the chart in a separate Kubernetes namespace. For more information about Kubernetes namespaces, see [Share a Cluster with Namespaces](https://kubernetes.io/docs/tasks/administer-cluster/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  [-n ] --generate-name 

```



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](https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#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](https://kubernetes.io/docs/concepts/services-networking/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](https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#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= 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](https://kubernetes.io/docs/concepts/configuration/configmap/) located at `/releases//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](https://helm.sh/docs/helm/helm_upgrade/) and [kubectl scale](https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#scale).



## Execute Deployed Functions

To evaluate MATLAB functions deployed on the server, see [Client Programming](https://www.mathworks.com/help/mps/client-programming.html). 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](https://www.mathworks.com/products/reference-architectures/request-new-reference-architectures.html).



## Get Technical Support



If you require assistance, contact [MathWorks Technical Support](https://www.mathworks.com/support/contact_us.html).



## License



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