Merge pull request #1 from mathworks-ref-arch/1.1.0

v1.1.0

Author: hannahpullen

.github/workflows/workflows.yml renamed to .github/workflows/helm-chart.yml

@@ -1,8 +1,9 @@
-name: Release Artifacts
+# Copyright 2024 The MathWorks, Inc.
+name: Release Helm Chart
 
-on: 
+on:
   release:
-    types: [created, edited]
+    types: [created]
 
 jobs:
   release-controller-image:
@@ -16,19 +17,18 @@ jobs:
       uses: actions/checkout@v4
 
     - name: Log in to GitHub Container Registry
-      uses: docker/login-action@v2
+      uses: docker/login-action@v3
       with:
         registry: ghcr.io
         username: ${{ github.actor }}
         password: ${{ secrets.GITHUB_TOKEN }}
 
     - name: Build and push Docker image
-      uses: docker/build-push-action@v3
+      uses: docker/build-push-action@v5
       with:
         push: true
         tags: ghcr.io/mathworks-ref-arch/matlab-parallel-server-k8s/mjs-controller-image:${{ github.event.release.tag_name }}
         context: ./controller
-        file: ./controller/Dockerfile
 
   release-helm-chart:
     runs-on: ubuntu-latest
@@ -38,23 +38,22 @@ jobs:
 
     steps:
       - name: Check out the repo
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Install Helm
         uses: azure/setup-helm@v4
 
-      - name: Lint the chart
+      - name: Lint chart
         run: helm lint mjs --set maxWorkers=4,matlabPVC=test,checkpointPVC=test,logPVC=test,workerLogPVC=test
 
       - name: Check chart versions
         run: grep "version. ${{ github.event.release.tag_name }}" mjs/Chart.yaml && grep "appVersion. ${{ github.event.release.tag_name }}" mjs/Chart.yaml # Use "." (any character) rather than ":", since ":" breaks YAML parser
 
-      - name: Package the chart
-        run: echo ${{ github.event.release.tag_name }} && helm package mjs --version ${{ github.event.release.tag_name }} --app-version ${{ github.event.release.tag_name }}
+      - name: Package chart
+        run: helm package mjs --version ${{ github.event.release.tag_name }} --app-version ${{ github.event.release.tag_name }}
 
       - name: Login to GitHub Container Registry
-        run: echo ${{ secrets.HELM_TOKEN }} | helm registry login ghcr.io/hannahpullen --username hannahpullen --password-stdin
-
-      - name: Deploy the chart
-        run: helm push mjs-${GITHUB_REF#refs/tags/}.tgz oci://ghcr.io/mathworks-ref-arch/matlab-parallel-server-k8s
+        run: echo ${{ secrets.HELM_TOKEN }} | helm registry login ghcr.io/mathworks-ref-arch --username hannahpullen --password-stdin
 
+      - name: Upload chart
+        run: helm push mjs-${{ github.event.release.tag_name }}.tgz oci://ghcr.io/mathworks-ref-arch/matlab-parallel-server-k8s

.github/workflows/parallel-server-images.yml

@@ -0,0 +1,118 @@
+# Copyright 2024 The MathWorks, Inc.
+name: Build and push MATLAB Parallel Server images
+
+on:
+  workflow_dispatch:
+  push:
+    # Trigger the workflow if image files or this workflow file are changed
+    branches:
+      - main
+    paths:
+      - "images/job-manager/**"
+      - "images/worker/**"
+      - ".github/workflows/parallel-server-images.yml"
+  schedule:
+    # Run at 00:00 on every Tuesday (2nd Day of the Week)
+    # This captures updates to matlab-deps, which is rebuilt every Monday
+    - cron: "0 0 * * 2"
+
+env:
+  LICENSE_FILE_PATH: ${{ github.workspace }}/license.lic
+  JM_IMAGE: ghcr.io/mathworks-ref-arch/matlab-parallel-server-k8s/mjs-job-manager-image
+
+jobs:
+  # Build the job manager image and push to GHCR.
+  build-push-job-manager-image:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        matlab-release: [r2024a]
+
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build local image
+        uses: docker/build-push-action@v5
+        with:
+          platforms: linux/amd64
+          context: ./images/job-manager
+          build-args: MATLAB_RELEASE=${{ matrix.matlab-release }}
+          tags: ${{ env.JM_IMAGE }}:${{ matrix.matlab-release }}
+
+      - name: Test MJS on container
+        env:
+          BIN_DIR: /opt/matlab/toolbox/parallel/bin
+        run: docker run ${JM_IMAGE}:${{ matrix.matlab-release }} bash -c "${BIN_DIR}/mjs start && ${BIN_DIR}/startjobmanager && ${BIN_DIR}/glnxa64/mjshealthcheck -matlabroot /opt/matlab"
+
+      - name: Push to GHCR
+        uses: docker/build-push-action@v5
+        with:
+          platforms: linux/amd64
+          context: ./images/job-manager
+          tags: ${{ env.JM_IMAGE }}:${{ matrix.matlab-release }}
+          push: true
+
+  # Build the worker image on top of the job manager image. This requires a large runner so we have enough storage for the local image.
+  build-push-worker-image:
+    runs-on: ubuntu-latest-m
+    needs: [build-push-job-manager-image]
+    permissions:
+      contents: read
+      packages: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        matlab-release: [r2024a]
+
+    env:
+      WORKER_IMAGE: ghcr.io/mathworks-ref-arch/matlab-parallel-server-k8s/mjs-worker-image
+
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build local image
+        uses: docker/build-push-action@v5
+        with:
+          platforms: linux/amd64
+          context: ./images/worker
+          build-args: MATLAB_RELEASE=${{ matrix.matlab-release }}
+          tags: ${{ env.WORKER_IMAGE }}:${{ matrix.matlab-release }}
+
+      - name: Generate MATLAB license file
+        run: echo '${{ secrets.MATLAB_LICENSE_FILE_R2024A }}' > ${{ env.LICENSE_FILE_PATH }}
+
+      - name: Test MATLAB on container
+        env:
+          MLM_LICENSE_FILE: /tmp/license.lic # License file path on container
+        run: docker run -v ${LICENSE_FILE_PATH}:${MLM_LICENSE_FILE} ${WORKER_IMAGE}:${{ matrix.matlab-release }} bash -c "MLM_LICENSE_FILE=${MLM_LICENSE_FILE} /opt/matlab/bin/matlab -batch 'version'"
+
+      - name: Push to GHCR
+        uses: docker/build-push-action@v5
+        with:
+          platforms: linux/amd64
+          context: ./images/worker
+          tags: ${{ env.WORKER_IMAGE }}:${{ matrix.matlab-release }}
+          build-args: MATLAB_RELEASE=${{ matrix.matlab-release }}
+          push: true

README.md

@@ -2,14 +2,14 @@
 
 [![View MATLAB Parallel Server in Kubernetes on File Exchange](https://www.mathworks.com/matlabcentral/images/matlab-file-exchange.svg)](https://www.mathworks.com/matlabcentral/fileexchange/167676-matlab-parallel-server-in-kubernetes)
 
-This repository contains utilities for using MATLAB® Parallel Server in a Kubernetes® cluster.
+This repository contains utilities for using MATLAB® Parallel Server™ in a Kubernetes® cluster.
 
 ## Introduction
 
 This guide explains how to deploy MATLAB Job Scheduler onto your Kubernetes cluster.
 You can then connect to the MATLAB Job Scheduler and use it to run MATLAB Parallel Server jobs on the Kubernetes cluster.
 
-For more information on MATLAB Job Scheduler and MATLAB Parallel Server, see the MathWorks documentation on [MATLAB Parallel Server](https://www.mathworks.com/help/matlab-parallel-server/index.html).
+For more information on MATLAB Job Scheduler and MATLAB Parallel Server, see the MathWorks® documentation on [MATLAB Parallel Server](https://www.mathworks.com/help/matlab-parallel-server/index.html).
 
 ## Requirements
 
@@ -20,7 +20,6 @@ Before you start, you need the following:
   - Uses Kubernetes version 1.21.1 or later.
   - Meets the system requirements for running MATLAB Job Scheduler. For details, see the MathWorks documentation for [MATLAB Parallel Server Product Requirements](https://www.mathworks.com/support/requirements/matlab-parallel-server.html).
   - Configured to create external load balancers that allow traffic into the cluster.
-- Docker® installed on your computer. For help with installing Docker, see [Get Docker](https://docs.docker.com/get-docker/).
 - Kubectl installed on your computer and configured to access your Kubernetes cluster. For help with installing Kubectl, see [Install Tools](https://kubernetes.io/docs/tasks/tools/) on the Kubernetes website.
 - Helm® version 3.8.0 or later installed on your computer. For help with installing Helm, see [Quickstart Guide](https://helm.sh/docs/intro/quickstart/).
 - Network access to the MathWorks Container Registry, `containers.mathworks.com`, and the GitHub® Container registry, `ghcr.io`.
@@ -51,14 +50,11 @@ Create these volumes using your preferred storage medium.
 For instructions, see the [Kubernetes PersistentVolume documentation](https://kubernetes.io/docs/concepts/storage/persistent-volumes/).
 
 The software requires three PersistentVolumes to retain job data and logs.
-You can also use a PersistentVolume to mount your own MATLAB Parallel Server installation onto the MATLAB Job Scheduler pods.
-If you do not create a PersistentVolume containing a MATLAB Parallel Server installation, you must use a Docker image that has MATLAB Parallel Server installed.
 
 Create a PersistentVolume for each of the following applications:
 - An empty PersistentVolume with access mode `ReadWriteOnce` for MATLAB Job Scheduler's checkpoint folder, which retains job data after exiting the session
 - An empty PersistentVolume with access mode `ReadWriteOnce` to retain logs from the MATLAB Job Scheduler job manager
 - An empty PersistentVolume with access mode `ReadWriteMany` to retain logs from the MATLAB Job Scheduler workers
-- A PersistentVolume with access mode `ReadOnlyMany` containing a MATLAB Parallel Server installation
 
 Now create a *PersistentVolumeClaim* for each PersistentVolume.
 You can create a PersistentVolumeClaim by using the following example configuration file.
@@ -82,25 +78,6 @@ spec:
       storage: <capacity>
 ```
 
-### Build MATLAB Parallel Server Docker Image (Optional)
-
-The MATLAB Job Scheduler pods require a MATLAB Parallel Server installation.
-By default, you mount this from a PersistentVolume, as described in the previous step.
-If you do not have a MATLAB Parallel Server installation to mount, you can build a Docker image containing a MATLAB Parallel Server installation instead.
-
-Build a Docker image that contains a MATLAB Parallel Server installation.
-- Specify `<release>` as a MATLAB release number with a lowercase `r`. For example, to install MATLAB R2024a, specify `<release>` as `r2024a`. The MATLAB release must be version R2024a or later.
-- Specify `<other-products>` as a space-separated list of MATLAB toolboxes you want to install. The toolbox names must match the product names listed on the MathWorks&reg; product page with any spaces replaced by underscores. For example, to install Parallel Computing Toolbox and Deep Learning Toolbox, specify `<other-products>` as `Parallel_Computing_Toolbox Deep_Learning_Toolbox`. For a complete list of product names, see [MathWorks Products](https://www.mathworks.com/products.html).
-- Specify `<my-tag>` as the Docker tag to use for the image.
-```
-docker build https://raw.githubusercontent.com/mathworks-ref-arch/matlab-dockerfile/main/Dockerfile --build-arg MATLAB_INSTALL_LOCATION=/opt/matlab --build-arg MATLAB_RELEASE=<release> --build-arg MATLAB_PRODUCT_LIST="MATLAB MATLAB_Parallel_Server <other-products>" -t <my-tag>
-```
-
-Push the image to a repository that is visible to your Kubernetes cluster.
-
-For more information on building a MATLAB Docker image, see [Create a MATLAB Container Image](https://github.com/mathworks-ref-arch/matlab-dockerfile) in the GitHub repository.
-
-
 ### Create Administrator Password Secret
 
 By default, MATLAB Job Scheduler in Kubernetes runs at security level 2.
@@ -123,24 +100,30 @@ Copy the following lines into a YAML file, `values.yaml`, and modify the values
 ```yaml
 matlabRelease: r2024a
 maxWorkers: 100
-matlabPVC: "matlab-pvc"
+
+# Licensing settings
+useOnlineLicensing: true
+networkLicenseManager: ""
+
+# PersistentVolumeClaim settings
 checkpointPVC: "checkpoint-pvc"
 logPVC: "log-pvc"
 workerLogPVC: "worker-log-pvc"
+
+# Security settings
 jobManagerUserID: 0
 jobManagerGroupID: 0
-matlabImage: ""
 ```
 Modify the following values:
 - `matlabRelease` &mdash; Specify the release number of the MATLAB Parallel Server installation.
 - `maxWorkers` &mdash; Specify the maximum number of MATLAB Parallel Server workers to run in the cluster. The cluster starts with zero workers and automatically scales up to this number as the cluster becomes busy.
-- `matlabPVC` &mdash; Specify the name of a PersistentVolumeClaim that is bound to the PersistentVolume with a MATLAB Parallel Server installation.
+- `useOnlineLicensing` &mdash; Option to use MathWorks online licensing. Set this parameter to true to use online licensing to manage licensing for your cluster users. When enabled, users must log in to their MathWorks account to connect to the cluster, and their account must be linked to a MATLAB Parallel Server license that is managed online. For more information about online licensing, see [Use Online Licensing for MATLAB Parallel Server](https://www.mathworks.com/products/matlab-parallel-server/online-licensing.html) on the MathWorks website. To learn how to set up online licensing, see the MathWorks documentation [Configure MATLAB Parallel Server Licensing for Cloud Platforms](https://www.mathworks.com/help/matlab-parallel-server/configure-matlab-parallel-server-licensing-for-cloud-platforms.html).
+- `networkLicenseManager` &mdash; To use a network license manager to manage licensing for your cluster users, specify the address of your network license manager in the format `port@host`. The license manager must be accessible from the Kubernetes cluster. You can install or use an existing network license manager running on-premises or on AWS&reg;. To install a network license manager on-premises, see the MathWorks documentation [Install License Manager on License Server](https://www.mathworks.com/help/install/ug/install-license-manager-on-license-server.html). To deploy a network license manager reference architecture on AWS, select a MATLAB release from [Network License Manager for MATLAB on AWS](https://github.com/mathworks-ref-arch/license-manager-for-matlab-on-aws).
 - `checkpointPVC` &mdash; Specify the name of a PersistentVolumeClaim that is bound to a PersistentVolume used to retain job data.
 - `logPVC` &mdash; Specify the name of a PersistentVolumeClaim that is bound to a PersistentVolume used to retain job manager logs.
 - `workerLogPVC` &mdash; Specify the name of a PersistentVolumeClaim that is bound to a PersistentVolume used to retain worker logs.
 - `jobManagerUserID` &mdash; Specify the user ID of the user account that MATLAB Job Scheduler should use to run the job manager pod. The user must have write permission for the checkpoint and log PersistentVolumes. To find the user ID, on a Linux machine, run `id -u`.
 - `jobManagerGroupID` &mdash; Specify the group ID of the user account that MATLAB Job Scheduler should use to run the job manager pod. The user must have write permission for the checkpoint and log PersistentVolumes. To find the group ID, on a Linux machine, run `id -g`.
-- `matlabImage` &mdash; Specify the URI of a Docker image that contains a MATLAB Parallel Server installation. Specify a URI only if you built a Docker image instead of mounting a MATLAB Parallel Server installation from a PersistentVolume. If you specify this parameter, set the `matlabPVC` parameter to an empty string (`""`).
 
 For a full list of the configurable Helm values that you can set in this file, see the [Helm Values](helm_values.md) page.
 
@@ -228,6 +211,13 @@ If you created a custom load balancer service, delete the service:
 kubectl delete service mjs-ingress-proxy --namespace mjs
 ```
 
+If you want to reinstall MATLAB Job Scheduler, you must ensure that the load balancer service is deleted first.
+To check the status of the load balancer service, run:
+```
+kubectl get service mjs-ingress-proxy --namespace mjs
+```
+If the load balancer service appears, wait for some time, then run the command again to confirm that the load balancer service is not found before proceeding with the MATLAB Job Scheduler reinstallation.
+
 ## Examples
 
 Create a cluster object using your cluster profile `<name>`:
@@ -311,6 +301,29 @@ end
 
 ## Advanced Setup Steps
 
+### Customize Worker Image
+
+The MATLAB Parallel Server workers run on an image that contains MATLAB, Simulink, all MathWorks toolboxes, and the Deep Learning Support Packages by default.
+If you want to increase the performance of creating worker pods or customise the toolboxes or support packages used, you have two options:
+1. Build a custom Docker image with only the toolboxes you need
+2. Mount the MATLAB installation from a PersistentVolume
+
+#### Build Custom Docker Image
+
+To build a custom Docker image, see [Create a MATLAB Parallel Server Container Image](images/worker/README.md).
+Push the image to a repository that is visible to your Kubernetes cluster.
+
+Modify your `values.yaml` file to set the `workerImage` and `workerImageTag` parameters to the URI and tag of your image before installating the Helm chart.
+
+#### Mount MATLAB from a PersistentVolume
+
+To mount MATLAB from a PersistentVolume, create a PersistentVolume and PersistentVolumeClaim with access mode `ReadOnlyMany` containing a MATLAB Parallel Server installation.
+For example, if your Kubernetes cluster runs on-premise, you could create a PersistentVolume from an NFS server containing the MATLAB Parallel Server installation.
+For details on creating the PersistentVolumeClaim, see the [Create Persistent Volumes](#create-persistent-volumes) section.
+
+Modify your `values.yaml` file to set the `matlabPVC` parameter to the name of your PersistentVolumeClaim before installating the Helm chart.
+The worker pods will now use the image URI specified in the `matlabDepsImage` parameter instead of the `workerImage` parameter.
+
 ### Customize Load Balancer
 
 MATLAB Job Scheduler in Kubernetes uses a Kubernetes load balancer service to expose MATLAB Job Scheduler to MATLAB clients running outside of the Kubernetes cluster.

mjs/Chart.yaml renamed to chart/mjs/Chart.yaml

@@ -3,5 +3,5 @@ apiVersion: v2
 name: mjs
 description: A Helm chart for MATLAB (R) Job Scheduler in Kubernetes
 type: application
-version: 1.0.0
-appVersion: 1.0.0
+version: 1.1.0
+appVersion: 1.1.0

chart/mjs/templates/_derived.tpl

@@ -0,0 +1,22 @@
+# Define derived settings for use in multiple template files.
+# Copyright 2024 The MathWorks, Inc.
+
+# Maximum number of pool proxies needed by this chart
+{{- define "derived.numProxies" -}}
+{{ divf .Values.maxWorkers .Values.workersPerPoolProxy | ceil }}
+{{- end -}}
+
+# MJS lookup port
+{{- define "derived.lookupPort" -}}
+{{ add .Values.basePort 6 | int }}
+{{- end -}}
+
+# Job manager port
+{{- define "derived.jobManagerPort" -}}
+{{ add .Values.basePort 9 | int }}
+{{- end -}}
+
+# Whether to create environment variables for each service in the namespace (default false to prevent creation of too many environment variables)
+{{- define "derived.enableServiceLinks" -}}
+{{ .Values.enableServiceLinks | default false }}
+{{- end -}}